[BUG] session summary/prompt-based hook recursion, docs contradictory

[kierr]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Dear Claude,

1. SessionStart events trigger session summaries before any user input
2. Those brand-spanking-new (and awesome) events trigger SubagentStop hooks
3. Any (incl. prompt-based) SubagentStop hooks start spiralling...
4. All 'internal' prompting events trigger more UserPromptSubmit hooks
5. Any (incl. prompt-based) UserPromptSubmit hooks spiral as well...

...leading to cascading recursive implosion!

Scoping internals via origin may be a wise move; perhaps a stop_hook_active-esque for prompt-based hooks? Otherwise a depth counter, parentId chaining, etc.

Additionally, docs are contradictory: "only supported for Stop and SubagentStop"1 vs. "Prompt-based hooks work with any hook event, but are most useful for [...] Stop/SubagentStop/UserPromptSubmit/PreToolUse"2

Love, Human

What Should Happen?

Session Summary, Session Memory, prompt-based hook magic

Error Messages/Logs

Steps to Reproduce

sequenceDiagram
  autonumber
  participant App as "Claude Code"
  participant Hooks as "Hook Engine"
  participant Model as "LLM"

  Note over App,Model: Hook recursion bug

  %% Session Start
  App->>Hooks: SessionStart
  Hooks->>Model: Generate session summaries (b9I/WY)
  Model-->>Hooks: N summaries created

  %% Subagent lifecycle
  loop For each summary
    Hooks->>Hooks: SubagentStart
    Hooks->>Model: Background subagent work
    Model-->>Hooks: Completed

    %% Bug: SubagentStop triggers prompt hook
    Hooks->>Hooks: SubagentStop → prompt hook fires

    %% Prompt hook execution
    Note over Hooks,Model: Prompt hook runs and emits a non-user UserPromptSubmit
    Hooks->>Model: Evaluate prompt condition
    Model-->>Hooks: Response

    %% Recursion loop
    loop Recursive loop
      Hooks->>Hooks: UserPromptSubmit (non-user)
      Hooks->>Model: Evaluate (prompt hook)
      Model-->>Hooks: Response
    end
  end

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.0.36

Claude Code Version

2.0.37

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

No response

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/10205
2. https://github.com/anthropics/claude-code/issues/9682
3. https://github.com/anthropics/claude-code/issues/2956

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

[kierr]

@dicksontsai 🔔 🙏

[kylesnowschwartz]

@kierr Thanks for raising this I was looking into using these hooks myself. Can you confirm that you're still seeing this issue? Would you mind describing your specific use case?

Edit: Regarding the contradictory docs - which do you observe to be correct? Are prompt based hooks truly stop/subagentstop only? Or actually work for other hooks?

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.