[DOCS] PermissionRequest hook docs omit deny-rule and bypass-mode policy caveats

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

PermissionRequest → "PermissionRequest decision control" and "Permission update entries"

Current Documentation

The PermissionRequest reference currently says:

updatedInput | For "allow" only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones

updatedPermissions | For "allow" only: array of permission update entries to apply, such as adding an allow rule or changing the session permission mode

setMode | Changes the permission mode. Valid modes are default, acceptEdits, dontAsk, bypassPermissions, and plan

The guide page also says:

The mode value is any permission mode like default, acceptEdits, or bypassPermissions, and destination: "session" applies it for the current session only.

The permissions docs separately say:

To prevent bypassPermissions or auto mode from being used, set permissions.disableBypassPermissionsMode or permissions.disableAutoMode to "disable" in any settings file.

What's Wrong or Missing?

The PermissionRequest docs do not say that these hook-driven updates are still constrained by policy checks after the hook returns.

A. updatedInput lacks an explicit deny-rule caveat

The hook reference explains how to rewrite tool input, but it does not say the rewritten input is re-evaluated against permissions.deny before execution. Claude Code v2.1.110 explicitly fixed this path for PermissionRequest hooks that return updatedInput, so the hook docs should state that a rewrite does not bypass deny rules.

B. setMode: "bypassPermissions" lacks an explicit policy caveat

The hook docs say setMode can switch to bypassPermissions, but they do not say that this update is blocked when permissions.disableBypassPermissionsMode is set to "disable". v2.1.110 fixed this enforcement path too.

As written, the hook pages make it easy to assume PermissionRequest can always apply these updates once it returns "allow", even though active permission policy still wins.

Suggested Improvement

Add a short note under PermissionRequest decision control and mirror it in the guide example:

• updatedInput is validated again against permission rules after the hook returns. Matching permissions.deny rules still block execution, and matching ask rules still prompt.
• updatedPermissions entries of type setMode are validated against active policy settings. setMode: "bypassPermissions" should mention that it is rejected when permissions.disableBypassPermissionsMode is "disable".
• Link these notes to the main permissions documentation so readers do not have to infer the interaction from separate pages.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | PermissionRequest reference, updatedInput, and setMode behavior |
| https://code.claude.com/docs/en/hooks-guide | Example showing updatedPermissions with setMode |
| https://code.claude.com/docs/en/permissions | General deny-rule precedence and disableBypassPermissionsMode policy text |

Total scope: 3 pages affected

Source: Changelog v2.1.110

Exact changelog entry:

Fixed PermissionRequest hooks returning updatedInput not being re-checked against permissions.deny rules; setMode:'bypassPermissions' updates now respect disableBypassPermissionsMode