Agent Teams: shutdown_request approval doesn't terminate teammate; reply delivery occasionally drops content

Agent Teams: shutdown_request approval doesn't terminate the teammate; reply delivery to lead occasionally drops content

Summary

Two related but distinct issues with the experimental Agent Teams feature in Claude Code (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, teammateMode: "tmux"):

1. Shutdown desync — when the lead sends shutdown_request to a teammate via SendMessage and the teammate replies with shutdown_approved, the teammate's process sometimes does not terminate. Idle notifications continue to arrive from the teammate indefinitely.

1. Reply delivery skew — substantive replies from a teammate to a lead-initiated SendMessage occasionally land in the teammate's tmux pane (visible to the human user) but the lead session's SendMessage callback receives only a routine idle_notification, not the structured reply event with content. The lead never sees the reply unless the human copy-pastes it.

Environment

• Claude Code 2.1.143
• macOS 15.5 (Darwin 25.5.0)
• iTerm2 with teammateMode: "tmux" engaged (verified by backendType: iterm2 in shutdown_approved payloads)
• Multiple long-running session with ~30+ teammates spawned + shut down over the day

Issue 1: Shutdown approval doesn't terminate

Reproduction shape

1. Lead spawns a worker teammate via Agent tool with team_name and name.
2. Worker completes its task.
3. Lead sends a shutdown via:

``
SendMessage(to: "<worker-name>", message: {type: "shutdown_request", reason: "..."})
``

1. System reports: Shutdown request sent to <worker>. Request ID: shutdown-<id>@<worker>
2. Worker responds via the protocol with:

``json
{"type": "shutdown_approved", "requestId": "shutdown-<id>@<worker>", "from": "<worker>", "timestamp": "...", "paneId": "...", "backendType": "iterm2"}
``

1. Expected: worker process terminates; lead receives a teammate_terminated system event.
2. Observed (intermittently): worker continues to emit idle_notification events forever. No teammate_terminated arrives. The worker's tmux pane stays alive.

Frequency

Seen 1 time out of ~30 shutdowns in a long session (~3%). The remaining 29 shutdowns terminated cleanly. The single failure was on a teammate that had been alive for ~6 hours with light workload.

Workaround attempts that didn't help

• Sending a follow-up SendMessage "are you still running?" — worker continues to emit only idle notifications without engaging the message body.
• Looking for a hard-kill: per the agent-teams docs, the only documented termination is shutdown_request. TaskStop doesn't apply to Agent teammates (only to Bash background tasks).

Suggested fix

Either:

• Make shutdown_approved actually exit the worker process unconditionally on receipt, OR
• Expose a force-terminate tool that the lead can call as a hard kill when graceful shutdown approval doesn't lead to process exit within a documented timeout (say 30s).

Issue 2: Reply delivery skew

Reproduction shape

1. Lead sends SendMessage to worker with a substantive prompt.
2. The Claude Code transcript for the WORKER shows the worker received the message and produced a complete substantive reply (e.g., a 200-word investigation summary).
3. The LEAD's SendMessage callback returns successfully (delivered to inbox).
4. Expected: the worker's substantive reply arrives at the lead as a discrete event (analogous to how teammate-initiated messages arrive at the lead per the docs' "automatic message delivery" promise).
5. Observed (intermittently): the lead receives only an idle_notification from the worker, not the structured reply. The reply content is visible in the user's tmux pane but not in the lead's conversation flow.

Frequency

Higher than Issue 1 — observed 3-4 times over the same long session. The pattern was the same each time: worker replies substantively but the lead receives only idle.

Suggested fix

• The idle_notification schema sometimes carries the substantive reply in its summary field; this is inconsistent. The substantive reply should either always be delivered as a discrete event, or always land in summary, but not silently sometimes neither.

Combined impact

These two bugs together create an operational gap where:

• The lead believes a teammate is shut down (because the lead got shutdown_approved)
• The teammate is actually still running
• Any further messages from the lead reach the teammate but the teammate's replies are lost
• The only way the user sees the worker is dead is by looking at the tmux pane directly

For long-running coordinated work (the agent-teams use case), this is a small but accumulating reliability issue. Mitigation today is "ignore the idle notifications" but a teammate that won't shut down lingers in memory and consumes a tmux pane.

Mitigations the lead session can apply meanwhile

1. Treat idle_notification with a non-empty summary field as containing reply content; check it.
2. After shutdown_approved, if teammate_terminated does not arrive within ~30s, send a follow-up forcing-action SendMessage and proceed without expecting termination.
3. Don't rely on shutdown for reliability — design the workflow so a lingering worker is harmless (file-isolation, branch-based work).

Related context

This came up during a long coordinated session running the agent-teams feature at scale (50-90 sub-agents over the course of a day). The pattern was reliable enough that the human user (Joshua) called it out, which prompted this report.