04-11 Agent Teams vs Subagents: Differences, Enablement, Collaboration

What this unit solvesSubagents are one-shot executors: they are spawned, finish a task, return a result, and their context does not persist. Agent Teams are addressable, continuously running, collaborative agents: once created they retain an identity, can receive messages, exchange state with other agents, and pick up tasks. This unit clarifies the lifecycle differences between the two mechanisms, how each is enabled, and covers three collaboration patterns — orchestrator-worker, parallel independent work, and peer messaging — so you can choose the right tool and avoid over-engineering your automation flows.

Learning objectives

After completing this unit you should be able to:

Distinguish the fundamental difference between a Subagent (one-shot spawn, result returned to the caller, context does not persist) and Agent Teams (addressable, continuously alive, collaborative).
Describe how each is enabled and its current limitations (as of 2026-06, Agent Teams is an experimental feature).
Name the three collaboration patterns (orchestrator-worker, parallel independent work, peer messaging) and identify the scenario each fits.
Decide whether a given task calls for a Subagent, Agent Teams, or no multi-agent architecture at all.

1. Definitions and core differences

Anthropic introduced Agent Teams starting with Claude Code v2.1.32 [1]. It is a separate multi-agent layer from 04-5 Subagents: instead of “spawn, run to completion, disappear,” it means “multiple Claude Code instances organized as a team, sharing a task list, messaging each other, addressable by both the user and the lead.”

Naming clarificationThis unit uses Subagent for the mechanism described in 04-5 (one-shot, isolated context, returns a result), and Agent Teams for the “agent teams” / teammate concept in Anthropic’s documentation (persistent, addressable, collaborative). Subagents and Agent Teams are independent mechanisms that can coexist: a single session can have both simultaneously, each playing a different role.

Core differences (as of 2026-06, per the official agent teams section [1]):

Dimension	Subagent	Agent Teams
Lifecycle	Terminated when the task ends	Persists until the lead dissolves the team
Addressability	Not addressable (caller initiates spawn)	Addressable by lead, other teammates, and the user
Context	Fresh context on every spawn	Persists across turns (each teammate accumulates its own context)
Communication	Returns result to caller only	Bidirectional messaging via mailbox, shared task list, idle notification
Concurrency limit	Multiple spawns allowed within the same session	One lead manages one team at a time [1]
Nesting	Cannot spawn subagents	Teammates cannot spawn a team or other teammates [1]
Token cost	Lower (only the summary result returns to the caller)	Higher (each teammate holds a full context window)
Ideal for	One-shot subtasks, read-only queries, parallel work where results do not need to interact	Sustained collaboration, multi-round feedback, shared state, user intervention during the run

Connection to 01-4 Context EngineeringA Subagent is like “moving a big task to swap space” — the main RAM only sees the result. Agent Teams is “opening N independent RAM modules that can pass messages to each other.” The former saves context; the latter buys collaborative capability. Choosing the wrong one means either burning tokens without a result, or trying to save tokens by cramming multi-round dialogue into a single context window and watching output quality degrade.

2. How to enable each

2.1 Subagents (04-5 covers this in full)

Invoke explicitly from a session or a skill with Agent(<name>), or let Claude auto-delegate based on the description field. Subagent definitions live in .claude/agents/, the user-level ~/.claude/agents/, a plugin’s agents/ directory, managed settings, or the --agents CLI flag. The lifecycle is exactly: spawn, run the task, return the result, terminate.

2.2 Agent Teams

As of 2026-06, Agent Teams is an experimental feature, disabled by default [1]. To enable:

// .claude/settings.json or ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or set the environment variable before launching:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Once enabled, ask Claude in natural language to build a team:

I want to design a CLI tool that tracks TODO comments in a codebase.
Build an agent team and explore this from three angles: UX, technical architecture, and devil's advocate.

Claude will create the team, spawn teammates, have each explore independently, and then synthesize the results [1].

Current limitations of Agent Teams

Disabled by default; requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
In in-process mode, /resume and /rewind do not restore teammates; after resuming the lead may try to contact a teammate that no longer exists [1].
Task status can lag (a teammate that fails to mark a task completed blocks dependent tasks) [1].
One lead can manage only one team at a time; tear down the current team before starting a new one.
Teammates cannot spawn their own team or other teammates.
The lead is fixed and cannot be transferred after session start.
All teammates inherit the lead’s permission mode at spawn time; individual permissions cannot be set separately.
Split-pane mode requires tmux or iTerm2 (VS Code integrated terminal, Windows Terminal, and Ghostty are not supported) [1].

2.3 Display modes

Agent Teams supports two display modes [1]:

