[DOCS] Hooks reference does not document that hyphenated MCP server names exact-match in v2.1.195

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Matcher patterns" and "Match MCP tools" sections of the hooks reference. The table of matcher evaluation rules and the MCP server naming examples need to mention the v2.1.195 fix that changes hyphenated identifiers such as mcp__brave-search from substring-matching to exact-match behavior.

Current Documentation

The hooks reference says:

| Only letters, digits, _, spaces, ,, and \| | Exact string, or list of exact strings separated by \| or , with optional surrounding whitespace | Bash matches only the Bash tool; Edit\|Write and Edit, Write each match either tool exactly |

The "Match MCP tools" section gives examples using only underscore-separated MCP server names:

mcp__memory__create_entities: Memory server's create entities tool mcp__filesystem__read_file: Filesystem server's read file tool * mcp__github__search_repositories: GitHub server's search tool To match every tool from a server, append .* to the server prefix. The .* is required: a matcher like mcp__memory contains only letters and underscores, so it is compared as an exact string and matches no tool.

Nothing in the reference acknowledges that MCP server names can contain hyphens, or explains what happens when a hyphenated identifier like mcp__brave-search is used as a matcher.

What's Wrong or Missing?

Claude Code v2.1.195 fixed hook matchers with hyphenated identifiers such as code-reviewer or mcp__brave-search that were accidentally substring-matching. After the fix, a matcher that contains only letters, digits, underscores, and hyphens is treated as an exact string, so mcp__brave-search no longer behaves like a prefix or substring matcher. To match all tools from that server, users need an explicit wildcard pattern such as mcp__brave-search__.*; without it, a bare server prefix will not match tool names like mcp__brave-search__search.

The reference's matcher rule table says a matcher with "only letters, digits, _, spaces, ,, and \|" is evaluated as an exact string, which silently omits the hyphen. Users authoring matchers for hyphenated MCP servers therefore cannot tell from the docs whether their matcher is exact or substring, and the "Match MCP tools" section never lists a hyphenated example such as mcp__brave-search or mcp__code-reviewer.

The release notes explicitly direct hyphenated MCP server authors to use mcp__brave-search__.* to match all tools from such a server; the hooks reference does not mention this pattern.

Suggested Improvement

Update the matcher rule row to include the hyphen:

| Only letters, digits, _, -, spaces, ,, and \| | Exact string, or list of exact strings separated by \| or , with optional surrounding whitespace | Bash matches only the Bash tool; Edit\|Write and Edit, Write each match either tool exactly |

Add a sentence below the matcher rule table:

In Claude Code v2.1.195 and later, hyphenated identifiers such as code-reviewer or mcp__brave-search are also compared as exact strings. Use a wildcard pattern such as mcp__brave-search__.* to match every tool from a hyphenated MCP server.

Extend the "Match MCP tools" example list to include a hyphenated server name, and add a worked example of the v2.1.195 fix:

mcp__brave-search__search: Brave Search server's search tool mcp__code-reviewer__run: Code reviewer server's run tool To match every tool from a hyphenated server, append .* exactly as for underscore-separated servers: ``json { "hooks": { "PreToolUse": [ { "matcher": "mcp__brave-search__.*", "hooks": [ { "type": "command", "command": "..." } ] } ] } } ``

Impact

Medium - Makes feature difficult to understand

Additional Context

Before the v2.1.195 fix, mcp__brave-search could accidentally match unrelated tool names that contained the same text because of how the hyphen was tokenized. After the fix, both mcp__brave-search and mcp__memory are evaluated as exact strings. Users with hyphenated MCP server names need to add the __.* wildcard to match all of a server's tools, otherwise their hook fires for none of them. The hooks guide ("Match MCP tools" tab at line 666 of the rendered guide) shows the same mcp__github__.* pattern and would benefit from the same hyphenated example.

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/hooks | matcher rule table and "Match MCP tools" section | Exact-match rule omits hyphen; MCP examples omit hyphenated servers |
| https://code.claude.com/docs/en/hooks-guide | "Match MCP tools" tab | Uses mcp__github__.*; same example needs the hyphenated-server variant |

Total scope: 2 pages affected