Subagents, Hooks & Memory¶
Subagents and delegation¶
subagent_invoke (capability local.subagent)¶
The model can spin up a second-level agent with an isolated context to run a subtask; only a summary comes back, so intermediate tool calls do not pollute the main conversation.
| Parameter | Default | Description |
|---|---|---|
prompt |
required | The subtask, as a single user message |
system_prompt |
empty | Override the subagent's role (reviewer / researcher / …) |
max_turns |
10 (cap 50) | Sub-loop turn limit to prevent runaway execution |
The subagent shares the main agent's provider, executor, tool table,
MemoryManager (plan progress, reflection hints), /rule rules, and
capability notices — but not session_path: subagents are disposable
and never write session history.
Enabling local.subagent also registers three expert tools with fixed
system prompts: review_code (bugs/security/performance/style),
write_tests (pytest generation), generate_docs (API docs and examples).
delegate / delegate_parallel (capability local.delegate)¶
Split complex tasks across multiple isolated subagents and aggregate:
delegate— sequential: one large prompt to a single subagent, full result returned.delegate_parallel— parallel: multiple(name, prompt)tasks at once; results are joined asname: resultfor the main agent.
| Parameter | Required | Description |
|---|---|---|
task |
yes | Task description |
system_prompt |
no | Role override |
tools |
no | Tool whitelist (e.g. ["read_file", "search_files"]); empty inherits the main tool table |
context_files |
no | File paths whose contents are prepended to the subtask |
max_turns |
no | Default 10, cap 50 |
timeout |
no | Per-subtask seconds, default 120 |
model |
no | Subagent model; inherits by default |
# config.toml
delegation = { max_concurrent = 5, default_timeout = 120 }
Subagents are always forbidden from delegating further (created with
allow_delegate=False), preventing infinite cascades. The allow_nested
config field is parsed and stored but currently has no effect.
Event hooks¶
.agenticx/hooks.toml inserts custom behavior at lifecycle points:
intercept dangerous tools, print warnings, run audit scripts, or ask for
confirmation.
| Event | Fires when |
|---|---|
before_tool_call |
Just before a tool executes |
after_tool_call |
After a tool execution completes |
on_error |
A tool raises or a subagent fails |
on_message |
A user message is received |
on_response |
An LLM response is received |
Governance actions dispatch first; a block hit short-circuits all
subsequent hooks:
| Category | Action | Behavior |
|---|---|---|
| Governance | block |
Block the operation, return a custom message to the agent |
| Governance | confirm |
Continue only after user confirmation |
| Governance | alert |
Red alert; escalates on tool failure |
| Extension | run |
Execute a shell command (run = "..." or argument array) |
| Extension | warn |
Yellow warning |
| Extension | log |
Write to the log, not the terminal |
# .agenticx/hooks.toml
[[hooks.before_tool_call]]
match = "write_file"
condition = "*.py"
action = "confirm"
message = "About to write {filename}, confirm?"
[[hooks.before_tool_call]]
match = "run_command"
content_pattern = "*rm -rf*"
action = "block"
message = "Dangerous command detected, blocked"
[[hooks.after_tool_call]]
match = "write_file"
condition = "*.py"
action = "run"
run = ["python", "-m", "py_compile", "{path}"]
on_fail = "warn"
silent = true
Matching fields: match (tool-name glob, default "*"), condition
(file-path glob extracted from arguments), content_pattern (content glob
over arguments JSON or results). Other fields: message (template),
on_fail (warn default / alert / block), silent.
Template variables include {tool_name}, {args}, {result}, {error},
{path}, {filename}, {filename_stem}, {content}, {exit_code},
{timestamp}.
Run-hook argument boundary
Run hooks pass template values as literal process arguments, without
a shell. Command strings containing variables are parsed before
substitution; pipes and redirections are rejected. The executable cannot
be templated; templated hooks cannot invoke shell interpreters or
interpolate Python code/module names; Windows targets must not be
.bat/.cmd. Only constant command strings keep shell execution. This
boundary does not sandbox a script that evaluates its arguments as code.
Skill packages can scope hooks to themselves via
.agenticx/skills/<name>/hooks.toml, mounted on the same HookBus. Hooks are
subject to trust and permission controls — see
Security.
Scheduled tasks (/cron)¶
Run Skills on a schedule; each run defaults to its own isolated subagent.
Tasks persist across sessions in ~/.config/AgenticX/cron_jobs.json.
/cron add every 5m skill weather Hangzhou
/cron add at 14:30 skill search AI morning briefing # one-shot
/cron add cron "0 9 * * 1-5" skill search morning briefing
/cron add every 1h skill weather Beijing skill search tech news
/cron add every 10m skill search service alerts condition "curl -sf http://health"
/cron add every 5m skill weather Hangzhou no-subagent # main conversation
Management: /cron list|pause <id>|resume <id>|remove <id>.
at tasks auto-disable after execution; each run has a 300-second timeout;
cron tasks do not run while privacy mode is enabled.
System prompt and project instructions¶
.agenticx/system-prompt.md (workspace) or
~/.config/AgenticX/system-prompt.md (global) replaces the base prompt;
workspace wins. The PromptPipeline then appends its sections — you do not
need to redeclare tool usage, rules, or identity:
[base prompt / system-prompt.md]
[Project instructions]
─── stable prefix: byte-identical for the whole session (prompt-cache friendly) ───
[Skills templates] [Skill package rules] [Disabled-capability notice]
[Long-lived operation rules] [Current plan] [Experience recall]
[Tool-chain context] [Directive proposals] [Environment info]
─── ephemeral suffix: recomputed every turn ───
Project instruction files are auto-discovered upward from the CWD,
first match wins: .agenticx/rules.jsonl > .agenticx/prompt.md >
.agenticx/prompt > .agenticx/instructions.md > .cursorrules >
.claude.md > CLAUDE.md. YAML frontmatter is stripped; long files are
truncated 60/40 head/tail at 8000 characters.
Rules vs profile¶
Two complementary memory forms:
| Dimension | /profile |
/rule |
|---|---|---|
| Content | Identity, preferences, tech stack (facts) | Operation rules, process constraints |
| Injection | Keyword recall — only relevant turns | Enabled rules — every turn |
| Storage | .agenticx/memory/<user_id>.json |
.agenticx/rules.jsonl |
| Example | "I'm a backend developer" | "Don't push after commit" |
Rule of thumb: /profile for "who I am"; /rule for "how things should
be done".
/rule add "Do not push after each commit; wait until the user says push"
/rule list | edit | enable <n> | disable <n> | remove <n> | clear
/profile list | search <kw> | add <text> | remove <n> | clear
More than 15 enabled rules triggers a trimming hint (tokens keep growing).
Directives auto-learning: tool-call sequences are recorded to
.agenticx/memory/behavior_patterns.json; after 5+ turns, adjacent tool
pairs seen 3+ times become rule proposals (confidence =
min(count / 10, 1.0), at most 2 pending at a time). Review with
/directives proposals, then /directives accept <id> or reject <id>.
Core does not learn directives or generate skills in the background by
default beyond this proposal mechanism; experimental skill evolution
requires the experimental pack and AGENTICX_EXPERIMENTAL=1.
Memory tiers and sessions¶
| Tier | Content | Lifecycle |
|---|---|---|
| Working | Conversation messages; token-budget compression against the model context window (soft threshold → LLM summarization of old messages, hard threshold → truncation) | Within session |
| Mid-term | Plan progress (TTL expiry), reflection hints, tool-chain patterns | Within session |
| Long-term | Cross-session experience learning (experiences.jsonl, CJK-aware retrieval) |
Across sessions |
Sessions (topics) isolate working memory:
.agenticx/session/<topic>/history.json. Long-term memories (profile,
skills, rules, experience) are shared across topics. Each topic can carry
scene memory (scene.md) injected whenever you switch back:
/session new|list|switch|rename|fork|remove
/session scene Context: data platform, Python 3.11, pytest only
/session scene set <text> # replace
/session scene clear
Experience memory records task outcomes and tool patterns; long tasks
(6+ messages) are summarized automatically, /summarize triggers manually,
and /feedback good|bad labels satisfaction. After 3+ consecutive tool
failures, a reflection hint nudges the model to change strategy.
Conversation history summaries live in .agenticx/memory/history.json
(/memory list|search|remove|clear). Every LLM call and tool execution is
traced to .agenticx/traces/<session>.jsonl for debugging and evaluation
(/trace, /report, /stats).
Context management commands: /compress replaces history with an LLM
summary; /undo reverts the last file write/delete via checkpoint
snapshots.