claude-code - 💡(How to fix) Fix [DOCS] Permissions docs still say Bash commands always prompt despite read-only exceptions [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Permission system" and Bash command approval behavior

Current Documentation

The docs currently say:

Tool type	Example	Approval required	"Yes, don't ask again" behavior
Read-only	File reads, Grep	No	N/A
Bash commands	Shell execution	Yes	Permanently per project directory and command

The permission modes page also says:

When Claude wants to edit a file, run a shell command, or make a network request, it pauses and asks you to approve the action.

And the headless docs say:

acceptEdits lets Claude write files without prompting and also auto-approves common filesystem commands such as mkdir, touch, mv, and cp. Other shell commands and network requests still need an --allowedTools entry or a permissions.allow rule, otherwise the run aborts when one is attempted:

What's Wrong or Missing?

Changelog v2.1.111 says: "Read-only bash commands with glob patterns (e.g. ls *.ts) and commands starting with cd <project-dir> && no longer trigger a permission prompt".

That behavior is not reflected in the current docs. The current permission docs still describe Bash approval as a blanket rule, and the headless docs still say non-listed shell commands prompt or abort unless explicitly allowed.

As a result, the docs are outdated about the current Bash permission flow for at least two user-visible cases:

• read-only Bash commands that include shell glob expansion
• commands prefixed with cd <project-dir> && that stay within the project directory

Suggested Improvement

Update the permissions documentation to describe the read-only Bash exceptions introduced in v2.1.111.

Suggested additions:

• Add a short note under the Bash permission rules explaining that some read-only Bash commands are auto-approved and no longer prompt.
• Include explicit examples such as ls *.ts and cd <project-dir> && git status.
• Clarify the boundary conditions: which read-only patterns are exempt, and which commands still prompt (for example writes, protected paths, networked actions, or commands outside the project/additional directories).
• Cross-reference the same behavior from permission-modes, tools-reference, and headless so those pages do not continue to imply that all Bash commands always require explicit approval.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 5 pages affected

Source: Changelog v2.1.111

Exact changelog entry: Read-only bash commands with glob patterns (e.g. ls *.ts) and commands starting with cd <project-dir> && no longer trigger a permission prompt