SubagentStop hook does not fire when team agents terminate via shutdown protocol

[todd-w-shaffer]

Summary

When a team agent (teammate) terminates via the shutdown_request → shutdown_approved protocol, the SubagentStop hook does not fire. This leaves external systems that track agent lifecycle via hooks with phantom agent counts that never decrement.

Reproduction

1. Enable agent teams: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
2. Register a SubagentStop hook that logs to a JSONL file (or any observable side effect)
3. Create a team and spawn teammates
4. Send shutdown_request to teammates
5. Observe that shutdown_approved is received, teammate_terminated system message appears, but SubagentStop hook never fires

Evidence

JSONL event log showing 6 team agents with agent.start events and no matching agent.stop:

# Team 1: resilience-architect and test-architect
{"ts":"2026-04-08T01:54:13Z","event":"agent.start","agent_id":"aacd2d977d5b10367","agent_type":"resilience-architect"}
{"ts":"2026-04-08T01:54:26Z","event":"agent.start","agent_id":"ad43c61987f3d60bd","agent_type":"test-architect"}
# Both received shutdown_approved — no agent.stop events ever appeared

# Team 2: three review agents
{"ts":"2026-04-08T02:09:22Z","event":"agent.start","agent_id":"a712f607506a003a7","agent_type":"reuse-reviewer"}
{"ts":"2026-04-08T02:09:22Z","event":"agent.start","agent_id":"a912c5cfbfc5e9ae4","agent_type":"quality-reviewer"}
{"ts":"2026-04-08T02:09:23Z","event":"agent.start","agent_id":"ab21e0518d3daf119","agent_type":"efficiency-reviewer"}
# All three received shutdown_approved — no agent.stop events

Meanwhile, regular subagents (non-team) and team agents that go through idle→wake cycles (via SendMessage) DO correctly fire SubagentStop. The issue is specifically the shutdown_request → shutdown_approved termination path.

Expected behavior

SubagentStop should fire for every agent that triggered SubagentStart, regardless of how the agent terminates (normal completion, shutdown protocol, or error).

Impact

Any plugin or hook that tracks agent count via SubagentStart/SubagentStop pairs will show permanently inflated counts after team sessions. This affects resource management tools that gate behavior on active agent count.

Environment

• Claude Code v2.1.94
• macOS Darwin 25.3.0
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Context

Discovered while building coolant, a resource management plugin that tracks agent lifecycle via hooks to drive a thermal monitoring dashboard. The breathing agent icons stay lit indefinitely after team agent shutdown because the stop events never arrive.

[github-actions]

Found 1 possible duplicate issue:

1. Subagent (Agent tool) does not fire Stop hook on completion #33049

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[todd-w-shaffer]

Duplicate of #27755 and #25147 — the missing SubagentStop on team agent shutdown is a subset of the broader issue where subagent lifecycle hooks don't fire on completion. Closing in favor of those.

Our workaround in coolant: agents that exceed a staleness threshold (3 min with no stop event) are visually dimmed in the dashboard rather than removed — orphaned but honest.

[todd-w-shaffer]

Reopening — this is not a duplicate of #27755 or #25147. The cited issues describe different failure modes:

#25147 — Background agents bypass Stop hooks

• Hook type: Stop (session-level), not SubagentStop
• Trigger: run_in_background=true
• Symptom: Hook never fires at all for background agents

#27755 — SubagentStart/SubagentStop unreliable for Task tool

• Hook type: SubagentStart/SubagentStop via settings.json
• Trigger: Task tool dispatches
• Symptom: Intermittent — hooks sometimes fire, sometimes don't; agent_type sometimes empty

