[DOCS] Permissions docs omit symlink-target matching for absolute `Read`/`Edit` allow rules

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Read / Edit permission rule syntax for absolute //path allow rules, especially how symlinked paths are evaluated

Current Documentation

The permissions page currently says:

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. Read and Edit rules both follow the gitignore specification with four distinct pattern types: | Pattern | Meaning | Example | Matches | | //path | Absolute path from filesystem root | Read(//Users/alice/secrets/**) | /Users/alice/secrets/** | * Edit(//tmp/scratch.txt): edits the absolute path /tmp/scratch.txt

The settings reference currently says:

Permission rules follow the format Tool or Tool(specifier). Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins.

No current page explains whether absolute Read(//path/**) and Edit(//path/**) allow rules are matched against the requested path string or the resolved symlink target.

What's Wrong or Missing?

Changelog v2.1.89 says:

Fixed Edit(//path/**) and Read(//path/**) allow rules to check the resolved symlink target, not just the requested path

That is user-visible permission behavior, but the published docs do not define it.

Users working with symlinked directories or files need to know whether an absolute-path allow rule is evaluated against:

1. the path they asked Claude Code to access, or
2. the real filesystem target after symlink resolution.

Right now the docs explain the //path syntax but not this matching rule. That leaves a security-sensitive ambiguity for anyone relying on Read(...) or Edit(...) allow rules around symlinked paths.

Suggested Improvement

Update https://code.claude.com/docs/en/permissions to document that absolute Read(//path/**) and Edit(//path/**) allow rules are evaluated against the resolved symlink target, not only the originally requested path.

Add one concrete example, such as a symlinked path request that is allowed only when the resolved target stays inside the allowed absolute path tree.

If the docs team wants this nuance surfaced outside the canonical permissions page, add a short cross-reference note in https://code.claude.com/docs/en/settings near the permission-rule syntax summary.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permissions | 137-169 | Read / Edit rule syntax defines absolute //path matching and examples, but does not say allow rules use the resolved symlink target |
| https://code.claude.com/docs/en/settings | 239-264 | Permission settings and quick syntax summary explain rule order and examples, but do not surface the symlink-resolution behavior for absolute file-path allow rules |

Total scope: 2 pages affected

Source: Changelog v2.1.89

Changelog entry:

Fixed Edit(//path/**) and Read(//path/**) allow rules to check the resolved symlink target, not just the requested path