Agent orchestration patterns in 2026: subagents, teams, and pipelines

Claude Code’s own documentation sizes its batch-migration example at 2,000 Python files, and its team guidance states that token costs scale linearly with the number of teammates, each consuming tokens in its own context window. A five-teammate team therefore equates to roughly five single-session budgets spending at once; the coordination overhead is paid whether or not the parallelism helps. After a year of running coding agents against production systems, a year in which I built several orchestrators of my own and later deleted them, my strongest conclusion is that orchestration is a question of coordination cost rather than framework choice. Most tasks belong on the lowest coordination level that works.

This guide maps the five levels as they exist in mid-2026, using Claude Code’s mechanisms as the reference implementation (currently the most complete set), together with the failure modes I have paid for personally.

The five levels

Ordered by coordination cost, the levels are: (1) a single agent with good practices, the default; (2) subagents, for side work that would flood the main context; (3) headless pipelines, for batch work over many items; (4) parallel sessions in git worktrees, for independent workstreams; and (5) agent teams, for parallel exploration with communication between the workers.

Level	Mechanism	Coordination cost	Use when
1	One agent, good practices	none	default, most tasks
2	Subagents	low	side work floods main context
3	Headless pipelines	low, deterministic	batch work over many items
4	Parallel sessions / worktrees	medium, manual	independent workstreams
5	Agent teams	high	parallel exploration with cross-communication

The rule I hold myself to is to move up a level only when the current one demonstrably fails, and never because parallelism sounds faster. Token costs scale linearly with the number of agents, while coordination failures scale worse than linearly.

Level 2: subagents for context isolation

The subagent documentation frames the mechanism precisely: use one “when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary.”

The primary value of subagents is context isolation. Each subagent runs in its own context window with its own system prompt, tool allowlist, and, optionally, a cheaper model such as Haiku. Exploration burns thousands of tokens reading files; a subagent spends those tokens in a disposable window and hands back three paragraphs.

I use them in two recurring ways. Firstly, for research before implementation: “use a subagent to investigate how auth handles token refresh” keeps the main session clean for the actual change. Secondly, for fresh-context review: a reviewer subagent that sees only the diff and the acceptance criteria, without the reasoning that produced the change. The implementing session is biased toward the code it has just written; a fresh context carries no such bias. (More on this gate in agentic coding best practices.)

A custom subagent definition (a markdown file with a description, a tool allowlist, and a model choice) becomes worthwhile the second time the same kind of worker gets spawned. In addition, routing mechanical work to a faster model is the cheapest cost reduction available at this level.

Level 3: headless pipelines driven by a shell script

For batch work over many items (migrations, audits, bulk generation), the official guidance is plain: generate a task list, then loop the CLI (command-line interface) over it in headless mode. The documented example sizes such a batch at 2,000 Python files.

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

This plainness is deliberate: the control flow lives in a shell script, which is deterministic, resumable, and debuggable, while the model handles exactly one well-scoped item per invocation with scoped permissions.

This level taught me my most expensive orchestration lesson. I once built a parallel orchestrator that coordinated a dozen concurrent workers from inside a single agent session. It worked in demos and collapsed in production: session limits, lost state, workers dying silently. The replacement, which has run reliably since, is a queue with a state file, processed one item at a time and driven by a system scheduler (cron or launchd), with each run resumable from the state file. When an orchestrator must survive for hours, the loop belongs in an external scheduler rather than in a model’s context window.

Two additions make a pipeline production-grade: (1) structured returns, instructing “Return OK or FAIL” (or JSON via --output-format json) so the script can branch and retry; and (2) a small trial first, since the same guidance recommends refining the prompt on the first 2-3 files before running the full set. Every batch failure I have had traced back to skipping the trial.

Level 4: parallel sessions in git worktrees

When workstreams are genuinely independent, for example two unrelated features or two repositories, the approach is to run multiple full sessions, each in its own git worktree so that edits cannot collide. The same page describes the writer and reviewer pair: one session implements, a second session with fresh context reviews, and the review comes back unbiased because the reviewer “won’t be biased toward code it just wrote.”

