[DOCS] Missing `once` property in primary Hook Configuration Structure reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

The Configuration > Structure section of the Hooks reference.

Current Documentation

The "Structure" section provides the following JSON schema and field descriptions:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

- hooks: Array of hooks to execute when the pattern matches - type: Hook execution type - "command" for bash commands or "prompt" for LLM-based evaluation - command: (For type: "command") The bash command to execute (can use $CLAUDE_PROJECT_DIR environment variable) - prompt: (For type: "prompt") The prompt to send to the LLM for evaluation - timeout: (Optional) How long a hook should run, in seconds, before canceling that specific hook

What's Wrong or Missing?

The documentation omits the once property from the primary configuration schema.

While the once property is mentioned later in the page under the sub-section "Hooks in Skills, Agents, and Slash Commands," it is missing from the main "Structure" section which defines how hooks are formatted in settings.json. As of version 2.1.0, the once property is a supported feature for hooks to prevent repeated execution in a single session, but a user looking at the main reference would not know it is a valid key for the hook object.

Suggested Improvement

Add the once property to the example JSON block and the list of hook object fields in the "Structure" section.

Updated JSON Example:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "once": true
          }
        ]
      }
    ]
  }
}

Updated Field Description:

• once: (Optional) Set to true to run the hook only once per session. After the first successful execution, the hook is removed for the remainder of the session.

Impact

High - Prevents users from using a feature

Additional Context

• This feature was explicitly added/stabilized in version 2.1.0.
• Centralizing this property in the main "Structure" section ensures users know it is available for project-level and user-level settings.json configurations, not just for Skills and Slash Commands.