Claude Code Agent Orchestration Patterns

Agent orchestration is the layer above subagents and agent teams: deciding which topology a task needs, what that choice costs, and which controls keep a multi-agent run honest. Claude Code gives you the primitives. It does not decide when delegation helps or when it quietly makes things worse.

Agent orchestration: What You’ll Learn

This guide covers agent orchestration as a design decision rather than a feature walkthrough. You will learn the two topologies Claude Code supports, the three coordination patterns built on top of them, what each one costs in tokens, and the governance controls that separate a reliable multi-agent run from an expensive one that produces confident nonsense.

It assumes you already know how to define a subagent and how to start a team. If you do not, read the subagents guide and the agent teams guide first. This page picks up where those leave off. The mechanics are covered there; the judgment is covered here.

Hierarchical delegation versus peer to peer teams

Every multi-agent setup in Claude Code is one of two shapes, and almost every agent orchestration mistake traces back to picking the wrong one.

Subagents are hierarchical. One orchestrator sits at the top and spawns focused children. Work flows down, results flow up, and that is the entire communication graph. Two subagents running at the same time cannot talk to each other. They cannot even observe that the other exists. Each one gets a task, works in its own context window, and returns a summary to the parent that spawned it.

That isolation is what makes the pattern useful. The orchestrator’s context stays clean because the search results, file dumps, and log output all stay inside the child. What comes back is a conclusion. The transcript stays behind. The official subagents documentation frames this as the primary reason to delegate at all.

Agent teams are peer to peer. There is no orchestrator. Several Claude instances share a task list on disk, and each teammate reads the list, claims work that is not yet taken, marks it in progress, does it, writes the result back, and looks for the next item. Coordination happens through the file. No parent process is involved.

The practical difference: teammates can see each other’s output. When one teammate discovers something that changes how the others should work, it lands in the shared file and everyone picks it up. In the hierarchical model that discovery is trapped inside one child until it returns to the parent, and by then its siblings have already finished doing the wrong thing.

Both are configured the same way, as markdown files with YAML frontmatter. What differs is the topology they run under. This matters because it means agent orchestration cannot be solved by editing a file. The same definitions produce different systems depending on how you run them.

Agent teams are experimental as of July 2026 and sit behind an environment variable, so treat their exact behavior as subject to change in a way the subagent interface is not. Build your governance around the topology rather than around a specific flag.

The map reduce pattern

Map reduce is the default hierarchical pattern and the one most agent orchestration should start with. The orchestrator decomposes a job into independent units, spawns one subagent per unit, and combines the returned results.

It fits when the units genuinely do not depend on each other. Auditing twelve services, summarizing forty documents, running the same migration across sixty files: each unit can be done in isolation and the combination step is mechanical.

The pattern degrades the moment units start depending on each other. If subagent seven needs a decision that subagent three made, the orchestrator has to serialize them, and you have paid for parallelism you cannot use. When you find yourself sequencing the map phase, the work was never a map reduce.

The reduce step deserves more attention than it usually gets. Combining structured results is cheap. Combining twelve free-text summaries means the orchestrator re-reads twelve blocks of prose, which reintroduces exactly the context bloat delegation was supposed to prevent. Define the return shape before you spawn anything.

A useful test for whether a job is really a map: could you shuffle the units into any order without changing the output? If reordering matters, there is a dependency you have not made explicit, and the pattern will surface it as an inconsistent result rather than an error.

The scrum pattern

Scrum is the peer to peer pattern. Teammates coordinate through a shared task list rather than through a parent, and dependencies live in the file itself rather than in an orchestrator’s head.

The mechanics are simple. Each teammate reads the list, finds an unclaimed item, marks it in progress so nobody duplicates it, works, writes the result back, and repeats. There is no central scheduler. Load balances itself, because a teammate that finishes early just takes the next available item.

What makes this worth the cost is cross visibility. In a debugging session with four competing theories, a teammate that rules one out writes that to the shared file and the others stop pursuing it. In a research task, a source that one teammate finds authoritative becomes available to everyone immediately. The hierarchical model has no lateral channel to carry any of this.

