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

Resolved 💬 12 comments Opened Apr 8, 2026 by todd-w-shaffer Closed Apr 18, 2026

Summary

When a team agent (teammate) terminates via the shutdown_requestshutdown_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_requestshutdown_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.

View original on GitHub ↗

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