[DOCS] [Permissions] Document `Tool(param:value)` parameter-match 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" (the section that starts with "Permission rules follow the format Tool or Tool(specifier)") and the related "Agent (subagents)" subsection that demonstrates Agent(AgentName) rules. The "Tool name wildcards" subsection is also a natural home for a sibling example.

Current Documentation

The current "Permission rule syntax" section describes only the bare-name and positional-specifier forms:

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

It then documents three pattern types under "Use specifiers for fine-grained control":

| Rule | Effect | | :----------------------------- | :------------------------------------------------------- | | Bash(npm run build) | Matches the exact command npm run build | | Read(./.env) | Matches reading the .env file in the current directory | | WebFetch(domain:example.com) | Matches fetch requests to example.com |

The only other place in the docs that uses the new param:value shape is the existing WebFetch(domain:example.com) example, which happens to look superficially similar but is documented as a host-name matcher, not an input-parameter matcher.

The "Agent (subagents)" subsection shows how to block a subagent by name but does not mention matching on the subagent's model field:

Use Agent(AgentName) rules to control which subagents Claude can use: Agent(Explore) matches the Explore subagent Agent(Plan) matches the Plan subagent * Agent(my-custom-agent) matches a custom subagent named my-custom-agent

The v2.1.178 changelog announces the new syntax but is the only place it appears:

Added Tool(param:value) syntax for permission rules to match a tool's input parameters (with * wildcard), e.g. Agent(model:opus) to block Opus subagents

What's Wrong or Missing?

A. The Tool(param:value) parameter-match syntax is not documented in permissions.md

The changelog for v2.1.178 (June 15, 2026) introduces a new permission-rule shape: Tool(param:value), which matches a tool invocation when the named input parameter has the given value. * works as a wildcard. The canonical example is Agent(model:opus) to block subagents that request the Opus model.

The "Permission rule syntax" section of permissions.md only documents the bare-name and positional-specifier forms. It does not describe the new param:value form at all, so users who only read the docs have no way to learn:

• that the syntax exists
• which tools accept it
• that * is a valid wildcard
• how it interacts with the existing deny / ask / allow evaluation order
• how it composes with positional specifiers (e.g. is Bash(cmd:git*) or Bash(git, *push*) the intended form when both command and another input field need to match?)

B. The Agent example in the changelog is not reflected in the "Agent (subagents)" subsection

The changelog's motivating example is Agent(model:opus) to block Opus subagents. The existing "Agent (subagents)" subsection of permissions.md (and the matching "Disable specific subagents" subsection of sub-agents.md) only show name-based matching (Agent(Explore), Agent(Plan), Agent(my-custom-agent)). Users looking for how to restrict which model a subagent can use will not find a documented answer.

Suggested Improvement

Option A: Comprehensive fix (preferred)

Add a new subsection under "Permission rule syntax" in permissions.md, between "Wildcard patterns" and "Tool name wildcards" (or directly under "Use specifiers for fine-grained control"), titled something like "Match on a tool's input parameters". Cover at least:

• The shape: Tool(param:value) — the parameter name on the left, the matched value on the right.
• The * wildcard for the value, e.g. Agent(model:*) matches any model and Agent(model:opus*) matches opus, opus-4-7, etc.
• That this works in allow, ask, and deny, with the same evaluation order as positional specifiers.
• That the parameter name must be a real input field of the tool. Agent(model:opus) works because model is an Agent input; arbitrary names are rejected (this should match whatever validation the runtime performs).
• A worked example mirroring the changelog:

{
"permissions": {
"deny": ["Agent(model:opus)"]
}
}

followed by an example using a wildcard:

{
"permissions": {
"deny": ["Bash(command:rm *)"]
}
}

(Use the canonical examples from the changelog and the codebase; verify before publishing.)

Then, in the "Agent (subagents)" subsection, add a short note that name-based matching and parameter matching are both available, and add a second example block that uses Agent(model:opus). Cross-reference from sub-agents.md "Disable specific subagents" subsection so the two pages stay in sync.

Option B: Minimum fix

Add a single paragraph and one example to the existing "Use specifiers for fine-grained control" subsection in permissions.md:

A specifier can also match a tool's input parameter using param:value syntax. For example, Agent(model:opus) blocks any subagent invocation whose model field is opus. The value side supports the * wildcard. This works in allow, ask, and deny rules and follows the same evaluation order as other specifiers.

{
"permissions": {
"deny": ["Agent(model:opus)"]
}
}

Then add a one-line cross-reference from the "Agent (subagents)" subsection and from sub-agents.md pointing to the new example.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permissions | Primary documentation location. "Permission rule syntax" section, "Use specifiers for fine-grained control" subsection, "Wildcard patterns" subsection, "Tool name wildcards" subsection, and "Agent (subagents)" subsection all need to acknowledge the new shape. |
| https://code.claude.com/docs/en/sub-agents | "Disable specific subagents" subsection (line ~538) only documents name-based matching. Should mention parameter matching with Agent(model:...) and link back to permissions.md. |
| https://code.claude.com/docs/en/cli-reference | --disallowedTools / --allowedTools description (line ~70) lists bare names, mcp__*, and scoped Bash(rm *) rules but does not mention the new Tool(param:value) shape. |
| https://code.claude.com/docs/en/settings | Settings schema table for permissions.allow / permissions.ask / permissions.deny references the same syntax and should be updated alongside permissions.md. |

Total scope: 4 pages affected.

Version: The new syntax ships in Claude Code v2.1.178 (June 15, 2026). The changelog entry at https://code.claude.com/docs/en/changelog is the only public source documenting it today.