Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Hook events and the decision-control documentation for permission-related hooks

Current Documentation

No documentation currently exists for the PermissionDenied hook.

The hooks reference currently lists these lifecycle events:

| SessionStart | When a session begins or resumes |
| UserPromptSubmit | When you submit a prompt, before Claude processes it |
| PreToolUse | Before a tool call executes. Can block it |
| PermissionRequest | When a permission dialog appears |
| PostToolUse | After a tool call succeeds |
| PostToolUseFailure | After a tool call fails |
| Notification | When Claude Code sends a notification |
| SubagentStart | When a subagent is spawned |
| SubagentStop | When a subagent finishes |
| SessionEnd | When a session terminates |

The same page's decision summary currently documents PreToolUse and PermissionRequest, but nothing for a post-denial retry hook:

| PreToolUse | hookSpecificOutput | permissionDecision (allow/deny/ask) |
| PermissionRequest | hookSpecificOutput | decision.behavior (allow/deny) |
| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |

The auto mode docs describe the behavior that this new hook is meant to intercept:

The fallback design keeps false positives from derailing a session: a mistaken block costs Claude a retry, not your progress.

What's Wrong or Missing?

Changelog v2.1.88 added a new hook:

Added PermissionDenied hook that fires after auto mode classifier denials — return {retry: true} to tell the model it can retry

The published docs still do not describe that hook anywhere outside the changelog.

That leaves three important gaps:

A. The event is not discoverable

The hook event tables omit PermissionDenied, so readers looking at the hooks reference, hooks guide, or plugin hook docs will not know the event exists.

B. The retry response contract is undocumented

The changelog mentions {retry: true}, but the hooks docs do not explain that this is the control surface for the new event, what happens if it is omitted, or how it differs from PreToolUse and PermissionRequest decisions.

C. The auto mode connection is undocumented

The permission docs explain that classifier false positives cost Claude a retry, but they do not connect that behavior to a hook users can customize after a denial.

Suggested Improvement

Add PermissionDenied to the hook event tables on the hook-related pages, then add a dedicated section on the hooks reference page that covers:

1. When the event fires: after an auto mode classifier denial
2. The full input schema for the event
3. The output contract, including a minimal example that returns {retry: true}
4. What Claude does when retry is omitted or set to false
5. Any scope or mode limitations, especially how this interacts with auto mode fallback behavior

The hooks guide should also add a short example for a false-positive denial workflow, and the plugin hooks reference should list PermissionDenied anywhere it says plugins support the same lifecycle events as user-defined hooks.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Relevant cross-reference:

Source: Changelog v2.1.88

Changelog entry:

Added PermissionDenied hook that fires after auto mode classifier denials — return {retry: true} to tell the model it can retry