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

  1. Create a team with TeamCreate
  2. Spawn a teammate agent with a long-running task (e.g., reading many large files and synthesizing output)
  3. Agent becomes unresponsive (stops processing messages, no idle notifications)
  4. Send shutdown_request via SendMessage — agent does not respond
  5. Attempt TeamDelete — fails with:

``
Cannot cleanup team with 1 active member(s): <agent-name>.
Use requestShutdown to gracefully terminate teammates first.
``

  1. Send multiple additional shutdown_request messages — agent never responds
  2. Wait 15+ seconds between attempts — still blocked
  3. No way to recover without manually deleting team files from ~/.claude/teams/ and ~/.claude/tasks/

Expected Behavior

  • TeamDelete should have a --force option or timeout that terminates unresponsive agents after N seconds
  • OR: shutdown_request should have a force: true option that kills the agent process without waiting for acknowledgment
  • OR: TeamDelete should accept a timeout parameter — if agents don't acknowledge within timeout, proceed with cleanup anyway

Actual Behavior

  • TeamDelete is 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)

  1. TeamDelete with force timeout: TeamDelete({ force_after_seconds: 60 }) — sends shutdown, waits N seconds, then terminates and cleans up regardless
  2. Force shutdown message type: SendMessage({ type: "force_terminate", recipient: "agent-name" }) — kills agent process immediately
  3. Agent heartbeat + auto-cleanup: If an agent hasn't sent any message (including idle notifications) for N minutes, mark it as dead and allow TeamDelete to proceed

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