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

Strong +1 from the hook API integration side. The contract gap this docs issue points out has a concrete runtime manifestation:

PermissionRequest hook responses that return behavior: "allow" combined with updatedPermissions: [{type: "setMode", mode: "bypassPermissions", destination: "session"}] have the setMode silently dropped in 2.1.110, 2.1.111, and 2.1.112. The behavior: allow half is honored (the current tool call proceeds) but the mode switch never takes effect, and the hook receives no error feedback. Other setMode values in the same payload shape (acceptEdits, default, plan, dontAsk) continue to work, so the mechanism is live — only this one documented value is gated silently.

No disableBypassPermissionsMode is set in any scope here.

Filed as a separate runtime bug with a product-agnostic minimal repro: #49525. Happy to keep both threads aligned.

Issue #48865 Verification

Title: [DOCS] PermissionRequest hook docs omit deny-rule and bypass-mode policy caveats
Issue Date: 2026-04-16
Verification Date: 2026-04-28
Status: RESOLVED

---

Issue Summary

This issue reports that the PermissionRequest hook documentation described updatedInput rewrites and setMode: "bypassPermissions" updates without clearly stating that rewritten input is still checked against active permission rules and that bypass-mode changes remain subject to policy restrictions.

---

Verification Results

Claim 1: The PermissionRequest reference now states that updatedInput is re-evaluated against deny and ask rules

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, line 1275: "behavior | \"allow\" grants the permission, \"deny\" denies it. Deny and ask rules are still evaluated, so a hook returning \"allow\" does not override a matching deny rule". At https://code.claude.com/docs/en/hooks, line 1276: "updatedInput | For \"allow\" only: modifies the tool's input parameters before execution... The modified input is re-evaluated against deny and ask rules".

Verdict: The hook reference now explicitly says that allowing a PermissionRequest does not bypass matching deny rules and that rewritten input is re-checked against deny and ask rules.

---

Claim 2: The PermissionRequest reference now states that setMode: "bypassPermissions" is constrained by active policy

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, line 1304: "setMode | mode, destination | Changes the permission mode. Valid modes are default, acceptEdits, dontAsk, bypassPermissions, and plan". At https://code.claude.com/docs/en/hooks, line 1309: "setMode with bypassPermissions only takes effect if the session was launched with bypass mode already available... and the mode is not disabled by permissions.disableBypassPermissionsMode. Otherwise the update is a no-op.".

Verdict: The hook reference now documents the exact bypass-mode policy caveat the issue requested.

---

Claim 3: The guide page now mirrors the bypass-mode policy caveat and points readers to the permissions docs

Status: RESOLVED

At https://code.claude.com/docs/en/hooks-guide, line 400: "To set a specific permission mode instead, your hook's output can include an updatedPermissions array with a setMode entry." At https://code.claude.com/docs/en/hooks-guide, line 403: "bypassPermissions only applies if the session was launched with bypass mode already available... and not disabled by permissions.disableBypassPermissionsMode.". The linked policy page also states the control at https://code.claude.com/docs/en/permissions, lines 45-48, including: "Administrators can prevent this mode by setting permissions.disableBypassPermissionsMode to \"disable\"" and "To prevent bypassPermissions or auto mode from being used, set permissions.disableBypassPermissionsMode or permissions.disableAutoMode to \"disable\" in any settings file".

Verdict: The guide now includes the missing bypass-mode restriction and links directly to the permissions documentation that defines the governing policy.

---

Current State

| Claim | Status |
|-------|--------|
| updatedInput is documented as being re-evaluated against deny and ask rules | RESOLVED |
| setMode: "bypassPermissions" is documented as subject to disableBypassPermissionsMode | RESOLVED |
| The guide mirrors the bypass-mode policy caveat and links to permissions docs | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/hooks
• Lines 1275-1276: PermissionRequest decision control now says deny and ask rules are still evaluated and that modified input is re-evaluated against deny and ask rules.

• URL: https://code.claude.com/docs/en/hooks
• Lines 1304-1309: Permission update entries now says setMode can target bypassPermissions only when that mode is available and not disabled by permissions.disableBypassPermissionsMode.

• URL: https://code.claude.com/docs/en/hooks-guide
• Lines 400-404: The guide example for updatedPermissions now includes the bypassPermissions caveat and links to the permissions page.

• URL: https://code.claude.com/docs/en/permissions
• Lines 45-48: The permissions page states that administrators can disable bypass mode and that permissions.disableBypassPermissionsMode can be set in any settings file.

---

Conclusion & Recommendation

Primary Concern: The issue reported that PermissionRequest hook docs did not clearly state that rewritten input and bypass-mode updates remain constrained by active permission policy.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current hooks reference now explicitly says that rewritten input is re-evaluated against deny and ask rules, and both the hooks reference and guide now state that setMode: "bypassPermissions" is limited by permissions.disableBypassPermissionsMode. The documentation now matches the requested clarification.

---

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.