[DOCS] Permission docs need content-level vs tool-level precedence clarification

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Configuring permissions - Permission rule evaluation

Current Documentation

The current documentation states:

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

This describes the evaluation order between rule types (deny beats ask beats allow), but does not address the relationship between tool-level and content-level rules.

What's Wrong or Missing?

Changelog v2.1.27 introduced a permission hierarchy change:

Permission hierarchy updated: Content-level ask now takes precedence over tool-level allow Example: allow: ["Bash"], ask: ["Bash(rm *)"] previously allowed all bash commands, but now prompts for permission on rm operations

This is a behavioral change that affects how users configure permissions. The previous behavior (tool-level allow overriding content-level ask) was arguably a bug, but users who relied on the old behavior need to understand:

1. More specific rules (with content specifiers) now take precedence over less specific rules
2. The example allow: ["Bash"], ask: ["Bash(rm *)"] now correctly prompts for rm commands

Suggested Improvement

Update the permission evaluation section in iam.md to clarify specificity:

### Rule evaluation

Rules are evaluated in order: **deny → ask → allow**. The first matching rule wins.

**Specificity matters:** When rules of the same type (e.g., both `allow`) conflict, more specific rules take precedence over general ones:

| Configuration | Command | Result |
|---------------|---------|--------|
| `allow: ["Bash"], ask: ["Bash(rm *)"]` | `rm -rf /tmp/test` | Prompts (ask) |
| `allow: ["Bash"], ask: ["Bash(rm *)"]` | `ls -la` | Allowed |
| `deny: ["Bash(curl *)"], allow: ["Bash"]` | `curl example.com` | Denied |
| `deny: ["Bash(curl *)"], allow: ["Bash"]` | `wget example.com` | Allowed |

Content-level rules (with specifiers like `Bash(rm *)`) take precedence over tool-level rules (like `Bash`), allowing you to set broad permissions with specific exceptions.

Impact

High - Prevents users from using a feature

Additional Context

Source: Changelog v2.1.27

Exact changelog entry:

Permission hierarchy updated: Content-level ask now takes precedence over tool-level allow Example: allow: ["Bash"], ask: ["Bash(rm *)"] previously allowed all bash commands, but now prompts for permission on rm operations

This is marked as High impact because users may have configured permissions expecting the old behavior, and security-sensitive operations (like rm) may now behave differently than expected.