[DOCS] Inconsistent documentation regarding `once: true` support for Agent hooks

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/hooks#hooks-in-skills-agents-and-slash-commands - https://code.claude.com/docs/en/sub-agents#hooks-in-subagent-frontmatter

Section/Topic

The configuration of lifecycle hooks within custom subagents, specifically the availability of the once: true execution flag.

Current Documentation

In hooks.md:

"Additional option for skills and slash commands: once: Set to true to run the hook only once per session. After the first successful execution, the hook is removed. Note: This option is currently only supported for skills and slash commands, not for agents."

In sub-agents.md:
The example code for a code-reviewer agent explicitly includes the flag:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
          once: true

What's Wrong or Missing?

There is a direct contradiction between the reference documentation and the feature guide. The Hooks reference states that once: true is specifically not supported for agents, while the Sub-agents guide uses it as a primary code example for agent-scoped hooks. This leaves the user unsure if the feature is implemented for agents or if the example provided will fail/be ignored.

Suggested Improvement

1. Verify Functionality: Determine if the once flag is actually supported in the Subagent runner.
2. Align Documentation:

• If once: true is supported for agents: Remove the restrictive note in hooks.md.
• If once: true is not supported for agents: Remove once: true from the code example in sub-agents.md to avoid leading users into non-functional configurations.

Impact

High - Prevents users from using a feature

Additional Context

This inconsistency appears to be a result of the rapid evolution of the hooks system across different component types (Skills, Commands, and Agents). Ensuring parity or clearly documented limitations is critical for users building automated verification workflows.