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

[coygeek]

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

[coygeek]

Issue #41791 Verification

Title: [DOCS] Hooks docs omit defer PreToolUse decision for headless --resume
Issue Date: 2026-04-01
Verification Date: 2026-04-27
Status: RESOLVED

---

Issue Summary

The issue reported that the permissionDecision: "defer" option for PreToolUse hooks (added in v2.1.89) was not documented across five docs pages, which only described three outcomes (allow, deny, ask).

---

Verification Results

Claim 1: hooks.md does not document permissionDecision: "defer"

Status: RESOLVED

The hooks reference now thoroughly documents defer:

• hooks.md:1072 — "four outcomes (allow, deny, ask, or defer)"
• hooks.md:1076 — "defer" described in the permissionDecision field table: "exits gracefully so the tool can be resumed later"
• hooks.md:1081 — Precedence rule includes defer: deny > defer > ask > allow
• hooks.md:666 — Summary table lists permissionDecision (allow/deny/ask/defer)
• hooks.md:962 — PreToolUse section: "allow, deny, ask, or defer the tool call"
• hooks.md:1105-1145 — Dedicated section "Defer a tool call for later" with full round-trip workflow (5 steps), deferred_tool_use payload example, timeout/retry behavior, single-call constraint, unavailable-tool handling, and permission-mode warning

Verdict: The hooks reference now has comprehensive defer documentation including the headless --resume workflow.

Claim 2: hooks-guide.md repeats only the three-option model

Status: RESOLVED

hooks-guide.md:539 now states: "A fourth value, "defer", is available in non-interactive mode with the -p flag. It exits the process with the tool call preserved so an Agent SDK wrapper can collect input and resume. See [Defer a tool call for later] in the reference."

Verdict: The guide explicitly mentions defer as a fourth option and links to the full reference.

Claim 3: permissions.md says hooks can only deny, force a prompt, or skip the prompt

Status: MOSTLY RESOLVED

permissions.md:232 still reads: "The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed." This omits defer. However, defer is exclusively a non-interactive/headless feature and the permissions page focuses on interactive permission management. The hooks-guide (which permissions.md links to) now covers defer explicitly.

Verdict: Minor wording gap remains but is not misleading — defer is irrelevant to the interactive permission flow this page describes.

Claim 4: headless.md does not document the deferred tool-call workflow

Status: RESOLVED

headless.md still only describes generic --resume usage (lines 202-217). However, the hooks reference (hooks.md:1105-1145) now contains a comprehensive "Defer a tool call for later" section that documents the complete headless defer/resume workflow, and the hooks-guide links to it. The information is well-covered in the canonical location.

Verdict: The workflow is documented in the hooks reference. A cross-reference from the headless page would be nice but the information is not missing.

Claim 5: cli-reference.md --resume flag does not mention deferred tool calls

Status: MOSTLY RESOLVED

cli-reference.md:90 describes --resume generically. The deferred tool-call resume workflow is comprehensively documented in hooks.md:1105-1145 instead.

Verdict: The --resume flag is a general-purpose feature used for many scenarios. The defer-specific resume workflow is documented in the appropriate location (hooks reference).

---

Current State

Claim	Status
hooks.md omits defer	RESOLVED
hooks-guide.md only shows three options	RESOLVED
permissions.md omits defer	MOSTLY RESOLVED (minor wording gap, not misleading)
headless.md omits defer/resume workflow	RESOLVED (documented in hooks reference)
cli-reference.md --resume omits defer	MOSTLY RESOLVED (documented in hooks reference)

---

Suggested Fix

N/A — issue has been resolved. The primary documentation gaps have been addressed with comprehensive coverage in the hooks reference and explicit mention in the hooks guide.

---

References

• https://code.claude.com/docs/en/hooks — PreToolUse decision control and "Defer a tool call for later" section
• https://code.claude.com/docs/en/hooks-guide — Mentions defer as fourth option with link to reference
• https://code.claude.com/docs/en/permissions — Hooks and permissions (interactive focus)
• https://code.claude.com/docs/en/headless — Generic --resume usage
• https://code.claude.com/docs/en/cli-reference — --resume flag reference

---

Conclusion & Recommendation

Primary Concern: The defer PreToolUse decision was undocumented at time of filing.

Resolution Status: RESOLVED

Recommendation: CLOSE

The hooks reference now has a comprehensive "Defer a tool call for later" section covering the full round-trip workflow, and the hooks guide explicitly calls out defer as a fourth option. Minor wording gaps on the permissions and headless pages are tangential — the canonical documentation is thorough and accurate.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.