[DOCS] Clarify Stop vs SubagentStop hook behavior in global settings vs component frontmatter

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/hooks https://code.claude.com/docs/en/sub-agents

Section/Topic

The "Hooks in Skills, Agents, and Slash Commands" section in hooks.md and the "Hooks in subagent frontmatter" section in sub-agents.md.

Current Documentation

In docs/en/sub-agents, under "Hooks in subagent frontmatter", the documentation states:

"Stop hooks in frontmatter are automatically converted to SubagentStop events."

However, in docs/en/hooks, under "Hook Events", Stop and SubagentStop are listed as distinct events:

Stop: Runs when the main Claude Code agent has finished responding. SubagentStop: Runs when a Claude Code subagent (Task tool call) has finished responding.

What's Wrong or Missing?

The documentation is inconsistent regarding the usage of Stop versus SubagentStop. While it explains that Stop in an agent's frontmatter translates to SubagentStop, the main configuration section implies they are entirely separate events without explaining the relationship or scope.

Users defining hooks in settings.json might mistakenly define a Stop hook expecting it to catch subagent events, or mistakenly use SubagentStop inside a component's frontmatter where Stop is expected. The distinction that Stop applies to the main agent in global settings, but applies to the specific agent in frontmatter settings, needs to be explicit to prevent configuration errors.

Suggested Improvement

Add a clarification note in the "Hook Events" or "Stop/SubagentStop Decision Control" section of docs/en/hooks.

Suggested text:

Note on Scope: Global Settings (settings.json): Stop hooks only trigger for the main agent loop. To catch subagents stopping, you must explicitly use the SubagentStop event. Component Frontmatter (Agents/Skills): Inside a component's definition, you define a Stop hook. Claude Code automatically maps this to a SubagentStop event scoped specifically to that component's execution.

Impact

High - Prevents users from using a feature

Additional Context

Severity: Minor. This primarily affects users attempting advanced hook configurations for custom agents.