claude-code - 💡(How to fix) Fix [DOCS] [Permissions] Agent(subagent) matching docs omit case- and separator-insensitive behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Agent (subagents)" section under permission rule formats

Current Documentation

The permissions page documents the Agent(AgentName) rule format with these examples:

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 documentation shows only exact-match examples and does not mention that matching is case-insensitive or separator-insensitive. A user reading these docs would reasonably conclude that Agent(code-reviewer) is a different rule from Agent(Code Reviewer) and that neither would match a subagent named "Code Reviewer" or "code_reviewer".

What's Wrong or Missing?

The Agent tool's subagent_type matching behavior changed in v2.1.140 to accept case- and separator-insensitive values. For example, "Code Reviewer" resolves to code-reviewer, meaning:

• Agent(code-reviewer) matches a subagent named "Code Reviewer"
• Agent(CodeReviewer) matches a subagent named "code-reviewer"
• Agent(CODE_REVIEWER) matches a subagent named "Code_Reviewer"

This behavior is not documented. Users who want to write permission rules for subagents do not know that they can use any case or separator variant and expect it to resolve correctly.

Suggested Improvement

Update the "Agent (subagents)" section in the permissions guide to document the case- and separator-insensitive matching behavior. Suggested addition:

Agent type matching is case-insensitive and separator-insensitive. Spaces, hyphens, and underscores are treated as equivalent separators. For example, Agent(code-reviewer), Agent(CodeReviewer), and Agent(Code_Reviewer) all match a subagent named "Code Reviewer". You can use whichever format is most convenient in your permission rules.

Impact

Medium - Makes feature difficult to understand correctly

Additional Context

Changelog reference: v2.1.140 — "Improved Agent tool subagent_type matching to accept case- and separator-insensitive values (e.g. "Code Reviewer" resolves to code-reviewer)"

Affected Pages:

Total scope: 3 pages affected