Mode	Setting	Behavior
in-process (default fallback)	`teammateMode: "in-process"`	All teammates run within the main terminal. `Shift+Down` cycles between them; you can send messages directly to any teammate.
split-pane	`teammateMode: "tmux"`	Each teammate gets its own pane. Requires tmux or iTerm2 + the `it2` CLI.

The default is auto: uses split-pane when launched inside a tmux session, otherwise falls back to in-process. To force a mode:

claude --teammate-mode in-process

Split-pane on Windows: psmux or WSL tmuxNeither tmux nor iTerm2 is Windows-native, so Windows users will land on in-process by default. Two paths exist for split-pane on Windows:

psmux: a Rust-based native Windows terminal multiplexer, compatible with existing .tmux.conf, no WSL or Cygwin required. Launch Claude Code inside a psmux session and teammates automatically open in separate panes. As of 2026-06 this is still a new project (version 0.1.x); evaluate its maintenance status before adopting it [4].
WSL tmux: install tmux inside WSL and run Claude Code from a WSL terminal. Split-pane behaves identically to native tmux, provided your project and toolchain are accessible on the WSL side.

2.4 Model selection

Teammates do not inherit the lead’s /model setting by default. To set a default teammate model: run /config inside Claude Code and select Default teammate model. Choosing “Default (leader’s model)” makes all teammates use the same model as the lead [1].

3. Collaboration patterns

3.1 Orchestrator-worker

A lead agent breaks down a task, then spawns multiple Subagents in sequence or in parallel, collects each result, and integrates them. Subagents are unaware of each other’s existence.

Lead: split this PR into three analysis tracks
  |-- spawn Subagent A (security)
  |-- spawn Subagent B (performance)
  +-- spawn Subagent C (style)
  collect three results, merge into one response

Agent Teams can implement this pattern too, but at greater cost. When Subagents are sufficient: each worker is independent, read-oriented, and its result can be merged; workers do not need to talk to each other.

3.2 Parallel independent work

Multiple Subagents process non-overlapping subtasks simultaneously (each operating on different files or modules); the main thread merges results at the end. The most common multi-agent pattern and the simplest to implement. Agent Teams can do this too, but adds unnecessary complexity. The criterion: workers do not need to communicate and results can be merged — Subagents are enough.

3.3 Peer messaging

Agent Teams communicate via mailbox, negotiating state across messages. Suited for workflows that require multiple rounds of feedback:

A reviewer sends comments back to a writer; the writer revises and sends back to the reviewer.
Multiple investigators each propose a hypothesis, challenge each other’s reasoning, and converge on a conclusion.
Multiple parallel exploration threads are finally integrated by the lead into a single synthesis.

Pattern selection examplesScenario 1: code review Three reviewers (security / performance / test coverage) each examine the same PR and return results. → Subagents are enough (results merge; no dialogue needed).Scenario 2: evaluating an open-source project A research-owner agent sends three Subagents to examine “code quality,” “community health,” and “licensing and maintenance.” Three results merge into a single recommendation. → Subagents are enough.Scenario 3: bug investigation with unknown root cause Spawn 5 teammates, each proposing one hypothesis, each challenging the others, each leaving behind evidence that survived the challenge. → Agent Teams add value (requires message exchange and a debate structure).Scenario 4: writer + reviewer iterating on a document draft Writer drafts, reviewer comments, writer revises, reviewer reviews again, multiple rounds until convergence. → Agent Teams (a Subagent dies after one round and cannot hold a multi-turn conversation).

4. Independent operation

4.1 When to let agents avoid each other

Subtasks with no shared mutable state (each reads different data, writes different files) → parallel independent work is the simplest and requires no synchronization mechanism. Implementation: each Subagent / teammate works in a separate worktree. Git worktrees are the physical isolation tool (see 04-5):

# create a separate worktree for each worker
git worktree add ../agent-A -b agent-A-branch
git worktree add ../agent-B -b agent-B-branch

4.2 When shared state is unavoidable

Task B’s input depends on Task A’s output → use sequential orchestration (B starts only after A finishes) or Agent Teams peer messaging; do not use parallel execution. Parallel work is especially fragile when dependencies exist: if A and B are both instructed to “read the same file and modify different sections,” the final merge will conflict. Map out dependencies first: if two tasks share mutable state, run them sequentially or let Agent Teams coordinate the exchange.

4.3 Strengthen the workflow with TeammateIdle / TaskCreated / TaskCompleted hooks

Agent Teams exposes three dedicated hook event points [1, see 04-6 Hooks]:

