Chapter 20: Agent Teams — Peer Collaboration and Cross-Session Safety

The multi-agent modes in Chapter 8 — a main agent spawning subagents, a coordinator dispatching workers, Swarm fanning out a batch of workers — look different but share one relationship at the core: one entity up top decides who to dispatch and when to collect, and the subagents it sends out are leaves that hand back a result and exit. Chapter 19's dynamic workflow swaps that "model as coordinator" for a script, but the script still fans out a batch of leaf workers. This chapter is about a different relationship: a team still has a fixed lead session at its head, but the members other than it are no longer leaves that hand back a result and go quiet — they can talk to each other directly through a tool called SendMessage, share one task list and one team memory, and members may even belong to different sessions, or different machines. This is Agent Teams. And once messages can flow laterally between peer members, and even between different sessions, a problem shows up that simply doesn't arise under a master/leaf structure — does a line that drifts in from another session count as your user directing you? The heart of this chapter is Claude Code's answer to that question (it does not), and the several gates it adds to the permission system to enforce it.

The evidence splits in two. The team's core — the TeamCreate and SendMessage tools, the Team↔task-list correspondence, the guard on cross-machine messaging — is readable line by line in the ~v2.1.6x snapshot source; it shipped alongside Opus 4.6 in v2.1.34, which falls inside the snapshot's window. But this chapter's real protagonist, the rule that "another session carries no user authority," together with a batch of new material on team artifact sharing, did not leak with the snapshot — it was pulled from the 2.1.202 client binary, and grep finds none of it in the snapshot. Put the two together and you can pin claims to source line numbers as well as to rule text extracted from the current binary; what you can't reach is the server-side half, and the end of the chapter says exactly where the trail cuts off.

20.1 Master/leaf vs. peer: two relationships in multi-agent

Start by connecting to Chapter 8. Its three orchestration modes — subagent, coordinator, Swarm — look different but share one relationship at the core: one entity up top decides "who to dispatch now, and how to synthesize once results come back," and the subagents it sends out are leaves that hand back a result and exit, with no cross-talk between them. Chapter 19's dynamic workflow goes one step further, swapping the coordinating model for a script — but what the script fans out is still leaves. Chapter 19 made a point of noting that a subagent's tool set has even the Agent and Workflow tools (the ones that could dispatch further) stripped out; it can only do the work, not build a team.

Agent Teams changes that relationship itself. A team has a fixed lead session heading it up — coordinating, assigning, synthesizing — but the members other than it are no longer leaf workers that can only wait to be dispatched and hand a result back: each can message the others on its own initiative, each can claim tasks from the shared task list, and all of them read the same team memory. Further out, members don't even have to live in the same session — one can be another Claude Code session you opened on the same machine, or a session bridged to another machine via Remote Control. Stack "peer" and "cross-session" together and you get a problem that never appears in master/leaf orchestration: a message comes in from another session, looking exactly like something your user typed — do you treat it as the user's instruction, or as a request from a peer colleague? The permissions are worlds apart — a user can authorize you to do dangerous things, a peer colleague cannot. Every safety design in the back half of this chapter is answering that one question.

Seen another way, Chapter 19 and this one draw a clean "who orchestrates whom" boundary. A workflow is a script orchestrating a batch of leaf workers top-down; the workers don't talk to each other and answer only to the script. A team is a lead session bringing along several teammates, whose members can also message each other laterally — with none of Chapter 19's script scheduling them turn by turn up top; coordination runs on the lead's assignments plus members messaging each other, and on racing for the work in the shared task list. The former's risk is "will the script misuse a worker" — a correctness problem; the latter's risk is "can one peer session overreach on another's behalf" — a safety problem. It's no accident that nearly all of this chapter weighs on the second: once a peer structure crosses sessions and machines, the boundary shifts from "who directs whom" to "who has the authority to authorize whom."

20.2 A team is a shared task list