In contrast to an agent team, nothing coordinates these sessions automatically; the discipline is manual git hygiene. Each session commits its own files immediately and never ends dirty. I enforce that with hooks now, because uncommitted work in a multi-session tree is work waiting to be overwritten, a lesson I also learned the expensive way.

Level 5: agent teams

Agent teams are the newest and heaviest mechanism, experimental and opt-in via the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable. One session becomes the lead and spawns teammates that are full independent sessions, coordinated through a shared task list (file-locked claiming, dependency-aware) and a mailbox for direct teammate-to-teammate messages.

The structural difference from subagents matters: subagents “report results back to the main agent only,” while teammates “message each other directly” and self-claim work. A team becomes appropriate when the value lies in the workers challenging each other’s findings, and the documentation’s strongest use case, competing-hypotheses debugging, is built on exactly that:

“Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other’s theories, like a scientific debate.”

The mechanism this exploits is anchoring: a single agent finds one plausible explanation and stops looking, and sequential investigation gets biased toward the first theory explored. Independent investigators attacking each other’s theories surface the explanation that survives scrutiny. The same shape works for parallel code review with distinct lenses (security, performance, and test coverage).

The costs, however, are documented just as plainly and match my testing: teams “use significantly more tokens than a single session,” token costs scale linearly with the number of teammates, and the recommended starting range is 3-5 teammates with 5-6 tasks per teammate; for 15 independent tasks, the guidance suggests starting with 3. The experimental edges are real: no session resumption of in-process teammates, task status that can lag, one team per session, and no nested teams. It should be noted that teams compose with the enforcement layer: hooks such as TeammateIdle and TaskCompleted can reject an agent going idle or a task closing until a quality script passes, placing deterministic gates around non-deterministic workers.

Cross-model consensus

One orchestration pattern sits outside the single-vendor levels: running agents from different vendors against each other. I keep both major coding agents wired to the same repository (one instruction file drives both), and for irreversible batch decisions I require independent models to agree before an action commits. Disagreement drops the item to a human queue.

The reason this seems to work is statistical: two models trained by different labs are likely to have differently distributed errors, so same-model teammates share blind spots while cross-vendor agreement is stronger evidence. I treat that as a working hypothesis rather than a measured fact; a tally of how often cross-vendor disagreement caught a real error, against how often it was noise, would settle it. No framework markets the pattern, since it spans vendors.

Anti-patterns from my own logs

Five anti-patterns account for most of my orchestration failures.

1. Parallelizing same-file work. The team documentation states that two teammates editing the same file leads to overwrites, and my git reflog confirms it. Overwrites are avoided by partitioning on file ownership, and work that cannot be partitioned should not be parallelized.
2. Orchestrating long-running loops inside a session. A context window does not persist across session limits, so it cannot reliably drive a job that must survive for hours. Long-running loops belong in an external scheduler with a state file, as described under level 3.
3. Adding agents to a task that is failing for non-parallel reasons. A task failing from vague requirements fails harder with five agents amplifying the vagueness. The specification has to be fixed before the task scales.
4. Leaving teams unattended. The documentation phrases it politely: “letting a team run unattended for too long increases the risk of wasted effort.” In my testing the waste is mostly tokens spent on work that later gets discarded. Check in, steer, and synthesize early.
5. Skipping the sequential baseline. If I cannot articulate why one agent with good practices cannot do the task, the task is not ready for orchestration.

Choosing a level

Side research clutters my session         → subagent
Same operation over 50+ items             → headless pipeline + scheduler
Two unrelated features this afternoon     → worktrees, two sessions
Root cause unknown, theories compete      → agent team, debate prompt
Decision is irreversible                  → cross-model consensus + human queue
Everything else                           → one agent, better prompt

The pattern across all five levels is that verification loops, instruction files, and review gates make a single agent reliable, and multiplying agents only pays off once that reliability is in place. TODO, dated July 2026: rebuild my flaky-test triage as a three-teammate debate gated by a TaskCompleted hook, and count the tokens against the single-session baseline.

---

Changelog: 2026-06-27: first published. 2026-07-05: rewritten in the house register. 2026-07-06: removed four aphoristic short sentences and reframed the cross-model claim as a resolution-bound hypothesis.