Claude Code's hook matcher mcp__lab fired 0 times in 42 calls, though the same string worked as a permission rule

A developer's 14 headless test runs of Claude Code 2.1.289 found that a hook matcher of `mcp__lab` fired 0 times across 42 calls to that MCP server's tools, while `mcp__lab__.*` fired 42 of 42, even though the same bare prefix passed to `--allowedTools` approved every call. The tests also showed an `if` condition of `mcp__lab` stayed silent (0 of 42) and that `mcp__lab__.*` itself fired 0 of 9 times once the server was bundled in a plugin, where tools use the scoped `mcp__plugin_<plugin>_<server>__<tool>` naming. The finding highlights three conflicting grammars for the same string: exact-match hook matcher, whole-server permission rule, and permission-style `if` filter.

Across 14 headless runs of Claude Code 2.1.289, a hook whose matcher was the server prefix mcp lab fired 0 times in 42 calls to that server's tools, while mcp lab . fired 42 of 42, and the same bare mcp lab passed to --allowedTools approved every call it covered. Two more strings stayed silent: an if condition of mcp lab 0 of 42 , and the documented fix mcp lab . itself once the same server was bundled in a plugin 0 of 9 . A hook on an MCP server is usually written for one of two jobs: log every call to that server, or check a call before it runs. Either way the hook sits behind a matcher , and the natural thing to type there is the server's prefix, mcp github or mcp memory , because that is how a permission rule names a whole server. Claude Code's hooks reference says that string does nothing: it "is compared as an exact string and matches no tool". A matcher that matches nothing doesn't break anything you can see. The settings file loads, the session runs, and the hook just never starts. We wanted to see that happen, and to see which other plausible strings behave the same way, so we built a three-tool MCP server, registered 22 hook groups against it side by side, and counted which ones fired for which tool. Everything below ran on 2026-10-05 between 16:24 and 16:39 UTC with Claude Code 2.1.289 claude --version and claude-opus-5-5 selected with --model opus . The documentation quotes come from https://code.claude.com/docs/en/hooks and hooks.md , permissions.md , mcp.md and cli-reference.md on the same site, plus the Claude Code CHANGELOG.md on GitHub, all fetched between 16:20 and 16:25 UTC the same day. The hooks page sorts matchers by the characters they contain. Its table has three rows, quoted as fetched: " " , "" , or omitted: "Match all", which "fires on every occurrence of the event". , - , spaces, , , and | ": "Exact string, or list of exact strings separated by The next paragraph adds that a regular-expression matcher "is tested with JavaScript's RegExp.prototype.test , which succeeds on a match anywhere in the value", and that you should wrap a pattern in ^ and $ "when you need a whole-string match". For tool events PreToolUse , PostToolUse and three others the value being tested is tool name . The MCP part is short. Tools are named mcp <server <tool , and then: "To match every tool from a server, append . to the server prefix. The . is required: a matcher like mcp memory or mcp brave-search contains only exact-match characters, so it is compared as an exact string and matches no tool." For plugins: "Tools from a plugin-bundled MCP server use a scoped server segment that includes the plugin name: mcp plugin <plugin-name <server-name <tool . A matcher written against the bare server key never fires for these tools." Two other pages use the same strings for something else. The permissions page, under its MCP heading: " mcp puppeteer matches any tool provided by the puppeteer server", and " mcp puppeteer uses wildcard syntax and also matches all tools from the puppeteer server". So in a permission rule the bare server prefix means the whole server, and is a glob. And the hooks page describes a second filter on each handler, the if field, as "Permission rule syntax to filter when this hook runs, such as "Bash git " or "Edit .ts " ." The changelog has two entries that matter here. 2.1.191: "Fixed hooks with comma-separated matchers e.g. "Bash,PowerShell" silently never firing". 2.1.195: "Fixed hook matchers with hyphenated identifiers e.g. code-reviewer , mcp brave-search accidentally substring-matching — they now exact-match. Use mcp brave-search . to match all tools from a hyphenated MCP server." That gives three grammars for one string. As a hook matcher, mcp lab is an exact name that no tool has. As a permission rule, it is the whole server. As an if condition, the docs point you to permission rule syntax, which suggests the whole server again. The lab tests all three. The lab directory has no git repository and no CLAUDE.md . It holds an MCP server, a hook logger, a settings file and two small JSON configs. The server is a Node script with no dependencies that reads newline-delimited JSON-RPC on stdin and answers initialize , tools/list and tools/call . It takes a name as its argument. Started as lab it offers three tools, ping , echo and echo upper ; started as lab-two it offers only ping . Every tools/call it receives is appended to calls.log with the server name, so we had a record of which calls actually executed that does not depend on Claude Code. The --mcp-config file registers it twice: { "mcpServers": { "lab": { "command": "node", "args": "<lab /server.js", "lab" }, "lab-two": { "command": "node", "args": "<lab /server.js", "lab-two" } } } That gives four tool names: mcp lab ping , mcp lab echo , mcp lab echo upper and mcp lab-two ping . The second server is there to test the hyphen from the 2.1.195 entry and, because lab-two starts with lab , to see whether a loose pattern written for lab also catches it. echo upper starts with echo for the same reason. Three more names come from a plugin. A directory called labkit holds a .claude-plugin/plugin.json naming it labkit and a .mcp.json that registers the same script under the key lab , loaded with --plugin-dir . Its tools appear as mcp plugin labkit lab ping , echo and echo upper , exactly the form the docs describe. The hook logger reads the hook's stdin, pulls out tool name and session id , and appends one line with its event and a label error handling trimmed : js const eventName, label = process.argv.slice 2 ; let raw = ""; process.stdin.on "data", c = raw += c ; process.stdin.on "end", = { const input = JSON.parse raw ; fs.appendFileSync path.join dirname, "fires.log" , ${new Date .toISOString }\t${input.session id}\t${eventName}\t${label}\t${input.tool name}\n ; } ; .claude/settings.json has 22 matcher groups under PreToolUse and the same 22 under PostToolUse , each with one command that runs the logger with its own label. Nineteen differ only in the matcher. The other three use mcp . as the matcher and add an if : mcp lab , mcp lab , and mcp lab ping . Trimmed to three groups, the file looks like this: { "hooks": { "PreToolUse": { "matcher": "mcp lab", "hooks": { "type": "command", "command": "node <lab /hooklog.js PRE m01" } }, { "matcher": "mcp lab . ", "hooks": { "type": "command", "command": "node <lab /hooklog.js PRE m02" } }, { "matcher": "mcp . ", "hooks": { "type": "command", "command": "node <lab /hooklog.js PRE i01", "if": "mcp lab" } } } } In the real file node and the script are absolute paths; <lab stands for the lab directory. The matchers cover what the docs list and what we would expect people to type: the bare prefix, the documented fix, one exact tool, a | list and a , list, the permission-style glob mcp lab , two looser prefixes, an anchored prefix, the hyphenated server with and without . , the bare server key lab , the bare tool name ping , a mixed list Bash|mcp lab , the plugin-scoped pattern, mcp . , and the three match-all forms , "" and no matcher at all. Each run was one claude -p call that asked the model to call the seven tools once each, in order, and report OK or FAILED for each one: claude -p "$PROMPT" --setting-sources project,local \ --strict-mcp-config --mcp-config "<lab /mcp.json" --plugin-dir "<lab /labkit" \ --allowedTools mcp lab mcp lab-two mcp plugin labkit lab \ --model opus --output-format stream-json --verbose --include-hook-events \ --max-turns 20 --session-id "$SID" --debug-file "runs/$NAME/debug.txt" < /dev/null --setting-sources project,local keeps our user settings, and the hooks and plugins they enable, out of the session. --include-hook-events puts a hook started event into the stream for every hook Claude Code starts, so we could check the logger against Claude Code's own count. CLAUDE CODE DEBUG LOG LEVEL=verbose made the debug file include the matcher lookups. We also unset the CLAUDE variables exported by the session we were working from, so the child runs did not inherit them. There were three conditions: --allowedTools gets the bare server prefixes, which is the permission-rule form the permissions page says covers a whole server. --strict-mcp-config removed, because in the allowed runs it kept the plugin's server out entirely the stream's init event listed only lab and lab-two , and the model reported the three plugin tools as unavailable . To keep the account's claude.ai connectors from joining once strict mode was off, these runs set ENABLE CLAUDEAI MCP SERVERS=false . The plugin:labkit:lab , Every run called every tool it could see exactly once, after one ToolSearch call to load the deferred MCP tools one run made a second ToolSearch call that found nothing . That makes 65 MCP tool calls that reached PreToolUse : 42 to the lab server's three tools, 14 to lab-two , and 9 to the plugin's copy. In every one of the 14 runs, the number of lines the logger wrote equaled the number of hook started events in the stream, 999 in total, so the log below is Claude Code's own count, not our script's. Each cell is the number of calls for which that group's hook ran, out of the calls made to that tool, summed over all 14 runs. ping , echo and upper are the lab server's three tools, two is mcp lab-two ping , plugin is the plugin's three tools together, and ToolSearch is the built-in tool the model used to load the MCP tools. matcher PreToolUse ping echo upper two plugin ToolSearch mcp lab 0/14 0/14 0/14 0/14 0/9 0/15 mcp lab-two 0/14 0/14 0/14 0/14 0/9 0/15 lab 0/14 0/14 0/14 0/14 0/9 0/15 ping 0/14 0/14 0/14 0/14 0/9 0/15 Bash|mcp lab 0/14 0/14 0/14 0/14 0/9 0/15 mcp . + if: mcp lab 0/14 0/14 0/14 0/14 0/9 0/15 mcp . + if: mcp lab 0/14 0/14 0/14 0/14 0/9 0/15 mcp . + if: mcp lab ping 14/14 0/14 0/14 0/14 0/9 0/15 mcp lab ping 14/14 0/14 0/14 0/14 0/9 0/15 mcp lab ping|mcp lab echo 14/14 14/14 0/14 0/14 0/9 0/15 mcp lab ping, mcp lab echo 14/14 14/14 0/14 0/14 0/9 0/15 ^mcp lab echo 0/14 14/14 14/14 0/14 0/9 0/15 mcp lab . 14/14 14/14 14/14 0/14 0/9 0/15 mcp lab 14/14 14/14 14/14 0/14 0/9 0/15 mcp lab 14/14 14/14 14/14 14/14 0/9 0/15 mcp lab. 14/14 14/14 14/14 14/14 0/9 0/15 mcp lab-two . 0/14 0/14 0/14 14/14 0/9 0/15 mcp plugin labkit lab . 0/14 0/14 0/14 0/14 9/9 0/15 mcp . 14/14 14/14 14/14 14/14 9/9 0/15 14/14 14/14 14/14 14/14 9/9 15/15 "" 14/14 14/14 14/14 14/14 9/9 15/15 omitted 14/14 14/14 14/14 14/14 9/9 15/15 There is no partial cell anywhere. Every matcher either fired on every call to a tool or on none of them, in every condition, so the 14 runs are 14 copies of the same answer. PostToolUse gave the same pattern for every call that executed: 37 calls in the allowed and plugin runs, the same 37 that the server recorded in calls.log . mcp lab fired for none of the 65 MCP calls, and neither did mcp lab-two , lab , ping or Bash|mcp lab . Each of them has only exact-match characters, so each was compared as a whole name, and no tool is called mcp lab , mcp lab-two , lab or ping . The list form fails the same way: Bash|mcp lab is two exact names, and neither is an MCP tool. That matches the documentation word for word. What we wanted to know was how loudly it fails. In the transcript, the stream, and the process's stderr empty in all 14 runs there was no sign of it. The -p run exited 0 and the model reported its calls as usual. The only trace was in the debug file we had asked for with --debug-file , which had three lines like this in all 14 runs, written at the first tool call of the session: WARN Hook matcher mcp lab matches no tool it is compared as an exact string . To match all tools from this server, use mcp lab . . See CHANGELOG v2.1.195. WARN Hook matcher mcp lab-two matches no tool it is compared as an exact string . To match all tools from this server, use mcp lab-two . . See CHANGELOG v2.1.195. WARN Hook matcher mcp lab matches no tool it is compared as an exact string . To match all tools from this server, use mcp lab . . See CHANGELOG v2.1.195. All three were written within a millisecond of each other, just before the first PreToolUse lookup, and the PostToolUse lookups with the same strings added none. The second mcp lab line comes from the Bash|mcp lab group: to make sure, we ran one more session in a separate directory whose settings held only that group, and its debug file had exactly one mcp lab warning while the hook stayed silent on the ping call the server logged. So Claude Code does recognize the server-prefix mistake, including inside a list, and tells you the fix. It just tells the debug log, which we had to ask for with --debug-file . lab and ping matched nothing and got no warning at all; the check seems to cover only the mcp <server shape. We also ran claude doctor in the lab directory, the read-only diagnostics command, and it printed "No installation issues found." with nothing about hooks. The hyphenated server is where version history matters. By the 2.1.195 changelog entry, a matcher like mcp lab-two used to substring-match, which would have made it fire on every lab-two tool, and since 2.1.195 it exact-matches and fires on none. On 2.1.289 we measured the second half: 0 of 14. We did not run an older version, so the first half is the changelog's word, not a measurement. Read together with the docs table, a hook written as mcp <server for a hyphenated server may have worked before that release and stopped working after it, with nothing in the session output to show the change. The allowed runs passed --allowedTools mcp lab mcp lab-two mcp plugin labkit lab . All 21 calls to lab tools in those runs 4 allowed runs and 3 plugin runs, three tools each executed and returned pong , a or B , and calls.log has all of them. In the seven runs without the flag, every MCP call came back as an error with the text Claude requested permissions to use mcp lab ping, but you haven't granted it yet. with the tool's own name , and calls.log gained nothing. So in a permission rule, the bare prefix mcp lab covered all three tools, as the permissions page says. In the same runs, the matcher mcp lab started no hooks. The if field was the surprise. The hooks page calls it permission rule syntax, and the permissions page says mcp puppeteer and mcp puppeteer each match a whole server. Both forms failed as if conditions: the group with matcher mcp . and if: "mcp lab" fired 0 times in 42 lab calls, and the one with if: "mcp lab " also fired 0 times. The debug file names the reason for each call: Skipping hook due to if condition "mcp lab" not matching , and the same for "mcp lab " . A full tool name worked. if: "mcp lab ping" fired on 14 of 14 ping calls and on nothing else. So on 2.1.289, in this lab, if accepted the permission-rule form for one MCP tool but not the forms for a whole server. Note that the matcher in front of all three handlers matched, so the if was the only thing deciding. Unlike the matcher case, the debug log gave no warning for these, only the per-call skip lines. The no-allow runs showed one more thing about PreToolUse . It fired for every one of the 28 denied MCP calls, with the same matcher pattern as the table, and PostToolUse fired for none of them. A PreToolUse logger counts attempts, including ones the permission system then refuses; if you want a record of calls that ran, it belongs in PostToolUse . Two strings that look like permission-style globs fired because they happen to be valid regular expressions, and a third shows how far a loose regex reaches. mcp lab is a glob in a permission rule, but a matcher with in it goes down the regular-expression path, where it means mcp lab followed by any number of underscores. Tested anywhere in the name, that is found in all three lab tool names, so it fired 42 of 42, and not on mcp lab-two ping , where lab is followed by a hyphen. It works, but not for the reason it looks like it does. mcp lab mcp la followed by any number of b s and mcp lab. went further and fired on mcp lab-two ping too, 14 of 14, because both patterns match the start of that name as well. The anchored ^mcp lab echo fired on echo and on echo upper , which is the docs' Edit. example in MCP form: a leading ^ only makes it a prefix test, and only a closing $ makes it a whole-name match. The exact forms did exactly what the docs table says. mcp lab ping fired on ping only. mcp lab ping|mcp lab echo and mcp lab ping, mcp lab echo each fired on ping and echo and not on echo upper , which confirms on this version that the comma-list fix from 2.1.191 holds, space included. mcp lab . , the form the docs and the debug warning both recommend, fired on all 42 lab calls and on nothing from lab-two , because the double underscore after the server name stops the prefix from running into lab-two . But it fired on none of the 9 calls to the plugin's copy of the same server, whose tools are mcp plugin labkit lab . Only mcp plugin labkit lab . , mcp . and the three match-all forms caught those. This is the documented plugin behavior. What it means in practice is that the right matcher depends on how the server was installed, and the same server can be installed both ways. , "" and an omitted matcher were identical: every MCP call plus all 15 ToolSearch calls. mcp . caught all 65 MCP calls and no built-in tool. The one-line fix is the one the warning already prints. Wherever a tool-event hook says "matcher": "mcp <server " , make it "matcher": "mcp <server . " , keeping the double underscore so it can't run into a server whose name starts the same way. If the server comes from a plugin, write mcp plugin <plugin <server . instead; the bare server key will not match. If you want one hook on one tool, the plain exact name is the tightest form there is. If a list is easier to read, | and , both worked. To find the dead matchers you already have, the cheapest check we found is the one that produced the warnings above. Run one claude -p session that makes at least one tool call, with --debug-file , and search the file for matches no tool . It caught every mcp <server -shaped matcher in this lab, including one inside a list. It did not catch lab or ping , so it is a check for the server-prefix mistake, not a general one. For if , don't rely on the server-wide permission forms on this version. Put the server filter in the matcher mcp lab . and use if for a single tool name, or drop it. And if a hook exists to keep a record of what a server did, register it on PostToolUse and check it against the server's own log once. Here those two counts agreed at 37, while PreToolUse also counted the 28 calls that never ran. You need Node and Claude Code; the server has no dependencies. The request loop of server.js , with the tool definitions, the calls.log line and the error replies cut out: js const serverLabel = process.argv 2 || "lab"; const tools = serverLabel === "lab-two" ? fullToolSet.slice 0, 1 : fullToolSet; const send = message = process.stdout.write JSON.stringify message + "\n" ; readline.createInterface { input: process.stdin } .on "line", line = { if line.trim return; const request = JSON.parse line ; if request.id === undefined return; if request.method === "initialize" { return send { jsonrpc: "2.0", id: request.id, result: { protocolVersion: request.params?.protocolVersion ?? "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: serverLabel, version: "1.0.0" } } } ; } if request.method === "tools/list" return send { jsonrpc: "2.0", id: request.id, result: { tools } } ; if request.method === "tools/call" { const output = runTool { name: request.params?.name, args: request.params?.arguments ?? {} } ; return send { jsonrpc: "2.0", id: request.id, result: { content: { type: "text", text: output } } } ; } } ; Then the steps: mcp.json two servers, above and the labkit plugin directory .claude-plugin/plugin.json plus a .mcp.json registering the same script under .claude/settings.json with one group per matcher you want to test under PreToolUse and PostToolUse , each calling the logger with its own label. claude -p command above, with --plugin-dir and fires.log by label and tool, and compare it with the hook started events in the stream and with calls.log . grep "matches no tool" runs/ /debug.txt and grep "Skipping hook due to if condition" runs/ /debug.txt . The prompt, as sent: This is a plumbing test of MCP tools. Call each of the following tools exactly once, one call at a time, in this order. Do not call any other tool, except ToolSearch if you need it to load these tools. 1. mcp lab ping 2. mcp lab echo with text "a" 3. mcp lab echo upper with text "b" 4. mcp lab-two ping 5. mcp plugin labkit lab ping 6. mcp plugin labkit lab echo with text "c" 7. mcp plugin labkit lab echo upper with text "d" If a tool is missing, denied or fails, do not retry it; move on. After the last one, reply with one line per tool: its name, then OK or FAILED. Every run was headless. We did not open the interactive /hooks menu or the in-session /doctor to see whether either shows the matcher warning. We did not run a version older than 2.1.195, so the claim that hyphenated server matchers used to fire is the changelog's. We tested PreToolUse and PostToolUse only, not PostToolUseFailure , PermissionRequest or PermissionDenied , which the docs say match on the same tool name, and not the Elicitation events, whose matcher is the server name rather than the tool name. In if we tried three forms and no parameter form. We did not test a single pattern meant to cover both the plugin copy and the direct copy of a server, and we did not test HTTP or MCP-tool hook handlers, Windows, or a model other than claude-opus-5-5 . Fourteen claude -p runs for the table on 2026-10-05 between 16:24 and 16:32 UTC, plus the one-group check at 16:38, Claude Code 2.1.289 on macOS, claude-opus-5-5 , Node 22 for the server and the logger. Four allowed runs, seven runs without an allow rule, three plugin runs. In those fourteen, 65 MCP tool calls reached PreToolUse , 37 executed, and the server logged the same 37. The logger wrote 999 lines and the streams carried 999 hook started events. Each run took 18 to 38 seconds. The reported cost was $0.617 for the fourteen and $0.675 with the check run. The whole lab is a 61-line server, a 20-line logger and one settings file, and the fourteen runs behind the table cost $0.617, so it is cheap to rerun against your own matchers before trusting them. If you have a hook matcher that turned out to match nothing, or a version where if: "mcp <server " does match, post the string and your Claude Code version in the comments below.