Subagent (Agent tool) does not fire Stop hook on completion
Resolved 💬 5 comments Opened Mar 11, 2026 by kok1eee Closed Mar 11, 2026
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
- Configure a Stop hook in
.claude/settings.jsonthat logssession_id - Spawn a subagent via the Agent tool (e.g.,
subagent_type: "Explore") - Wait for the subagent to complete and return results to the parent
- 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
UserPromptSubmitandPreToolUsehooks → 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
- #7881 — SubagentStop
session_idsharing (different: about ID collision, not missing events) - #19045 — Orphaned processes after parent ends (different: about process cleanup, not hook lifecycle)
- #29881 — Stop hook not fired on silent tool stop (related but about mid-turn stalls, not subagent completion)
This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