Distinguish Claude Code Subagents and Agent Teams
A subagent performs an isolated subtask and returns the result to the main session. An agent team consists of separate sessions with shared coordination and direct message exchange. These are different surfaces, and confusing them isn't worth it.
Claude Code recommends subagents for self-contained work that creates a lot of intermediate context: exploring modules, running tests, analyzing logs. A subagent has its own context window, tools, and permissions, then returns a summary to the main conversation. Agent teams are a different surface: a lead session coordinates teammates, and teammates work in independent contexts and can talk to each other. As of the cutoff, the documentation marks teams as experimental and disabled by default, lists resume, coordination, and shutdown limits; to enable it, the flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is given.
Property · Subagent · Agent team
- Context - Separate, the result returns to the main session; Separate for each teammate
- Communication - Mostly through the main agent; Teammates can talk directly
- Best fit - A short isolated investigation or check; Sustained parallel work over independent areas
- Risk - Summaries overflow the main context; Cost, coordination overhead, file conflicts
The official cost page gives a benchmark of about 7x tokens for agent teams relative to a standard session when teammates work in plan mode. This is a characteristic of a specific product and mode, not a universal price of the multi-agent pattern.
Start with research and review. The official agent-teams best practices advise choosing self-contained tasks and avoiding file conflicts. Parallel editing of one tightly coupled area stays a poor fit regardless of UI convenience.
One product is covered. The broader choice is a framework, and it must be made by the mechanism you need, not by a slogan.