[DOCS] Hooks docs omit `defer` `PreToolUse` decision for headless `--resume`

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

PreToolUse decision control, especially the new permissionDecision: "defer" behavior for headless -p sessions and the --resume workflow for deferred tool calls

Current Documentation

The hooks reference currently says:

PreToolUse hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level decision field, PreToolUse returns its decision inside a hookSpecificOutput object. This gives it richer control: three outcomes (allow, deny, or ask) plus the ability to modify tool input before execution.

permissionDecision | "allow" skips the permission prompt. "deny" prevents the tool call. "ask" prompts the user to confirm.

The hooks guide repeats the same three-option model:

Claude Code reads permissionDecision and cancels the tool call, then feeds permissionDecisionReason back to Claude as feedback. These three options are specific to PreToolUse: "allow": skip the interactive permission prompt. Deny and ask rules, including enterprise managed deny lists, still apply "deny": cancel the tool call and send the reason to Claude * "ask": show the permission prompt to the user as normal

The headless docs currently describe --resume only generically:

Use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation.

The permissions page likewise says only:

The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed.

What's Wrong or Missing?

Changelog v2.1.89 added a fourth PreToolUse permission decision:

Added "defer" permission decision to PreToolUse hooks — headless sessions can pause at a tool call and resume with -p --resume to have the hook re-evaluate

The published docs still describe PreToolUse as a three-outcome API (allow, deny, ask). That is now outdated.

A. The hooks reference does not document permissionDecision: "defer"

There is no reference entry explaining that defer is valid, when a hook should return it, or what Claude Code does with the pending tool call.

B. The headless workflow is undocumented

No current page explains that a headless claude -p session can pause at a deferred tool call, then be resumed later with claude -p --resume <session-id> so the same PreToolUse hook can run again after external state changes.

Without that documentation, headless integrators have to infer the feature from the changelog alone.

Suggested Improvement

Update the hooks and headless docs together:

1. In https://code.claude.com/docs/en/hooks, expand PreToolUse decision control to include permissionDecision: "defer" alongside allow, deny, and ask.
2. Add a short example showing a hook deferring a tool call until some external prerequisite is satisfied.
3. In https://code.claude.com/docs/en/hooks-guide and https://code.claude.com/docs/en/permissions, update the prose that currently describes only three PreToolUse outcomes.
4. In https://code.claude.com/docs/en/headless and https://code.claude.com/docs/en/cli-reference, document the deferred-tool workflow:

• headless run reaches a PreToolUse hook
• hook returns permissionDecision: "defer"
• the session is resumed later with claude -p --resume <session-id>
• the hook is re-evaluated before the tool call continues

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/hooks | 958-964 | PreToolUse decision control says there are only three outcomes and lists only allow, deny, and ask |
| https://code.claude.com/docs/en/hooks-guide | 492-498 | Guide repeats the three-option PreToolUse model |
| https://code.claude.com/docs/en/permissions | 201-205 | Permissions page says hooks can deny, force a prompt, or skip the prompt |
| https://code.claude.com/docs/en/headless | 177-193 | Headless docs explain generic --resume usage but not deferred tool-call continuation |
| https://code.claude.com/docs/en/cli-reference | 84 | --resume flag reference does not mention resuming a deferred headless tool call |

Total scope: 5 pages affected

Source: Changelog v2.1.89

Changelog entry:

Added "defer" permission decision to PreToolUse hooks — headless sessions can pause at a tool call and resume with -p --resume to have the hook re-evaluate