Subagent

Subagent orchestration -- spawn background agents to work on tasks in parallel.

Lifecycle

Subagents follow this status flow: pending -> running -> completed / failed / aborted

• Spawn: Use subagent_spawn with a label, objective, and type. The subagent runs autonomously.
• Mid-run communication: Subagents can send notifications to the parent via notify_parent while still running -- useful for sharing interim findings or signaling that they are blocked.
• Auto-notification: The parent conversation is automatically notified when a subagent reaches a terminal status (completed/failed/aborted). Do NOT poll subagent_status.
• Read output: Use subagent_read after the subagent reaches a terminal status to retrieve its full output.

Types

There are three subagent types. Every one of them runs in the background: the spawn call returns straight away with an id, and the result reaches you as a notification. Pick one with two questions: does it need to change anything, and what do you want back?

recall is local information search across memory, the personal knowledge base, past conversations, and workspace files. Use it when a subagent needs prior context that is not already in the prompt.

researcher and builder can call notify_parent for mid-run communication with the parent.

A researcher is scoped to the fixed read-only list above: it cannot write or edit files, run commands, reach a connector, or otherwise persist output. If the task must produce a file, save results, run a command, or act on an outside system, spawn a builder: a researcher finishes without producing anything, and the delegated write silently no-ops.

Model tier is a separate knob. Use inference_profile to run any type on a stronger or cheaper model. A persona is not a type: see the fallback below.

Legacy names and unknown roles

The older role names still work: planner and investigator run as a researcher, coder and general run as a builder. The spawn result names the type that actually ran.

Any other role text is treated as a persona, not a type. The subagent runs as a researcher (read-only) with that text framing how it approaches the task, and the spawn result says so. That is deliberate least privilege: an invented or misspelled role must never silently hand out write access. If the task genuinely needed to write, the subagent reports that it cannot, and you re-spawn it with role: "builder".

Omitting role entirely runs a builder, so a spawn that names no type keeps your full tool surface.

Verification

Checking that something is actually done is not a fourth type. It is a researcher with output_contract: "verdict".

A verdict subagent returns, for each criterion in the objective, PASS or FAIL plus the exact evidence (file path, line, value, or quote), CANNOT VERIFY where the evidence is missing, and nothing else. Give it the criteria explicitly in the objective; a vague "check the work" gets you a vague list.

It runs on a cheaper model by default, because checking a claim against evidence that already exists is mechanical work, not investigation. An explicit inference_profile still wins if a check genuinely needs a stronger model, and so does a profile pinned on the subagentSpawn call site in config (see Inference Profile below).

The other contracts: output_contract: "artifact" tells a builder that the deliverable is the thing produced and to end by listing the exact files it created or modified. "report" is the default and asks for nothing extra. A contract that does not match the type is rejected rather than quietly changed, and the advisor takes no contract (it has its own framing).

Consulting the Advisor

The advisor is the one type you may spawn on your own judgment, unprompted: you do not wait for the user to ask for a subagent. The background types (researcher, builder) stay delegation-driven: reach for them to offload work, typically when the user's request calls for it.

A consult is expensive (a stronger model reviews your brief and answers), so reserve it for moments where a second perspective can genuinely change the outcome. Most tasks need no consult at all: a routine task with an obvious approach does not require sign-off, before you start or after you finish. Orient yourself first (read the relevant files, understand the task), then consult the advisor:

• Before you commit to an approach on a consequential or ambiguous task: the design space is wide, a wrong approach would be costly to unwind, or requirements pull against each other.
• When you get stuck or are weighing a change in direction.

The consult runs in the background like every other spawn: subagent_spawn returns immediately, and the guidance arrives as a notification when the advisor finishes. Keep working while it thinks. It is read-only, runs on a stronger model, and sees ONLY the brief you write in objective plus a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace). It cannot read this conversation, so the quality of its guidance tracks the quality of your brief. Write a substantive one:

• The task or goal, stated in full.
• Your plan, or the options you are weighing against each other.
• The key evidence you already have: file paths, command output, results, decisions already made.
• The specific question you want answered.

The environment snapshot is what lets its guidance point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.

The advisor has read-only workspace tools (file_read, file_list, code_search) so it can open a file or search the code when a decisive fact would change its advice. It uses them sparingly, for verification rather than exploration, and it cannot change anything or persist output. It has no memory search and cannot see other conversations or external systems, and it runs on a budget of 8 tool calls and 5 minutes, after which it is stopped and you are told which ceiling it hit. So put the evidence you already have (a file's contents, a command's output, results gathered elsewhere) into the objective rather than making it go find them: a brief that carries its own evidence gets better advice than one that spends the budget looking for it.

