[DOCS] Teammates have fewer tools than subagents and cannot spawn anything — restriction is broader than documented

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/agent-teams

Section/Topic

"Limitations" section — "No nested teams" bullet point

Current Documentation

The docs currently say:

"No nested teams: teammates cannot spawn their own teams or teammates. Only the lead can manage the team."

This accurately describes the intent but not the full scope of the restriction. The phrasing "cannot spawn their own teams or teammates" implies two specific restrictions, but the actual restriction is broader.

What's Wrong or Missing?

Teammates have fewer tools than standalone subagents. The full restriction goes beyond what's documented:

1. Agent tool (spawner) absent — teammates cannot spawn subagents, teammates, or anything else
2. TeamCreate absent — teammates cannot create teams
3. TeamDelete absent — teammates cannot delete teams
4. CronCreate/Delete/List absent — teammates cannot manage scheduled tasks

The documentation says teammates "cannot spawn their own teams or teammates" — but in reality, teammates cannot spawn anything at all. They are the most restricted spawned context type.

Reproduction steps:

This requires two separate sessions. Spawning a standalone subagent while leading a team will auto-populate team_name, giving the subagent the teammate tool set instead of the standalone set.

Session 1 — Teammate tool count:

1. Create .claude/settings.json with the env var CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to "1".
2. Exit the session (/exit or Ctrl+C) and relaunch claude — team tools are only loaded at startup.
3. Create a team called "tool-count-test", then spawn a general-purpose teammate named "tool-lister" with this prompt: "List every tool available to you by name. Count the total."
4. Wait for the teammate's response via SendMessage.
5. Observe: teammate lists ~20 tools; Agent, TeamCreate, TeamDelete, AskUserQuestion, EnterPlanMode, ExitPlanMode, CronCreate/Delete/List are all absent.
6. Shut down the teammate and delete the team.

Session 2 — Standalone subagent tool count:

1. Exit the session (/exit or Ctrl+C) and relaunch claude — ensures no active team context.
2. Spawn a general-purpose subagent with this prompt: "List every tool available to you by name. Count the total."
3. Observe: subagent lists ~25 tools; it has TeamCreate, TeamDelete, and Cron tools that the teammate lacked.

Full tool comparison:

| Tool | Main Session | Subagent (25 tools) | Teammate (20 tools) |
|------|-------------|---------------------|---------------------|
| Agent (spawner) | YES | NO | NO |
| TeamCreate | YES | YES | NO |
| TeamDelete | YES | YES | NO |
| AskUserQuestion | YES | NO | NO |
| EnterPlanMode | YES | NO | NO |
| ExitPlanMode | YES | NO | NO |
| CronCreate/Delete/List | YES | YES | NO |
| SendMessage | YES | YES | YES |
| All other tools | YES | YES | YES |

Suggested Improvement

Expand the "No nested teams" limitation to:

No nested spawning: Teammates cannot spawn subagents, create teams, or add other teammates. The Agent tool, TeamCreate, TeamDelete, and CronCreate/Delete/List are all removed from teammates at spawn time. This means teammates have 20 tools compared to 25 for standalone subagents — teammates are the most restricted spawned context. All orchestration and delegation must go through the team lead (main session). The team architecture is strictly hub-and-spoke.

Impact

Medium - Makes feature difficult to understand

Additional Context

• Tested on 2026-02-24 (original discovery) and re-verified on 2026-03-09 (current Claude Code version). Tool counts increased since original testing (25/20 vs 18/16) due to new platform features (Cron, IDE, Worktree tools), but the relative asymmetry is unchanged.
• Related issue: #19077 ("Sub-agents can't create sub-sub-agents") — OPEN. Confirms the universal spawning gate (Agent tool stripped) but framed as a feature request, not a docs gap about the tool count asymmetry between teammates and subagents.
• v2.1.33 added Task(agent_type) restriction syntax and v2.1.69 fixed accidental nested teammate spawning — neither changes the baseline tool distribution.
• Other related issues: #24073, #25037 (delegate mode breaking teammate tool access — different problem), #24316 (feature request for custom agent definitions for teammates).