[BUG] Agent Stop hook receives "SubagentStop" instead of "Stop" as hook_event_name

Open 💬 2 comments Opened Jan 19, 2026 by shanraisshan

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?

When defining a Stop hook in an agent's frontmatter (feature introduced in 2.1.0), the hook_event_name passed to the hook script is "SubagentStop" instead of "Stop".

This contradicts the official documentation and breaks consistency with other agent hooks (PreToolUse and PostToolUse), which correctly pass their configured names.

Agent Configuration Example:

---
name: my-agent
hooks:
  Stop:
    - hooks:
    -         - type: command
    -           command: echo "$HOOK_INPUT" >> /tmp/hook-debug.log
    -           timeout: 5000
    - ---
    - ```
**Expected `hook_event_name`:** `"Stop"`
**Actual `hook_event_name`:** `"SubagentStop"`

| Hook | Defined As | Received As | Status |
|------|------------|-------------|--------|
| PreToolUse | `PreToolUse:` | `"PreToolUse"` | Correct |
| PostToolUse | `PostToolUse:` | `"PostToolUse"` | Correct |
| Stop | `Stop:` | `"SubagentStop"` | Inconsistent |

### What Should Happen?

When a `Stop` hook is defined in agent frontmatter, the `hook_event_name` should be `"Stop"` to match:

1. The configuration key in the frontmatter (`Stop:`)
2. 2. The official documentation
3. 3. The behavior of other agent hooks (`PreToolUse` and `PostToolUse` correctly pass their configured names)

### Error Messages/Logs

```shell

Steps to Reproduce

  1. Create an agent file .claude/agents/test-agent.md with a Stop hook:
  2. ```yaml
  3. ---
  4. name: test-agent
  5. hooks:
  6. Stop:
  7. - hooks:
  8. - type: command
  9. command: echo "$HOOK_INPUT" >> /tmp/hook-debug.log
  10. timeout: 5000
  11. ---
  12. Test agent instructions
  13. ```
  14. Spawn the agent using the Task tool
  15. Let the agent complete its work
  16. Check the logged JSON input in /tmp/hook-debug.log
  17. Observe that hook_event_name is "SubagentStop" instead of "Stop"

Claude Model

None

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.0+ (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Workaround:

if hook_event_name == "SubagentStop":
    hook_event_name = "Stop"

This bug was discovered while implementing voice hooks for agents. The workaround maps SubagentStop back to Stop before processing, but this shouldn't be necessary since the frontmatter defines Stop: not SubagentStop:.

View original on GitHub ↗

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