Subagent Orchestration

You own the task, and by default you do it. Subagents buy you three things — context isolation, parallelism, and independent judgment — and cost you the context you write into the prompt, the latency of the round trip, the checking the result needs, and visibility into how the work was done. Use them sparingly: delegate a bounded piece only when one of the three benefits outweighs those costs for it, or a governing instruction requires independent assistance, and write the assignment so the missing visibility does not matter.

Reading a bundled role's Role perspective and applying it yourself is not delegation and does not need this workflow. It leaves your model, effort, permissions, and ownership untouched, and it counts as self-review, so it does not satisfy an independent-verification gate. Use the steps below only when you are considering or carrying out an actual dispatch.

Full detail: references/subagents.md and references/model-routing.md.

1. Decide whether to delegate

Delegate when at least one is true:

• Context isolation — answering needs many files read, and you want the answer without the reading.
• Parallelism — several genuinely independent pieces can run at once.
• Independent judgment — a reviewer who never saw the implementer's reasoning will catch what the implementer cannot.

Do it yourself otherwise — and that is the normal case, including substantial multi-file work. Do not delegate because a role is available or cheap, because the task is large, because a graph has a node, because a perspective would be useful (apply it yourself), or because you have not used a subagent yet. Do not delegate tightly coupled work that would need its context rebuilt at every handoff, or work you have already done. No sequence of planner, implementer, reviewer, tester, and documentation passes is ever required.

Before the first dispatch, set a finite allowance of launches and retries within the authority you actually have, and for each helper note what it returns, how you will verify it, and the benefit. Keep framing, integration, validation, and the final answer. Direct work waives nothing: the skills, references, graph planning, and verification the task needs apply either way.

2. Pick the role

One consequence of permission modes worth remembering: senior-reviewer runs in plan mode and cannot reliably run tests, linters, type checkers, or builds — those commands prompt or go to the classifier. When a review needs a suite executed, that is test-triager, which runs in default.

3. Choose the model for the work

Pick the model for what the helper is actually being asked to do, to minimize the total cost of a correct, accepted result — tokens, the context you repeat into the prompt, retries, corrections, and your own verification afterwards — not the token price alone. Choose sufficient capability upfront; a cheap attempt that has to be redone is the expensive option.

Each bundled definition declares the default for its typical work — haiku on the two lookup roles, opus with effort: medium on the four judgment roles — and the call selects the actual model: pass it explicitly every time, including on a retry, a replacement, and a leaf a local-orchestrator dispatches. An Opus role given only extraction or a summary can be dispatched on haiku; judgment work never goes to Haiku; opus and fable are not helper routes. The choice never follows the main session's model.

Effort cannot be passed on the Agent call — only a definition sets it, and it overrides session effort while the subagent runs. So dispatch bundled roles, not built-in agent types, when reasoning depth matters; a low-effort session still gets senior-reviewer at medium. medium is Anthropic's documented default for Opus 5.5 and matches or exceeds Opus 5 at high there; high, xhigh, and max on a helper remove that economy and burn usage on work you verify regardless. Haiku has no effort levels.

Keep your own session as the user configured it: do not change its model or effort, and do not toggle fast mode, for yourself or on a helper's behalf. Two things can silently change what actually runs: CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 ignores every definition's model and blocks the per-call model (and on Claude Code before v2.1.251, a plain CLAUDE_CODE_SUBAGENT_MODEL already outranked the call), and an organization allowlist can substitute. If either is in effect or you cannot tell what ran, report it and keep the work yourself rather than accepting a substituted model. Only you reassign a helper's route, within the approved routes, on task evidence, and within the allowance; a helper never changes its own. Never route a child to fable, and never raise effort, to rescue a failing assignment — sharpen it once, then bring the work back.

4. Write the assignment

The subagent sees only this — not your conversation, not the user's request, not the files you have open.

Goal:
[One outcome, stated so you could verify it.]

Context:
[The request, the constraint, the current state. Only what bears on this.]

Scope:
[Where to look or what to change.]

Non-goals:
[What to leave alone. This prevents the most common failure — scope drift.]

