Repository navigation
fix(mcp): reconcile agent-config tool refs against the final server map - #11989
Conversation
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS App-ownership completeness is reconstructed inside Watch
[DESIGN-REVIEWED] 61c35de |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the deliberate cost: any rebuild while a binary is off PATH now revokes that server's auto-approvals, and a human re-grants after every such hiccup. Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: FIX — stop renamed/uninstalled MCP servers leaving dead
[FIRST-PRINCIPLES-REVIEWED] 61c35de |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsI've read the full diff, the discovery pass output (no candidates), and verified the load-bearing facts: No findings. [OPUS-REVIEWED] 61c35de Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
d414572 to
d8cd455
Compare
d8cd455 to
1354c2f
Compare
1354c2f to
062b849
Compare
|
On the First Principles CONCERNS, item 6: naming the bypassing path rather than deleting the strip.
Delegating instead of deleting does not work either. The purge runs before the The divergence the review names is real and worth stating plainly: the purge's Happy to be overruled if the preference is to delete the strip and adjust its |
1d5bf8f to
ba88fe9
Compare
|
Fixed in The finding is correct. Why the remedy is worth taking as stated. Every round of findings on this predicate has been an instance of one conflict:
One set cannot be right for both, so each compromise produced a new hole. Evidence. Collapsing the two predicates back into one reproduces this finding exactly: One test changed its expectation and I am flagging it rather than letting it pass as a rename. One proof I did not get. I mutation-verified the grant side. The mirror mutation -- making flake8, isort, mypy and the comment-history gate clean on all four files. |
ba88fe9 to
03b6060
Compare
|
F2 is real and is fixed. F1 asks for the opposite of the previous round's F1.
Those are mutually exclusive orderings of the same two lines. The adjudication records the conflict rather than resolving it: it notes the in-code comment "states plainly that an EXACT app claim is unambiguous and must NOT be rescued by a co-declaring source", says "the finding argues the opposite ordering", and still upholds on the torn tie-break rather than on the merits. I am not going to alternate that line each round. Implementing F1 re-opens the round-5 finding by construction, and the round after would presumably raise it again, so the loop has no terminating state. Whichever ordering ships needs to be a decision, and I do not get to make it by being the last one to push. What each ordering costs, so whoever rules has both sides. Exact-claim-wins (current): a disabled app's grant never lingers on a name a reopened gate could hand to a managed server, at the cost that a user server colliding exactly with a disabled app's alias loses its per-tool refs, and the next successful rebuild restores a whole-server grant instead. Vouched-wins: that user server keeps its narrower refs, at the cost that an app aliasing onto a gated managed name keeps an auto-approval while switched off. Both sit on Board otherwise. |
|
Fixed in I was wrong to call round 7 a contradiction. Its remedy said "let a non-gated The mechanism this round named is real, and it decides the question. I checked it rather than taking it on wording. At
A suffixed sibling stays ambiguous under either, so any vouching still outranks the guess there. Both halves are pinned and mutation-proven, each killing exactly one test. Letting the gate vouch reproduces the round-6 finding: 550 tests green across Worth stating plainly, since I had claimed the opposite one head ago: this predicate has taken eight rounds of findings, every one real, and the last two were the same correct point that I mishandled once. I withdraw the loop claim. |
|
Both items fixed in The advisory was right and it was my own doing. F1 is the same blindness I fixed one level down. Last head I stopped What I did not take, and why. The remedy says to treat any occupied unlisted entry that is not a directory as unread. That includes an entry which inspects cleanly as a plain file. I declined that half: an ordinary non-app file in the apps root is indistinguishable from an overwritten app root, so counting it would hold ownership permanently incomplete, and incomplete ownership narrows the exemption for every unclaimed name on every rebuild. I could not establish whether stray files normally live in that directory -- the reads I needed were refused repeatedly by the gateway's path resolver -- so I chose the form that cannot misfire in normal operation over the form that closes one more case. The residue that leaves: an app root overwritten by a plain regular file reads as absent. It is narrower than what this head fixes, and it is stated here rather than discovered later. Both halves are pinned as a pair on the same shape of input. A dangling 552 tests green across |
Round 10: rebased for freshness, and both Design watch items closed
The freshness check, which is why this head exists
Rebased onto Design item 1: the spec, which AGENTS.md requires in the same commitAGENTS.md line 31 says to update the owning doc "in the same commit when you change
Design item 2: verified, and it was rightThe claim was that a dropped mount ref leaves nothing at default log level. That A Two tests pin the pair, and the first reads the shipped default instead of spelling 554 tests pass across First Principles item 5, declined with the conflict namedThe subtraction asks to exempt grants only for vouched or gated names and delete Item 8 is the same duplicate-strip finding dispositioned at 5742013857 and sharpened |
The one red on
|
cixuuz
left a comment
There was a problem hiding this comment.
Thorough fix for a real reported bug (#3310): dangling @ref entries surviving server renames/removals, with a per-tool allowedTools grant leak on the path that never reaches PreToolUse. The two-exemption-set design (mounts fail-open toward keeping refs since dropping is unrecoverable; grants fail-closed toward revoking since a stale grant is the real risk) is sound and consistently applied. Verified RESERVED_TOOL_NAMESPACES exists as referenced. SEL audit added for grant revocation, matching the standing audit-parity convention. Extensive test coverage of the tricky edges (dangling app-root symlink/junction, transiently-unread ownership claims, revocation audit).
Round 11: rebased onto current main, no code changeThe previous head Rebased onto The same-file overlap is genuinely disjoint from my section. Main's change to Scoped tests on the rebased tree: 554 pass. Four gates clean, two locally red and both main-owned.
Cost this round, stated rather than buried. The force-push dismisses the |
Board on
|
Round 12: the maintainer ruled for GPT's finding, and it is implementedThe decision on The change is one condition
My first cut followed the remedy's literal wording and was wrongI gated the grant on Four tests carry the contract, three of them controls in tests about other things
Both halves are mutation-pinnedMaking the grant unconditional again gives four failures of the form Verification on the rebased tree554 tests pass across The comment gate earned its place this round: it caught two phrases I had written BaseRebased onto |
Round 13: both reviewers found the mirror of the last fix, independently, and they were right
The defect
I verified the chain before acting rather than taking two reviewers' word: The fix is the ruling applied to the other listThe branch is now an unconditional
Four existing tests changed on the mount half only
A new test, Both halves pinned, and each mutation hits only its own halfRe-gating the mount on the completeness flag kills five mount assertions, Verification555 tests pass across the four suites, all
Base
|
Round 14: the same asymmetry, one branch over
Why this is new rather than a re-litigationRounds 2 and 3 were about a base whose app is switched OFF: round 2 added the It is also the rule the maintainer already set, applied one branch over. The The change
Exactness only ever narrows the grant, so round 2's case is unaffected: a family No existing test covered this, which is why it survivedAll 278 tests passed with the fix applied and nothing changed, so the enabled-base Both directions are mutation-pinned against that one test. Dropping the exactness Verification556 tests pass across the four suites, all
|
Round 15: the finding is real, and its cited line was the wrong location
Two wrong guesses, each disproved by measurementFirst I assumed a disabled server is dropped from the final Second I excluded disabled entries from the grant half of The real location
ref = f"@{alias}"
if spec.get("disabled") or alias in _disabled_anywhere:
for key in ("tools", "allowedTools"):
lst = config.get(key)
if lst is not None and ref in lst:
lst.remove(ref)It removes the exact The comment four lines above this block already rules the behaviour out: "under- It is also the live consequence of something First Principles raised several The fixThe disable now removes every ref the alias owns, matched on the Tests
Mutation: neutralising the per-tool arm reproduces the original failure exactly, 557 tests pass across the four suites, all Base
|
Split: this PR now keeps only the ref-prune and the grant ruleThe maintainer ruled to split rather than keep fixing round by round. This PR Everything else moves to #12149, with public reproductions and test boundaries. Removed from this PR
A correction to two earlier commentsMy round-15 and round-16 comments describe the disable-path per-tool fix as landed Why split rather than continueThe previous head had every review lane clean, GPT included, for the first time on Splitting gives those their own review budget and lets the settled part land. State556 tests pass across the four affected suites. |
kiro-cli mounts what mcpServers declares, so a @ref naming a server absent from that map mounts nothing. Several rebuild passes narrow the map without touching the ref lists: the resolution pass replaces mcpServers wholesale and drops unresolvable servers by omission, and the locked app re-merge deletes app entries whose app is not confirmed enabled. The refs those passes leave behind are probed on every discovery cycle, and an allowedTools ref is worse than cosmetic -- that list never reaches the PreToolUse gate, so the grant sits on the name and a server added under it inherits an auto-approval nobody granted for it. prune_dangling_tool_refs runs once over the FINAL map, inside the write funnel, so it covers every narrowing pass including one added later. WHAT IS EXEMPT, and why each exemption is narrow: A reserved kiro namespace is not a server ref at all. RESERVED_TOOL_NAMESPACES is imported from the module documented as the ONE reader of the tools ref vocabulary, so the two cannot drift. @Builtin is listed by kiro's own configuration reference, never appears in mcpServers, and carries the whole built-in tool surface plus the tool_search loader. A server whose DECLARED COMMAND did not resolve on this pass keeps its refs, because the next rebuild reverses that absence once the binary is installed and an existing config never re-adds a template ref. The set is collected in the one branch that means it rather than inferred from "declared but missing from the final map": a commandless stub, a spec that is not a dict, and a server the locked app re-merge deletes are real absences no later pass reverses, and inferring would retain exactly the refs this exists to drop. That exemption ends for a name an app owns unless the app is positively enabled, since otherwise nothing re-adds the entry and the grant is left sitting on the name. Ownership is read from the app manifests that MINT these keys, never inferred from the name: mcp_server_alias returns a slash-free name unchanged, so a global mcp.json server keyed `npm:foo` reaches the config with its colon intact, and an installed app called `npm` that declares only `bar` does not own it. The enumeration covers DISABLED apps deliberately, because "an app owns this name and is switched off" is the whole case and it is invisible to a collection that stops at enabled apps. Ownership is read twice, once before this rebuild's work and once at the reconcile, and a key EITHER read claims needs a positive enablement answer: an app uninstalled mid-rebuild has left both the listing and its manifest, so a late read alone cannot tell "its app is gone" from "no app ever owned this", and the second of those is the permissive answer. A gated-off shipped server keeps its refs while its entry is withheld, by the decision the withhold audit records. Dropping a ref out of allowedTools REVOKES an auto-approval, which is a permission decision, so it emits mcp_auto_approve_revoked into the same SEL feed as the withhold in the same pass instead of only an INFO log. Auditing never fails the rebuild. The server-name split reuses the spelling agent_capabilities._materialize and apps.bridges already use, so the per-tool form (@server/tool, @server/*) resolves to the same server in all three. Fails safe: a non-dict mcpServers yields no readable verdict and drops nothing; non-string and sigil-less entries are left to the passes that own them. An unreadable app registry or manifest claims no ownership, the same answer as "no app owns this name", because the app path then contributed nothing to this rebuild either and destroying an ordinary server's unrecoverable grant is the worse of the two failures. The install harness stubs command resolution by echoing every command, which makes the unresolved-command branch unreachable, so _run_install takes an optional resolver override. Existing callers are unchanged. One existing fixture declared no server beside an MCP ref it asserts is kept, which is the dangling state itself; it now declares that server so its assertions rest on tool_search seeding rather than on the unreconciled state. Closes #11980
|
Round 18 on The finding, and why it is in scope. The cited code is the app-family branch this PR added in round 14. When a candidate is itself a claimed alias whose own app is switched ON, the The fix. The deciding set is the candidate itself when the candidate is exactly claimed, and the alias family only when nothing claims it exactly. Family matching exists for a name with no claim of its own, where the suffix is the only evidence available; where an exact claim exists, that claim answers. Mount and grant both read the narrowed set, because the harm ran through both. Test and mutation evidence. Both halves are pinned independently:
Each mutation kills only its own assertions. The fixture needed two attempts, which is worth recording. Verification. 557 tests green: 280 in The spec moved with the code. No rebase was needed this round: Scope is unchanged: a finding naming key normalization, the shared-server disable pass, the deleted-proxy purge, or app-family mount policy belongs to #12149. |
|
Design Review's CONCERNS on The watch item is correct. Board on this head: 77 lanes success, 11 skipped, zero failing-class conclusions after deduplicating to the newest attempt per lane, and The one thing outstanding is the |
Review-ready on
|
Problem / Motivation
kiro-climounts whatmcpServersdeclares, so a@refintoolsorallowedToolsnaming a server absent from that map mounts nothing. Several passesof
rebuild_agent_confignarrow the server map without touching the ref lists:config["mcpServers"] = valid_servers, so a serverwhose command does not resolve is dropped by OMISSION;
del servers[_k]for an app-namespaced entry whoseapp is not confirmed enabled.
Neither strips the refs, and nothing else reconciles them, so the refs stay in the
rendered file indefinitely.
Reported first-hand in #3310's comment of 2026-08-27, reached by renaming MCP
servers: after several renames the reporter's
~/.kiro/agents/kirocrew.jsonheld 21servers against 9 in
~/.kiro/settings/mcp.json, every orphan matched anMCP probe failed [...]warning, and each also had dangling@<name>refs in bothtoolsandallowedTools. Split out of #3310 as #11980 because that issue'sremaining scope is credential-lifecycle decisions while this half is a mechanism.
The invariant is not new to this PR. It is stated twice already, and enforced only
where the deleting code happens to remember it:
mcp_cleanup.purge_deleted_proxy_from_configstrips refs alongside its owndeletes, with a comment giving the reason;
agent_capabilities._materializefiltersallowedToolson exactly this test,server-present and not disabled.
Why it matters
Each dangling ref keeps a dead name in front of discovery, so the cost grows with
every rename instead of settling, and the only visible symptom names a server the
user believes they already removed.
The
allowedToolsside is worse than cosmetic. That list is the one path that neverreaches the PreToolUse gate, which the rebuild's own comments call out. A grant left
there is bound to the NAME, not to the server that earned it, so a server added
under that name later inherits an auto-approval nobody granted for it.
What changed
mcp_cleanup.prune_dangling_tool_refsdropstools/allowedToolsrefs whoseserver the final map does not hold. It is called once inside
_finalize_and_write,the funnel every write path goes through, so one reconcile covers every narrowing
pass including one added later rather than each pass remembering separately. It sits
before
_seed_kas_permissionsfor the reason that call already documents: thatfunction reads
allowedToolsto build the KAS policy, so a policy seeded firstwould describe refs this then removes.
Two absences are exempt, because the rebuild expects them and a later pass reverses
them while an existing config deliberately never re-adds a template ref:
this rebuild's PATH. This case also reaches the per-tool grant, which nothing
re-emits: the ref sync only ever writes whole-server
@aliasrefs, so dropping@server/searchover one bad PATH would lose it for good.its
mcpServersentry is withheld while itstoolsref is retained, so removingthat ref would unmount the server permanently once the gate reopened. I did not
know about this class when I first wrote the pass; an existing test caught it, and
removing the exemption still fails that test, which is how I know the exemption is
load-bearing rather than defensive.
Server extraction reuses the spelling
agent_capabilities._materializeandapps.bridgesalready use,ref[1:].split("/", 1)[0], so the per-tool forms(
@server/tool,@server/*) resolve to the same server in all three. A secondspelling would let the three disagree about which refs dangle.
Fails safe in both directions: a
mcpServersthat is not a dict yields no readableverdict so nothing is dropped, and non-string or sigil-less entries are left to the
passes that own them.
What review changed about the change
Three blocking findings, all real, all fixed rather than overridden.
A reserved kiro namespace is not a server ref.
@builtinis listed by kiro'sown configuration reference, never appears in
mcpServers, and carries thewhole built-in tool surface plus the
tool_searchloader. The first version ofthis reconcile deleted it from both lists at the funnel every write goes
through, on every rebuild, with an existing config that never re-adds the
entry.
RESERVED_TOOL_NAMESPACESis now imported from the module documented asthe ONE reader of the
toolsref vocabulary, so the two cannot drift, and@builtinsurvival is pinned at the helper and through a full rebuild.The exemption is collected in the one branch that means it -- a command was
declared and did not resolve -- instead of inferred from "declared but missing
from the final map". Inferring swept in a commandless stub, whose retained
allowedToolsref is a grant left sitting on a name that a different servercan be bound to next.
An app-scoped name stays exempt only while its app is still enabled, because a
server can fail to resolve here and have its app deregistered concurrently.
Dropping a ref out of
allowedToolsrevokes an auto-approval, so it now emitsmcp_auto_approve_revokedinto the same SEL feed as the withhold in the samepass, rather than only an INFO log.
Deliberately NOT in scope
The orphaned
mcpServersentries themselves are not pruned.rebuild_agent_configrecords the opposite decision, that the unmount has no safe lever in this file
because the generated config is simultaneously the mount decision and the only home
for agent-only configuration, so dropping an entry destroys whatever lives only
there. A server defined only in the agent config is documented as supported in the
same function. That decision is parked as #6171 and is a maintainer's call, not
something to reverse inside a ref fix, so #11980's first acceptance item is
deliberately unmet and its comment thread says so.
Tests
test/test_mcp_dangling_tool_refs.py, 14 cases on the helper: both ref forms, thepresent-server control, non-
@and non-string passthrough, a bare sigil, repeatedoccurrences, surviving order, idempotence, and the four not-a-dict shapes.
test_a_rebuild_drops_a_ref_whose_server_the_map_does_not_declareintest/test_agent.pypins the CALL SITE through a real install rather than thehelper alone, and measures both sides: the orphan's refs are gone from both lists
and the declared server keeps both its mount and its grant.
Mutation-verified, six mutations, each caught and each by a bounded set:
known = set(servers)(drop the exempt union)_ref_serverreturns the whole refif not serversinstead ofisinstance(..., dict){}instead ofconfigThe
declaredguard is pinned by a PAIR of tests on the same input, one with thedeclaration and one without, so a blanket keep cannot pass as the guard.
Targeted suites: 14/14 new, 255/255
test_agent.py, 374/374 across the four mostaffected files, 295/295 across the remaining rebuild-touching files.
flake8,isort,mypyclean; the comment-history gate passes on all four changed files.One existing fixture had to change and I am flagging it rather than leaving it in
the diff unremarked:
test_existing_config_seeds_missing_tool_searchdeclared anempty
mcpServersbeside an MCP ref it asserts is preserved, which is the danglingstate itself. Its subject is
tool_searchseeding and order, so the fixture nowdeclares that server and every assertion it makes about its own subject is
unchanged. The alternative, asserting the ref is dropped, would have destroyed its
ability to test the governance point it exists for.
Pattern harvest
Rule candidate: semgrep
Pattern: a name-keyed map is narrowed by rebinding it to a filtered copy
(
config["mcpServers"] = valid_servers) or bydel servers[key], in a functionthat never calls the reconcile which strips references naming the removed keys.
This generalizes, and the shape of the miss is the part worth keeping. The
invariant "no
toolsorallowedToolsref may name an absent server" wasalready written down twice in the tree and already enforced twice, and both
enforcement points sit on a path that DELETES a server:
purge_deleted_proxy_from_configstrips the refs it orphans, and the capabilitybuilder skips an
allowedToolsref whose server is not present. Neither of thetwo sites fixed here deletes a server. One drops a server by OMISSION, by
rebinding the map to the subset that resolved, and one removes a locked app
entry during a later re-merge. Both are correct about the server map, and
neither is on the path that carries the cleanup.
That is the class: an invariant maintained at N removal sites is broken by the
N+1th, and a new removal site appears every time there is a new reason to
withhold a server. This fix moves enforcement to one reconcile at the end of the
rebuild, after every writer, so the next narrowing site inherits it instead of
having to remember it. The rule candidate is the ratchet for any future site
that does not flow through that boundary.
Closes #11980