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

  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

  • #7881 — SubagentStop session_id sharing (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)

View original on GitHub ↗

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