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.