Delegate tasks to subagents

A subagent is a child session with its own context window. Delegate multi-file investigation, independent verification, or parallel work so the main conversation receives only a concise result. Each child needs a self-contained brief because it does not inherit the parent's conversation.

{"prompt":"Inspect the retry logic. Return a short answer with file:line evidence and what you did not check.","agent_type":"Explore","max_tool_use_iterations":30}

An agent_type chooses a named agent with a supplied system prompt and enforced tool allowlist. Omit it for a general child. The parent can override a type's default model and budget. Children inherit the parent's permissions but cannot ask you a question directly; path-approval requests and MCP elicitations are declined. They return a Blocked or Asking result for the parent to resolve. A child does not receive a separate MCP manager.

Dispatch parametersCopy Anchor Link

A pinned cwd confines the child to that checkout in confined sessions. readRoots and writeRoots add access without replacing its normal scope; roots have no confinement effect on a previously unconfined session with no explicit cwd or worktree isolation. readRoots can accompany isolation, while writeRoots cannot. For an image in your prompt, pass the attachment name or ID to the child; see Images.

Parallel compositionCopy Anchor Link

Use compose for a directed acyclic graph of up to 20 child tasks. Independent nodes start in parallel; an edge { from: "research", to: "report" } waits for research before starting report. Nodes are leaves and cannot dispatch further agent, skill, or compose calls. Upstream outputs are passed to downstream prompts as explicitly untrusted data. Cycles fail validation. Fail-fast is on by default; set fail_fast: false when independent surviving results are still useful.

{"nodes":[{"id":"research","prompt":"Find relevant code and report citations","agent_type":"Explore","max_tool_rounds":30},{"id":"tests","prompt":"Find coverage gaps and report citations","max_tool_rounds":50},{"id":"report","prompt":"Summarize both findings"}],"edges":[{"from":"research","to":"report"},{"from":"tests","to":"report"}]}

Each node can override the following, without changing sibling nodes:

node_timeout_ms bounds each node's runtime. A timed-out node can surface partial findings; siblings continue unless failure policy cancels them. See Worktrees for setup and preservation of isolated checkouts.

Background results and live inspectionCopy Anchor Link

A background agent returns a job ID immediately. On completion, the REPL automatically shows a notice and injects a background-subagent-result into the next model turn. Telegram delivers the result to its chat. End your turn instead of polling; /bgsub:join manually retrieves or replays the full result. A REPL injection is capped at 16 KB and names the join command when truncated. AFK_BG_AUTO_DELIVER=0 opts out of REPL auto-delivery. If the active goal changed while the child ran, the delivered result is labelled superseded="true" to warn that its conclusion may no longer fit the current objective.

In the REPL, /tasks lists running, recently completed, and logged children. Select one with Enter or run /tasks:view <id> to see its conversation and live output; Esc returns, and /tasks:cancel <id> cancels a running child. During a streaming parent turn, Tab opens the live task view. There you can type a message and press Enter to send it to the running child, then Esc to return. For a model-created background job, the parent can instead call send_message_to_agent with the job ID; user-backgrounded jobs are not steerable by that tool. A child dispatched with progress_events: true can call emit_progress; updates arrive in a later parent turn. Sibling children can share findings through workspace_publish and workspace_query, or subscribe to matching workspace entries. For persisted background job event logs outside the REPL, use afk bg list, afk bg tail <jobId>, or afk bg replay <jobId>; these commands can read prior logs after the parent process exits, but the job itself does not survive that exit.

Budget, timeouts, and recoveryCopy Anchor Link

Unnamed agent calls have no tool-round cap by default. general-purpose defaults to 150, and read-only named types to 50. Internal skill and compose forks default to 50. At a round cap, AFK gives the child one final tool-free response to summarize partial findings rather than killing it mid-tool. For multi-file implementation and testing, give the child a larger explicit budget rather than relying on the read-only default. Foreground child turns have a 45-minute wall-clock bound; background children have 60 minutes. The idle watchdog aborts a child after eight minutes without observable progress by default; it pauses while tools run or a provider communicates a legitimate rate-limit wait. AFK_SUBAGENT_IDLE_TIMEOUT_MS=0 disables the idle bound, not the wall-clock bound.

The three tree-wide budget variables are opt-in; each stops a dispatch when its configured limit is reached. get_runtime_state({ view: "subagents" }) shows active handles and, when enough history exists, a 30-day subagentOutcomeSummary grouped by model, agent type, and depth. It includes success rate, cap-hit rate, and median latency for groups with at least three runs, useful when choosing a larger budget or a different type.

AFK_SUBAGENT_AUTO_RESUME_ON_USAGE_LIMIT=1 lets forked children park on a usage-limit 429 instead of failing immediately; it is off by default. The environment default is ignored for daemon children because there may be no human to change accounts, although an explicit caller setting can override that. An interrupted parallel wave can produce a [wave-resume] offer at the next interactive session start: it lists unsettled units, missing worktrees, and dependencies. This does not automatically re-dispatch work or accept a yes/no reply. Re-dispatch ready units deliberately after checking their listed working directories. Unattended sessions show offers only with AFK_WAVE_RESUME_UNATTENDED=1.

Cancelling a parent cascades to its running children. A child failure reports to its parent, not automatically to all siblings unless compose's fail-fast policy applies. Ask for concise answers with file and line references, then independently check high-risk conclusions.

RelatedCopy Anchor Link