[DOCS] Permissions page omits `$HOME` matching for home-path `Read(...)` deny rules in Bash

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Read and Edit path matching rules, especially ~/path home-directory patterns and how Read(...) deny rules apply to Bash-recognized file commands

Current Documentation

The docs currently say:

Read rules apply 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.

They also say:

Read and Edit deny rules apply to Claude's built-in file tools and to file commands Claude Code recognizes in Bash, such as cat, head, tail, and sed.

And the path syntax table says:

| ~/path | Path from home directory | Read(~/Documents/*.pdf) | /Users/alice/Documents/*.pdf |

What's Wrong or Missing?

The live page explains that Read(...) deny rules can target home-directory paths and that the same deny rules apply to recognized Bash file commands, but it does not document the path-equivalence behavior added in v2.1.163.

The v2.1.163 changelog says:

Fixed deny rules on home-directory paths (e.g. Read(~/Desktop/**)) not blocking Bash commands that reference the path via $HOME

That leaves one missing behavior detail:

A. The docs never say that ~/... deny rules also match $HOME-expanded Bash paths

Users can reasonably read the current page as meaning they must write separate rules or avoid environment-variable forms in shell commands. The page documents ~/ as a home-relative path syntax, but it does not say that a deny rule like Read(~/Desktop/**) should also block recognized Bash reads such as cat "$HOME/Desktop/file.txt".

Without that note, the documented rule syntax is incomplete for the Bash enforcement case that v2.1.163 fixed.

Suggested Improvement

Add one explicit note or example in the Read and Edit section after the path-pattern table or the Bash-enforcement warning.

Suggested addition:

Home-directory patterns also match equivalent $HOME references in Bash-recognized file commands. For example, Read(~/Desktop/**) blocks commands like cat "$HOME/Desktop/notes.txt" the same way it blocks cat ~/Desktop/notes.txt.

An adjacent example would make the behavior easier to discover:

Read(~/Desktop/**): blocks reads under your Desktop folder, including Bash commands that reference the same location through ~/Desktop/... or $HOME/Desktop/...

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permissions | 189-235 | Read/Edit deny-rule scope, path syntax, and symlink semantics for file access |

Total scope: 1 page affected

Behavior changed in Claude Code v2.1.163.