wenshao · Oct 6, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/docs/design/mcp-tool-name-provider-compatibility.md b/docs/design/mcp-tool-name-provider-compatibility.md
@@ -1,5 +1,7 @@
 # MCP Tool Name Provider Compatibility
 
+[English](mcp-tool-name-provider-compatibility.md) | [简体中文](mcp-tool-name-provider-compatibility.zh-CN.md)
+
 ## Problem
 
 Qwen Code currently accepts MCP tool names using Gemini's character set. Names such as `literature.search_pubmed` become `mcp__server__literature.search_pubmed`, which Gemini accepts but stricter OpenAI-compatible and Anthropic-compatible endpoints may reject before the tool can run.
@@ -15,15 +17,32 @@ Use one deterministic provider-safe normalization rule for MCP tool names:
 - Keep the final name at 63 characters or fewer, which is accepted by Gemini and stricter OpenAI-compatible and Anthropic-compatible providers.
 - Use the registered name throughout an MCP invocation instead of rebuilding it from raw server and tool names.
 - Normalize MCP names in restored OpenAI and Anthropic request history so sessions created before the change remain sendable.
-- Continue matching legacy MCP permission and disabled-tool entries by carrying the exact pre-normalization alias derived from the raw server and tool names. This also preserves names truncated by the previous middle-truncation algorithm without broadening wildcard matches.
+- Continue matching legacy MCP permission and disabled-tool entries by carrying the exact pre-normalization identity derived from the raw server and tool names. This also preserves names truncated by the previous middle-truncation algorithm without broadening wildcard matches.
 
 No provider-specific alias table is introduced. Legal existing names remain byte-for-byte unchanged, so Gemini behavior and normal built-in tools are unaffected.
 
 Restored names produced by the previous middle-truncation algorithm are already provider-safe and remain unchanged in historical messages. Their removed middle cannot be reconstructed reliably, so converters do not guess a new hash-based name; exact permission and disabled-tool compatibility instead uses the raw-name alias available during MCP registration.
 