TeammateIdle: teammate is about to enter idle. Return exit 2 to give feedback and keep it working.
TaskCreated: a task is being created. Return exit 2 to block creation.
TaskCompleted: a task is being marked complete. Return exit 2 to reject completion and give feedback.

These three events are the right places for “teammate collaboration quality gates”: teammate finishes writing code but hasn’t run tests and is about to go idle? Block with TeammateIdle. Teammate marks a task complete but the commit message doesn’t follow team conventions? Reject with TaskCompleted.

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-tests.sh"
          }
        ]
      }
    ]
  }
}

5. Cost and complexity

5.1 When not to parallelize

Parallel execution adds extra context cost and coordination complexity. If subtasks depend on each other, or if integrating results costs more than the decomposition saves, run sequentially. Three cost-evaluation questions:

Are the subtasks truly orthogonal? Shared input, cross-reads and cross-writes, shared mutable state → not orthogonal; parallel execution will actually be slower.
Is integrating the results manageable? If three results contradict each other and require extensive secondary coordination → the gains from decomposition disappear.
Does the speedup from parallelism offset the extra token cost? 5 Haiku workers vs 1 Sonnet run end-to-end: 5 workers burn 5x context; 5x speedup is the theoretical ceiling. Real-world speedup is often only 2-3x (due to communication overhead, synchronization, and idle time).

5.2 Model selection

Worker agents should use the cheapest model available (Haiku); only the main orchestrator or lead needs Sonnet or Opus reasoning capability (see 04-5). Agent Teams does not inherit the lead’s model by default ([1] section 2.4); explicit assignment is required to control costs:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Alternatively use /config to set the default teammate model to a Haiku-class model.

5.3 Known limitations

Agent Teams is an experimental feature. Officially documented limitations [1]:

In in-process mode, resume does not restore teammates.
Task status can lag.
Shutdown can be slow (teammates finish their current tool call before stopping).
One lead can manage only one team.
No nesting.
Lead is fixed and cannot be transferred.
Permission mode is decided at spawn time; it cannot be changed after the team starts.
Split-pane mode requires tmux or iTerm2.

CLAUDE.md works normally for teammatesAnthropic explicitly states that teammates read CLAUDE.md as project-level guidance [1]. This is the most direct way to govern teammate behavior. Put cross-teammate conventions in CLAUDE.md rather than relying on the lead to explain them every time.

6. Tool comparison

Concept	Anthropic Claude (primary)	OpenAI	Google	GitHub Copilot	Cursor (brief)
One-shot sub-agent	Subagent (`Agent(<name>)` tool) [04-5]	Configuration-based [needs source verification]	Configuration-based [needs source verification]	Configuration-based [needs source verification]	Configuration-based [needs source verification]
Persistent / addressable agent	Agent Teams (v2.1.32+, experimental) [1]	Swarm / Assistants (similar concept) [needs source verification]	Configuration-based [needs source verification]	Configuration-based [needs source verification]	Configuration-based [needs source verification]
Shared task list	Yes (`~/.claude/tasks/<team>/`) [1]	Configuration-based	Configuration-based	Configuration-based	Configuration-based
Inter-agent messaging	Yes (mailbox + `SendMessage`) [1]	Configuration-based	Configuration-based	Configuration-based	Configuration-based
Teammate hook events	TeammateIdle, TaskCreated, TaskCompleted [1, 04-6]	N/A	N/A	N/A	N/A
Display modes	in-process / split-pane (tmux / iTerm2) [1]	Configuration-based	Configuration-based	Configuration-based	Configuration-based
Physical isolation	`isolation: worktree` ([04-5])	Environment layer	Environment layer	Environment layer	Environment layer

Naming and boundaries

Agent Teams (v2.1.32+) is an experimental feature, disabled by default; enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 [1].
For OpenAI, GitHub Copilot, and Cursor, the specific multi-agent mechanisms follow each vendor’s current official documentation; entries marked “needs source verification” should be confirmed.
Cursor is a third-party IDE (Anysphere); this Playbook only covers it briefly in one column.

Hands-on exercises

Run each of the three patterns once (20 minutes)

Orchestrator-worker (Subagent): in your current project, use three Subagents in parallel to review from security, performance, and test-coverage angles. Observe the cost of integrating three results in the main thread.Parallel independent work (Subagent): have three Subagents each refactor a different module. Observe whether worktree isolation turns out to be necessary.Peer messaging (Agent Teams — first enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1): build a team of 3 teammates and have them each propose a hypothesis about an unfamiliar bug, then challenge each other. Observe whether token cost is noticeably higher than the Subagent patterns above.

Strengthen the workflow with a hook (10 minutes)

