[DOCS] Subagent frontmatter hooks docs still say `--agent` sessions do not trigger them

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Hooks in subagent frontmatter

Current Documentation

The docs currently say:

Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes. Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention. They do not fire when the agent runs as the main session via --agent or the agent setting. For session-wide hooks, configure them in settings.json.

What's Wrong or Missing?

This section still describes the pre-v2.1.116 behavior.

Changelog v2.1.116 says: Agent frontmatter hooks: now fire when running as a main-thread agent via --agent.

That directly contradicts the current note on the sub-agents page, which still tells users that frontmatter hooks do not fire when the agent runs as the main session via --agent or the agent setting.

As written, the docs send users to settings.json for a case that is now supported in agent frontmatter, so anyone trying to configure hook behavior for claude --agent <name> sessions gets outdated guidance.

Suggested Improvement

Update the note in Hooks in subagent frontmatter to reflect the current behavior introduced in v2.1.116.

At minimum, the page should now say that frontmatter hooks also fire when the whole session runs with claude --agent <name> or the agent setting.

It would also help to clarify any event-specific differences between:

• an agent spawned as a subagent via the Agent tool or an @-mention
• an agent running as the main-thread session via --agent

For example, if Stop is only remapped to SubagentStop for spawned subagents, that distinction should be stated explicitly.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 510-514 | The note explicitly says frontmatter hooks do not fire when the agent runs as the main session via --agent or the agent setting. |

Total scope: 1 page affected

Source: Changelog v2.1.116 — https://code.claude.com/docs/en/changelog

Relevant changelog entry:

Agent frontmatter hooks: now fire when running as a main-thread agent via --agent