Subagent orchestration

Decomposing a development task across multiple Claude Code subagents that run independently under a coordinating orchestrator, with explicit context isolation and result aggregation.

How it works

The lead agent plans, scopes each piece, dispatches it to a worker subagent, and reconciles the returns; the lead never executes the work itself. Each worker holds its own context window and its own permission scope, so anything that worker reads, hallucinates, or fails on stays inside that worker’s lane. What returns to the lead is a digested finding, not the worker’s intermediate token stream, which keeps the synthesis short enough to review end-to-end.

Why it matters

Context isolation is what makes parallel agent work trustworthy on production code. Three single-context failure modes stay contained under orchestration: a runaway exploration cannot flood the shared window because there is no shared window, a hallucination in one branch cannot reach the others because the branches cannot see one another, and an over-broad permission scope cannot bleed across tasks because each lane is scoped at dispatch. The pattern has a cost: dispatch and reconciliation overhead is real, so a task small enough for one context window pays a tax under orchestration that the isolation does not earn back.

In practice

A research wave fans out: each worker subagent takes one source set under read-only access, investigates inside its own context window, and returns a distilled finding to the lead. The lead reconciles those findings without ever holding the union of sources in a single window, so a worker that veers off the source set fails inside its lane rather than corrupting the synthesis.

Practical considerations

Permission scoping is set per dispatch rather than inherited from the orchestrator: a worker that does not need write access does not get it, and a worker that surprises with an unexpected action can only reach what its dispatch scope allowed. The compression of each worker into a single digested finding is what lets the orchestrator continue past the fan-out without inheriting the union of intermediate token streams; without that compression the lead would pay the same context cost as a single-context agent. The failure-mode taxonomy, the when-not-to-orchestrate sizing rule, and the operational anti-patterns are treated in depth in the Subagent Orchestration in Production cornerstone.

Defined by Ready Solutions AI