This issue (#44971) — SubagentStop not fired on team agent shutdown protocol

• Hook type: SubagentStop (works perfectly for non-team agents)
• Trigger: Team agent terminated via shutdown_request → shutdown_approved
• Symptom: 100% reproducible — SubagentStop NEVER fires for this specific code path

Key distinction: Our SubagentStart/SubagentStop hooks fire reliably and symmetrically for every regular subagent (Agent tool). We have JSONL evidence of dozens of clean start/stop pairs in the same session. The failure is isolated to one specific termination path: the team agent shutdown protocol.

Evidence from a single session showing both working and broken hooks:

# Regular subagent — SubagentStop fires correctly ✓
{"ts":"…T02:08:24Z","event":"agent.start","agent_id":"af6ce16ba…","agent_type":"general-purpose"}
{"ts":"…T02:08:58Z","event":"agent.stop","agent_id":"af6ce16ba…","agent_type":"general-purpose"}

# Team agent — SubagentStart fires, SubagentStop never fires ✗
{"ts":"…T02:09:22Z","event":"agent.start","agent_id":"a712f6075…","agent_type":"reuse-reviewer"}
# ← shutdown_approved received, teammate_terminated system message appeared, NO agent.stop ever

# Same pattern for all 5 team agents in the session:
# a712f607… (reuse-reviewer)    — start only, no stop
# a912c5cf… (quality-reviewer)  — start only, no stop
# ab21e051… (efficiency-reviewer) — start only, no stop
# aacd2d97… (resilience-architect) — start only, no stop
# ad43c619… (test-architect)    — start only, no stop

This is a team-specific code path issue, not the general SubagentStop unreliability described in #27755.

[todd-w-shaffer]

Additional finding: shutdown protocol bypass affects hook-driven state

The missing SubagentStop on the shutdown protocol path has a compounding effect beyond missed events. Any system that tracks agent count via SubagentStart/SubagentStop pairs — including Claude Code's own hook infrastructure — will accumulate phantom agents that never decrement.

In our testing, this caused SubagentStart hooks that read agent count to make incorrect decisions for the remainder of the session, since their count inputs were permanently inflated by terminated-but-untracked agents.

The distinguishing signal for debugging: in the same session, SubagentStop fires correctly for every Agent tool subagent that completes normally. It only fails for agents that terminate via shutdown_request → shutdown_approved. This points to a specific code path in the team agent shutdown handler that doesn't call the same hook dispatch as normal agent completion.

Minimal repro narrowed to one variable:

1. Spawn agent A via Agent tool (no team) → SubagentStart fires, agent completes → SubagentStop fires ✓
2. Spawn agent B via Agent tool with team_name → SubagentStart fires, send shutdown_request, receive shutdown_approved → SubagentStop never fires ✗

Same hook config, same session, same matcher (.*). The only variable is the termination path.

[todd-w-shaffer]

Shameless plug — coolant is the thermal dashboard that surfaced this bug. The orphaned team agents were visible as breathing hexagons that never stopped. We've since added stale-agent dimming so orphaned dots fade to ~35% brightness after 3 minutes, making the missing SubagentStop events immediately obvious at a glance.

[yurukusa]

Your root cause analysis is spot on — the shutdown protocol handler bypasses the hook dispatcher that normal agent completion uses.

Alternative workaround: PostToolUse hook on SendMessage

Since teammate_terminated system messages do appear (as you noted), and SendMessage is the tool used to communicate with team agents, you can use a PostToolUse hook on SendMessage to detect shutdown completion and synthetically handle cleanup:

#!/bin/bash
# team-agent-stop-synthetic.sh
# PostToolUse hook — detects team agent shutdown and triggers cleanup
# TRIGGER: PostToolUse
# MATCHER: SendMessage

INPUT=$(cat)
RESULT=$(echo "$INPUT" | jq -r '.tool_result // empty' 2>/dev/null)

# Check if the SendMessage response indicates shutdown
if echo "$RESULT" | grep -qi 'shutdown_approved\|teammate_terminated\|agent.*shut.*down'; then
  AGENT_ID=$(echo "$INPUT" | jq -r '.tool_input.to // empty' 2>/dev/null)
  TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  # Log synthetic stop event
  echo "{\"ts\":\"$TIMESTAMP\",\"event\":\"agent.stop.synthetic\",\"agent_id\":\"$AGENT_ID\",\"reason\":\"shutdown_protocol\"}" >> /tmp/agent-lifecycle.jsonl

  # Signal to your tracking system
  echo "Team agent $AGENT_ID terminated via shutdown protocol (synthetic stop)" >&2
fi

exit 0

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "SendMessage",
      "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/team-agent-stop-synthetic.sh"}]
    }]
  }
}

This catches the termination at the moment shutdown_approved comes back, rather than waiting for a staleness timeout. The tradeoff is that it depends on the response text containing recognizable shutdown keywords — your 3-minute staleness approach in coolant is more robust as a fallback.

Both approaches could complement each other: the hook for immediate detection, staleness dimming for any edge cases the hook misses.