[DOCS] Hooks reference missing `async` configuration option

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Configuration" section, specifically the "Structure" subsection that documents hook configuration fields.

Current Documentation

The docs list these hook configuration fields:

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

The async option is not documented.

What's Wrong or Missing?

The async configuration option for hooks is not documented. This option allows hooks to run in the background without blocking Claude Code's execution—useful for logging, notifications, or other side-effects that shouldn't slow down the agentic loop.

Example configuration that works but isn't documented:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./my-analysis.sh",
        "async": true,
        "timeout": 30
      }]
    }]
  }
}

Suggested Improvement

Add async to the documented fields list in the "Structure" subsection:

After the existing timeout bullet, add:

* async: (Optional) When true, the hook runs in the background without blocking Claude Code's execution. Useful for logging, notifications, or side-effects that shouldn't slow down the workflow. Default: false

Optionally add a use case note:

Tip: Use async: true for hooks that perform logging, send notifications, or have other side effects that don't need to block Claude's execution.

Impact

Medium - Makes feature difficult to understand

Users cannot discover this feature through the documentation. They must find it through external sources (announcements, community discussions) or trial and error.

Additional Context

Source: Feature announced by Claude Code developer @bcherny on X: https://x.com/bcherny/status/2015524460481388760

Affected Pages:
| Page | Section | Notes |
|------|---------|-------|
| https://code.claude.com/docs/en/hooks | Configuration > Structure | Primary location where hook fields are documented |
| https://code.claude.com/docs/en/hooks-guide | Quickstart examples | Could benefit from an async example |

Total scope: 2 pages affected

Cross-reference: The hooks reference already documents timeout as an optional field—async follows the same pattern and should be documented alongside it.