Repository navigation
fix(acp): stop asserting harness-mounted MCP servers absent - #14614
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] efce193 |
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: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Only check left: no in-repo consumer parses the old sentence (grep found 0); confirm external alerting doesn't key on "absent from the session". Not justified as shipped
What this change shipsInventory (7 items) — 6 justifiedIntent: FIX — stop the unresolved-
Unconditional hedge on kiro-cli/KAS is derived, not symmetry: [FIRST-PRINCIPLES-REVIEWED] efce193 |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
dd8acca to
6c76dff
Compare
6c76dff to
95549bb
Compare
95549bb to
516d804
Compare
516d804 to
d2f15b1
Compare
d2f15b1 to
404dc50
Compare
|
404dc50 to
32440d0
Compare
|
Rebased onto current main to clear a merge conflict in |
|
The unresolved-ref warning closed with a sentence the detector cannot back: that the listed tools are absent from the session. The detector judges the wire array (or, where the harness loads the spec itself, the spec) alone, and no backend's array is provably the session's whole MCP surface. Claude Code loads its own user- and project-scope mcpServers and plugins beside the array Crew sends, codex-acp merges Crew's array on top of what ~/.codex/config.toml declares, and kiro-cli loads the global ~/.kiro/settings/mcp.json into every agent whatever the spec declares -- so a same-named server may be serving a listed ref while nothing of Crew's shows it. The closing sentence now claims only what the wire proves, on every backend: Crew's projection delivers none of those servers, and the harness may mount a same-named server from its own configuration, so a listed ref may still be served and the line cannot tell which. The comments and docs that called the array the session's "entire" or "whole MCP surface" say the same. The detector's satisfaction rule is untouched, no harness configuration is read, and no backend id is consulted. Fixes #13652
32440d0 to
efce193
Compare
|
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed on behalf of the maintainers (sweep 2026-09-28): readiness passed, required checks green on efce193, no blocking review threads, security posture unchanged. Approving and merging.
Problem / Motivation
Goal: A harness that mounts MCP servers from its own configuration is not told by Crew that those servers are absent: the unresolved-
@serverwarning says only what Crew can see.With
agent.acp_backend = "claude",kiro_crew.acp.mcp_ref_guardlogs its warning with the closing sentence "Those tools are absent from the session with nothing else to say so". Claude Code mounts its own user- and project-scopemcpServersand its plugins beside the array Crew sends, and none of those ever appear in Crew'ssession/newarray. So servers that were mounted and answering in the session were listed as absent, on one line with servers that really were missing (thekirocrew-*servers only travel on Crew's array). An agent that read the line told the user those tools were unavailable, and the user had to correct it. codex-acp has the same shape on record: it merges Crew's array on top of what~/.codex/config.tomldeclares, and kiro-cli loads the global~/.kiro/settings/mcp.jsoninto every agent whatever the spec declares. No backend's wire array (or spec) is provably the session's whole MCP surface.Why it matters
The line mixes a true finding with a false one and words both as certain. Whoever is diagnosing a broken session, a person or an agent, cannot tell which entries to believe, and the definitive wording sends them the wrong way.
Not a goal
~/.claude.json, a project.mcp.json,~/.codex/config.tomlor a plugin set. That makes a harness's own configuration file an input to Crew's detector, a seam decision the triage excluded on purpose, and it would still miss what plugins mount. The list stays what the wire proves; only the verdict sentence changes.unresolved_server_refsandACP_BACKENDS_SPEC_SERVERS_OFF_WIREare untouched): Crew cannot mark those refs satisfied without reading the harness's configuration.What changed (motivation → approach → change)
src/kiro_crew/acp/mcp_ref_guard.pysrc/kiro_crew/cli_doctor.py_doctor_unresolved_mcp_refs, no-mirror branch) said "absent from its sessions with nothing to say so"; it now carries the same hedged sentence as the runtime line, unconditionally. The broker-stub caveat and the registry pointer are unchanged.test/test_acp_mcp_ref_guard.py,test/test_cli_doctor.pydocs/system-specs/modules/agent-host-contract.mdsrc/kiro_crew/agent_sdk/backends.py,src/kiro_crew/agent_sdk/mcp_refs.py,src/kiro_crew/acp/client.py,src/kiro_crew/acp/harness/codex.py,src/kiro_crew/providers/mirrors/claude_code.py,src/kiro_crew/docs/agent-spec-fields.md,docs/system-specs/modules/claude-code-provider.mdgrep -rni "entire MCP surface|whole MCP surface" src docsfinds none).The symptom is a sentence, not a list. "Absent" is the strong claim, and the detector cannot back it anywhere: it reads the wire (or, on kiro-cli and KAS, the spec) alone, by design, and cannot tell a server the harness mounted itself from one nobody mounted. The hedge therefore applies to every backend, not only the claude session the issue reports, because no backend's wire array is provably its whole MCP surface: kiro-cli's own record in this repository (
src/kiro_crew/apps/bridges.py,acp/mcp_session_report.py) is that the global~/.kiro/settings/mcp.jsonis loaded into every agent with no off switch. The line says what the detector knows and stops there: "Crew's projection delivers none of those servers; the harness may mount a same-named server from its own configuration, so a listed ref may still be served and this line cannot tell which. The harness still works." The fields and the mirror remedy that follows are unchanged, and the leading clause now says the same thing the verdict does: the ref names nothing in Crew's projection, not nothing the session receives. The line does not claim that such a copy escapes the spec's tool narrowing: the deny rules Crew seeds are keyedmcp__<server>__<tool>, so a same-named copy is narrowed like the projected one.No per-backend branch at all, per harness-parity H6: the hedge is the weaker claim and needs no per-harness record, so nothing here reads a backend id or a spec field to choose a verdict.
One docstring in
test_acp_mcp_ref_guard.py(the codex composition-path test) said the guard's definitive sentence is exactly right for a server the mirror withholds; it now says codex gets the qualified sentence, because the operator's ownconfig.tomlis the one thing the wire cannot rule out. That is a deliberate reversal of the earlier claim, on the codex record inagent_sdk/backends.py.Review rounds (each row is that round's line, verbatim):
dd8acca627): reworded the leading clause (Opus21d8fcaae5e2), carried the hedge into the doctor's no-mirror branch (Opusf44ebe40eb24), reworded the doc premise (Opus0cc86c68a2e7), and made the hedge conditional on the spec'sincludeMcpJson(GPTd833401a6be9).includeMcpJson: falsedoes not provably exclude the project mcp.json (Design); the hedge stays unconditional as FP settled it. The three wording fixes of Round 1 stay. Rebased after main's #14623 moved_doctor_unresolved_mcp_refsout ofcli_doctor.py: the doctor hedge now lives insrc/kiro_crew/doctor_checks/mcp.py(same sentence, same no-mirror branch, test follows it), andcli_doctor.pyis no longer in the diff.516d8048fe): corrected the contract's KAS sentence --AcpRuntime._guard_unresolved_mcp_refsruns the same guard from_finish_create_sessionandload_session, so KAS is checked at runtime as well as statically, not "statically only" (GPTagent-host-contract.md:327); softened the guard's code comment on kiro-cli's global~/.kiro/settings/mcp.jsonfrom "into every agent whatever the spec declares" to "by default (a spec may opt out of the global file withincludeMcpJson: false)", asagent-spec-fields.mdrecords it (Opus21d8fcaae5e2, re-printed) -- comment text only, the emitted sentence and its unconditional shape unchanged; the contract's twin of that sentence is softened identically. Rebased onto main's #14651 (hermetic hop-guard cases on macOS), the heal for the inheritedmacOS (2)red.d2f15b149e, Opus advisory ×2): the r3 sweep is finished across the claim family --actually about to receive,whatever the spec,into every agent,what the session … receive,no server this session gets,absent from the session-- over src/, test/, docs/ and website/docs; every occurrence describing this guard or its report field now carries the hedge wording (the two Opus items plus the sweep's own hits), the emitted sentence and its unconditional shape untouched (no condition, no set). The sweep ledger follows. The round lines moved into this table, verbatim, becauseWhat changedhad passed the prepare-pr skill's 500-word prose cap (534) with Round 3; table rows are outside that count by the check's own rule.test_pid_reader_ratchetdrift, tracked in #14776, not this PR's.e88e807786to pick up #14778, the #14776 heal; no content change.Round 4 sweep ledger:
test/test_acp_mcp_ref_guard.py:367docstringincludeMcpJson: false)" (Opus)test/test_acp_mcp_ref_guard.py:265,:702docstringssrc/kiro_crew/providers/mirrors/README.md:28src/kiro_crew/acp/mcp_session_report.py:418(unresolved_refsfield),:461(record_unresolved_refs)src/kiro_crew/agent_sdk/mcp_refs.py:23,:171src/kiro_crew/agent_sdk/backends.py:1466(ACP_BACKENDS_SPEC_SERVERS_OFF_WIREcomment)src/kiro_crew/acp/session_mcp.py:453docs/system-specs/modules/agent-host-contract.md:302test/test_acp_mcp_ref_guard.py:374,:396src/kiro_crew/acp/mcp_ref_guard.py:47_log_saferedaction, not this claimsrc/kiro_crew/doctor_checks/mcp.py:116,src/kiro_crew/providers/mirrors/README.md:291no-channelrow: pi-acp forwards no array, a registry-declared transport property, not this guard's verdictsrc/kiro_crew/mcp_gateway/rewriter.py:2304KIROCREW_SESSION_KEY, steering and scratch-tree "into every agent"; "session receives" in unrelated subsystems)Backwards compatibility
Compatible: one log line changes wording (leading clause and closing sentence) on every backend, the doctor's no-mirror row changes wording the same way, and the comment and doc sentences that described the array change with it. Nothing parses those sentences; the session MCP report carries
unresolved_refsas data and is unchanged. No vocabulary is added.Tests
TestTheWarning::test_the_verdict_claims_only_what_the_wire_proves_on_every_backend, parametrized overACP_BACKENDS_KNOWN, pins the full rendered line on every backend: the new leading clause, fields and remedy, the hedged sentence present, and neither "absent from the session", "nothing else to say so" nor "this session receives" anywhere. Red on main, green on this head.TestUnresolvedMcpRefs::test_the_no_mirror_verdict_claims_only_what_the_wire_provespins the hedge on the doctor's no-mirror branch for goose and kiro alike, with the broker-stub caveat and the registry pointer kept.Red-first evidence, on unmodified source with the wording test added (the claude case is shown; every backend rendered the same definitive sentence on main):
On this head,
-n0one file at a time:test_acp_mcp_ref_guard.py89 passed;test_cli_doctor.py265 passed. Black ratchet (scripts/check_black_formatting.py), isort, flake8 and mypy on the changed Python files pass;HARNESS_BASE_REF=origin/main scripts/check_harness_parity.pyclean;docs_lint.py --testanddocs-lint.shpass;push_guard.py --require-single-on-basereports a single commit onmain.Local review round on the first head (one lane at a time, read-only reviewers, CI's own contracts): GPT (
gpt-5.6-sol) and Opus (claude-opus-5) each returned no blocking finding and one advisory on the claude-only form, that codex has the same own-configuration record and a branch per harness is the shape harness-parity H6 forbids; both are answered by the final shape, which has no per-backend branch. First Principles (claude-fable-5) ran four times as the shape narrowed: it moved the fix from a named set to the wire-fed set, deleted the "narrowing does not reach" clause (the deny rules Crew seeds are keyedmcp__<server>__<tool>, so a same-named copy is narrowed like the projected one), had every "entire/whole MCP surface" sentence in comments and docs reworded, and finally showed that kiro-cli's global settings-file record makes "absent" unprovable there too; this head is its Subtraction applied verbatim, so no fifth run was made. The codex composition-path test docstring, which said the definitive sentence was exactly right for a mirror-withheld server, is reworded to the hedge as a deliberate reversal on the codex record inagent_sdk/backends.py.Manual verification
N/A — unit coverage sufficient: the change is one sentence emitted on every backend, and the tests render the log line through the real
warn_unresolved_server_refspath for every known backend and the doctor row through_doctor_unresolved_mcp_refs.Screenshots / video
no-visual-delta
Why no screenshot: backend log and
kirocrew doctorwording only; no frontend file changed and nothing rendered differs.Related Issues
Fixes #13652
Pattern harvest
Rule candidate: review-prompt
Pattern: a diagnostic asserts a negative ("absent", "nothing else to say so") about a surface its inputs do not observe; a log line may only claim what the data it read can prove, and when a harness can add to that surface behind Crew's back the weaker sentence is the one the evidence supports.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement