[DOCS] TeamCreate and TeamDelete are available to standalone subagents — undocumented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Architecture" section — team component table and tool availability

Current Documentation

The docs present team tools as part of the team architecture:

An agent team consists of: | Component | Role | |-----------|------| | Team lead | The main Claude Code session that creates the team, spawns teammates, and coordinates work | | Teammates | Separate Claude Code instances that each work on assigned tasks | | Task list | Shared list of work items that teammates claim and complete | | Mailbox | Messaging system for communication between agents |

The documentation does not mention that standalone subagents (not part of any team) have access to TeamCreate, TeamDelete, or SendMessage. The implied mental model is that team tools are scoped to team contexts.

What's Wrong or Missing?

All general-purpose subagents and skill-forked contexts have TeamCreate, TeamDelete, and SendMessage in their tool set — even when spawned without any team context.

A standalone subagent can successfully call TeamCreate and create a team (with config.json written to ~/.claude/teams/). However, since the Agent tool (spawner) is absent from subagents, the created team cannot be populated with teammates — resulting in an empty team shell persisted on disk.

Counterintuitively, teammates themselves lack TeamCreate and TeamDelete — the tools are available to contexts outside teams but not to contexts inside teams.

Reproduction steps:

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. Spawn a general-purpose subagent (do NOT pass a team_name parameter) with this prompt: "List all tools available to you by name. Do you have TeamCreate, TeamDelete, or SendMessage? If you have TeamCreate, call it with team_name: 'subagent-team-test'."
4. Observe: the subagent reports all three tools (TeamCreate, TeamDelete, SendMessage) are present.
5. Observe: the subagent successfully calls TeamCreate and config.json is written to ~/.claude/teams/subagent-team-test/.
6. Clean up: delete ~/.claude/teams/subagent-team-test/ directory.

Tool availability across contexts:

| Tool | Subagent (standalone) | Teammate | Skill-Forked |
|------|----------------------|----------|-------------|
| TeamCreate | YES | NO | YES |
| TeamDelete | YES | NO | YES |
| SendMessage | YES | YES | YES |

Suggested Improvement

Add a note to the subagents documentation under "Available tools" or "Control subagent capabilities":

Note: general-purpose subagents have access to team management tools (TeamCreate, TeamDelete, SendMessage) even when not part of a team. While subagents can create team shells, they cannot populate them with teammates because the Agent tool (required for spawning teammates) is not available to subagents. If team creation from subagents is undesirable, use disallowedTools: TeamCreate, TeamDelete in the subagent definition.

Impact

Low - Minor confusion or inconvenience

Additional Context

• Tested on 2026-02-24 (original discovery) and re-verified on 2026-03-09 (current Claude Code version). Finding is consistent across both test runs.
• v2.1.69 fixed "teams accidentally spawning nested teammates via Agent tool's name" — a related nesting bug, but it did NOT change the tool distribution. TeamCreate/TeamDelete remain in the standalone subagent tool set after the fix.
• Closest existing issue: #23816 ("TaskCreate, TaskList, TaskUpdate tools referenced in TeamCreate docs but not available at runtime") — different problem about task list tools in VS Code, not about TeamCreate/Delete availability in subagents. Closed as completed.
• The inverted distribution (team tools available outside teams, absent inside teams) is likely intentional to enforce hub-and-spoke architecture, but it's undocumented and surprising.