Skills:
[The applicable skills, each with its SKILL.md path, to read before the covered
work. Leaf roles cannot discover or invoke skills themselves — their `tools`
allowlist omits `Skill`.]

Write ownership:               (only for subagents that edit)
[Exact files this subagent owns. No concurrent sibling may own them too.]

Workspace:
[The current workspace. Do not create or request a worktree.]

Evidence required:
[Paths, symbols, command output, reproduction steps, citations.]

Acceptance condition:
[How you will decide the result is good.]

Stop and report if:
[The situations where stopping beats continuing.]

Keep the payload small: paths and accepted results, never transcripts or long logs.

5. Run them in parallel when they are independent

Dispatch independent subagents in one message so they run concurrently.

Sequence only for a real dependency — the second genuinely cannot start without the first one's accepted output. Ordering that just reflects your list is not a dependency, and enforcing it costs you the parallelism.

Before parallel writers: confirm file ownership is disjoint. If it is not, serialize them. A separate worktree does not fix overlapping writes; it defers the conflict.

Claude Code caps concurrent subagents (20 by default) and fails spawns past it. Treat that as backpressure — let running work finish instead of queuing speculative work. Every launch counts against your allowance; expand it only for a newly discovered dependency, an invalidated gate, or a changed user scope, and record why.

6. Nesting, if you use local-orchestrator

Claude Code allows nesting three layers below the main conversation by default. This playbook uses two:

layer 0   you
layer 1   direct worker, or local-orchestrator
layer 2   leaves — cannot spawn

There is no flag to verify before a local-orchestrator can dispatch; nesting is already on. The cap holds because every leaf role carries disallowedTools: Agent. An operator can additionally set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 2; that is hardening, not a precondition, and you do not change it from inside a task.

Assistance is flat by default: a helper does its bounded work without spawning. local-orchestrator is the one authorized nesting workflow, chosen explicitly by you for a slice with genuine fan-out. When one worker can do the slice, dispatch that worker.

7. Verify before you accept

A returned result is a claim.

• Does the evidence meet the acceptance condition, or does it just sound right?
• Do the named paths and symbols exist and say what the result says? Spot-check the load-bearing ones.
• Did anything outside scope change?
• Was validation actually run, or is its absence explained? A reason for omitting a check is not a passing check.
• Were the skills the assignment named actually applied? Their required outputs are the evidence; a mention is not.
• Did the child add machinery the assignment did not call for — an abstraction, state, configurability, or a workaround where a boundary fix was in scope?
• Did the helper earn its cost — did the benefit you recorded before dispatch actually arrive, and did it tell you something you did not already have?
• Have you read the final diff yourself?

When two subagents disagree, resolve it against primary evidence — code, tests, schemas, logs, runtime behavior. Do not prefer the more confident one.

One retry with a sharper assignment is reasonable, after you state the failure evidence and what will change; it consumes the allowance and stays within the approved routes — a different model is not a substitute for a sharper assignment. A second identical failure is information: report the blocker. Prefer a bounded correction or finishing the piece yourself over a chain of reviewers, and never cancel required verification to finish sooner.

Never accept a conclusion because it sounds confident.

8. Keep these decisions yourself

Architecture. Security, authentication, authorization, privacy. Payments. Destructive operations. Data migrations and persisted schemas. Concurrency, locking, caching. Public API compatibility. Release and production configuration. Final acceptance.

A subagent can gather the evidence. You make the call.

9. Worktrees

Start in the current workspace with an auxiliary-worktree budget of zero, and expect to stay there. Only you may authorize isolation: worktree, and only with the base ref recorded — an isolated subagent branches from the repository default branch, not your HEAD, unless worktree.baseRef is set to head.

One active auxiliary needs no extra approval; two or more need the user's. Before your final response, every task-created auxiliary is either integrated and removed, or preserved with an exact blocker. The worktree-lifecycle skill holds the full rules.

10. Report

Lead with the outcome. State what changed or was answered, what validation ran and what it produced, anything still blocked, and — when helpers were used — which ones, what you accepted from them, and how the allowance was spent. Reconcile any helper still running: close an optional one whose output is no longer needed through the supported controls, preserving its useful output. Work you did directly gets no orchestration report.