fix(acp): skip skill_search under registry mode instead of aborting the session
Problem / Motivation
Goal: On a registry-governed (enterprise MCP registry) host, a chat session composes and runs instead of hard-failing every turn because skill_search cannot be bound.
On KiroCrew 0.8.0+ a governed host degrades to a single canned error on every turn, in every session: Cannot bind skill_search to this session without losing native MCP restrictions. Check the agent's kirocrew-core server configuration. The control-plane servers resolve cleanly (kiro-cli mcp list shows [x] kirocrew-core), so this is not a server-resolution failure — the whole chat is dead, not just one tool.
Why it matters
This makes the release unusable on governed/enterprise hosts: the entire chat session is aborted over one control-plane tool that could never bind under the active governance, and the error misleadingly points at "kirocrew-core server configuration" when the server is fine.
Not a goal
- Does not weaken governance. Nothing new is mounted; under registry mode
kirocrew-coreis still resolved by the admin's catalog with no per-session identity element, andskill_searchstill cannot bind there. POLICY ∩ PROFILE is untouched. - Does not change the per-server/settings-restriction path (a user-authored
disabledTools/mute/non-stdio transport, or an unreadable settings file) — those still refuse the session by name, because they are per-session and user-fixable. Outside registry mode a genuinely misconfigured search agent still hits the generic abort.
What changed (motivation → approach → change)
- Symptom: every chat turn on a governed host returns the generic "Cannot bind skill_search …" abort.
- Root cause: under registry mode the per-session identity element Crew mounts for a search agent can never be minted for ANY agent (kiro-cli resolves managed entries against the admin's catalog by map key). But the skill projection did not read registry mode: it still stripped the agent's
skill://resources and marked it a search agent, promising an element the mount cannot produce. The session-start guard then met a search agent with no element and aborted the whole session. - Approach: fix the producer, not the consumer. The projection is the right seam because registry mode is a static, install-level ceiling (like the spec it already judges at preparation), and leaving the consumer to paper over the mismatch would strip the agent's native skills and degrade
skill_searchtoidentity_unattestedfor nothing. - Change:
prepare_native_skill_projection(src/kiro_crew/acp/skill_projection_parts/preparation.py) now reads the registry ceiling once and, under it, leaves each agent EXACTLY as authored on both clients — keeps itsskill://resources, mounts no managed element, injects noskill_search, and does not add it tosearch_agents. The ceiling is the mount's own gate, now one helpersession_mcp.registry_withholds_control_plane(): the control-plane marker decision the spec writer already makes (managed_mcp._registry_marker_for("kirocrew-core", registry_mode), reached through thekiro_crew.agentfacade = registry mode is declared AND an admin registry may govern this sign-in) AND the admin's security policy does not setmcp_registry_local_control_plane(#28444, read throughplatform.governance.registry_local_control_plane_permitted).kiro_control_plane_serverscalls the same helper for its early return (its behaviour is unchanged), so the projection only promisesskill_searchwhere the shared runtime's mount giveskirocrew-coreits element. On a registry-mode sign-in no admin registry can govern (Builder ID / social), or with the admin's opt-in on, agents are projected exactly as without registry mode and keepskill_search. With the opt-in on, the direct client's injectedkirocrew-coreentry is still unmarked, so kiro-cli's registry filter can drop it there, as on main today; the direct client has no session-start guard, so nothing aborts. The decision is not gated onper_session_element, because kiro-cli's registry filter is symmetric: it keeps only entries carrying"type": "registry"and drops every unmarked one. So under the ceiling the managedkirocrew-coreelement cannot bind for any agent on either client — the shared runtime mints no per-session identity element, and the direct client's injectedkirocrew-coreentry is unmarked, so kiro-cli drops it. Gating on the element would still strip + inject on the direct client, promising askill_searchwhose server kiro-cli then drops and losing the agent'sskill://skills, and would let the two clients write opposite overlay states on one workspace. The inheritance overlay follows the same ceiling (the same predicate): under the ceiling neither client applies the overlay — forcingchat.disableInheritingDefaultResources=truewhile Crew supplies no discovery would leave an inherited-only agent (andkirocrewwith noskill://resources) with neither Crew's bounded skill directory nor kiro-cli's native default skill trees, so the overlay is instead restored and kiro-cli's native inheritance stays on; gating it on the shared predicate also stops alternating shared-runtime and direct-client spawns from writing opposite overlay states on one workspace. With no search agent to collide with, the mount's existing empty registry-mode verdict refuses no session. A singlelogger.warningis emitted once per preparation under the ceiling, naming thatskill_searchis withheld and that discovery falls back to kiro-cli's native resource inheritance — so the degradation is observable rather than silent (the old path aborted loudly). The owning specdocs/system-specs/modules/acp-client.mdis updated to document this.
Backwards compatibility
Compatible: no contract is rejected, renamed or removed. The only behaviour change is under registry mode, where a search agent previously had its session aborted; it now composes and runs as authored. No field, type, or key changes.
Removes nothing: outside registry mode the projection behaves exactly as before (same strip, same skill_search injection, same search_agents); the registry-mode branch only stops stripping/injecting, restoring the agent's authored view.
_registry_mode() is fail-safe: a config read it cannot complete is treated as governed (returns True) so an unmarked local server never launches past a ceiling that may be in force. A consequence is accepted here: while the config plane is intermittently unreadable, spawns alternating between a failed read (governed → overlay restored) and a good read (ungoverned → overlay written) flip chat.disableInheritingDefaultResources back and forth. The flip is bounded and self-correcting — it exists only during the degraded state the fail-safe already warns about loudly, and the next successful read settles the setting to the operator's true declaration — so it is treated as an accepted property of the fail-safe rather than gated on distinguishing the two True sources, which would widen a shared helper's contract.
Tests
test_registry_mode_leaves_the_agent_as_authored_and_starts_the_session— under registry mode the projected view keeps itsskill://resources, injects noskill_search, the agent is not insearch_agents, and_unpooled_control_planesstarts the session without raising. It also asserts the direct client (per_session_element=False) is left as authored too — not a search agent,skill://resources kept — since kiro-cli's symmetric registry filter drops its unmarkedkirocrew-coreentry, so promising it askill_searchwould strip its skills for a tool that could not bind.test_a_search_agent_with_nothing_granting_the_element_still_reaches_the_guard— outside registry mode a genuinely misconfigured search agent (mount produced nothing, no reason, no stub) still hits the generic abort, proving the change is scoped to registry mode.test_the_registry_marker_on_the_spec_entry_is_crews_own_only_while_the_mode_is_onupdated: under registry mode the agent is no longer a search agent but still gets a published view; thetype: registrymarker-ownership assertions are unchanged.test_registry_mode_keeps_native_inheritance_and_the_agents_skill_resources(intest/test_native_skill_projection.py) — under registry mode the inheritance overlay is not applied (chat.disableInheritingDefaultResourcesis not forced true) and the agent's authoredskill://resources survive, so an inherited-only agent keeps kiro-cli's native skill trees. It asserts BOTH clients (per_session_elementtrue and false) make the same overlay decision under registry mode, so alternating spawns on one workspace cannot flip-flop the setting.test_registry_mode_on_an_ungovernable_sign_in_projects_as_without_registry_mode(intest/test_native_skill_projection.py) — registry mode declared butregistry_governance_known_unreachable()true: the agent is a search agent, itsskill://resources are stripped and the inheritance overlay is applied, exactly as without registry mode, matching the mount, which mints the element there. It fails on the projection-only_registry_mode()gate (set() != {'custom'}) and passes on the shared predicate.test_registry_mode_with_the_admin_opt_in_keeps_skill_search(intest/test_native_skill_projection.py) — registry mode declared with the security policy'smcp_registry_local_control_planeon: the agent is a search agent, itsskill://resources are stripped,kirocrew-coreis in the view and the inheritance overlay is applied. It fails when the helper ignores the opt-in (assert True is False).test_registry_mode_with_the_admin_opt_in_keeps_skill_search_and_starts_the_session(intest/test_native_skill_projection_sources.py) — the same opt-in on the shared runtime: the agent is a search agent and_unpooled_control_planesreturns thekirocrew-coreelement, so the session starts without the "Cannot bind skill_search" abort.test_registry_mode_leaves_the_agent_as_authored_and_starts_the_sessionalso asserts (viacaplog) that alogger.warningnaming the withheldskill_searchis emitted under registry mode, so the fallback is observable.- All other pre-existing tests continue to pass.
Pattern harvest
Rule candidate: when two readers split one decision (here the projection decides whether an agent depends on skill_search; the mount decides whether the element can exist), a whole-install ceiling must be read by BOTH or the one that doesn't will promise something the other cannot deliver. The defect was the projection ignoring _mcp_registry_mode() while the mount honoured it, so the projection marked a dependency the mount then could not satisfy. This is a design-review observation rather than a mechanical semgrep pattern — the invariant is "both readers of a split decision consult the same ceiling", which a lint rule cannot express without the surrounding control flow. Captured so the two-readers-must-agree invariant is remembered.
Manual verification
N/A — unit coverage sufficient for the code path. The projection's registry-mode branch is exercised with _registry_mode() monkeypatched true, asserting the agent is left as authored and the session composes through the runtime's own _unpooled_control_planes start guard. A CI job cannot run a registry-governed kiro-cli (that needs an enterprise profile + admin MCP catalog), so an end-to-end transcript from a governed host would require the #20298 reporter or a maintainer with such a host.
Screenshots / video
N/A — backend-only change, no user-visible frontend surface.
Related Issues
Fixes #20298
Follow-up: #27662 tracks the separate artifact_save identity_unattestable refusal on registry-governed hosts. This PR stops the session abort; it does not make identity-scoped kirocrew-core tools work under registry mode.