Dispatching Subagents
Overview
Core principle: Delegate to go faster and to keep your own context clean — but treat the host
as a budget, not an infinite pool. The goal is lower wall-clock, not maximum concurrency.
Ten agents that make the machine swap are slower than three that don't.
Two wins from delegating, and they're different:
- Parallelism — independent work runs at once, so wall-clock ≈ the slowest chain, not the sum.
- Context hygiene — a subagent reads the haystack and hands you the needle; the file dumps
never enter your context. Reach for this even when you don't need speed.
Reach for a Subagent When
- Fan-out search / exploration — "where is X handled", sweeping many files or naming conventions. Delegate; keep the conclusion, not the excerpts.
- Independent tasks — spikes of two rival approaches, reviewing N files, building M targets — anything with no ordering dependency between the pieces.
- Adversarial verification — spawn independent skeptics to try to refute a claim (behavior unchanged? bug real?). Diverse lenses catch what one pass misses.
- Anything that would flood your context with output you won't keep.
Don't When
- Steps depend on each other — B needs A's output. Delegating then blocking on it buys nothing but overhead.
- It's one known lookup — you know the file and symbol. Just read it.
- The work is smaller than the dispatch cost — spawning an agent to save five seconds loses.
Free Parallelism First
Independent tool calls in a single message run concurrently — no subagent needed. Before
spawning anything, batch the handful of independent reads/greps into one message. Use subagents
when you need context isolation or genuine fan-out beyond a few calls.
The Host Budget
Classify every unit of work before deciding how wide to go:
| Class |
Examples |
How wide |
| Cheap / read-only |
Read, Grep, Glob, search agents, analysis |
Fan out — but cap ~5–8. More adds coordination churn, not speed. |
| Heavy / compute |
build, compile, full test suite, install, render, containers, DB |
Serialize, or cap to ≤ (cores − 2). Never run N full builds at once. |
Heuristic: heavy jobs concurrent ≤ nproc − 2; cheap agents a flat ~5–8. When mixing, the
heavy class sets the limit — a single build can saturate the machine on its own.
Before a Wide Fan-Out
- Scout first. Send one agent (or one check) to confirm the approach before launching
twelve down the same dead end. Cheap insurance against expensive mistakes.
- Know the machine.
nproc for cores; check current load. On a busy laptop, dial it down —
your fan-out shares the host with the user's editor, browser, and running app.
- Pipeline over barrier. Don't make fast agents idle waiting for the slowest before any
result moves on. Let each result flow to its next stage as it lands; wall-clock drops and
fewer agents sit live at once.
- Chunk huge lists. 200 files is not 200 agents (a thundering herd). Batch into a handful of
agents each handling a slice.
Craft Each Agent's Task
A subagent starts blank — it does not inherit your context, so hand it exactly what it needs
and nothing it doesn't:
- Focused scope. One domain per agent ("fix the abort tests in X"), not "fix everything." Broad scope loses the agent.
- Self-contained. Paste the error text, the file path, the relevant facts. Don't assume it saw your session.
- Constraints. Say what not to touch — "tests only", "don't refactor production code" — or it may reshape the world.
- Named output. Tell it what to return (a summary, a verdict, the patch). Its final text is the result you get back — vague ask, vague result.
Dispatch all independent tasks in one message so they run at once. When they return: read each
summary, check the changes don't conflict, and run the full suite once to confirm they compose.
Parallel Edits Need Isolation
Read-only fan-out is safe. Concurrent edits are not — two agents writing the same tree race and
corrupt each other. If parallel tasks mutate files, give each its own worktree, or partition so no
two touch the same file. When in doubt, parallelize the reading/analysis and serialize the writing.
→ REQUIRED SUB-SKILL: Use using-worktrees for the isolation mechanics — including the
harness's built-in isolation: "worktree" flag, which creates and cleans up the worktree for you.
Common Mistakes
- One agent per item for hundreds of items. Thundering herd. Chunk it.
- 8 parallel test suites on a 4-core laptop. Swap death; slower than running them in twos.
- Fanning out before the approach is proven. Scout with one, then widen.
- Delegating a dependent step, then blocking on it. No parallelism gained — just dispatch overhead.
- Maximizing agent count. Wall-clock is set by the slowest chain and the host's limits, not by how many agents you launched.
1---2name: dispatching-subagents3description: Use when work can be split across subagents or parallel tool calls — fan-out search, independent build/spike/review tasks, adversarial verification — or when deciding how many things to run at once without overwhelming the host or ballooning total runtime4---56# Dispatching Subagents78## Overview910**Core principle:** Delegate to go faster and to keep your own context clean — but treat the host11as a **budget**, not an infinite pool. The goal is *lower wall-clock*, not *maximum concurrency*.12Ten agents that make the machine swap are slower than three that don't.1314Two wins from delegating, and they're different:1516- **Parallelism** — independent work runs at once, so wall-clock ≈ the slowest chain, not the sum.17- **Context hygiene** — a subagent reads the haystack and hands you the needle; the file dumps18 never enter your context. Reach for this even when you *don't* need speed.1920## Reach for a Subagent When2122- **Fan-out search / exploration** — "where is X handled", sweeping many files or naming conventions. Delegate; keep the conclusion, not the excerpts.23- **Independent tasks** — spikes of two rival approaches, reviewing N files, building M targets — anything with no ordering dependency between the pieces.24- **Adversarial verification** — spawn independent skeptics to try to *refute* a claim (behavior unchanged? bug real?). Diverse lenses catch what one pass misses.25- **Anything that would flood your context** with output you won't keep.2627## Don't When2829- **Steps depend on each other** — B needs A's output. Delegating then blocking on it buys nothing but overhead.30- **It's one known lookup** — you know the file and symbol. Just read it.31- **The work is smaller than the dispatch cost** — spawning an agent to save five seconds loses.3233## Free Parallelism First3435Independent **tool calls in a single message run concurrently** — no subagent needed. Before36spawning anything, batch the handful of independent reads/greps into one message. Use subagents37when you need context isolation or genuine fan-out beyond a few calls.3839## The Host Budget4041Classify every unit of work before deciding how wide to go:4243| Class | Examples | How wide |44|---|---|---|45| **Cheap / read-only** | Read, Grep, Glob, search agents, analysis | Fan out — but cap ~5–8. More adds coordination churn, not speed. |46| **Heavy / compute** | build, compile, full test suite, install, render, containers, DB | Serialize, or cap to **≤ (cores − 2)**. Never run N full builds at once. |4748**Heuristic:** heavy jobs concurrent ≤ `nproc − 2`; cheap agents a flat ~5–8. When mixing, the49heavy class sets the limit — a single build can saturate the machine on its own.5051## Before a Wide Fan-Out52531. **Scout first.** Send *one* agent (or one check) to confirm the approach before launching54 twelve down the same dead end. Cheap insurance against expensive mistakes.552. **Know the machine.** `nproc` for cores; check current load. On a busy laptop, dial it down —56 your fan-out shares the host with the user's editor, browser, and running app.573. **Pipeline over barrier.** Don't make fast agents idle waiting for the slowest before *any*58 result moves on. Let each result flow to its next stage as it lands; wall-clock drops and59 fewer agents sit live at once.604. **Chunk huge lists.** 200 files is not 200 agents (a thundering herd). Batch into a handful of61 agents each handling a slice.6263## Craft Each Agent's Task6465A subagent starts blank — it does **not** inherit your context, so hand it exactly what it needs66and nothing it doesn't:6768- **Focused scope.** One domain per agent ("fix the abort tests in X"), not "fix everything." Broad scope loses the agent.69- **Self-contained.** Paste the error text, the file path, the relevant facts. Don't assume it saw your session.70- **Constraints.** Say what *not* to touch — "tests only", "don't refactor production code" — or it may reshape the world.71- **Named output.** Tell it what to return (a summary, a verdict, the patch). Its final text *is* the result you get back — vague ask, vague result.7273Dispatch all independent tasks **in one message** so they run at once. When they return: read each74summary, check the changes don't conflict, and run the full suite once to confirm they compose.7576## Parallel *Edits* Need Isolation7778Read-only fan-out is safe. **Concurrent edits are not** — two agents writing the same tree race and79corrupt each other. If parallel tasks mutate files, give each its own worktree, or partition so no80two touch the same file. When in doubt, parallelize the *reading/analysis* and serialize the *writing*.8182→ **REQUIRED SUB-SKILL:** Use **using-worktrees** for the isolation mechanics — including the83harness's built-in `isolation: "worktree"` flag, which creates and cleans up the worktree for you.8485## Common Mistakes8687- **One agent per item for hundreds of items.** Thundering herd. Chunk it.88- **8 parallel test suites on a 4-core laptop.** Swap death; slower than running them in twos.89- **Fanning out before the approach is proven.** Scout with one, then widen.90- **Delegating a dependent step, then blocking on it.** No parallelism gained — just dispatch overhead.91- **Maximizing agent count.** Wall-clock is set by the slowest chain and the host's limits, not by how many agents you launched.
atgreen