fix(acp): skip skill_search under registry mode instead of aborting the session

Merged
DO
10d ago
+405-18

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-core is still resolved by the admin's catalog with no per-session identity element, and skill_search still 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_search to identity_unattested for 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 its skill:// resources, mounts no managed element, injects no skill_search, and does not add it to search_agents. The ceiling is the mount's own gate, now one helper session_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 the kiro_crew.agent facade = registry mode is declared AND an admin registry may govern this sign-in) AND the admin's security policy does not set mcp_registry_local_control_plane (#28444, read through platform.governance.registry_local_control_plane_permitted). kiro_control_plane_servers calls the same helper for its early return (its behaviour is unchanged), so the projection only promises skill_search where the shared runtime's mount gives kirocrew-core its 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 keep skill_search. With the opt-in on, the direct client's injected kirocrew-core entry 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 on per_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 managed kirocrew-core element cannot bind for any agent on either client — the shared runtime mints no per-session identity element, and the direct client's injected kirocrew-core entry is unmarked, so kiro-cli drops it. Gating on the element would still strip + inject on the direct client, promising a skill_search whose server kiro-cli then drops and losing the agent's skill:// 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 — forcing chat.disableInheritingDefaultResources=true while Crew supplies no discovery would leave an inherited-only agent (and kirocrew with no skill:// 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 single logger.warning is emitted once per preparation under the ceiling, naming that skill_search is 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 spec docs/system-specs/modules/acp-client.md is 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 its skill:// resources, injects no skill_search, the agent is not in search_agents, and _unpooled_control_planes starts 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 unmarked kirocrew-core entry, so promising it a skill_search would 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_on updated: under registry mode the agent is no longer a search agent but still gets a published view; the type: registry marker-ownership assertions are unchanged.
  • test_registry_mode_keeps_native_inheritance_and_the_agents_skill_resources (in test/test_native_skill_projection.py) — under registry mode the inheritance overlay is not applied (chat.disableInheritingDefaultResources is not forced true) and the agent's authored skill:// resources survive, so an inherited-only agent keeps kiro-cli's native skill trees. It asserts BOTH clients (per_session_element true 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 (in test/test_native_skill_projection.py) — registry mode declared but registry_governance_known_unreachable() true: the agent is a search agent, its skill:// 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 (in test/test_native_skill_projection.py) — registry mode declared with the security policy's mcp_registry_local_control_plane on: the agent is a search agent, its skill:// resources are stripped, kirocrew-core is 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 (in test/test_native_skill_projection_sources.py) — the same opt-in on the shared runtime: the agent is a search agent and _unpooled_control_planes returns the kirocrew-core element, so the session starts without the "Cannot bind skill_search" abort.
  • test_registry_mode_leaves_the_agent_as_authored_and_starts_the_session also asserts (via caplog) that a logger.warning naming the withheld skill_search is 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.