[Docs] Ambiguity and Contradiction in `Read` Permission Rule Enforcement

\### Subject: [Docs] Ambiguity and Contradiction in Read Permission Rule Enforcement

Labels: documentation, security, bug

Summary

The documentation for Claude Code's IAM Read permission rules is both ambiguous and internally contradictory. The iam page describes the application of these rules to tools like Grep and Glob as a "best-effort attempt," while the settings page implies enforcement is absolute ("completely invisible").

This conflict creates critical uncertainty around a core security feature. Users cannot confidently configure access control policies without a clear, deterministic definition of how Read rules are enforced across all file-access tools.

Location of Conflicting Documentation

1. Ambiguous Statement: en/docs/claude-code/iam

• Section: "Tool-specific permission rules" -> "Read & Edit"

1. Contradictory Statement: en/docs/claude-code/settings

• Section: "Excluding sensitive files"

The Problem in Detail

1. Ambiguous Language Creates Uncertainty

The iam documentation states:

Edit rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply Read rules to all built-in tools that read files like Grep, Glob, and LS.

The term "best-effort attempt" is not suitable for describing a security control. It implies that the rule enforcement may fail under certain conditions, but the documentation provides no information on what those conditions are. This prevents users from trusting the permission system to reliably protect sensitive data.

2. Contradictory Language Prevents Clear Understanding

In direct contradiction to the "best-effort" language, the settings documentation states:

Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.

This statement implies a guaranteed, deterministic block, which is the expected behavior for an access control rule.

As a user, it is impossible to know which statement is correct. Does a deny rule like Read(./secrets/**) guarantee that Grep and LS cannot access that path, or is there a chance the "best-effort" attempt might fail?

Analysis and Impact

For security policies to be effective, their behavior must be predictable and guaranteed. The current state of the documentation has the following negative impacts:

• Erodes User Trust: The ambiguity undermines confidence in Claude Code's security and permission model.
• Prevents Confident Configuration: Administrators cannot confidently deploy organization-wide security policies (e.g., via managed-settings.json) without knowing if they will be strictly enforced.
• Potential for Misconfiguration: Users might create a Read deny rule believing it provides complete protection, but if the "best-effort" enforcement fails, sensitive file content could be inadvertently exposed to the model via tools like Grep.

Furthermore, internal instructions for the model suggest that the Grep tool is "optimized for correct permissions and access," indicating that the intended behavior is likely strict enforcement. The "best-effort" language in the public documentation appears to be an inaccurate and misleading description of the feature's design.

Suggested Resolution

To resolve this issue, please:

1. Confirm the Definitive Behavior: Internally verify how Read permission rules are applied to all relevant tools (Grep, Glob, LS, etc.).

1. Update and Unify the Documentation: Remove all ambiguity and ensure the language is consistent across all pages.

• If Enforcement is Strict (Recommended):

Update the text to be explicit. For example:
> "A Read deny rule for a path is strictly enforced and will prevent all file-access tools, including Grep, Glob, and LS, from reading or searching that path."

• If Enforcement is Not Guaranteed:

The documentation must clearly explain the limitations. It should detail the specific scenarios or edge cases where a Read rule might not be applied to other tools.

1. Remove Ambiguous Terms: The phrase "best-effort attempt" should be removed entirely from security-related documentation and replaced with precise, deterministic language.

Clear and accurate documentation for security features is essential. Thank you for your attention to this critical detail.