Subagent (Agent tool) does not fire Stop hook on completion

[kok1eee]

Description

When a subagent spawned via the Agent tool (or TeammateTool) completes and returns results to the parent agent, no Stop hook is fired. Other lifecycle hooks (UserPromptSubmit, PreToolUse, PostToolUse) fire correctly for the subagent with its own session_id, but the completion event is missing.

Steps to reproduce

1. Configure a Stop hook in .claude/settings.json that logs session_id
2. Spawn a subagent via the Agent tool (e.g., subagent_type: "Explore")
3. Wait for the subagent to complete and return results to the parent
4. Observe that the Stop hook fires for the parent session but never fires for the subagent session

Expected behavior

When a subagent completes (returns results to parent), a Stop hook should fire with the subagent's session_id, allowing external tools to detect session lifecycle completion.

Actual behavior

• Subagent fires UserPromptSubmit and PreToolUse hooks → external tools register a new session
• Subagent completes → no Stop hook → external tools see a "ghost session" that never ends
• Ghost sessions accumulate over time

Impact

Hook-based external tools (session monitors, sidebars, etc.) cannot distinguish between:

• A subagent that is still running
• A subagent that has completed

This leads to ghost sessions accumulating in any tool that tracks sessions via hooks.

Environment

• Claude Code version: 2.1.x (latest)
• OS: macOS (Darwin)
• Hooks used: Stop (shell script)

Related issues

• SubagentStop hook cannot identify which specific subagent finished due to shared session IDs #7881 — SubagentStop session_id sharing (different: about ID collision, not missing events)
• [BUG] Task tool subagent processes not terminated after parent session ends (Linux) #19045 — Orphaned processes after parent ends (different: about process cleanup, not hook lifecycle)
• Stop hook not fired when Claude stalls mid-turn after tool result (silent tool stop) #29881 — Stop hook not fired on silent tool stop (related but about mid-turn stalls, not subagent completion)

[github-actions]

Found 2 possible duplicate issues:

1. Background agents bypass Stop hooks #25147
2. [BUG] SubagentStart/SubagentStop unreliable for settings.json hooks — cascade failures break agent lifecycle management #27755

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

[theQuert]

This is a real pain point — our cc-reaper Stop hook relies on exactly this lifecycle event, and the fact that subagents don't fire it means Layer 1 cleanup only covers the parent session.

Our workaround: PGID-based process group cleanup. Since Claude Code sessions are process group leaders, the parent session's Stop hook can kill -- -$PGID to clean up the entire process tree — including subagent children that never fired their own Stop hook. This sidesteps the missing subagent Stop event entirely.

For crash scenarios where no Stop hook fires at all, we fall back to a background daemon (proc-janitor) that scans every 30s for orphaned process groups.

git clone https://github.com/theQuert/cc-reaper.git && cd cc-reaper && bash install.sh

Would love to see this fixed upstream though — proper subagent lifecycle hooks would make community tooling much more reliable.

[tazawa-masayoshi]

Closing as duplicate of #27755 and #25147, which cover this problem more comprehensively.

Our specific observation (foreground Agent tool / TeammateTool subagents also don't fire Stop hooks on completion — not just run_in_background agents) is a subset of the same root cause described in #27755.

Thanks to the authors of those issues for the detailed analysis and workaround documentation.

[kok1eee]

Closing as duplicate of #27755 and #25147, which cover this problem more comprehensively.

Our specific observation (foreground Agent tool / TeammateTool subagents also don't fire Stop hooks on completion — not just run_in_background agents) is a subset of the same root cause described in #27755.

Thanks to the authors of those issues for the detailed analysis and workaround documentation.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.