[DOCS] Hook docs imply PreToolUse `allow` can override deny rules

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

PreToolUse decision control and permission precedence

Current Documentation

The hook reference currently says:

permissionDecision | "allow" bypasses the permission system, "deny" prevents the tool call, "ask" prompts the user to confirm

The hook guide also says:

"allow": proceed without showing a permission prompt

But the permissions docs say:

Rules are evaluated in order: deny -> ask -> allow. The first matching rule wins, so deny rules always take precedence.

What's Wrong or Missing?

Claude Code v2.1.77 fixed a case where PreToolUse hooks returning "allow" could bypass deny permission rules, including enterprise managed settings.

The current docs read as if permissionDecision: "allow" overrides the entire permission system, which conflicts with documented deny-first precedence and is especially risky for teams relying on managed policies.

Suggested Improvement

Clarify the interaction between hook decisions and permission rules.

Suggested changes:

• explain that permissionDecision: "allow" skips prompting but does not override deny rules
• state explicitly that managed deny rules still win
• add an example showing a hook returning allow while a matching deny rule still blocks the action

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | PreToolUse table says "allow" bypasses the permission system |
| https://code.claude.com/docs/en/hooks-guide | Guide says "allow" proceeds without a permission prompt |
| https://code.claude.com/docs/en/permissions | Permissions page says deny rules always take precedence |

Total scope: 3 pages affected

Source: Claude Code v2.1.77 release notes

Exact release entry:

Fixed PreToolUse hooks returning "allow" bypassing deny permission rules, including enterprise managed settings