By default, a subagent talks only to the main agent that started it. Sometimes that’s exactly the limit you hit. Two workers are chasing competing theories of the same bug, and the useful move would be for one to tell the other, “that can’t be it, here’s why.”

That’s what agent teams are for. They’re also expensive, which is the catch.

What a team is

Agent teams are subagents (helper agents that each start with their own fresh context) that can talk to each other.

Compare that with an ordinary subagent. Its final report is its return value to the main agent that started it. While it runs, it can also exchange messages with that main agent through SendMessage, and the main agent can resume it later the same way. By default, that’s the only conversation it has. (A worker explicitly given SendMessage, in a workflow for example, can message other agents too.)

A team makes peer messaging the default. Instead of a lead (the main agent that created the team) dispatching workers and waiting for their reports, teammates share a task list, claim work from it, and message each other directly.

TL;DR: teams are only worth their cost when workers need to change each other’s minds mid-task. If the lead only needs final answers, subagents give you the same parallelism for about half the tokens a team would use, and can use worktree isolation (each worker in its own checkout of the repository) when you explicitly set isolation: worktree in the definition or invocation. Without that setting, ordinary subagents share the main session’s working directory. See the subagent configuration reference.

Turning a team on

Teams are experimental and off by default. Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable, in your shell or a settings file. Then ask the lead, which is the session you’re talking to, for a team in plain language: “Spawn three teammates to review PR #142: one security, one performance, one test coverage.” Each teammate starts like a fresh session. It loads your CLAUDE.md, MCP servers, and skills, plus the spawn prompt, but it doesn’t get the lead’s conversation. Since Claude Code v2.1.233, task-tracking tools are disabled by default on Opus 4.8+, Sonnet 5+, Fable 5+, and Mythos 5+. Set CLAUDE_CODE_ENABLE_TODO_TOOLS=1 to restore that model-gated tool set, as the release notes specify, and verify the shared task tools are available before relying on them.

What they cost

• A three-teammate team runs about 3–4× the tokens of one sequential session.
• Teammates in plan mode (the read-only plan permission mode, where an agent proposes a plan before changing anything) run about 7×.
• Teams buy you latency, not savings. One field report on one incident triage: about 10 minutes instead of 30–45 working solo, at roughly $8–10 instead of $2–3 in token spend.

Sometimes that’s a great trade. Just make it on purpose.

Good fits

• Competing hypotheses: Each teammate tries to disprove the others’ theories, not just defend its own.
• Cross-layer features: Frontend, backend, and tests working in parallel, after you’ve frozen the contract between them.
• Multi-lens review: Security, performance, and test coverage looking at the same change and arguing about severity.

Things that will bite you

• The setting changes your subagents, too: In interactive sessions with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS turned on, a named Agent call becomes a teammate unless it is a fork or passes isolation on the call itself, as the team launch reference explains. Headless and SDK named agents remain ordinary subagents. A converted teammate runs in the main working directory and doesn’t apply the definition’s isolation: worktree, preloaded skills, or permissionMode. Frontmatter isolation alone doesn’t prevent conversion; explicit isolation on the invocation keeps an ordinary worker. My own settings had this turned on globally, which may well explain a chunk of my worktree friction. Keep it off in your user settings and turn it on per repository. (The fields are explained in Configuring Subagents.)
• Runaway spawns: In one reported case, a teammate with no tools or model restriction inherited the ability to spawn more agents on Opus, recursed, and burned about 77% of a five-hour usage limit in under an hour. The nesting limit for ordinary subagents didn’t stop a teammate from recursing. Codex also needs an explicit roster and concurrency policy: its V2 runtime supports nested agents, and the older agents.max_depth setting is ignored by V2. Give every role an explicit tools list and model, state the roster size, and require workers to return to the coordinator rather than delegate further. Verify the active runtime’s limits instead of assuming a depth-one boundary.
• The lead does the work itself: Instead of waiting for teammates, the lead starts implementing. Tell it to wait.
• Idle looks dead: The lead decides a quiet teammate has died and spawns a duplicate.
• Plan approval is automatic: A teammate in plan mode stays read-only until it submits a plan. Then the lead approves it automatically, without reading it. Nobody reviews the plan unless you build that step in, with a hook. This is the same fatigue we’ll look at in Reviewing Agent Work.

The real quality gate

Team-specific hooks are where you get control back. A hook is a script the harness runs automatically at a set point. These three fire at team events:

• TaskCreated: Fires when a task is added to the shared list.
• TaskCompleted: Fires when a teammate marks a task done. A hook that exits with code 2 (the code that tells a hook to block) refuses the “done” until your tests actually pass.
• TeammateIdle: Fires when a teammate goes quiet. A hook that exits 2 sends its stderr message to the teammate as feedback, and the teammate keeps working instead of going idle. Keep a retry count in the hook so it gives up after a few tries and doesn’t loop forever.

Reach for a team when the workers need to argue. Otherwise, use subagents and save the tokens.