dispatching-subagents

name	dispatching-subagents
description	Use when about to spawn or delegate work to a subagent (Agent/Task tool), choosing a model tier (haiku/sonnet/opus) for a task, writing a delegation prompt, deciding whether something should be delegated at all, verifying a delegated result, or after a delegated task failed twice and needs escalation.

🌐 繁體中文（canonical） · English mirror

Subagent Dispatch Rules (dispatching-subagents)

Goal: the main conversation's context holds only conclusions and decisions; the execution details are outsourced. Delegation prompt templates are in references/templates.md.

0. When NOT to delegate (read this first, to avoid over-delegation)

• A single-point lookup where you already know the exact file and location (e.g. read the value on line N of some config file) → Read it yourself; it's cheaper than dispatching an agent.
• Conversational replies, explaining concepts, changing one or two lines → do it yourself.
• Criterion: known exact file path or a unique keyword, and the content you expect to read is < 200 lines → do it yourself; needs a search across multiple directories or guessing at naming → delegate.

1. The commander does not take the field

The following work is always dispatched to a subagent; the main conversation only receives conclusions:

• Bulk file reading / repo scanning / "find every place that uses X" → Explore agent (read-only, cheapest).
• Web lookups, reading docs, comparing options → general-purpose agent (can use WebSearch/WebFetch).
• Batch file edits (the same pattern applied in many places) → general-purpose agent.
• Designing an implementation approach → Plan agent.
• Code review → code-reviewer agent (with system-architect for a second, design-level round).

2. The delegation trio (every delegation prompt must contain these; templates in references/templates.md)

1. Goal and motivation: what to do and why (so the agent can judge for itself when it hits a fork).
2. Acceptance criteria: a mechanically checkable definition of done (e.g. "compiles and paste the last 5 lines of the gradle output", not "ensure quality").
3. Report format: return only conclusions + file:line; write long artifacts to a specified path and return the path.

3. The actually-available values for model and effort (verified 2026-07-03)

• The Agent tool's model parameter: haiku / sonnet / opus. Omitting it = inherit the main conversation's model, which is the correct default.
• The Agent tool has no effort parameter; effort is decided by the agent definition's frontmatter or the session's effortLevel.
• The Workflow tool (multi-agent orchestration) is not present in every harness; use it only when the user explicitly asks for multi-agent orchestration and the tool actually exists.
• Selection basis:
  • haiku: mechanical batch application (pattern already verified), format conversion, simple grep aggregation.
  • Omit (= same tier as main conversation): general search, implementation, review.
  • opus: architecture trade-offs, root-causing hard bugs, judging a multi-option review.
  • Note: the top of the escalation ladder is the strongest tier you have available (in this table, opus); do not assume there is a higher tier to dispatch to. For taste/ambiguity questions that even the strongest tier can't solve: get a second opinion from a different model family → give the user options and honestly flag low confidence.

4. The reporting contract (write this into every delegation prompt)

• Return only: conclusions, key evidence (file:line, the tail of test output), and blockers hit.
• Forbidden: pasting whole files back, a play-by-play of the process.
• Artifact over ~50 lines → write it to a file (scratchpad or a specified path), return the path.

5. Escalation / de-escalation path

• haiku fails once → escalate straight to the main-conversation tier and re-dispatch; do not reason with haiku.
• A same-tier agent fails the same subtask twice in a row → escalate to opus, and put the complete failure trace (what it did, what it output, why that counts as failure) into the new prompt — an escalation without the trace is just swapping the model and guessing again.
• After the pattern is solved: write the solution up as explicit steps and de-escalate back to haiku to batch-apply it to the remaining locations.
• Retry ceiling: at most 3 attempts within one model tier; the counter resets to zero when escalating to a new tier. If the top tier also burns through its 3 → stop, and handle it per judgment.md §3's "when to ask the user".

5.5 The side-effect boundary of read-only / research tasks (field lesson 2026-07-06)

When dispatching a "research / audit / read-only" task, the prompt must define which verification commands are permitted to run — "read-only" does not automatically stop the agent from running commands with side effects.

• ❌ Dispatching "research what could be improved in this project" with no constraints → to verify "the tests pass" the agent runs npm test, whose tests write to the production DB, and the research task contaminated the data.
• ✅ The prompt spells out: "read only the source and config; before running tests/build, first confirm whether it writes to production resources, and if unsure, report back and do not run it." To verify "are the tests green", prefer reading the CI record or asking the user, not running them yourself.

6. The doer does not verify their own work

Scope: delegated tasks, and high-risk changes (release paths, deletions, public APIs). For a ≤3-file small fix the main conversation did itself, running compile/tests and pasting the output is enough — no separate acceptance agent needed. The one who did the work does not verify their own work. Acceptance of a delegated task is always dispatched to a fresh-context agent (freshly opened, given no implementation history, only the acceptance criteria):

• File-type output → read-back: the new agent reads the file and answers "does it contain X, Y, Z".
• Code → run the tests or actually compile/execute, paste the output; if there are no tests, write a minimal reproduction.
• High-risk judgment (architecture, security, whether to delete something) → second opinion: dispatch another agent to review from the opposing stance ("try to overturn this conclusion"), or judge among multiple answers and pick the best.
• The acceptance criteria must include at least one item that "actually executes and pastes the output" — an acceptance list with only existence checks does not qualify.
• If the verification agent says it fails → go back to the implementer (carrying the verification output); do not have the main conversation stamp it approved because it "looks fine by eye".