A consult is one-shot: the advisor takes no subagent_message follow-up, and its whole answer is the guidance in its notification. If you need something else weighed in on, spawn a new advisor with a brief that carries the new question and what the first consult told you.

Because the guidance lands after you have moved on, consult early: spawn the advisor before you commit to an approach, not after you have built on one. When its guidance arrives, weigh it against what you have done since. Adopt what still applies, and say so plainly if it means undoing a step you already took.

Parent Communication

Subagents use notify_parent to send messages to the parent conversation while still running. Each notification has an urgency level:

• info -- Progress updates, minor findings. The parent is informed but does not need to act.
• important -- Key findings, significant results. The parent should review when convenient.
• blocked -- The subagent needs guidance or a decision from the parent to continue.

Use notifications judiciously -- one per major finding or milestone. Do not send a notification for every small step.

Naming

Subagents can be referenced by label instead of UUID. The label parameter is accepted on subagent_message, subagent_status, subagent_read, and subagent_abort as an alternative to subagent_id. Label lookup is case-insensitive.

Use descriptive labels when spawning subagents (e.g., "research-auth-libraries", "implement-login-form") so they are easy to reference later.

Reading Output

subagent_read returns the subagent's assistant text output. Use the last_n parameter to retrieve only the most recent N assistant messages instead of the full history. This is useful for large outputs where you only need the final result.

Ownership

Only the parent conversation that spawned a subagent can interact with it (check status, send messages, abort, or read output).

Silent Mode

Set send_result_to_user: false when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.

Repeat Spawns

Spawning an objective that several near-identical subagents have already completed in the last day can come back as a message about those earlier runs instead of a new subagent. Read what the earlier run produced with subagent_read, or narrow the objective to what is actually still missing.

A second message covers the other shape: near-identical copies that are still running and have returned nothing yet. There is nothing to read in that case, so wait for the running ones to report back, or narrow the objective to the part they are not covering.

Either way it is advisory, not a block: pass confirm_repeat: true to spawn anyway.

Inference Profile

Set inference_profile to an llm.profiles key when a subagent should run under a specific model profile.

When it is omitted, the subagent takes the subagentSpawn call site's default model selection. It does not pick up the profile the spawning turn is running on: a profile pinned on a conversation is a choice about that conversation, and it does not follow the work that conversation delegates.

An advisor is the one exception: it takes the stronger llm.advisorProfile by default, since a consult is only worth having when it brings a stronger read than your own.

An inference_profile you name explicitly wins, unless the model catalog does not report it as tool-capable, in which case it is replaced by the subagentSpawn default with a note on the spawn result. An advisor applies that same fallback.

output_contract: "verdict" takes a cheaper profile, so a verdict runs cheap unless you name an inference_profile yourself. A profile pinned on the subagentSpawn call site in config also beats the cheap preset, so an operator can decide what checks run on.

Fork Mode

Forks are sub-agents that inherit the parent's full context -- messages, system prompt, and memory -- sharing the KV cache for near-free context inheritance. Use forks when the task benefits from knowing what you've been discussing; use a regular sub-agent when the task is self-contained.

Key behaviors: A fork honors the type you name, so role: "researcher" gives a read-only fork. A fork that names no type runs as a builder and so keeps your full tool surface, which is what the system prompt it inherits describes. A persona reaches a fork through its task framing rather than its prompt, since the prompt is yours verbatim. send_result_to_user defaults to false. Read fork output with last_n: 1 to get only the final synthesis.

When to fork vs regular sub-agent:

Rule of thumb: "Does this task need to know what we've been talking about?" If yes, fork. If the objective is fully self-describing, use a regular sub-agent with a scoped type.

Tips

• Do NOT poll subagent_status in a loop. You will be notified automatically when a subagent completes.
• Prefer researcher unless the task has to change something. Read-only is the smaller blast radius, and most delegated work is reading.
• Spawn a researcher and a builder in parallel for research-then-implement workflows -- the researcher gathers context while the builder starts on the known parts.
• Use notify_parent for interim findings instead of waiting for completion. This lets the parent act on partial results early.
• Use subagent_message to send follow-up instructions to a running subagent.
• Use subagent_abort to cancel a subagent that is no longer needed.
• Spawn a subagent when the work is extensive: a sweep across a large codebase, deep research across many sources, or an investigation whose raw output (file slices, grep output, logs) would flood your context. Do quick work inline -- a few file reads or searches, an ordinary web lookup -- since a spawn pays for a whole fresh context and is slower than just doing the work.
• Delegate long root-cause investigations (log forensics, multi-file "why is X happening?" digs) to a researcher: it does the digging in its own context and returns a compact root-cause report, instead of crowding your conversation with intermediate output.
• Scale the fan-out to the task. Most tasks need zero or one subagent. Split work across multiple subagents only when the parts are genuinely independent and each is substantial on its own.