Agent Teams: Mesh Topology and Five Ways to Die

Knowledge Comic Series — Maximum technical depth, minimum words.

The Misunderstood Star

Claude Code Agent Teams’ communication system is a wide-open pipe.

The recipient field in SendMessage accepts any teammate name. The routing logic does exactly one thing:

Append JSON to ~/.claude/teams/{team}/inboxes/{recipient}.json

No whitelist. No ACL. No hardcoded “can only talk to Lead” restriction.

But everyone runs star topology. Why?

Because of that one line at the end of Lead’s spawn prompt:

"When done, send a summary message to the team lead."

One sentence. Topology locked.

Opening Mesh

Change the spawn prompt to:

"You can coordinate directly with 'backend-dev' via
SendMessage(recipient='backend-dev'). Agree on the API
contract before either of you starts coding. Send final
summary to team-lead when both sides are done."

The system routes as normal. frontend-dev’s message lands in inboxes/backend-dev.json. backend-dev picks it up on their next turn.

No config changes. No tool changes. No code changes.

Mesh Communication Diagram

frontend-dev ←──SendMessage──→ backend-dev
      │                              │
      └──────SendMessage─────→ team-lead
                                     │
                          (receives final results only,
                           blind to intermediate coordination)

Lead’s only visibility comes from idle notifications, which contain just four fields:

{ "type": "idle", "from": "frontend-dev", "timestamp": "...", "idleReason": "..." }

What peers discussed, what they agreed on — Lead has zero visibility — unless teammates proactively report back.

Five Ways to Die

Whether star or Mesh, every teammate process has five ways to terminate.

Death #1: Clean Shutdown ✅

Lead sends shutdown_request. Teammate replies approve: true. System returns teammate_terminated.

Three log lines. Clean and done.

This is the only death with a complete protocol.

Death #2: Rate Limit Silent Kill ☠️

API quota exhausted. Last log line reads:

"You've hit your limit · resets 5am"

Process exits immediately. No notification sent to Lead or peers.

Inbox may still contain unread messages.

This is the most poisonous death.

Even deadlier under Mesh — if A is waiting for B’s API contract response, but B got killed by rate limit, A waits forever. Lead sees two idle notifications and assumes everything is fine.

Death #3: Natural Idle After Completion 😴

Teammate finishes work. Last assistant message is a plain text summary with no tool calls.

Runtime determines “no next step” and emits an idle notification. Process doesn’t terminate — it enters a wait state: new inbox messages wake it up, silence keeps it hanging.

Under Mesh, this is the normal “waiting for peer reply” state.

But Lead cannot distinguish “waiting for peer” from “actually done.”

Death #4: Leader Session Ends 💀

Lead closes terminal or session times out.

All teammates with backendType: "in-process" die with it — they run in the same process tree.

No shutdown protocol. No notification. Unread inbox messages become orphan files.

Under Mesh, if A and B are mid-conversation, Leader exits — both vanish simultaneously.

Death #5: Max Turns Timeout ⏱️

Task(max_turns=N) or the template’s 30-minute ceiling. When reached, forced stop.

Under Mesh, if one side times out while the other waits for a reply, the effect is identical to Rate Limit Silent Kill — the waiting side never receives a message.

The Real Risk of Mesh

Of the five deaths, only the first (clean shutdown) has complete lifecycle management.

The other four are “silent disappearances” — the other side doesn’t know you’re dead, and you don’t know they’re waiting for you.

Not a Big Deal Under Star

All messages flow through Lead. If Lead doesn’t get a reply, it knows something went wrong — shutdown and fall back to a sub-agent.

But Under Mesh…

Two peers chatting, Lead blind to content. One silently dies:

A → SendMessage(to=B, "Is your API schema ready?")
    ↓
    Written to inboxes/B.json ← success (system doesn't check if B is alive)
    ↓
    A waits for reply... idle... idle... idle...
    ↓
    Lead sees A stuck in idle, thinks A is frozen
    ↓
    Lead shuts down A
    ↓
    Both agents' work — wasted

Conclusion

Star is not a technical limitation. It’s risk management.

The pipe is wide open. But opening Mesh means handling the “silent dead” problem yourself.

Currently the system has no heartbeat, no delivery confirmation, no “peer offline” callback.

SendMessage always returns success: true
Even if the recipient's process died long ago