Repository navigation
fix(acp): the skill projection reads what withholds kirocrew-core - #14078
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify a kirocrew-core restriction hand-authored in the primary agent's spec now fails the shared spawn (all agents), not just that agent's sessions — confirm the AcpRuntimeError text reaches the dashboard. Suggestions
[DESIGN-REVIEWED] 9d1503e |
|
Intent: Make the skill projection and the control-plane mount decide whether |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify on kiro-cli itself the one external claim the settings-file What this change shipsInventory (10 items) — 10 justifiedIntent: FIX — a dashboard tool toggle (or a stale settings entry) broke every session of the default agent with an error naming the wrong file; the refusal now names the real file, restriction, and way back.
[FIRST-PRINCIPLES-REVIEWED] 9d1503e |
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: |
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: |
3c16f83 to
a73e7e3
Compare
a73e7e3 to
1126a47
Compare
1126a47 to
f5aa916
Compare
f5aa916 to
4df5d87
Compare
8a16f3f to
d510967
Compare
The control-plane mount withholds kirocrew-core's per-session element when the agent spec, the global MCP settings or the project's MCP settings carries a restriction the element cannot express; the skill projection decided the same question from the spec alone, so a tool disabled from the dashboard left every session of the default agent failing at session/new with an error naming the wrong file. Both readers ask one predicate over one source set, and a withheld element refuses the agent at preparation with a message naming the file, the restriction and the way back.
d510967 to
9d1503e
Compare
|
Problem / Motivation
Turning off any single
kirocrew-coretool in the dashboard's MCP tab breaks every session of the defaultkirocrewagent on the kiro backend. The toggle writesdisabledToolsforkirocrew-coreinto the global~/.kiro/settings/mcp.json, and the next session start fails withCannot bind skill_search to this session without losing native MCP restrictions. Check the agent's kirocrew-core server configuration.The agent spec that message points at is clean; the setting that caused the failure is in the global file, so the user hunts in the wrong place. A stalekirocrew-coreblock from an older release (atimeout, a non-stdiotype, a mute) fails the same way, which is how the second report hit it after an upgrade without touching a toggle.Why it matters
Until the user hand-edits
mcp.jsonor re-enables the tool, the default agent cannot start a session, and the error gives no route back. Two reports in one day, on macOS 0.7.0 and Windows 0.7.1.What changed (motivation → approach → change)
kirocrew-core's availability through one predicate over one source set, split by what each source is: the agent spec is judged at preparation and refuses the view; the settings files are read once per session start, by the mount alone, whose verdict comes back with the array and refuses that one session, naming the file, the restriction and the way back -- stub or no stub in the array, with the spawn and every other agent's sessions standing. The direct client, which mounts the declaration natively, keeps a view whose spec restricts other tools.session_mcp.native_settings_sources(acp/session_mcp.py)mcp.jsonthe dashboard writes, then the project's.kiro/settings/mcp.json. A file that fails the gated read raisesNativeSettingsUnreadable, which names it.session_mcp.native_mount_withholding(acp/session_mcp.py)_NATIVE_ELEMENT_KEYSisagent._MANAGED_MCP_ENTRY_KEYS - {"timeout"}: an injected element replaces the same-named declaration andacp_server_elementemits notimeout, so atimeoutset there keeps the declaration native rather than run the server on the default with nothing to say so;autoApprovestays in the table as a preference, not a restriction), a transport a user chose that is not stdio, a mute (mcp_entry_is_muted), or a non-emptydisabledToolswithholds the element, and the verdict says which file and which restriction, and the way back: the dashboard's MCP tab is offered only for a mute ordisabledToolsin the global settings -- the one file that tab writes -- while a restriction in the spec or the project's file is offered the edit that removes it there, since sending the user to the tab would leave that restriction in place and refuse the next session again. Kiro Crew's own marks on an entry restrict nothing: theregistrytransport value_enforce_managed_mcp_ownershipstamps underagent.mcp_registry_mode-- on the spec's managed entry while that mode is on, the one state in which Crew writes it; the predicate reads the mode itself (crews_registry_marker= the spec's declaration AND registry mode on), because outside registry mode kiro-cli drops a marked entry wherever it is declared, so the same value on the spec with the mode off (a marker the rebuild has not yet removed, or a line someone wrote) and in a settings file in any state is one that would have the mount launch a server kiro-cli refuses, and it withholds like any non-stdio type -- and thex-kirocrew/x-kirocrew-derivedbookkeeping keys (_NATIVE_INERT_KEYS) -- kiro-cli reads none of them as a setting. Every user-authored value the verdict repeats passes through_named, which runs the first_NATIVE_NAMED_WINDOW(1024) characters through the package's one sink cleaner (mcp_session_report.sanitize_sink_text: redact, drop control characters, then cut) and cuts the result at_NATIVE_NAMED_CHARS(64) characters -- the value is text from a settings file, the project's checked out with the repository, and the verdict reaches the gateway's log, where a newline or an escape sequence in a tool name would write a line of its own; cleaning the window whole before the cut means a credential is redacted before a cut could split it, and the window rather than the file is what a value costs (the redactors are regular expressions whose time grows faster than the text on some shapes: 100,000 digits measured at 10.8 s)._NATIVE_NAMED_TOOLS(8) bounds how many values are named, and a settings path goes through the same cleaner and is cut from the front at_NATIVE_NAMED_PATH_CHARS(256) so the tail that locates the file survives: the verdict is retained per agent for the life of the runtime while the file it quotes is read up to the reader's 50 MB ceiling. The way back is one sentence in both arms (_remedy): where the tab writes the file, "re-enable the server in the dashboard's MCP tab, or set disabled to false there"; where it does not, the edit stands alone, "set disabled to false there", since "re-enable the server" would only restate it.kiro_control_plane_servers(acp/session_mcp.py)NativeControlPlaneMount:elements, andwithheldby server name -- theNativeMountWithholding, or theNativeSettingsUnreadablethat withheld every element), both from its one read of the settings files; the predicate is reached before the array is consulted, so a name a broker stub already carries gets no element either way but its restriction is still judged and surfaced. When it withholds an element it logs the verdict at DEBUG -- the one trace of why for an agent outside the projection, which gets no refusal message.prepare_native_skill_projection(acp/skill_projection.py)kirocrew-coreentry AS AUTHORED, before the managed launch replaces it (the replacement carries onlyautoApprove,disabledToolsandtimeout, so atypeor an extra key would otherwise be dropped unjudged and the control plane mounted despite it), and over the spec alone: a restriction authored there is static for the view's life and takes the refusal arm that already serves a disabledskill_search. The settings files are deliberately not read here -- they are written while a runtime is warm and shared by every agent of the process, so a restriction there must not cost the spawn; this module reads no settings file at all. The newper_session_elementkeyword (defaultTrue, the shared runtime) says whether an element will replace the declaration: withFalse-- the direct client -- the spec predicate is not asked, because no element replaces anything there and a restriction the view copies (disabledToolson other tools, atimeout) reaches the session as written;skill_searchitself disabled or excluded still refuses the view._unpooled_control_planes(acp/runtime.py)mount.withheld["kirocrew-core"]) with the file-naming sentence, at everysession/newandsession/load. It reads nothing again: the earlierNativeSkillProjection.withholdingre-read the files for this decision, and between the mount's read and that one a toggle undone in between answered "allowed", sending the session to the generic wrong-file guard (or, behind a stub, carrying it while its array was built under the restriction); the method is gone. A stub is accepted only when the mount's read allows the element, because its overlay was written once, from the files as they were, and carries a kiro-cli-only restriction no better than the element does. The pre-existing wrong-file guard remains for what it was written for: an element neither granted nor pre-empted while the files allow it.AcpClient._spawn(acp/client.py)per_session_element=False: the direct client runs one kiro-cli process for one session, carries the identity on the process environment and mountskirocrew-corenatively from the view, so the element question does not arise there. On the previous head a specdisabledTools: ["learn_add"]-- a supported customization -- refused the view and the direct client's spawn died with an uncaughtValueError._spawn_admitted(acp/runtime.py)AcpRuntimeErrorcarrying the projection's sentence (Agent 'kirocrew': kirocrew-core is withheld by the agent spec: ...) -- the error the provider's startup paths handle aroundspawn()-- instead of the projection's bareValueError, which leftspawn()as an internal failure with the actionable text unread.acp-client.mdandmemory-skills-hooks.mdsay which files decide and when, that the mount is their one reader and hands its verdict on with the array, that the direct client mounts the declaration natively and keeps a view with restrictions on other tools, that the authored entry is what the spec judgement reads, that a stub is judged past, which marks are Crew's own and not restrictions, what bounds the message, and that every value and path it repeats goes through the package's sink cleaner over a bounded window before the cut.Two functions answered one question from different files.
kiro_control_plane_serverswithholds thekirocrew-coreper-session element when any declaration the session is subject to (the spec entry, the global settings, the project settings) carries a restriction the element cannot express, because mounting it without the restriction would widen the tool surface behind the user's back.prepare_native_skill_projectiondecided whether the agent may rely on that element by reading the spec'skirocrew-coreentry alone, sokirocrewstayed insearch_agents, and_unpooled_control_planesturned the disagreement into the hardAcpRuntimeErroratsession/new; with the broker on, a stub already in the array was accepted without any question, so a toggle written after the overlay went unenforced on that path.With one predicate over one source set, an agent whose SPEC withholds the element is refused at preparation and never enters the search set, so the
session/newguard is unreachable for that shape and the spawn that would load its view fails asAcpRuntimeErrorcarrying the reason. An agent whose spec is clean gets its view and its alias, and the settings decide each session, read once by the mount, whose verdict the runtime refuses on:Agent 'kirocrew': kirocrew-core is withheld by the global MCP settings (<path>): its disabledTools lists learn_add; re-enable those tools in the dashboard's MCP tab, or remove the disabledTools entry there to restore skill search. That refusal is per session, so the spawn and the other agents' sessions on the shared runtime stand, undoing the toggle restores the next session without a respawn, and a broker stub written before the toggle does not carry a session past it. The session is refused rather than started without the element because the view already dropped the agent's skill resources on the element's promise and a natively mountedkirocrew-corecarries no identity and answersidentity_unattestedto everyskill_search. On the direct client no element replaces the declaration, so the same specdisabledToolson other tools keeps the view and reaches the session as written. Mounting the element without the restriction stays closed, and agents that never asked for the element (no skill mapping, not the default agent) are untouched. Backend only, no UI change.Backwards compatibility
Compatible: no config key, file or contract is added, renamed or removed. The shapes that fail on main at
session/newwith the misdirected error are refused with the named one instead -- at preparation for a spec-authored restriction, at that session's start for a settings restriction; every unrestricted shape mounts and projects the same way (test_no_restriction_anywhere_leaves_the_search_agent_exactly_as_beforeis green on main and on this head), and so do thetype: registrystamp on the spec entry and Crew's bookkeeping keys; aregistryvalue in a settings file keeps the declaration native as it does on main. Atimeouton the entry keeps the declaration native as it does on main, and the verdict now names the key. A view the spec refuses fails the spawn asAcpRuntimeError, the type the startup paths already translate, instead of a bareValueError. A broker stub ahead of the element still carries a session while the files allow the element; after a toggle it no longer does, which is the enforcement the toggle promised. The direct client behaves as on main for a specdisabledToolson other tools or atimeout: the view stands and kiro-cli honours the restriction natively. Internal API:kiro_control_plane_serversreturns aNamedTuple(elements,withheld) instead of the bare array; its one production caller is the runtime, and the tests that read the array take.elements.Tests
test/test_native_skill_projection_sources.pyis new: 76 tests, 74 red on main (measured against anorigin/maincheckout at4d683462c2with its own sources). A tool disabled in the global settings, in the project settings, a mute, a non-object entry, aheaderskey and anhttptransport in a settings file each leave the view and the alias in place and refuse the search agent's session by file and restriction on a warm runtime, and the mount withholds the same element. A mute or adisabledToolsin the global settings is offered the dashboard's MCP tab as the way back; the same restriction in the project's file or the spec is offered only the edit that removes it there. AdisabledTools, a mute or anhttptransport authored in the spec refuses the view at preparation naming the spec, and atype: httporheadersspec entry is refused before the managed launch replaces it and is not mounted either. Atimeouton the spec entry refuses the view at preparation naming the spec and the key; on the global or the project entry it leaves the view and refuses that session naming the file and the key, and the mount emits no element -- because the elementacp_server_elementbuilds from that entry carries notimeout._NATIVE_ELEMENT_KEYSis the spec rebuild's own table lesstimeout, and every key the element emits is in it. A view the spec refused (adisabledTools, anhttptype) failsspawn()asAcpRuntimeErrorcarrying the projection's exact sentence, caused by itsValueError, before any process is started. Theregistrytransport value on the spec entry withholds nothing while registry mode is on (a user'ssseis still judged there); with the mode off the same value on the spec is refused naming the spec and the type -- the view at preparation, and the session mount for the search agent and for an agent outside the projection alike, with no element -- and in the global or the project file it refuses that session naming the file and the type in either mode, and the mount emits no element (red on the previous head: with the mode off the marked spec entry was accepted and the element mounted). Crew's provenance marker and derived record leave the agent projected and the element mounted while a mute beside the marker is still judged. No restriction anywhere leaves the search agent exactly as before (green on main too). Unreadable settings refuse the session and name the file. A session of an agent the spec refused reaches no guard. A broker stub in the session array does not carry a restricted search agent's session -- for the global toggle and for a project-level mute -- and does carry it while the files allow the element; on one warm runtime a stub carries the first session, a toggle written before the second refuses it naming the file, and undoing the toggle restores the third. On one warm runtime without a stub, a global toggle, a project mute or a corrupted global file written before the second session refuses that session withAgent 'kirocrew':plus the exact sentence the mount's own verdict renders, never theCannot bind skill_searchguard. The direct client's_spawn(), driven over a mocked process with a specdisabledTools: ["learn_add"], reaches the launch under the view's alias with the list on the view'skirocrew-coreentry and the search tool granted, while the same spec on the shared runtime still refuses the view (red on the previous head:ValueErrorout of_spawn());per_session_element=Falsekeeps adisabledToolson other tools and atimeoutand still refusesskill_searchitself disabled. The mount hands on the verdict it withheld on from its one read -- for a toggle, for a toggle behind a stub, for an unreadable file (every identity-bound name), and an empty map when the files allow -- and a session start reads the settings files exactly once whatever the answer and whatever the array carries (red on the previous head: two reads whenever the guard was reached). A toggle undone between the mount's read and a second one can no longer send the session to the wrong guard or carry it behind a stub: the session is refused for the verdict its array was built on, naming the file, after one read (red on the previous head both ways). Structural pins showcreate_sessionandload_sessionboth reach_unpooled_control_planes, that it refuses onmount.withheldoutside the stub acceptance and mentions neither a re-read nor the projection method that used to do it, that the projection type has nowithholdingattribute, that preparation asks the predicate over the spec alone and the mount over the same entry with the global and project sources, once, and that neither module keeps a private copy of the merge or the predicate -- the projection module names no settings reader at all. The settings-source order, the unreadable cause and the bounded tool list are pinned, seven shapes of a 100,000-character value each render to an exact cut string under_NATIVE_NAMED_TOOLS * (_NATIVE_NAMED_CHARS + 2) + 256characters while a name exactly at the bound is repeated whole, and a settings path past_NATIVE_NAMED_PATH_CHARSis named by its tail in the source label, the unreadable error and its explanation alike, while a short one is repeated whole in the platform's own rendering (the pin compares againststr(Path(...)), so it holds on the Windows shard too). A tool name and a key carrying a newline, a carriage return and an escape sequence render with none of them and every character of the sentence printable, a credential-shaped tool name renders redacted, and a settings path carrying a newline and an escape sequence is repeated cleaned in the source label, the unreadable error and its explanation alike (red on the previous head: the newline and the credential reached the sentence as written); a value padded with newlines ahead of 100,000 characters still renders the exact cut string, and a value the window did not hold whole renders what the cleaner left of it plus the marker, under the ceiling. The remedy is one sentence in both arms: with the tab, "re-enable the server in the dashboard's MCP tab, or set disabled to false there" (and the same fordisabledTools); without it, the edit alone, and the whole rendered sentence is pinned both ways (red on the previous head: "re-enable the server set disabled to false there"). The direct client's mocked process binds_UNALLOCATABLE_PID, the shared spelling fromtest/test_update_provider.py, so a cleanup path that signals it reaches no live process on the runner (SASTkirocrew.mock-pid-allocatableon the previous head), and the spawn hands its process factory straight through the Windows cleanup admission the way the sibling spawn tests do (test_acp_spawn_offload), since the admission owns the factory and creates the child through the loop's own transport where a mockedcreate_subprocess_execis never reached (the Windows shard on the previous head:FileNotFoundErrorfrom_create_windows_subprocess_owned); the cleaned-path pin compares the tail in the platform's own rendering (str(Path(...))), the Windows shard's other red.test/test_native_skill_projection.py: thenative_treefixture pins the globalmcp.jsoninto the temp tree so the projection's read never touches the host's own file.test/test_session_token_identity.pyreads the mount's.elements. Theprepare_native_skill_projectiondoubles intest/test_acp_client.py,test/test_acp_spawn_offload.pyandtest/test_subagent_shared_scratch.pyaccept the new keyword.test/test_acp_runtime.py,test/test_acp_session_mcp.py,test/test_harness_parity.py,test/test_kas_spawn.py,test/test_acp_client.py,test/test_acp_spawn_offload.pyandtest/test_subagent_shared_scratch.pypass with them, and so dotest/test_mcp_gateway_control_plane_repair.py,test/test_acp_mcp_ref_guard.py,test/test_mcp_session_report.py,test/test_mcp_session_report_wiring.py(the sink cleanersession_mcpnow imports),test/test_agent.py,test/test_codex_session_mcp.pyandtest/test_kas_agents.pyunchanged: 2459 named tests together on this head, each module run by name with-n0.Local review: no local review lane read
3c16f831d8; the server round was its first read. No local lane read1126a47befeither. One pinned local GPT lane (gpt-5.6-sol, the CI lane's contract extracted from the base) read6d66eaa8faand returned no blocking finding and one advisory -- the remedy for a project-scoped mute ordisabledToolssent the user to the dashboard's MCP tab, which writes only the global file -- fixed inf5aa916ab1. The server GPT lane readf5aa916ab1and blocked on theregistrymarker being exempt in a settings file too (a value kiro-cli drops outside registry mode, so the mount would launch a server kiro-cli refuses);4df5d87797exempts the marker on the spec's managed entry only, red-first, andfeab9c1c3cis its replay onto7b2da39c53. The server round onfeab9c1c3cblocked on the direct client refusing a view for a specdisabledToolsnaming other tools, and its design lane suggested the mount surface its own verdict rather than the runtime re-reading the files; both landed in6df6cec26d, red-first, which no local lane read (the fleet's execution cap left none). The server round on6df6cec26dblocked on the refusal repeating a settings value as the file spells it -- a newline or an escape sequence in adisabledToolsname reaching the gateway's log as a line of its own -- and found the remedy's no-tab arm running two clauses together, while SAST flagged the direct-client test's mocked pid as one a live process can own; all three landed in8a16f3f007, red-first, which no local lane read (execution cap). The server round on8a16f3f007blocked on theregistryexemption being keyed on the spec's declaration alone -- with registry mode off, a marked core entry on any agent's spec had the mount launch the managed stdio server kiro-cli itself drops -- and the Windows shard failed the two new tests above; both landed ind5109674f9, red-first where the sources decide, which no local lane read (execution cap). The server round ond5109674f9is clean: GPT with one advisory -- this test module's docstring described the projection as reading the same files the mount reads, while the implementation judges the spec at preparation and the settings files at each session start -- Opus with no findings, Design and First Principles PASS. This head rewrites that docstring to describe the split and changes nothing else; no local lane read it (execution cap): the server round is this head's first model read. On this headBackend Tests (Windows) (1)failed one test outside this PR's files,test/test_history_index_worker.py::test_a_contended_write_waits_instead_of_failing(assert 0.296 >= 0.3: the runner's sleep returns early), which is #13215 (billygerhard,platform: windows); that job is rerun once, and every other shard and lane on this head is green.Overlap
Rebased onto main
4d683462c2after #14268 merged; the Windows reds from #14249 clear. One commit on that tip: the replay's tree is identical togit merge-tree --write-treeof the previous head against it (empty diff), and the round-7, round-8 and round-9 changes are amended into the same commit.mainhas since moved to47594b83(five commits; one of them, #12684, touchessrc/kiro_crew/acp/client.py, which this PR also touches, and its suite was still running when this head was pushed):git merge-tree --write-treeof this head against it is clean, and the base is left on the verified-green4d683462c2rather than replayed onto an unverified tip.git merge-tree --write-treeof this head against #13635's headd5d0db6bc0(thesession_mcp.pyBOM strict reader) and against #13974's head0f22bd0542(theskill_projection.pyandruntime.pytail: per-run work dirs and refused alias unlinks) each return a clean tree with no conflict, so whichever of the overlapping pairs lands second rebases onto the other with no conflicting hunk as of these heads.Manual verification
N/A — unit coverage sufficient: the runtime tests drive
_unpooled_control_planeswith a projection prepared from a real globalmcp.jsoncarrying the toggle's exact shape, before and after the toggle lands, which is thesession/newpath both reports failed on.Related Issues
Second report of the same failure: #13786 (0.7.1, Windows desktop app; recovered by deleting and re-adding the
kirocrew-coreblock).Follow-up: #14125 -- let a
kirocrewsession run with akirocrew-coretool toggle expressed (the element or a gate carrying the restriction, or a dashboard warning at toggle time) instead of refusing it. The Design lane's watch on this PR: the toggle's apparent promise (lose one tool) and its effect (lose the default agent's sessions until the toggle is undone) still diverge; this PR fixes the diagnosis and the drift between the two readers, not that trade-off, which #14125 owns.Fixes #13639
Pattern harvest
Rule candidate: review-prompt
Pattern: two readers of one configuration question that each merge the sources themselves — the predicate that mounts a server and the projection that promises the mount — drift on the source set; the merge and the predicate belong in one function both call.
Rule candidate: review-prompt
Pattern: a reader that waives a restriction because another path will supply the server (a broker stub, a cached element) is trusting presence as proof; the waiver holds only if that path is built from the same sources and can carry the same restriction, and when either is false the sources alone must decide.
Rule candidate: review-prompt
Pattern: a verdict computed once at spawn over files that other writers keep editing is a snapshot; every later decision that depends on it must re-read or be refused, and a validator run on a normalized copy of a declaration instead of the declaration itself lets every field the normalization drops pass unjudged.
Rule candidate: review-prompt
Pattern: a key table borrowed whole from a neighbouring writer answers that writer's question ("what may a spec entry retain"), not this reader's ("what can the element express"); when an element replaces the declaration it is named after, the admitted keys are the ones the element emitter actually emits, so derive the table from the emitter or subtract what it leaves behind, and pin the two against each other.
Rule candidate: review-prompt
Pattern: a producer that reads shared files and returns only the positive half of its answer (the elements it built) forces its consumer to read the same files again for the negative half (why one is missing); between the two reads the files can change, and the consumer then acts on an answer the producer never gave -- return the verdict with the data it was computed from, one read, one answer.
Rule candidate: review-prompt
Pattern: a check that exists because one MECHANISM cannot carry a field (a per-session element replacing a declaration) must be gated on that mechanism being in play; run where the declaration stays native and the field is honoured as written, it refuses a supported customization for a problem that does not arise there.
Rule candidate: review-prompt
Pattern: bounding how much of a user-authored value a message repeats is not the same as cleaning it -- a cut value still carries the newline or escape sequence that writes its own log line, and the value's file may arrive with a repository checkout; the message goes through the sink cleaner before the cut, and the cleaner reads a window rather than the file, or the bound on the message becomes an unbounded regular-expression cost on the reader.
Rule candidate: review-prompt
Pattern: an exemption for a marker the product writes itself must be keyed on the STATE in which the product writes it, not on the PLACE where it usually sits; keyed on the place alone, it grants the marker in exactly the state where the consumer that reads the marker drops the entry, and a line anyone can add to that place becomes a way past the guard.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)