Agent Team Protocols in Claude Code
Run Claude Code agent teams with explicit task ownership, message discipline, verification, and safe shutdown.
What You’ll Learn
Claude Code agent teams are a CLI feature, not a generic message-bus framework. A lead session creates teammates, coordinates a shared task list, and receives their messages. This lesson focuses on the operational protocol that makes the feature reliable:
- enable the experimental team surface explicitly;
- give every teammate non-overlapping ownership;
- use the shared task list as the source of truth;
- require evidence before marking work complete, and let hooks enforce it;
- shut teammates down when their scoped work ends.
Enable Agent Teams Deliberately
Agent teams remain experimental in Claude Code 2.1.305. Enable them for the process that needs them, together with the Task tools, so the team has a shared task list on current models:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude
Without CLAUDE_CODE_ENABLE_TODO_TOOLS=1, a lead on a current model such as Opus 5.5 has no Task tools: agents coordinate through messages only, and the task-based steps below don’t apply. You can also put both variables in the env block of a settings file (Session 9 shows the JSON). Settings apply however claude is launched, so they are the safer choice for split-pane teammates, which run as separate Claude Code processes; a one-command opt-in is easier to audit and remove.
Start in Plan mode when the work has unclear boundaries:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 \
claude --permission-mode plan
Plan first, then let the lead create teammates only after file ownership and acceptance criteria are clear. Approving the lead’s plan is your review gate. Teammates start in the lead’s permission mode (except dontAsk), and a teammate spawned while the lead is still in plan mode plans read-only first, then has its plan approved automatically in the lead’s session without your review. Its edits and commands still go through permission prompts, which appear in the lead session.
The Team Contract
Use this contract in the lead prompt. Naming each teammate gives you a stable address for later prompts and messages:
Create two teammates named frontend-verifier and api-verifier.
frontend-verifier:
- owns src/components/ and browser tests
- must not edit API files
api-verifier:
- owns src/api/ and API tests
- must not edit frontend files
Each teammate must:
1. claim only its assigned task;
2. report changed files;
3. run affected tests;
4. send failures and evidence to the lead;
5. avoid reverting another teammate's edits.
The contract is intentionally concrete. Agent teams coordinate through Claude Code’s task and messaging tools; they do not need an invented request_id protocol layered on top.
Task Ownership Is the Concurrency Boundary
A useful task contains four fields:
Owner: api-verifier
Scope: src/api/** and tests/api/**
Outcome: endpoint returns the documented schema
Evidence: pnpm test tests/api && example response
Do not assign two teammates to the same writable files. If two tasks touch one shared module, either give that module to the lead or serialize the tasks.
Good decomposition:
Task A — inspect and patch API implementation
Task B — update independent browser coverage
Task C — read-only review of the combined diff
Bad decomposition:
Task A — improve authentication
Task B — fix authentication tests
Both may edit the same files, so the ownership boundary is ambiguous.
Messages Should Carry Decisions and Evidence
Ask teammates to send messages when one of these events occurs:
- a blocker changes the plan;
- a shared interface must change;
- tests fail outside the assigned scope;
- the task is complete with verification evidence.
A message reaches one named teammate; there is no broadcast, so a change that affects everyone needs one message per recipient.
A completion message should look like:
Completed API validation.
Changed: src/api/session.ts, tests/api/session.test.ts
Verification: 14/14 tests passed
Open issue: none
The lead remains responsible for integrating evidence, checking the final diff, and running the product-level gate.
Enforce the Gate with Hooks
Hooks turn parts of the protocol into checks that Claude Code runs for you. In a session with the Task tools, a TaskCompleted hook runs whenever a task is about to be marked complete, including when a teammate ends its turn with a task still in progress. Exiting with code 2 keeps the task open and sends your stderr message back to the agent as feedback:
{
"hooks": {
"TaskCompleted": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-tests.sh"
}
]
}
]
}
}
#!/bin/bash
# .claude/hooks/require-tests.sh
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
if ! pnpm test 2>&1; then
echo "Tests are failing. Fix them before completing: $TASK_SUBJECT" >&2
exit 2
fi
exit 0
A TeammateIdle hook works the same way when a teammate is about to go idle: exit code 2 sends the feedback and keeps the teammate working. Hooks enforce minimum gates; they do not replace the lead’s final verification.
Inspect and Recover
If a teammate stalls, open its transcript from the agent panel and inspect the shared task status before creating replacement work. Task status can lag behind the work, so check whether the task is actually done before reassigning it. A direct message also wakes a teammate that is waiting to retry a failed request. Reassign only the unfinished task; do not duplicate the entire team.
When a task uncovers an interface dependency:
- pause the dependent task;
- assign the shared interface to one owner;
- document the new contract;
- unblock downstream work;
- rerun both affected test sets.
This produces a small dependency graph instead of uncontrolled parallel editing.
End the Team Cleanly
When all assigned work is integrated:
- ask the lead to shut each teammate down (a teammate that isn’t finished can reject the request with an explanation);
- confirm no task remains in progress;
- review the combined diff;
- run the complete affected test/build gate;
- close the lead session only after evidence is collected.
Shutdown can take a moment, because a teammate finishes its current request or tool call first. Claude Code removes the team’s runtime config when the session ends, so there is no separate cleanup step.
The important distinction is that teammate completion is not product completion. The lead’s final verification is the completion gate.
Hands-On Run
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 \
claude --permission-mode plan \
"Plan a two-owner audit: one teammate for the CLI reference UI and one for MCP tests. Keep file ownership disjoint and report exact verification."
After approving the plan, ask the lead to create the team, track the shared tasks, and return a consolidated verification report.
Next Session
Session 11 turns this coordination model into bounded, non-interactive CLI automation with claude -p, structured output, budgets, and external schedulers.