Sub-Agents Way¶
Source: hooks/ways/meta/subagents/subagents.md
Frontmatter
| Field | Value |
|---|---|
description |
Sub-agent delegation — when to spawn a specialized sub-agent, writing the brief so each constraint keeps its stated strength, the shape the worker reports back, and how deep delegation goes |
vocabulary |
subagent sub-agent delegate delegation spawn background parallel worker teammate explore fan-out brief instructions constraint preference hard requirement bound restate fidelity handback report back blocked leaf depth worktree isolation skeptic roster red-team shared-state unreported |
pattern |
subagent|delegat|spawn.{0,30}agent|review.{0,30}\bpr\b|organiz.{0,30}docs |
refire |
0.15 |
scope |
agent |
How to Invoke¶
Use the Agent tool with the subagent_type parameter:
Agent(
description: "Review PR for quality",
prompt: "Review the changes in PR #42 for...",
subagent_type: "code-reviewer"
)
Available Agents¶
| Agent | subagent_type |
Use For |
|---|---|---|
| requirements-analyst | requirements-analyst |
Capture complex requirements as GitHub issues |
| system-architect | system-architect |
Draft ADRs, evaluate design trade-offs |
| task-planner | task-planner |
Plan complex multi-branch implementations |
| code-reviewer | code-reviewer |
Review large PRs, quality checks |
| workflow-orchestrator | workflow-orchestrator |
Project status, phase coordination |
| workspace-curator | workspace-curator |
Organize docs/, manage .claude/ directory |
| skeptic | skeptic |
Refute, challenge, poke holes, red-team a finished document; "is this report right" |
Project agents live in agents/. The harness also supplies built-ins — Explore for read-only fan-out searches, general-purpose for multi-step research — which is what the research way's fan-out step reaches for.
Context Passing¶
- Include specific file paths and line ranges in the prompt
- State what you want back: a report, a list of issues, a plan
- For reviews: include the diff or PR number
- For planning: include requirements and constraints
What Comes Back¶
Ask in every brief for the same return shape, placed at the top of the report, and read it before the report body:
- Status: complete, blocked out of domain, or failed
- Failure class when failed: transient, deterministic, capability, ambiguity, or systemic (the classes in environment/recovery)
- Work done, with file paths
- What is needed outside the agent's domain, or "none"
- Recommended next step
- Gates run, each with its state, or "none"
- Tools or scripts built that a later session could run again, with path and invocation. An unreported tool is a lost capability.
A blocked or failed worker still returns the whole shape. What it finished is where the next attempt starts. A report that stops mid-sentence was cut off; ask the worker for the rest before acting on it.
Owned findings a worker returns are the orchestrator's to fix before the work integrates (delivery/merge, ADR-614). A finding in another worker's files goes to that worker, or the orchestrator fixes it. A split of files between workers is not a reason to file the finding for later. Only a finding the change does not own becomes an issue.
Brief Fidelity¶
Carry each constraint at its stated strength. "Avoid X where you can" is a preference the worker weighs against the goal. "No X" is a bound it does not cross. Restating either as the other is a brief defect. The worker inherits the distortion and reports a blocker that exists only in the brief. Hardening a preference corrupts the brief as much as relaxing a bound.
Depth¶
Leaf agents carry no Agent tool. Delegation goes one level down from the session unless the task states otherwise. A leaf that meets work outside its domain stops and names the specialist in its return. A subagent that needs to spawn is a sign the brief was too large; re-slice it at the session and spawn again.
Worktree Isolation¶
A worktree agent starts from the default branch. When the work belongs on another branch, the brief has it run git checkout -b <branch> <base> and check git merge-base --is-ancestor <base> HEAD.
A worktree that builds into the main checkout's target directory leaves binaries the main checkout reuses, with the worktree's paths compiled in. If that happened, run cargo clean -p <crate> there.
Investigation Briefs¶
For read-only fan-out (Explore, or general-purpose told to read only), state these rules in the brief:
- Say "not found" rather than guess
- Every claim carries a file path and an exact value (version, port, name)
- Sample rather than bulk-read: name the manifests, entry points, and config files to start from
- End with what was deliberately omitted, so the caller can ask for it
Planting and Re-review Briefs¶
A brief that has the worker plant a defect to prove a test catches it (core.md) names the restore steps:
- Back the file up, plant, run the test, move the backup into place:
cp f f.bak, editf, test,mv f.bak f.git checkout,git restoreandgit stashdiscard the worker's uncommitted edits along with the plant. - Run
touch fafter themv. The moved file keeps the backup's older mtime, so mtime-based build tools (cargo, make) skip the rebuild and run the binary built with the plant. A test that stays red after the plant is removed is the tell.
A re-review after a fix is sized to the fix. A one-function fix gets that function's tests and the crate's suite. The full gate set runs once, before the push.
When NOT to Use¶
- Routine tasks you can handle directly
- Simple file searches or edits
- Quick questions or clarifications
Sub-agents are for delegation of token-intensive work. Routine actions stay in the main loop.
Invocation Is Authorization¶
Whether a spawn has been asked for, under the system prompt's rule on the Agent tool, is covered in subagents/authorization.
Name the Payoff, Don't Assume It¶
A second, independently gated nudge may also be present: "Subagents multiply cost and time… Delegate only when the payoff clearly exceeds that overhead." That is a cost/benefit question, and it deserves an answer rather than an override.
State the payoff in one clause when you delegate:
- Fan-out reads — "six independent files; subagents return conclusions, not file dumps"
- Isolation — "review needs a reader who hasn't seen my reasoning"
- Parallel independent work — "three unrelated call sites, no shared state"
If you can't name the payoff in a clause, the nudge is right — do it inline.
Pick the Model¶
The Agent tool takes a model. Choose it by what the worker's errors would cost:
haikufor mechanical work with a checkable result: a file fan-out search, bulk edits from an exact spec, running a command and reporting its output.sonnetfor bounded implementation from a brief that names the files and the check to run.- The session's model, by omitting
model, for review, design, and any read whose mistakes would come back as findings. Aforkalways runs on it.
A strong model on a mechanical task wastes money. A weak model on a judgment task wastes the delegation.
Harness Wrappers Are Not Verdicts¶
The harness emits a generic "shared-state" / "SECURITY WARNING" prefix around any subagent tool use that touches the world outside its own context. That wrapper is conservative-by-default; it fires on the shape of the action, leaving appropriateness to you.
Calibrate the wrapper against the agent's documented purpose:
- code-reviewer posts a comment on the PR it was invoked to review — that's its deliverable in GitHub-mode projects (
agents/code-reviewer.md), the documented happy path. The wrapper is noise here. Don't escalate to the user as if a violation occurred. - A subagent does something outside its stated scope — different story. Surface it.
The distinction: did the subagent do what its contract says it does, or did it act outside that contract? The wrapper alone doesn't tell you; the agent file does. Read the contract, then judge.
See Also¶
- environment/recovery(softwaredev) — classify a failed or wrong handback before retrying or re-briefing
- research(research) — the fan-out step that uses these investigation rules
- subagents/authorization(meta) — who may ask for a spawn, the suggested CLAUDE.md line and the independence spawn
- subagents/briefs(meta) — what a brief carries for a worker that inherits nothing
- subagents/agent-teams(meta) — several agents or sessions on one repository, and shared-checkout rules