[DOCS] Subagent docs omit the workspace-trust requirement for agent frontmatter hooks

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

“Define hooks for subagents,” especially hooks declared in an agent markdown file’s frontmatter.

Current Documentation

The section currently says:

Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via --agent or the agent setting.

It then says:

All hook events are supported.

The section does not say that the agent file’s own folder must be covered by accepted workspace trust before those hooks can run.

What's Wrong or Missing?

Claude Code 2.1.218 fixed agent frontmatter hooks running from untrusted folders: the hooks now require the agent file’s own folder to have accepted workspace trust.

The current documentation presents frontmatter hooks as running whenever the agent is spawned, without explaining this trust boundary. A repository or user may define an agent whose instructions are trusted but whose hook commands are not, and the docs give no explanation for why the hook does not run until the folder is trusted.

Suggested Improvement

Add a security note to the frontmatter-hooks section stating that Claude Code runs an agent’s frontmatter hooks only when the folder containing that agent file is covered by an accepted workspace-trust decision. Explain how project, user, and plugin agent locations are evaluated, and link to the workspace-trust section of the permissions documentation.

Include a short troubleshooting example: if the agent runs but its frontmatter hook does not, open the agent from the relevant folder, accept workspace trust, and retry. Clarify that this requirement applies to the hook command and does not change the agent’s ordinary prompt or tool behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Agent frontmatter hook execution |
| https://code.claude.com/docs/en/hooks | Hook trust and execution model |
| https://code.claude.com/docs/en/permissions | Workspace trust and accepted-folder scope |

Total scope: 3 pages should describe the same hook trust boundary.

The behavior was changed in Claude Code v2.1.218.