Agent Team Protocols in Claude Code

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;
• shut teammates down when their scoped work ends.

Enable Agent Teams Deliberately

Agent teams remain experimental in this release. Enable them for the process that needs them:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

You can also place the environment variable in your managed Claude Code environment, but 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 --permission-mode plan

Plan first, then let the lead create teammates only after file ownership and acceptance criteria are clear.

The Team Contract

Use this contract in the lead prompt:

Create one teammate for frontend verification and one for API verification.

Frontend owner:
- owns src/components/ and browser tests
- must not edit API files

API owner:
- 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 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.

Inspect and Recover

If a teammate stalls, inspect the shared task status before creating replacement work. Reassign only the unfinished task; do not duplicate the entire team.

When a task uncovers an interface dependency:

1. pause the dependent task;
2. assign the shared interface to one owner;
3. document the new contract;
4. unblock downstream work;
5. 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:

1. ask each teammate to stop;
2. confirm no task remains in progress;
3. review the combined diff;
4. run the complete affected test/build gate;
5. close the lead session only after evidence is collected.

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 --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.