The failure mode is drift. With no orchestrator checking outputs, nothing structurally validates what teammates write back. A teammate that misreads the task writes a confident wrong result to the shared file, and the others build on it. Scrum without an explicit validator is the riskiest agent orchestration configuration described on this page.

The shared file is also the thing to design deliberately. It is the entire coordination surface, so vague task descriptions in it produce vague work. Write items that a teammate can claim and finish without asking a question, because there is nobody to ask.

Claiming is worth thinking about too. Two teammates that read the list at the same moment can both see the same item as unclaimed and both start it. The waste is usually small, but it grows with team size and with how long each item takes. Keeping items short reduces the window in which a double claim can happen, and it makes a duplicated item cheap when one does.

The hybrid pattern

Hybrid splits a job by phase. The orchestrator plans and decomposes, hands the parallel execution phase to a team, then takes the results back and synthesizes.

This works because planning and execution have different shapes. Decomposition is a single coherent judgment that one context should make. Execution is parallel work that benefits from teammates seeing each other. Synthesis is again a single judgment. Forcing all three into one topology means two of them run in the wrong shape.

The cost is coordination overhead at each handoff, and hybrid inherits the token profile of its most expensive phase. Reach for it when a job has genuinely distinct phases, not because it sounds more sophisticated than the alternatives. Most jobs that look like hybrid candidates are map reduce jobs with an untidy planning step.

What each topology actually costs

Delegation is not free, and the multipliers are large enough to change which approach is correct.

The Hatchworks analysis of Claude sub-agents and agent teams reports subagent runs at roughly four to seven times the token cost of a single session, and agent teams at roughly fifteen times. These are reported observations from that analysis rather than figures published by Anthropic, so treat them as an order of magnitude rather than a precise rate. Your own numbers will move with task shape and how much context each agent loads.

The direction is what matters. A fifteen times multiplier is only justified when cross visibility actually improves the output. If teammates never read each other’s results, you paid team prices for map reduce work. This is an expensive mistake and it hides well, because the work still gets done, just at roughly three times the cost it needed.

The multiplier also has a floor effect. Every spawned agent pays a startup cost: it loads its system prompt, its instructions, and enough context to be useful. For a task that takes the main session ninety seconds, that overhead exceeds the work. Delegation earns its cost on tasks that are long, repetitive, or context heavy, not on quick ones.

Cost is also why agent orchestration decisions should be revisited rather than set once. A pattern that made sense when a job had forty independent units may be indefensible when the job shrinks to four.

Governance controls that keep a run on the rails

Four controls do most of the work of making multi-agent runs reliable. None are enabled by default, which is why agent orchestration takes ongoing judgment.

Minimum permission tool lists. Declare only the capabilities an agent needs. A reviewer needs to read files and inspect a diff. It does not need write access, and giving it write access means a reviewer can silently become an editor.

name: security-auditor
description: Audits one service for known vulnerability classes and reports findings
tools: [Read, Grep, Glob, Bash(git diff:*)]

The narrower list buys predictability as well as safety. An agent that cannot write cannot produce a surprising change, so its output is always something you review rather than something you discover later.

Validation gates. Something must check agent output before it is treated as true. In the hierarchical model the orchestrator does this by construction, because results pass through it. In a peer team nothing does, so you have to add a validator teammate whose only job is checking other teammates’ work. A validator that also does production work will approve its own output.

Structured output contracts. Specify the return shape in the agent’s system prompt rather than accepting prose. Structured results can be counted, filtered, deduplicated, and compared without another model pass.

{
  "service": "billing-api",
  "findings": [
    { "severity": "high", "file": "src/auth.ts", "line": 42, "issue": "token expiry check is off by one" }
  ],
  "blocked": false
}

The blocked field matters more than it looks. It gives the agent a way to say it could not finish, which is the difference between an empty findings list meaning “clean” and meaning “I never ran”. Silent empty results are dangerous precisely because they look like success.

Obstacle reporting. Instruct agents to report blockers rather than fix them. An agent that hits a missing dependency and installs it has left its scope, and now its result is entangled with a change nobody reviewed. Reporting keeps the decision with whoever can see the whole picture.

These four controls compose. Narrow tools limit what can go wrong, structured output makes results checkable, validation gates check them, and obstacle reporting keeps agents inside the boundary the first control drew.

