fix(mcp): admin opt-in for Crew session identity under MCP registry

Merged
DO
14d ago
+556-68

Problem / Motivation

Goal: On an MCP registry-governed host, an administrator can opt in so that artifact_save and the other identity-scoped kirocrew-core / kirocrew-cron tools work from a dashboard session. Without the opt-in the host stays exactly as locked down as today, and the refusal says why and how to enable it.

On a host with agent.mcp_registry_mode on, every identity-scoped kirocrew-core call is refused identity_unattestable (reported on #22375: Refusing tool call 'artifact_save': session mcp tool policy unresolved (identity_unattestable)). kiro-cli launches the servers from the admin's catalog, which gives them no session identity, and Crew mounts no per-session identity element under registry mode.

Why it matters

Enterprise customers on registry-governed Kiro profiles lose most of the product (artifacts, spawn_run, memory, monitors) once #22375 lets their sessions start. The refusal they get today does not say the registry is the cause or what an admin can do about it.

Not a goal

  • Turning session identity on by default under registry mode. Mounting Crew's element widens a governed host past the admin's catalog, so it stays off unless an admin opts in.
  • A new identity channel that needs no mount (for example a token the catalog-launched server reads from disk). That is a separate design.
  • Fixing the session abort under registry mode. That is #22375; this PR only helps once #22375 lands.
  • Mounting identity for opt-in Crew servers (kirocrew-dashboard, kirocrew-computer), builtin app servers or third-party servers under registry mode.
  • The KAS backend, which cannot carry the registry marker at all.

What changed (motivation → approach → change)

Symptom → cause: kiro_control_plane_servers returned an empty mount whenever registry mode was on. That element is the only place a kiro-cli dashboard session hands its signed identity to Crew's servers. The catalog-launched server then resolves a session only from the unsigned pid file and fails closed.

Approach: a policy-only security policy field, mcp_registry_local_control_plane (a JSON boolean, off when absent), owned by the admin:

  • Default (off): same behaviour as before. Nothing is mounted under registry mode and the call stays refused, except on a sign-in no admin registry can govern (kiro_cli.registry_governance_known_unreachable()), which mounts the control plane on main already and is unchanged here. The identity_unattestable refusal and its warning log line now add the cause and the exact fix (mcp_shared_policy.registry_identity_note), but only on kirocrew-core / kirocrew-cron when registry mode is declared and the field is still off, the one case where setting it fixes the refusal.
  • On: the per-session identity element is mounted for kirocrew-core and kirocrew-cron only, so those two run from the local install instead of the catalog entry.
  • Why security_policy.json: it is already a READONLY keystone in the sandbox and refused by the agent file gate, so the agent cannot flip the switch. Profiles may not set the field, and in tier composition it is authority-only: a lower tier cannot supply it.

Where: the field is parsed in src/kiro_crew/platform/governance_parts/parsing.py, re-exported by the src/kiro_crew/platform/governance.py facade, carried on GovernanceCeiling in carriers.py, and classed authority-only in tiers.py. The policy read is registry_local_control_plane_permitted in carriers.py (next to active_update_pins), served through the platform.governance facade; it is the single read for both the mount gate in src/kiro_crew/acp/session_mcp.py and the refusal note, so the two cannot disagree. To keep session_mcp.py under the file-line cap, session_mcp_restricted_servers moves unchanged into the sibling src/kiro_crew/acp/session_mcp_restricted.py and is re-imported under its old name. The refusal note is src/kiro_crew/mcp_shared_policy.py, appended in src/kiro_crew/mcp_shared_dispatch.py and re-exported through the src/kiro_crew/mcp_shared.py facade; it is given the server's name and reads registry mode through agent._mcp_registry_mode, the mount gate's reader.

Docs: the governance guide gains a section on the opt-in and its trade-offs. architecture/mcp.md, the governance, acp-client and claude-code-provider specs, and the session_servers docstring now describe it, and the docstring and spec no longer claim kiro-cli filters an injected session/new element under registry mode.

Backwards compatibility

Compatible: the field is new and optional. An absent field reads as off, which is the existing behaviour, and every policy that loads today still loads.

The one definition that leaves session_mcp.py is session_mcp_restricted_servers, moved unchanged into acp/session_mcp_restricted.py and re-imported into session_mcp under the same name, so every reader still resolves it:

Reader: src/kiro_crew/acp/session_mcp.py:session_mcp_projection -- chat -- calls the re-imported name; test/test_acp_session_mcp.py and test/test_codex_session_mcp_projection.py pass
Reader: src/kiro_crew/providers/mirrors/codex.py:session_projection -- chat -- reaches it through session_mcp_projection and names it only in prose; test/test_codex_session_mcp_projection.py passes
Reader: src/kiro_crew/providers/mirrors/opencode.py:session_projection -- chat -- reaches it through session_mcp_projection; test/test_opencode_session_mcp.py passes
Reader: test/test_acp_session_mcp.py:session_mcp.session_mcp_restricted_servers -- release -- attribute access on session_mcp still resolves via the re-import; the test passes

Tests

test/test_registry_local_control_plane.py:

  • Policy field: absent means off, a JSON boolean is taken as written, any other value fails the load, a profile cannot carry it, and a lower tier cannot supply it.
  • Admin-only: the agent file gate refuses a write to security_policy.json, and the sandbox mounts it read-only.
  • Permission read: no policy, the field absent, or an unreadable ceiling all mean off; true means on.
  • Mount:
    • registry mode with the switch off mounts nothing;
    • registry mode with the switch on mounts exactly kirocrew-core and kirocrew-cron (kirocrew-dashboard and mochi:mochi are granted in the spec but not mounted);
    • outside registry mode the switch changes nothing.
  • Refusal: an identity_unattestable call through the stdio loop is refused, and the text names the field only on kirocrew-core / kirocrew-cron under registry mode with the field off (not on kirocrew-dashboard or an app server, and not once the admin has opted in).

test/test_governance_tier_ladder.py classifies the new ceiling field as authority-only.

Mutant check, run by hand: with main's kiro_control_plane_servers swapped back in, test_registry_mode_with_the_switch_on_mounts_core_and_cron_only fails ([] == ['kirocrew-core', 'kirocrew-cron']).

Proof: PROVEN test/test_governance_tier_ladder.py::TestEveryCeilingFieldHasAComposeClass::test_every_field_is_classified_exactly_once (head d8a3eb49c95c)

Manual verification

Not run on a real registry-governed Kiro profile, because none is available here. The reporter on #22375 confirmed that mounting this element under registry mode makes artifact_save work. This PR puts exactly that mount behind the admin opt-in, limited to kirocrew-core and kirocrew-cron.

Screenshots / video

N/A — no frontend change.

Related Issues

Fixes #27662
Part of #20298

Only helps once #22375 (the registry-mode session abort) lands.

Sibling sweep

Swept: git grep -n "_registry_mode()" -- src/
Sibling: src/kiro_crew/acp/session_mcp.py -- changed here
Sibling: src/kiro_crew/acp/kas_agents.py -- not affected -- KAS cannot carry the registry marker, a documented separate limitation
Sibling: src/kiro_crew/mcp_gateway/session_servers.py -- not affected -- broker stubs are never built for registry-marked entries; docstring corrected here

Pattern harvest

Not generalizable: a one-off between a governance ceiling and the one identity channel it suppressed; the fix is an explicit admin opt-in, not a reusable code pattern.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff