Orchestration & Agent Teams

A single agent in a single context window has two limits: its work is serial, and the window fills up. Orchestration is how you get past both. You spread independent work across agents that run in parallel, and each one works in its own fresh context. The common refrain right now is that single-agent workflows are giving way to teams, but "team" is three different tools depending on how the agents need to coordinate.

The three tools

Tool	Coordination	Communication	Reach for it when
Subagents	hub and spoke	you delegate, one summary comes back	fan out independent work, or isolate a noisy task
Agent teams	peers	agents message each other, share a task list	collaborative work where they must coordinate live
Workflows	scripted	deterministic fan-out with verification stages	repeatable multi-stage pipelines (review, migrate, research)

Pick by coordination, not by size. Ten subagents doing isolated searches are still hub-and-spoke. Two agents that have to agree on an interface are a team.

The building blocks

Subagents. Separate Claude instances launched from your session, each in its own context window. The model is delegate-and-return: the subagent works in isolation and only its final summary comes back, so the brief in and the summary out are the whole interface. It inherits CLAUDE.md, skills, and MCP servers, but not your conversation history. Launch several in one message to run them in parallel. Whether a subagent can spawn its own depends on the surface (see Nesting depth below). See Subagents.

Agent teams. Full peer sessions that message each other and share a task list, rather than reporting up to one orchestrator. Real peer protocols have emerged for running a team on one repo: a shared append-only channel, git worktrees per agent, explicit ownership boundaries, and an acknowledge-and-merge discipline so two agents do not stomp the same files. Use this only when agents genuinely need to coordinate; the protocol is overhead you do not want for simple fan-out. See Agent teams.

Workflows. Deterministic, scripted orchestration. Scripts persist at .claude/workflows/<name>.js, are invoked by name with args, compose one level deep, and are cron-schedulable (the bridge to Loops & Autonomy). The primitives are agent (one subagent, optionally with a schema for structured output), parallel (a barrier, all results together), and pipeline (no barrier, each item flows through all stages independently). Default to pipeline; reach for a parallel barrier only when a stage genuinely needs every prior result at once. See Workflows.

Decide: which one?

1. Independent work, you just need the results back? → subagents, launched in one message.
2. Agents must coordinate live or share evolving state? → an agent team with a shared channel and ownership boundaries.
3. A repeatable multi-stage pipeline with verification? → a workflow.
4. A single lookup in a file you already know? → don't orchestrate at all. Delegation has overhead; read it inline.

Recipes

1. Fan-out search. Delegate "find where X happens" and multi-file sweeps to Explore subagents; keep the conclusions, not the file dumps. Launch them in one message so they run concurrently.

2. Plan then build. Use the Plan agent to research and return a step-by-step plan, then execute (yourself or via a general-purpose agent). Keeps planning context out of the build.

3. Parallel streams. Genuinely independent tracks, one agent per track, all launched in a single message. Wall-clock drops to the slowest single track, not the sum.

4. A peer team on one repo. Spin up agents in their own git worktrees with clear ownership boundaries and an append-only coordination channel. Each owns its files; merges go through an acknowledge step. This is the only setup where two agents safely touch one repo.

5. A scripted review workflow. pipeline over review dimensions: each dimension finds candidates, then each finding is adversarially verified by independent skeptics before it survives. The verification stage runs as soon as a dimension finishes, not after all of them.

Failure modes

• Over-delegation. A subagent for a single lookup costs more than it saves. Delegate breadth, not one fact.
• Assuming shared context. Subagents do not see your history, and team members do not see each other's unless you give them a shared channel. Coordination has to be explicit.
• More agents, slower run. A parallel barrier waits for the slowest agent, wasting the fast ones. Use pipeline unless a stage truly needs all prior results together.
• Silent caps. A fan-out that quietly keeps only the top N reads as "covered everything" when it did not. Log what was dropped.
• Designing too deep. Nesting depth depends on the surface (see Nesting depth below). Default to one level and let the top coordinate, rather than building agents that build agents, unless you are on a surface that supports deeper nesting.

Quick reference

You want	Reach for	Key form
Isolated fan-out, results back	subagents	launch several in one message
Plan without polluting build context	Plan agent	delegate, then execute
Live coordination on one repo	agent team	worktrees + ownership + ack/merge
Repeatable multi-stage pipeline	workflow	pipeline by default, parallel for barriers
Detached or scheduled fan-out	workflow + cron	.claude/workflows/<name>.js

Nesting depth

Claude Code 2.1.172 (June 2026) added nested subagents in the Agent SDK: a foreground subagent can spawn its own at any depth, while a background subagent is capped once it is five levels below the main agent. The interactive CLI Agent tool and the Workflow tool still nest one level only. So whether a subagent can spawn a subagent depends on the surface: yes in the SDK, no in interactive sessions and workflows. Default to shallow nesting and go deeper only where the surface supports it.