Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Subagent frontmatter hooks docs still say `--agent` sessions do not trigger them

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
RAW_BUFFERClick to expand / collapse

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:

PageLine(s)Context
https://code.claude.com/docs/en/sub-agents510-514The 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

extent analysis

TL;DR

Update the documentation for "Hooks in subagent frontmatter" to reflect the current behavior introduced in v2.1.116, where frontmatter hooks also fire when the whole session runs with claude --agent <name> or the agent setting.

Guidance

  • Review the changelog entry for v2.1.116 to understand the updated behavior of frontmatter hooks.
  • Update the note in the "Hooks in subagent frontmatter" section to remove the contradiction and provide accurate information.
  • Consider adding clarification on event-specific differences between agents spawned as subagents and those running as main-thread sessions.
  • Verify the changes by checking the documentation and testing the behavior of frontmatter hooks in different scenarios.

Example

No code snippet is necessary for this issue, as it is related to documentation updates.

Notes

The update should be made to the "Hooks in subagent frontmatter" section on the affected page (https://code.claude.com/docs/en/sub-agents), specifically lines 510-514.

Recommendation

Apply workaround: Update the documentation to reflect the current behavior, as the outdated information is causing confusion and making the feature difficult to understand. This will ensure that users receive accurate guidance on configuring hook behavior for claude --agent <name> sessions.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#SSR setup#ISR setup#authentication setup#request error#file not found

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Subagent frontmatter hooks docs still say `--agent` sessions do not trigger them