What is a team? Start with the snapshot-era entry point, TeamCreate — its description, a 6.9KB full text in the snapshot source, puts it plainly: creating a team is creating a task list, teams correspond one-to-one with task lists, Team equals TaskList. (This explicit TeamCreate is the snapshot-era usage; the current version changed the entry point, covered at the end of this section.) On disk it's two things: a team config file ~/.claude/teams/\{team-name\}/config.json, and a task-list directory ~/.claude/tasks/\{team-name\}/. The first holds the member roster, the second holds all of the team's tasks.

The description gives a seven-step usage that reads collaboration as an assembly line. First TeamCreate builds the team — and in the same step, the task list. Then the Task tool adds tasks, which land automatically in this team's list. Then the key step: use the Agent tool to spawn a teammate with a team_name and a name, and that agent joins the team. Then TaskUpdate assigns a task's owner to some idle teammate, who does it and TaskUpdates it to completed. Between turns, a teammate that goes idle automatically enters an idle state and sends a notification — the description makes a point of saying "be patient with idle teammates." When everything's done, SendMessage sends a shutdown_request to close the team gracefully.

This explicit team-creation usage has been simplified by the current 2.1.202. In this version, TeamCreate/TeamDelete are no longer presented as regular tools; instead, every session comes with an implicit team by default — the Agent tool description this very session received marks the team_name parameter plainly as "Deprecated; ignored. The session has a single implicit team," with a comment adding that it "carries the session-derived team name and will be removed in a future release." In other words, teaming has gone from "explicitly create a team first, then add members into it" to "every session is itself a team; spawn a teammate directly with the Agent tool and a name." This change touches only the team-creation entry point; the addressing, shared memory, and cross-session safety rules covered below are all unaffected — the mechanisms carry over unchanged.

Woven into that description are several rules that read like lessons learned the hard way. One is that who you assign what depends on agent type: read-only agents (Explore, Plan) are for research, search, and planning — don't expect them to edit files; work that touches files needs a full-access agent like general-purpose. One is how you recognize teammates — read the members array in config.json, where each member has a name, agentId, and agentType, and communication always goes by name, never by UUID. One more is how to claim work without stepping on each other: the task list is shared, so a teammate that finishes its own work goes to check TaskList and, in task-ID order, claims the next unclaimed task, notifying the team lead if it gets stuck. The last concerns visibility: teammates can DM each other privately (peer DMs), but summaries of those private chats go into the idle notifications sent to the team lead — the lead can see "those two are collaborating" but can't read the full text of the DM.

Worth noting: the team didn't build a separate substrate for collaboration. Team equals TaskList means it reuses the existing task list directly — shared tasks, the owner field, claiming and marking complete are all primitives the task system already had, and the team just wraps them in a multi-member shell. Spawning a teammate still goes through the Agent tool; delivering a teammate's message reuses the same main-loop mechanism of "arriving as a new turn." What's genuinely new is mainly a layer of addressing (the four to forms in the next section) and a layer of cross-session memory sync. The payoff of layering collaboration on existing primitives is that every step of team life — which team was created, who claimed which task, who marked what complete — falls automatically into the task system's traceable record.

20.3 SendMessage: your plain output is invisible; you must send explicitly

How do teammates talk? Through a tool called SendMessage, whose description is a single sentence — send a message to another agent. There's a mechanism here that's easy to miss but matters a great deal, and the description emphasizes it: the plain text you print is not visible to other agents; to get through to someone, you must call this tool. Conversely, a message a teammate sends you is delivered automatically — you don't check an inbox. Address teammates by name, never by UUID.

Who it goes to is set by to, which has four forms, running from nearest to farthest. Nearest is a teammate's name, e.g. "researcher" — a point-to-point message to one member of the same team. Writing "*" broadcasts to the whole team — the description says outright this is expensive, cost growing linearly with team size, to be used only when everyone genuinely needs to know. Farther out, "uds:/path/to.sock" reaches another Claude session on the same machine, over a Unix domain socket, hidden behind the UDS_INBOX feature flag, with the peer's address discovered via ListPeers. Farthest is "bridge:session_...", reaching a session bridged via Remote Control and possibly on another machine, also found via ListPeers. The four forms map to four distances — same team, same-team broadcast, same-machine cross-session, cross-machine — and the farther the distance, as the next section shows, the tighter the gate.