Choosing a topology

Three questions settle most cases.

Default to a single session. Move to subagents when context pollution is the actual problem, meaning intermediate output you will never reference again is crowding out work you care about. Move to agent teams only when the second row is a genuine yes. Sound agent orchestration is mostly the discipline of not escalating past what the task needs.

A Worked Example

Take a concrete job: audit a repository for security issues across twelve services. Here is what the same work looks like under each topology.

Run it in a single session and it works, for a while. The model reads service one, finds two issues, moves to service two. By service nine the context holds nine services of file contents and the findings from the early services have been summarized into vagueness. The last three audits are measurably worse than the first three, and nothing in the output tells you that. Consistency, more than speed, is what delegation actually buys you here.

Run it as map reduce and each service gets a fresh auditor with an identical prompt. Service twelve is audited as carefully as service one, because the twelfth auditor has never seen the other eleven. Each returns structured findings. A separate validator subagent then checks each finding against the actual file before it reaches the report, which matters because a fresh auditor with narrow context produces confident false positives more often than one that has been reading the codebase for an hour.

The orchestrator reduces twelve structured results into one report. Total cost is roughly five times the single session, and the output is more uniform.

Now suppose the third auditor finds a vulnerability class that is not service specific: a shared authentication helper that mishandles token expiry, used across the codebase. Under map reduce that finding is trapped. Auditors four through twelve were spawned with the original prompt and know nothing about it. You get one report of the shared bug, in one service, and eleven audits that never looked for it.

Run it as a team and that changes. A teammate that finds the shared helper bug writes it to the task list as a new pattern to check. Every teammate that claims a service after that point checks for it. The finding propagates during the run rather than after it. Propagation during the run is what the fifteen times multiplier actually buys. If the audit has no shared patterns to find, you paid for it and got nothing.

For this job the team wins, because security issues cluster around shared code and cross visibility compounds. For a job with genuinely independent units, a translation pass over sixty files, map reduce wins and the team is waste. The shape of the task decides this. Good agent orchestration includes being willing to conclude that a plain session was sufficient.

Agent orchestration: Common Mistakes to Avoid

Most agent orchestration failures are not exotic. They are the same four errors, and each has a clear tell.

• Over delegating. Spawning agents for work the main session would finish faster. If the task takes under a minute inline, the startup overhead exceeds the work.
• Relying on automatic delegation. Matching a task to an agent by description alone is unreliable. Name the agent explicitly when it matters.
• Running a peer team with no validator. Nothing checks teammate output structurally, so a confident wrong result becomes shared context for everyone else.
• Granting broad tool access by default. An agent with write access it never needed is an agent that can surprise you, and the surprise usually surfaces after the run.

Agent orchestration: Best Practices

• Start with a single session. Escalate to subagents only when context pollution is the real, observed problem.
• Define the return shape before spawning anything. Structured output makes the reduce step cheap.
• Give every agent the narrowest tool list that lets it finish its job, and nothing beyond it.
• Put a validator between agent output and anything that consumes it, especially in peer teams.
• Invoke agents by name rather than trusting description matching to route work correctly.

Agent orchestration: Frequently Asked Questions

Can a subagent spawn its own subagents?

Treat it as unavailable. Nesting multiplies cost unpredictably and removes the orchestrator’s visibility into what is running. Restrict which agents a coordinator can spawn instead.

Why does automatic delegation pick the wrong agent?

Routing depends on matching your request against agent descriptions, which is inherently fuzzy. Write sharp, specific descriptions, and name the agent explicitly when the choice matters.

How many agents should run in parallel?

Fewer than you think. Concurrency is capped by your machine anyway, and every extra agent adds cost and review burden. Scale to the number of genuinely independent units.

Do agent teams share one context window?

No. Each teammate has its own. They share a task file on disk, which is why coordination is explicit: anything a teammate should know has to be written to that file.

When is a single session still the right answer?

Whenever the work is sequential, short, or needs one coherent judgment throughout. Most tasks fit here. Delegation is the exception you reach for when a specific problem calls for it.

Agent orchestration comes down to three judgments: pick the topology the work actually has, pay the multiplier only when cross visibility earns it, and never let agent output reach a decision without a validation gate in front of it.