+## Rule matching
+
+Permission rules and `disallowedTools` blocklists may be written in a legacy spelling (`mcp__foo.bar__tool`) that no longer equals the registered provider-safe name. Matching works as follows (`packages/core/src/permissions/rule-parser.ts`):
+
+- Each `DiscoveredMCPTool` advertises `permissionAliases`: the **exact raw identity** `mcp__<server>__<tool>` first, then the legacy `generateLegacyMcpToolName` reduction when it differs. A verbatim provider-safe registration lost nothing and advertises no alias. The registry (`ToolRegistry.getPermissionAliases`) and the invocation (`permissionFlow.ts`) read this same array.
+- An alias is accepted as the tool's raw identity only when its own normalization **is** the registered name, so a different server's tool can never supply the raw identity a rule is matched against. The raw prefix comes from the user's configured server key, not from the server. Exact three-part entries are the one exception: they additionally match the advertised legacy reduction as a whole string, without this normalization check; grants additionally pass the registry ambiguity check below.
+- Exact, server-level, and wildcard patterns are then compared **literally** against the registered name and the raw identity, plus the gated legacy reduction the next bullet describes. Nothing is reconstructed and nothing is hashed in this matcher: a registered name whose tail merely imitates a normalization hash proves nothing. An earlier design reconstructed candidate raw names and verified them against the unkeyed FNV-1a name hash; that proved only an existential (some raw name under the rule's prefix normalizes to this registered name) and was forgeable, so it was deleted rather than gated (#10199).
+- Grant matching reads the legacy reduction only when it still vouches for its server. Restrictive matching additionally uses producer-derived spellings as described below. Character substitution leaves the server segment recognizable; past 63 characters `generateLegacyMcpToolName` truncates to `slice(0, 28) + '___' + slice(-32)`. Surviving the 28-character head window is necessary but not sufficient: `_` is legal in both segments, so two short keys that differ only around the separator (`acme-weather-forecast` vs `acme-weather-forecast_`, `github` vs `github__create_reposito`) can flatten to one byte-identical reduction that a flattened comparison cannot attribute. The vouching decision is made once, at the single publication point: `permissionAliases` advertises a truncated reduction only when the window also pins down where the key ends — the whole `__` separator fits inside it, or the key ends exactly at its edge, and the key's legacy image contains no `__` and does not end with `_` (`legacyReductionVouchesForServer`). A cut that reached the server segment keeps only its first 23 characters, so two different long keys can land in one byte-identical window; that reduction cannot authorize either server. The spelling-based matcher consumes the publication by alias membership — `__` is reserved in neither segment of `mcp__<server>__<tool>` and the reduction rewrites characters, so the server boundary cannot be re-derived from the flattened spelling. Prefix arms use the raw identity's length-preserving legacy substitution when the legacy alias is published. It contains the reduction's faithful head without its injected `___`, so no separate truncated window is needed. Exact entries still compare the whole published spelling.
+- Identity-backed wildcard matching extracts the registered tool segment from the producer's provider-safe server boundary, independently of the rule's server spelling. Thus `mcp__foo.bar__get_data_*` on `foo.bar/get+data`, and prefixes reaching a registration hash or truncation cut, keep covering their own tool rather than losing a restriction.
+- `disabledTools` never reaches `rule-parser.ts`. `ToolRegistry.isToolDisabled` matches it separately: it reads the ungated `disabledToolAliases` array by exact set membership, and additionally still compares `normalizeMcpToolName(entry)` against the registered name, so a legacy-spelled entry can also disable a colliding server's tool. That normalization arm predates #10199 and fails closed — do not delete it on this document's authority without a behaviour decision.
+- The legacy `sanitizeToolNameForProvider` reduction was deliberately removed from matching: it made `mcp__foo.bar` rules reach the differently-registered server `foo_bar`. Do not reintroduce it. Pure per-tool matching still accepts provider and legacy spellings for compatibility and restrictive coverage. An allow match that depends on a lossy spelling is additionally rejected when the current session registry contains another raw identity claiming that server spelling or full tool rendering. Thus `mcp__foo_bar`, `mcp__foo_bar__*`, and a legacy exact entry cannot grant to `foo:bar` while `foo_bar` is also registered. A shared published middle-truncated legacy alias cannot grant either distinct tool. Wildcard grants resolve their server boundaries against the live producer identities. A complete raw whole-server boundary selects that server. Boundaries in the same contiguous underscore separator use the rule's explicit raw server segment; different separator positions make a tool prefix ambiguous and require confirmation for both claimants. Thus `mcp__foo____i*` selects `foo/__internal_debug` over `foo_/_internal_secret`, and `mcp__foo__*` selects `foo` over `foo__bar`; `mcp__foo__bar__deploy*` requires confirmation when both `foo/bar__deploy_x` and `foo__bar/deploy_y` are registered. A lossy or cut head without a complete boundary cannot grant while another registered rendering claims it. Raw exact rules and unique registered exact names retain priority. Bare whole-server rules support keys containing `__`, but cannot grant that server when another identity claims the string as a full tool name. A single producer's underscore tool prefix and deliberate coarse raw prefixes such as `mcp__foo*` remain valid; single-claimant aliases retain compatibility. Both permission evaluation and relevant-rule detection apply this guard. The registry is read on every decision across both model-visible and App-only tool pools, deduplicated by raw identity, so registration and removal take effect immediately without a cached alias table. Deny, ask, and `disallowedTools` preserve restrictive coverage under the boundary conditions below; `disabledTools` matching is unchanged. Direct matcher callers without a registry remain compatibility predicates, not an ambiguity-safe standalone grant authority.
+- A bare `*` is not an MCP pattern and matches no MCP tool; `mcp__*` and `mcp__server__*` keep their documented meanings.
+- Restrictive rules (`deny`, `ask`, and `disallowedTools`) also match the raw and historical spellings generated from the producer-carried `mcpIdentity`, even when alias publication withholds the legacy reduction. This preserves exact restrictions and faithful historical prefixes on long server keys. The existing identity-aware matcher retains the producer's server/tool boundary, and a registered-name cut may additionally restrict every matching claimant. A prefix that stops at or inside the key's own server separator, in its raw, provider-safe, or legacy spelling, restricts every tool of that key, including tools whose names start with `_`; this matches `main` and is restrictive-only. If several tools share a lossy restrictive spelling, all remain restricted; use the registered exact name to target just one. `allow` never uses this fallback, and no additional alias channel is published.
+- Asymmetry: a lost match can remove an explicit restriction even when a trusted server would otherwise run without a prompt. Enforcement paths therefore carry both advertised aliases and producer identity. Callers without identity retain the gated spelling behavior; callers without a live registry cannot certify wildcard grant ambiguity.
+
 ## Verification
 
 - Unit tests for valid, invalid, colliding, long, stable, and idempotent names.
 - MCP tool tests for registration, permission rules, reconnect lookup, and disabled tools.
+- Collision tests (`mcp-server-rule-collision.test.ts`): cross-server forgery witnesses (exact, server-level, and wildcard shapes), middle-truncation over-match, legacy-spelled deny coverage, and the no-alias posture.
 - OpenAI and Anthropic converter tests for restored history containing dotted MCP names.
+- Registry-backed allow tests with real producer identities: safe/unsafe server pairs, two unsafe claimants, exact same-server tool aliases, shared middle truncation, live registration/removal, single-claimant compatibility, raw/coarse rules, and unchanged deny/ask coverage.
 - Core package build and typecheck.