Multi Agent

Multi-Agent Coordination — WrongStack

What this is

A leader delegates narrow subtasks to workers, collects structured results, and synthesizes one unified output. Parallelism buys wall-clock time on work that is genuinely independent. It costs a multiple of the tokens and it costs coherence — every worker starts blind, and anything the leader forgets to put in the brief simply does not exist for that worker.

So the bar is not "could this run in parallel". The bar is "will this finish meaningfully faster or better in parallel, given that I have to write N briefs and reconcile N results".

"It won't fit in one context" is no longer a reason to fan out. With windows running from 200K to 1M, work that used to require splitting now loads comfortably into a single agent — and a single agent that sees everything produces better cross-cutting analysis than five that each see a fifth. Fan out for wall-clock time and for genuinely independent attention. Do not fan out because of a size limit you last measured on a smaller model; check whether the whole thing simply fits first.

The decision gate

Walk these in order. A single no means do the work in one agent.

1. Plural targets? More than one file, package, module, or question. A single atomic task is not a fleet.
2. Independent? Can target B be worked on without target A's output? If there is a sequential dependency, either chain it inside one agent or use the fleet pattern with explicit hand-off — do not one-shot fan it out.
3. ≥5 tool calls per subtask? Below that, spawn overhead exceeds the benefit. Read three small files yourself.
4. No shared mutable state? Subagents share nothing — no memory, no session state, no variable scope. Work that needs a common scratchpad stays local.
5. Can each subtask be described in a paragraph? If a target needs three pages of context to explain, the leader is the one who understands it. Keep it.

✅ Good fits

• "Audit these 50 files for X" — one worker per chunk of 5–10 files
• "Run tests in all 12 packages" — parallel pnpm test per package
• "Refactor 3 independent modules" — one worker each
• "Review this PR + check the tests + check the docs" — three parallel workers

❌ Avoid

• Single atomic task under 5 tool calls — overhead exceeds benefit
• Tasks requiring shared state — subagents have isolated contexts
• Long sequential dependencies — chain within one agent, don't fan out
• Exploratory work where the next step depends on what the last step found

Sizing the fleet

• Chunk by target, not by worker count. 50 files → 5–10 workers of 5–10 files each. Not 50 workers, and not 2 workers of 25.
• Practical ceiling per turn scales with the leader's window — roughly 10 workers at 200K, up to ~25 at 1M. The limit is not whether the results fit; it is that synthesis quality falls off well before the context does. Twenty-five reports is already more than one pass can reconcile carefully. For larger sets, run sequential waves and synthesize incrementally between them.
• Uniform chunks. One worker with 30 files and four with 2 means the fleet finishes when the slow one does, and the big one is the one that exhausts.
• Same role per wave where possible. Mixed roles in one batch are fine, but mixed scopes make the results hard to reconcile.

Writing the task brief

This is where fan-outs succeed or fail. The worker sees the brief and nothing else — not the conversation, not the leader's plan, not what sibling workers are doing. Assume total amnesia.

Every brief carries five things:

1. Exact scope — literal paths or globs, never "the auth code"
2. The specific question — what to look for, not "review this"
3. Definition of done — what makes the subtask complete
4. Return format — what fields the leader needs back for aggregation
5. Boundaries — what NOT to touch, especially whether to edit or only report

// ✅ Good — narrow, focused, self-contained
batch_tool_use([
  { tool: "delegate", input: { task: "Audit auth/session.ts for null-deref bugs. Report each as file:line + severity (critical/high/medium/low) + one-line fix. Do not edit files.", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/token.ts for null-deref bugs. Report each as file:line + severity + one-line fix. Do not edit files.", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "Audit auth/refresh.ts for null-deref bugs. Report each as file:line + severity + one-line fix. Do not edit files.", role: "bug-hunter" }},
])

// ❌ Too broad — will exhaust budget
{ task: "Audit all packages for bugs" }

// ❌ No scope, no format — results won't aggregate
{ task: "Look at the auth stuff and tell me if it's ok", role: "bug-hunter" }

// ❌ Role mismatch
{ task: "Write documentation for the API", role: "bug-hunter" }

Asking every worker for the same result shape is what makes deduplication and prioritization possible later. Decide the shape before dispatching.

Passing artifacts between workers

Subagents share nothing, so if worker B needs worker A's output the leader must move it: either inline it in B's task description, or have A write to a file and give B the path. There is no third option — no implicit inheritance, no shared scope.

Roles

Match the role to the task. A bug-hunter writing docs, or a refactor-planner running a security audit, produces confident output shaped by the wrong priorities — which is worse than no output, because it reads as authoritative.

Execution patterns

One-shot fan-out — all workers in one turn

Use when subtasks are fully independent.

batch_tool_use([
  { tool: "delegate", input: { task: "...", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "...", role: "bug-hunter" }},
  { tool: "delegate", input: { task: "...", role: "bug-hunter" }},
])

Dispatch the whole batch in a single turn. Firing them one at a time serializes the fleet and throws away the only thing parallelism was for.

Each delegate call returns at once with a delegation id; the workers run in the background and every result is delivered to the leader automatically as a [DELEGATION RESULT] block as its worker finishes. Do not poll or re-await them — keep working, or end the turn; on hosts that support it a new turn starts when results arrive. Leave wait unset for fan-out: wait: true is for a single short task whose verdict gates the very next step.

Fleet pattern — stateful, multiple turns

Use when there are dependencies (worker 2 needs worker 1's artifact), or when you want to reuse workers and decide yourself when results are collected.

spawn N subagents → assign_task per subagent → await_tasks

Keep the dependency chain shallow. A four-deep chain of workers is a sequential program with extra failure modes; write it as one agent instead.

Reading results

Check stopReason on every result — never assume a worker finished.