Add a TeammateIdle hook to .claude/settings.json, switch to tmux mode with /teammateMode (or stay in in-process), and verify the hook fires.

Common pitfalls

Anti-pattern list

Designing dependent subtasks as parallel work: integration requires extensive secondary coordination and ends up slower than a sequential run. Map dependencies first using 01-5 Workflow Engineering.
Agent Teams message loops without a termination condition: leads to infinite message exchanges or silent deadlock. Every message exchange must have an explicit exit condition (accept / reject / escalate).
Using the strongest model for every agent: ignores the fact that worker tasks are fine on Haiku, and lets cost spiral. Workers use Haiku; the Lead uses Sonnet/Opus.
Treating Agent Teams like threads: Agent Teams are full Claude Code instances with a complete context window, full tool access, and full permissions — not “cheap Subagents.” Expect their token usage to match that of an independent session.
Forgetting that CLAUDE.md applies to teammates: teammates do not inherit the lead’s conversation history, but they do read the project’s CLAUDE.md [1]. Write cross-teammate conventions into CLAUDE.md; do not rely on the lead to re-explain them every run.
Using Agent Teams for small tasks: a 5-line grep is a Subagent job; teams are designed for collaborative, multi-round work. Starting with 3 teammates is over-engineering [1].

Self-check

The bar for passing this unit

Can you produce a table showing how Subagents and Agent Teams differ across lifecycle, addressability, communication mechanism, and token cost?
Can you decide which mechanism fits each of these three tasks?
- Refactoring three independent modules
- Generating multiple competing hypotheses about an unknown bug
- Adding a feature that spans 5 files (5 self-contained subtasks)
In your most recent multi-agent design, were the subtasks genuinely orthogonal — or did they just feel like they should be parallel?
Does your CLAUDE.md state explicit criteria for “which tasks go to a Subagent” vs “which go to Agent Teams”?

Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.

[1] Anthropic, “Orchestrate teams of Claude Code sessions,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/agent-teams (as of 2026-06; v2.1.32+ enablement, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, mailbox, shared task list, teammate hook events, display modes, known limitations)
[2] Anthropic, “Create custom subagents,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/sub-agents (as of 2026-06; full subagent frontmatter, isolation: worktree, skills preloading, Task renamed to Agent in v2.1.63)
[3] Anthropic, “Hooks,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/hooks (as of 2026-06; TeammateIdle, TaskCreated, TaskCompleted events, exit 2 interception semantics)
[4] psmux, “psmux: native terminal multiplexer for Windows,” GitHub, 2026. [Online]. Available: https://github.com/psmux/psmux (as of 2026-06; Rust single binary, compatible with .tmux.conf, Windows-native, no WSL or Cygwin required; teammates automatically open in separate panes when Claude Code is launched inside a psmux session; version 0.1.x, a new project)

Subagent design and isolation: worktree: 04-5 Subagents.
Combining Skills with Subagents: 04-4 Skills.
Cross-agent integration interfaces: 04-9 MCP Integration.
Enforcement via hooks: 04-6 Hooks.
Context isolation concepts: 01-4 Context Engineering.
Multi-step task orchestration: 01-5 Workflow Engineering.

​Learning objectives

​1. Definitions and core differences

​2. How to enable each

​2.1 Subagents (04-5 covers this in full)

​2.2 Agent Teams

​2.3 Display modes

​2.4 Model selection

​3. Collaboration patterns

​3.1 Orchestrator-worker

​3.2 Parallel independent work

​3.3 Peer messaging

​4. Independent operation

​4.1 When to let agents avoid each other

​4.2 When shared state is unavoidable

​4.3 Strengthen the workflow with TeammateIdle / TaskCreated / TaskCompleted hooks

​5. Cost and complexity

​5.1 When not to parallelize

​5.2 Model selection

​5.3 Known limitations

​6. Tool comparison

​Hands-on exercises

​Common pitfalls

​Self-check

​Sources and further reading

Learning objectives

1. Definitions and core differences

2. How to enable each

2.1 Subagents (04-5 covers this in full)

2.2 Agent Teams

2.3 Display modes

2.4 Model selection

3. Collaboration patterns

3.1 Orchestrator-worker

3.2 Parallel independent work

3.3 Peer messaging

4. Independent operation

4.1 When to let agents avoid each other

4.2 When shared state is unavoidable

4.3 Strengthen the workflow with TeammateIdle / TaskCreated / TaskCompleted hooks

5. Cost and complexity

5.1 When not to parallelize

5.2 Model selection

5.3 Known limitations

6. Tool comparison

Hands-on exercises

Common pitfalls

Self-check

Sources and further reading