laurigates Agent Teams
Experimental: Agent teams require
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1and may change between Claude Code versions.
BREAKING (Claude Code 2.1.178): The explicit
TeamCreate/TeamDeletetools were removed. Every session now has one implicit team whenCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1is set — there is nothing to create or tear down. Theteam_nameparameter is still accepted but ignored on the tools that took it (e.g.Agent), so older invocations don't error; omit it in new code. Coordination is otherwise unchanged: spawn teammates with theAgenttool, coordinate withSendMessage, and track work withTaskCreate/TaskList/TaskUpdate.
Task tools are opt-in on current models (Claude Code 2.1.233+).
TaskCreate/TaskGet/TaskUpdate/TaskList/TodoWriteare not exposed on Opus 4.8, Sonnet 5, Fable 5 / 5.1, Mythos 5 or newer unless the session opted in — see.claude/rules/agentic-permissions.md§ "Standard Permission Sets" → "Task-tool availability" for the three opt-ins and the full semantics. On a session without one, a lead cannot create or assign shared tasks: set the variable, or coordinate viaSendMessagealone and carry the task list in the lead's own message to each teammate. CheckTaskListis callable before spawning teammates.
For the worked setup examples, communication snippets, shutdown procedures, the worktree path-resolution recovery routine, and common dispatch patterns, see REFERENCE.md.
When to Use This Skill
| Use agent teams when... | Use subagents instead when... |
|---|---|
| Multiple agents need to work in parallel | Tasks are sequential and interdependent |
| Ongoing communication between agents is needed | One focused task produces one result |
| Background tasks need progress reporting | Agent output feeds directly into next step |
| Complex workflows benefit from task coordination | Simple, bounded, isolated execution |
| Independent changes to the same codebase (with worktrees) | Context sharing is fine and efficient |
Sub-Agent Caveat: Spawn Teams from the Main Thread
Agent and the related parallel-spawn tools may not be present in a
sub-agent's tool surface, even if the parent conversation has them. A
sub-agent designed to orchestrate its own team can silently degrade to sequential
single-thread execution — same content, ~5× longer wall-clock — without surfacing
the failure until its post-completion summary.
| Situation | Recommended pattern |
|---|---|
| Fan-out from the main conversation | Spawn parallel Agent calls directly — full tool surface available |
| Sub-agent orchestrating its own team | Avoid by design: split the work so the main thread does the fan-out |
| Sub-agent must orchestrate a team | Detect tool availability up front; report sequential fallback as a first-class outcome |
Detection contract to brief into a coordinating sub-agent: confirm the
Agent tool is callable; if not, do not silently fall back — report
"Parallel fan-out unavailable in this sandbox; executed sequentially." as the
first line of the summary, then continue sequentially with the same input
contract. Plan top-level orchestration in the main conversation when you can.
Native Team Tools
The implicit team (2.1.178) needs no create/delete step — these tools operate on the one team the session already has:
| Tool | Purpose |
|---|---|
Agent |
Spawn a teammate (give it a name; team_name is accepted but ignored) |
SendMessage |
Send DMs, broadcasts, shutdown requests, plan approvals |
TaskCreate / TaskList / TaskUpdate |
Create, discover, and assign/advance shared tasks |
TaskOutput |
Get output from a background agent |
TaskStop |
Stop a running background agent |
The setup sequence — TaskCreate → spawn teammates via the Agent tool (with a
name) → TaskUpdate to assign → receive results automatically — is shown with
full code in REFERENCE.md → Team setup workflow.
Teammate messages are delivered to the lead's inbox between turns; no polling needed.
Task Management
| State | Meaning |
|---|---|
pending |
Not yet started |
in_progress |
Assigned and active (one at a time per teammate) |
completed |
Finished successfully |
blocked |
Waiting on another task (blocked_by field) |
Teammates claim tasks in ID order (lowest first) via TaskList +
TaskUpdate, and skip blocked tasks until their blocker completes.
Communication (SendMessage)
| Type | Use When |
|---|---|
message |
Direct message to a specific teammate (recipient = name, not agentId) |
broadcast |
Critical team-wide announcement (N teammates = N round-trips — use sparingly) |
shutdown_request / shutdown_response |
Graceful teammate exit handshake |
plan_approval_response |
Approve or reject a teammate's plan |
DM, broadcast, and discovery (Read ~/.claude/teams/<name>/config.json →
members) examples are in
REFERENCE.md → Communication.
Key Teammate Rules
- Mark exactly ONE task
in_progressat a time. - Use
TaskUpdate(notSendMessage) to report task completion. - Idle after every turn is normal — idle ≠ unavailable; a message wakes a teammate.
- All communication requires
SendMessage— plain text output is NOT visible to the lead. - Use the name field (not agentId) for
recipient.
Lead Preflight Checklist
Before drafting the PRP and launching agents, a 30-second sweep prevents multi-edit renaming work after agents return:
| Check | Command | Why |
|---|---|---|
| Next ADR/PRD/PRP sequence number | ls docs/blueprint/adrs/ | sort -V | tail -1 |
Prevents numbering collisions in parallel doc writes |
| Filename conflicts | git ls-files | grep <filename> |
Scope tables can't guard against a stale mental model of the tree |
| Hardware pin budget (embedded) | Read pin_config.h or equivalent |
Prevents pin assignments overlapping across Phase 1 agents |
Out-of-Scope Discovery Protocol
Include the out-of-scope discovery protocol in every agent's prompt when that
agent has an exclusive write scope — it prevents the "investigate out of scope →
exhaust budget → truncated summary" failure mode. Copy the verbatim block from
REFERENCE.md → Out-of-scope discovery protocol:
the agent stops immediately on an out-of-scope dependency, lists it under an
Out-of-scope dependencies summary section, and exits for the lead to triage.
Worktree Isolation Hazard
Worktree-isolated agents can have Edit/Write silently resolve relative paths
against the parent repo instead of their worktree (upstream bug
#1091), landing
commits on the wrong branch with no immediate signal. Harden every
worktree-isolated prompt with the absolute-path preamble, run the lead
post-flight check (git diff origin/main..HEAD + git status --porcelain from
the parent), and use the cherry-pick + rebase recovery — all in
REFERENCE.md → Worktree path resolution.
See also .claude/rules/agent-coworker-detection.md.
Resuming Worktree-Isolated Agents
SendMessage-resume of a completed worktree-isolated agent (Agent with isolation: "worktree") loses worktree isolation — the resumed run executes in the orchestrator's main checkout, not the worktree. For parallel file-mutating work, re-dispatch a fresh isolation: "worktree" agent instead of resuming; reserve SendMessage-resume for read-only / single-checkout continuations. See parallel-agent-dispatch → "Resuming agents: SendMessage loses worktree isolation" (issue #1546).
Sandbox Considerations
In web sessions (CLAUDE_CODE_REMOTE=true):
- Sub-agents (teammates) may encounter TLS errors on
git push— delegate all push/PR operations to the lead. - Each teammate runs in its own process context.
- Worktree isolation is recommended for independent filesystem changes.
Quick Reference
Workflow Checklist
-
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1set (the implicit team exists; no create step) - Task tools opted in when the lead runs on Opus 4.8+/Sonnet 5/Fable 5.x/Mythos 5 (
.claude/rules/agentic-permissions.md§ "Task-tool availability"); verifyTaskListis callable before the firstTaskCreate -
TaskCreatefor each work unit - Spawn teammates via the
Agenttool with aname(noteam_nameneeded) -
TaskUpdateto assign tasks (or let teammates self-assign) - Receive messages automatically; respond via
SendMessage -
SendMessage shutdown_requestto each teammate when done (noTeamDelete)
Key Paths
| Path | Contents |
|---|---|
~/.claude/teams/ |
Implicit-team state (members: name, agentId, agentType) |
~/.claude/tasks/ |
Shared task list state |
Address teammates by the name you gave them at spawn — that is the reliable
handle, independent of any on-disk layout.
Common Mistakes
| Mistake | Correct Approach |
|---|---|
| Using agentId as recipient | Use the name given at spawn |
Calling the removed TeamCreate/TeamDelete |
The team is implicit (2.1.178); spawn with Agent, shut down with shutdown_request |
Passing team_name and expecting routing |
It is accepted but ignored — there is one implicit team |
| Sending broadcast for every update | Use message for single-recipient comms |
| Polling for messages | Messages delivered automatically — just wait |
| Sending JSON status messages | Use TaskUpdate for status, plain text for messages |
| Sub-agent pushes to remote | Delegate push to lead orchestrator |
Related Skills and Rules
parallel-agent-dispatch— worktree preflight, scope budgets, and the Return Contract every teammate must emit on exit. Team dispatches are a superset of plain parallel fan-out; follow both..claude/rules/agent-development.md— agent file structure, model selection, worktree isolation.claude/rules/agentic-permissions.md— granular tool permission patterns.claude/rules/sandbox-guidance.md— web sandbox constraints and push delegation