[DOCS] Permission docs omit deny-rule tool-name glob semantics for `"*"` and unknown tool warnings

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Permission rule syntax for bare tool names, tool-name wildcards, MCP globs, and validation warnings

Current Documentation

The permissions reference currently says:

"Permission rules follow the format Tool or Tool(specifier)."

It also documents MCP wildcard syntax:

"mcp__puppeteer__* wildcard syntax that also matches all tools from the puppeteer server"

But it does not document the new deny-rule tool-name glob behavior added in v2.1.166.

What's Wrong or Missing?

Claude Code v2.1.166 adds new validation and matching behavior for the tool-name position of permission rules:

• A deny rule with "*" denies all tools.
• Allow rules reject non-MCP globs.
• Unknown tool names in deny rules warn at startup.

The current docs explain command/path wildcard patterns and MCP tool wildcards, but they do not distinguish those from whole-tool-name glob behavior. Users reading the permissions reference cannot tell whether "*" is valid, whether it belongs only in deny, whether non-MCP globs are allowed in allow, or how startup validation treats unknown tool names.

This is especially important because the same page already uses * in several different contexts: Bash command patterns, Read/Edit gitignore-style paths, MCP tool names, and the Bash(*) all-command form.

Suggested Improvement

Add a short "Tool-name wildcards and validation" subsection near "Permission rule syntax" or "Tool-specific permission rules":

In the tool-name position, deny rules may use `"*"` to deny every tool. MCP tool-name globs such as `mcp__server__*` are supported. Non-MCP tool-name globs are rejected in allow rules. Unknown tool names in deny rules produce a startup warning so misspellings do not silently create ineffective policy.

Also add an example:

{
"permissions": {
"deny": ["*"],
"allow": ["mcp__github__*"]
}
}

If the example above is not intended as a supported combination, document the supported equivalent.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permissions | 70-132 | Permission rule syntax and wildcard command patterns |
| https://code.claude.com/docs/en/permissions | 244-249 | MCP wildcard syntax only |
| https://code.claude.com/docs/en/cli-reference | 69 | --disallowedTools describes deny rules without wildcard/validation caveats |
| https://code.claude.com/docs/en/tools-reference | 57-85 | Tool-name configuration overview does not mention "*" deny behavior or unknown-tool warnings |

Total scope: 3 pages affected.

Version reference: Claude Code v2.1.166 release notes state that deny-rule tool-name globs now support "*" for all tools, allow rules reject non-MCP globs, and unknown tool names in deny rules warn at startup.