[DOCS] Permissions docs do not show `Agent(type)` rules for subagent type restrictions

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"Permission rule syntax" and the subagent type matching cross-reference

Current Documentation

The permissions page says parameter rules can match top-level tool inputs:

"Deny and ask rules can match a top-level input parameter on any tool with Tool(param:value)."

The examples include:

"Agent(model:opus) | Agent calls that request the Opus model tier"

and:

"Agent(isolation:worktree) | Agent calls that request a git worktree"

The subagents page separately documents allowlisting subagent types in an agent's tools field:

"To restrict which subagent types it can spawn, use Agent(agent_type) syntax in the tools field."

What's Wrong or Missing?

Claude Code v2.1.186 fixed Agent(type) deny rules and Agent(x,y) allowed-types restrictions for named subagent spawns. The docs mention these mechanisms separately, but they do not clearly document the permission-rule form for denying specific subagent types.

The permissions page examples show model and isolation, but not the subagent type form. The subagents page shows Agent(worker, researcher) for tools, but does not cross-link to denying specific agent types with permission rules.

Suggested Improvement

Add Agent(type) examples to the permissions rule syntax section and cross-link them from the subagents page. For example:

{
  "permissions": {
    "deny": ["Agent(security-reviewer)"]
  }
}

Clarify the distinction between:

• tools: Agent(worker, researcher) in an agent definition: allowlist the subagent types that can be spawned.
• permissions.deny: ["Agent(type)"]: block a specific subagent type even when the Agent tool is otherwise available.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permissions | Permission rule syntax examples omit subagent type deny rules |
| https://code.claude.com/docs/en/sub-agents | Subagent type allowlist syntax should cross-link to permission deny rules |
| https://code.claude.com/docs/en/tools-reference | Already points to Agent type matching and can remain the quick reference |

Total scope: 3 pages affected