[BUG] Agent frontmatter hooks: changelog (v2.1.0) says 3, official docs say "all", but only 6 of 16 actually fire

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?

The v2.1.0 changelog states agent frontmatter hooks support only 3 hooks:

"Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle"

Meanwhile, the official hooks docs says "All hook events are supported" in frontmatter.

Neither statement is accurate. Testing confirms exactly 6 of 16 hooks actually fire in agent sessions:

| Hook | Fires in agent? |
|------|:-:|
| PreToolUse | Yes |
| PostToolUse | Yes |
| PermissionRequest | Yes |
| PostToolUseFailure | Yes |
| Stop | Yes |
| SubagentStop | Yes |

The remaining 10 hooks (Notification, PreToolUseRejected, SubagentStart, etc.) do not fire in agent contexts.

How I tested

1. Created an agent .md file with all 6 hooks configured in frontmatter
2. Ran the agent and performed actions that trigger each hook type:

• Read a file (PreToolUse + PostToolUse)
• Wrote a file (PreToolUse + PostToolUse + PermissionRequest)
• Ran a bash command (PreToolUse + PostToolUse + PermissionRequest)
• Read a non-existent file (PostToolUseFailure)
• Completed agent session (Stop + SubagentStop)

1. All 6 hooks fired as expected

Expected

The changelog and/or documentation should clarify that 6 hooks are supported in agent frontmatter — not 3 (changelog) and not "all" (official docs).

What Should Happen?

The changelog and official documentation should accurately state that 6 hooks are supported in agent frontmatter: PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop, and SubagentStop.

Currently the changelog says 3 and the official docs say "all" — neither is correct.

Error Messages/Logs

No error — this is a documentation accuracy issue, not a runtime bug.

Steps to Reproduce

1. Create an agent file .claude/agents/test-agent.md with all 6 hooks configured in frontmatter:

```yaml
hooks:
PreToolUse:

• matcher: ".*"

hooks:

• type: command

command: "echo PreToolUse fired"
PostToolUse:

• matcher: ".*"

hooks:

• type: command

command: "echo PostToolUse fired"
PermissionRequest:

• matcher: ".*"

hooks:

• type: command

command: "echo PermissionRequest fired"
PostToolUseFailure:

• hooks:
• type: command

command: "echo PostToolUseFailure fired"
Stop:

• hooks:
• type: command

command: "echo Stop fired"
SubagentStop:

• hooks:
• type: command

command: "echo SubagentStop fired"
```

1. Run the agent: /agents test-agent
2. Have the agent perform: a file read, a file write (triggers PermissionRequest), a read of a non-existent file (triggers PostToolUseFailure), then complete
3. Observe all 6 hooks fire — not just the 3 documented in the changelog

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.49 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

This is a documentation accuracy issue, not a runtime bug. The hooks themselves work correctly — the problem is that the changelog understates the number of supported agent hooks (says 3) while the official docs overstate it (says "all").

Reference repo with test agent: https://github.com/anthropics/claude-code (tested with a custom agent using hooks in frontmatter)