[DOCS] Permissions docs missing Bash cmd: specifier syntax for permission rules

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Permission rule syntax" section — specifically the Bash tool-specific rules

Current Documentation

The permissions page documents Bash permission rules using direct command matching:

Bash(npm run build) — Matches the exact command npm run build Bash(npm run test *) — Matches Bash commands starting with npm run test Bash(npm *) — Matches any command starting with npm Bash(* install) — Matches any command ending with install

The docs also note:

The space before * matters: Bash(ls *) matches ls -la but not lsof, while Bash(ls*) matches both. The legacy :* suffix syntax is equivalent to * but is deprecated.

There is no documentation of the cmd: prefix syntax (e.g., Bash(cmd:*) or Bash(cmd:git *)).

What's Wrong or Missing?

The cmd: specifier prefix for Bash permission rules is completely undocumented. A v2.1.76 bug fix confirms the syntax is intentional and actively used:

"Fixed Bash(cmd:*) permission rules not matching when a quoted argument contains #"

Users who write Bash(cmd:*) or Bash(cmd:git *) in their permission rules have no documentation explaining:

• What cmd: means as a specifier prefix
• How Bash(cmd:git *) differs from Bash(git *) in matching behavior
• When to use cmd: vs. plain command matching
• Whether cmd: applies to the entire shell expression or just the base command name

Without documentation, users cannot predict whether their cmd:-prefixed rules will behave correctly, especially with quoted arguments, pipes, or compound commands (which are explicitly mentioned in the same v2.1.76 release: "Fixed 'don't ask again' in the Bash permission dialog showing the full raw command for pipes and compound commands").

Suggested Improvement

Add a cmd: subsection to the Bash permission rules section in permissions.md:

Under "Tool-specific permission rules → Bash", add:

The cmd: specifier The cmd: prefix matches against the base command name rather than the full shell expression. This is useful when rules need to match commands that may include quoted arguments, pipes, or compound constructs: | Rule | Effect | |------|--------| | Bash(cmd:git) | Matches any Bash invocation whose command is git, regardless of arguments | | Bash(cmd:git *) | Matches any git command followed by any arguments | | Bash(cmd:*) | Matches all Bash commands (equivalent to Bash) | Use cmd: when your allow/deny rules need to be resilient to quoted arguments containing special characters like #, pipes (|), or compound operators (&&, ;).

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permissions | "Permission rule syntax" and "Tool-specific permission rules → Bash" sections — cmd: specifier absent |
| https://code.claude.com/docs/en/settings | allow, ask, deny array examples do not show cmd: usage |

Total scope: 2 pages affected

Source: Changelog v2.1.76

Fixed Bash(cmd:*) permission rules not matching when a quoted argument contains #