TeamDelete blocked indefinitely by hung agent that ignores shutdown_request
Resolved 💬 3 comments Opened Mar 7, 2026 by mmphego Closed Mar 11, 2026
Bug Description
When a teammate agent becomes unresponsive (hung), TeamDelete is permanently blocked because it requires all agents to gracefully shut down first. There is no force-kill or timeout mechanism to recover from this state.
Reproduction Steps
- Create a team with
TeamCreate - Spawn a teammate agent with a long-running task (e.g., reading many large files and synthesizing output)
- Agent becomes unresponsive (stops processing messages, no idle notifications)
- Send
shutdown_requestviaSendMessage— agent does not respond - Attempt
TeamDelete— fails with:
````
Cannot cleanup team with 1 active member(s): <agent-name>.
Use requestShutdown to gracefully terminate teammates first.
- Send multiple additional
shutdown_requestmessages — agent never responds - Wait 15+ seconds between attempts — still blocked
- No way to recover without manually deleting team files from
~/.claude/teams/and~/.claude/tasks/
Expected Behavior
TeamDeleteshould have a--forceoption or timeout that terminates unresponsive agents after N seconds- OR:
shutdown_requestshould have aforce: trueoption that kills the agent process without waiting for acknowledgment - OR:
TeamDeleteshould accept atimeoutparameter — if agents don't acknowledge within timeout, proceed with cleanup anyway
Actual Behavior
TeamDeleteis permanently blocked by any single hung agent- No force-kill mechanism exists
- Only workaround is manually removing files:
``bash``
mv ~/.claude/teams/<team-name> /tmp/
mv ~/.claude/tasks/<team-name> /tmp/
Impact
- Operational blocker: Long-running audit/analysis workflows that spawn multiple agents are vulnerable to one hung agent blocking full team cleanup
- Resource leak: Hung agent process continues consuming resources with no way to terminate it through the API
- Workflow disruption: User must manually intervene with filesystem operations, breaking the abstraction
Environment
- Claude Code CLI (latest)
- macOS Darwin 25.3.0
- Agent was spawned with
subagent_type: "general-purpose",run_in_background: true - Agent task: reading 16+ files and synthesizing a long-form analysis document
- Agent appeared to hang during file reads (no output produced, no messages sent, no idle notifications for extended period)
Suggested Solutions (in order of preference)
TeamDeletewith force timeout:TeamDelete({ force_after_seconds: 60 })— sends shutdown, waits N seconds, then terminates and cleans up regardless- Force shutdown message type:
SendMessage({ type: "force_terminate", recipient: "agent-name" })— kills agent process immediately - Agent heartbeat + auto-cleanup: If an agent hasn't sent any message (including idle notifications) for N minutes, mark it as dead and allow
TeamDeleteto proceed
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