Agent Teams: lead session hangs indefinitely when IPC unix socket peer disconnects (no timeout)

Bug Description

With CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enabled, the lead Claude Code session hangs indefinitely and becomes completely unresponsive. This happened twice in one evening. The session enters a permanent S+ (sleeping) state with 0% CPU and must be force-killed.

Process-level forensic analysis shows the session lost all TCP connections to the Anthropic API and has a dangling unix socket (->(none)) — the IPC peer disconnected and the lead is stuck waiting for a response that will never arrive. There is no timeout or reconnect mechanism.

Reproduction Steps

1. Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json
2. Start a Claude Code session and work normally (invoke skills, use tools)
3. After ~30-60 minutes, the session freezes mid-tool-call — no response, no spinner progress, completely unresponsive
4. Ctrl+C does not recover it

Forensic Evidence

Compared the hung process against healthy sessions running simultaneously on the same machine:

| Metric | Hung session (PID 93302) | Healthy session (PID 94180) | Healthy session (PID 3901) |
|--------|-------------------------|---------------------------|--------------------------|
| TCP to API (160.79.104.10) | 0 connections | 3 ESTABLISHED | 6 ESTABLISHED |
| Unix sockets | 1 dangling (->(none)) | 1 connected | 3 connected |
| CPU | 0% | 0.7% | 19.8% |
| Process state | S+ (blocked) | S+ (responsive) | R+ (running) |
| Open FDs | 173 (144 skill-related) | 33 | 148 |
| Child processes | caffeinate -i -t 300 (mid-tool-call) | — | Normal |

Key observations:

• Zero TCP connections: Every healthy session has 3-6 ESTABLISHED connections to 160.79.104.10 (Anthropic API). The hung session has none — they all dropped.
• Dangling unix socket: unix 0x60d3cf982484c4c2 -> (none) — the IPC peer disconnected. Healthy sessions show all sockets connected (->0x...).
• caffeinate child: Confirms the session was mid-tool-call when it hung. caffeinate -i -t 300 is spawned during tool execution.
• Session worked for ~58 minutes before hanging (started 21:18, caffeinate spawned 22:16).

Expected Behavior

• Session should detect lost API connections and reconnect or surface an error
• IPC socket communication should have a timeout — if a peer disconnects, the session should recover rather than block forever
• At minimum, Ctrl+C should be able to interrupt the blocked state

Actual Behavior

• Session blocks permanently with no recovery path
• No error output, no timeout, no reconnect attempt
• Only way to recover is kill <pid> from another terminal

Environment

• Claude Code version: 2.1.72
• OS: macOS Darwin 25.2.0 (Apple Silicon, 16 GB RAM)
• Setting: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json
• Context: 9 concurrent Claude sessions (1.4 GB RSS total), system under memory pressure (100 MB free, heavy swap). Memory pressure may contribute to connection drops but the lack of timeout/recovery is the bug.

Related Issues

• #31788 — TeamDelete blocked by hung teammate (related: no force-kill for hung agents)
• #29271 — No distinction between idle-but-alive and dead teammates
• #25254 — Team agent messages not delivered, causing deadlock
• #25243 — Sessions frequently freeze/hang on macOS

This may share a root cause with #25243, with Agent Teams IPC being the specific trigger mechanism.

Suggested Fix

1. Timeout on IPC reads: If no response from a unix socket peer within N seconds, surface an error and attempt recovery
2. Socket keepalive/health check: Detect when a unix socket peer disconnects (->(none)) and handle it gracefully
3. API connection monitoring: Detect when all TCP connections to the API are lost and attempt reconnect or fail with an error message