[DOCS] Permissions docs under-specify Windows path matching and Read deny behavior in Grep/Glob

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Read and Edit path pattern matching on Windows, and how Read(...) deny rules affect built-in Grep/Glob/file discovery behavior

Current Documentation

The docs currently say:

Edit rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply Read rules to all built-in tools that read files like Grep and Glob, to @file mentions in your prompts, and to the selection and open-file context that a connected IDE shares with Claude.

And later on the same page:

On Windows, paths are normalized to POSIX form before matching. C:\Users\alice becomes /c/Users/alice, so use //c/**/.env to match .env files anywhere on that drive. To match across all drives, use //**/.env.

The settings reference also says:

This replaces the deprecated ignorePatterns configuration. Files matching these patterns are excluded from file discovery and search results, and read operations on these files are denied.

What's Wrong or Missing?

In v2.1.162, the changelog says:

Fixed Windows permission rules never matching when spelled with backslashes (~\, \\server\share) or case-variant paths, and Read deny rules not hiding files from Glob/Grep results.

The current docs do not explain that behavior clearly.

A. Windows-native rule spellings are still under-documented

The permissions page documents only POSIX-form examples such as //c/.... It does not say whether Windows-native spellings like ~\..., UNC paths such as \\server\share\..., or case-variant Windows paths are accepted and normalized before matching.

B. Read deny behavior across search tools is described inconsistently

The settings page says denied files are excluded from file discovery and search results, but the permissions page only says Claude makes a "best-effort attempt" to apply Read rules to Grep and Glob. After the v2.1.162 fix, readers need one clear explanation that matching Read(...) deny rules hide those files from built-in Glob/Grep results in addition to blocking direct reads.

Suggested Improvement

Update the permissions docs to make the Windows and search-tool behavior explicit.

For example:

• In the Windows path-matching section, add a note that Claude Code normalizes Windows-native path spellings before matching, including home-directory backslash paths, UNC/network-share paths, and paths that differ only by case on Windows.
• In the Read and Edit section, state directly that matching Read(...) deny rules hide files from built-in file discovery, Glob, and Grep results as well as denying direct read access.
• Mirror that wording in the sensitive-files/settings guidance so the permissions and settings pages describe the same behavior in the same terms.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permissions | 191-210 | Read rules are said to apply to Grep/Glob on a best-effort basis, and Windows examples document only POSIX-form patterns |
| https://code.claude.com/docs/en/settings | 575-591 | Sensitive-file guidance says denied files are excluded from file discovery and search results, but does not cross-link the Windows/path-matching details |

Total scope: 2 pages affected

Version context: https://code.claude.com/docs/en/changelog for v2.1.162 documents Windows backslash/case-variant path matching and Glob/Grep hiding as shipped behavior.