Skip to content

fix(mcp-gateway): launch reserved kirocrew-* servers from the managed invocation - #13155

Merged
bolichen97 merged 1 commit into
mainfrom
fix/toolbox-shim-control-plane
Sep 24, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/toolbox-shim-control-plane

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Since 0.7.0.8, an agent spec that launches Kiro Crew's own MCP servers with the ordinary Toolbox command, "command": "kirocrew", gets servers that mount and list their tools but refuse every call with identity_unattested. No cron, no subagents, no lessons, no memory. A new session does not help; the spec is what is wrong. Reported from a fleet where every affected spec came from a package manager, on Linux and macOS alike.

Why it matters

The managed command embeds the user's home and the installed version (~/.toolbox/tools/kirocrew/0.7.0.8/bin/kirocrew; on macOS a path inside the app payload). No spec author outside Kiro Crew can write it, and a spec that pins it breaks on the next upgrade. So every hand-authored spec is dead on this check, and the only accurate error line lives in a daemon log no session shows. Two engineers reached three wrong diagnoses before finding it.

What changed (motivation → approach → change)

Where Before Now
mcp_gateway/rewriter.py a stubbed kirocrew-* entry launched the spec's command with the spec's env and autoApprove composes the entry from the managed launch outward (_repair_control_plane_entry), for a spec-declared and a settings/mcp.json-injected reserved name alike: spec restriction fields carry over, env is held to the ownership rule (_owned_control_plane_env), a spec autoApprove and every other key are dropped and named; managed launch joins the fingerprint (schema 9)
acp/session_mcp.py kiro_control_plane_servers skipped the entry when its command differed mounts the managed command/args; restrictions still withhold
mcp_gateway/gatewayd.py, backend.py, mcp_caller.py, mcp_shared.py denial reason only in mcp-gatewayd.stdout reason rides the frame as identity_denial; the refusal quotes it
docs/architecture/mcp.md described the spec's command as the spawn target token-gate section describes the repair and the identityDenial channel

The bare launcher kirocrew resolves through PATH to the shared Toolbox dispatcher, toolbox-exec. That is a different file from the versioned binary, so gatewayd._spawns_own_control_plane, which compares the spawned binary by realpath, refused the token. The check was right about the file. It was wrong to trust the spec for what to spawn.

A reserved name now always runs the managed source of truth, the same way agent._enforce_managed_mcp_ownership rewrites the disk entry and the codex and opencode projections REPLACE theirs. The rewriter does this before it resolves, hashes or bakes anything, so the stub target, KIROCREW_MCP_TARGET_* and the gate's expectation are one value. The gate itself is unchanged and still refuses the declared launch; the repair is what closes the gap, and a third-party binary squatting a reserved name gets our binary, not the token for its own. The grant, disabled, disabledTools, timeout and type stay the spec's. The entry's env is held to the same ownership rule the disk writer and the ACP element already apply: Kiro Crew's reserved namespace, loader channels, home-deriving and launcher-exec keys are dropped, so a spec cannot hand our binary a KIROCREW_APPROVAL_MODE=auto. a spec autoApprove is dropped and named (kiro-cli honours it before the PreToolUse gate; no managed declaration carries one). Any other key is dropped and named in the log.

Backwards compatibility

Compatible: a spec that already carries the managed launch round-trips byte-identical (test). A spec whose reserved-name command was wrong went from a dead server to a working one. The caller meta gains an optional identityDenial key that old backends ignore (schema unchanged, additive).

Tests

  • test/test_mcp_gateway_control_plane_repair.py (new): the ticket's reproduction end to end with the real managed entry and the real gate, for the Toolbox shim and a reaped version pin; target env agrees with the stub; already-managed spec is silent; unreserved names untouched; unresolvable managed name left as declared; every reserved name repaired; the repaired entry composed from the managed source outward (restriction fields kept, autoApprove and stray keys dropped, spec autoApprove dropped and named); declared env held to the ownership rule (reserved namespace, loader, home and launcher keys dropped; ordinary key kept) for both a repaired and an exact launch; a scalar args on a reserved or third-party entry no longer aborts the rewrite pass (_spec_args, also used by the stub builder); fingerprint sees the managed launch; gate reports its reason; denied backend gets the reason and never the token; meta round trip.
  • test/test_session_token_identity.py: the old command restriction case is replaced by a parametrized repair test over spec and settings sources, with a negative control that the declared launch never reaches the element; a scalar args (8080, true, a dict) on a reserved name is compared, not iterated, so session/new does not abort.
  • test/test_mcp_shared.py: the identity_unattested refusal quotes the daemon's denial when the frame carries it; the existing text is unchanged without it.
  • test/test_mcp_gateway_stub_session_token.py, test/test_mcp_gateway_claim.py: doubles carry the new control_plane_denial field and the gate's denial keyword.

Manual verification

Not run on the reporter's host. The regression test drives the same rewriter and gate the daemon uses on the exact spec shape from the ticket. A reader with an affected spec can confirm after upgrade with grep "is not the spec's" ~/.kiro/crew/logs/mcp-gatewayd.stdout (stops appearing after a gateway restart).

Related Issues

no linked issue: reported through an internal ticket; this PR is the fix.

Pattern harvest

Rule candidate: review-prompt
Pattern: an identity gate that compares a spawned command against a managed value must also own the spawn (REPLACE from the managed source), or every hand-authored consumer fails closed with no path to conform.

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

@bolichen97
bolichen97 requested review from a team and smeyffret September 23, 2026 19:36
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Intent: A spec that names one of Kiro Crew's own MCP servers (kirocrew-core, kirocrew-cron, and the other reserved kirocrew-* names) always launches the managed invocation and so is handed the session token, whatever command the spec spelled. Operators see why a reserved-name backend was denied a token in the refusal itself and in kirocrew doctor.
Not a goal: Accepting the Toolbox dispatcher (toolbox-exec) as an equivalent binary in the gate; relaxing any check in _spawns_own_control_plane; repairing entries under non-reserved names; repairing reserved names declared only in the global settings/mcp.json (Kiro Crew never writes them there).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of a8efc537aa70b157da8b9096b7884cff02f0a791 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify on a real Toolbox-shim host that the repair clears identity_unattested — the fix ships tested only against a simulated shim.

Suggestions

  • The managed-env ownership rule now lives in three parallel implementations (agent._enforce_managed_mcp_ownership, session_mcp._managed_element_env, rewriter._owned_control_plane_env); a future key class added to one site silently skips the others — consolidate into one shared helper or pin three-way parity with a test.

[DESIGN-REVIEWED] a8efc53

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of a8efc537aa70b157da8b9096b7884cff02f0a791 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Manual verification was never run on an affected host — confirm on a real Toolbox install that a bare-kirocrew spec now attests after upgrade.

Not justified as shipped

  • Item 9 — rides along: the scalar-args hardening (_spec_args, _declared_launch, _build_stub_entry) also changes third-party entries, beyond the fix; declared in the Tests section, named harm (one "args": 8080 aborted the rewrite pass for every agent), no premise risk.

What this change ships

Inventory (10 items) — 9 justified

Intent: make hand-authored specs' reserved kirocrew-* servers actually work (the gate denied the token because the spec's spelling spawned the wrong file) — FIX.

  1. A reserved kirocrew-* spec entry now launches the managed binary, whatever the spec spelled — justified
  2. Same repair for a settings/mcp.json-injected reserved name — justified
  3. The ACP projection mounts the managed launch instead of silently skipping a mismatched entry — justified
  4. A spec autoApprove on a reserved name is dropped and logged — justified
  5. Spec env/stray keys on a reserved name held to the existing ownership rule — justified
  6. The identity_unattested refusal now quotes the daemon's denial reason (identityDenial on the frame) — justified
  7. The gate's argv-mismatch reason names a count, never the spawned values — justified
  8. Overlays regenerate when the managed binary moves (fingerprint schema 9) — justified
  9. A scalar args no longer aborts the rewrite pass or session/new, third-party entries included — rides along
  10. docs/architecture/mcp.md updated in the same commit — justified

[FIRST-PRINCIPLES-REVIEWED] a8efc53

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of a8efc537aa70b157da8b9096b7884cff02f0a791 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/mcp_caller.py:203 -- "never a credential" contradicts the required credential redaction -> Fix: describe the denial as untrusted, potentially credential-bearing text.

FINDING -- src/kiro_crew/mcp_gateway/rewriter.py:406 -- "Runs once per reserved entry per rewrite pass" contradicts calls from both fingerprinting and entry repair -> Fix: remove the inaccurate call-count claim.

[GPT-REVIEWED] a8efc53

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a8efc537aa70b157da8b9096b7884cff02f0a791: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the fix/toolbox-shim-control-plane branch from af46edc to 7fb45cf Compare September 23, 2026 19:52
@bolichen97

Copy link
Copy Markdown
Contributor Author

Re-pushed as 7fb45cf: the Internal Content Scan Gate flagged ticket ids and a user home path in comments and test fixtures; both replaced with neutral text. No behaviour change.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@bolichen97

bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor Author
  • rebutted: shared repair helper across the five seams (span=f4d325d1febb)

The five seams already read ONE source, managed_mcp_spec_entry; what differs per seam is the container being repaired (a disk mcpServers dict entry, an ACP element, a stub --target-command/--target-args pair, a codex/opencode config block), not the value. A helper would take an entry and return it with two keys swapped, and each caller would still own its logging, its restriction checks and its container shape, so it removes no decision.
A cross-seam pinning test exists in substance: test_control_plane_backends_contain_session_mcp_and_justify_the_difference and test_identity_bound_set_is_every_managed_server pin the set, and each projection's own tests pin its REPLACE against the same managed fixture. Disproportional for a fix PR; a sixth projection would meet IDENTITY_BOUND_SERVERS and these tests first.

@bolichen97

bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 4, the denial reason on the frame is load-bearing, not a ride-along (span=f021e2717713)

The repair removes the binary-mismatch denial only. _spawns_own_control_plane still denies for a non-empty LD_*/DYLD_*/PYTHON* in the child env, an import root shadowing kiro_crew, a closed spec_gate, and an unresolvable managed name. Each still produces the same identity_unattested refusal whose text points at the token and the spec, with the true cause only in logs/mcp-gatewayd.stdout; that mis-pointing is the second of the three diagnostic failures the report names, and it is what cost two engineers three wrong diagnoses.
Cost is one optional meta key (identityDenial, emitted only when set, ignored by old backends), one backend field, and one appended sentence in the refusal. Removing it leaves every residual denial as opaque as the reported one was.

@bolichen97

bolichen97 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 6, the baseline prune is required for this PR's black gate to pass (span=4ccc768984db)

scripts/check_black_formatting.py fails when a baselined file is black-clean ("baselined file(s) are now black-clean. Remove them"). test/test_knowledge.py went clean on main in #13140 without the prune, so every PR opened since is red on that gate until one of them carries the one-line removal. This PR does; it touches nothing else in that file. A separate PR for a one-line baseline prune would leave this fix red until it merged.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed a8efc537aa70b157da8b9096b7884cff02f0a791 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] a8efc53

Verdict parsed from the review's SHA-scoped output markers for commit a8efc537aa70b157da8b9096b7884cff02f0a791.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a8efc537aa70b157da8b9096b7884cff02f0a791: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the fix/toolbox-shim-control-plane branch from 7fb45cf to a33d558 Compare September 23, 2026 20:16
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: item 5, the doctor row is deleted (span=94e2ce0b00d5)

Subtraction taken as proposed: _doctor_hand_authored_control_planes, _hand_authored_control_planes, their call, the two doctor tests and the ratchet bump are gone in a33d558; cli_doctor.py and test_agent_spec_hardened_reads.py are byte-identical to main. The refusal text in mcp_shared.py is the one surface for the residual denials.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: Scalar args abort session creation (span=5b73f976724d)

Both comprehensions now go through _declared_launch, which iterates args only when it is a list or tuple and otherwise reads it as no args, the same rule acp_server_element applies. A scalar args on a reserved name compares as "not the managed launch" and the managed one is mounted. Fixed in a33d558.
Test: test_kiro_identity_projection_survives_a_scalar_args_on_a_reserved_name over 8080, "--flag", a dict and True, in the spec and in a settings override; negative control run on the pre-fix module raised TypeError for the non-string cases.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • rebutted: function-local import in the rewriter (span=ceaed7314cf2)

Not a circular import and not an oversight: gatewayd imports rewriter at module load and deliberately keeps kiro_crew.agent off the daemon's boot path (its CONTROL_PLANE_BACKENDS is read from the mcp_cleanup leaf for exactly this reason, and _spawns_own_control_plane uses the same function-local import). A top-level import here would put kiro_crew.agent back on that path. The comment at the import now states this in a33d558. The cli_doctor.py half is moot: that code is deleted.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: doctor scan reads only the user-level agents dir; row excuses entries the projection still withholds (span=f44ebe40eb24)

Both findings are on the doctor row, which is deleted in a33d558 (First Principles subtraction, item 5). No scan remains to widen, and no text remains to over-promise. The point that a reserved-name entry carrying disabledTools is withheld by the projection stands and is pre-existing behaviour this PR does not change; the refusal text names the missing token for that case as before.

@bolichen97
bolichen97 force-pushed the fix/toolbox-shim-control-plane branch 2 times, most recently from 513bcfc to a6f50dd Compare September 23, 2026 20:43
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: Reserved servers retain attacker-controlled control environment (span=74a9af46f464)

_repair_control_plane_entry now holds the entry's declared env to the managed-entry ownership rule (_owned_control_plane_env): sanitize_spec_env drops loader channels and the reserved KIROCREW_* namespace, then the home-deriving and launcher-exec key classes go, in the same order as agent._enforce_managed_mcp_ownership and session_mcp._managed_element_env. Applied to every reserved entry, not only a repaired launch, so a spec that copies the managed command exactly cannot hand our binary KIROCREW_APPROVAL_MODE=auto either. Fixed in a6f50dd.
Tests: test_the_repaired_entry_holds_its_env_to_the_managed_ownership_rule (repaired and exact launch; KIROCREW_APPROVAL_MODE, KIROCREW_HOME, LD_PRELOAD, PYTHONPATH, HOME, PATH, NODE_OPTIONS dropped, MY_FLAG kept) and test_a_reserved_entry_whose_env_is_entirely_withheld_loses_the_env_key.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: mcp.md still specifies the pre-PR spawn-target model (span=44fac92d0a13)

The token-gate section of docs/architecture/mcp.md now states that a stubbed reserved name's launch and env are re-derived from the managed source before the target mapping is baked, why the gate is unchanged, and how the denial reason reaches the backend (Backend.control_plane_denial -> CallerContext.identity_denial / identityDenial -> the refusal text). In a6f50dd.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • rebutted: pin the reserved-name rule once as a harness-parity invariant (span=31f86888b7e8)

Same ground as the round-1 answer on this class (span f4d325d1febb): the five seams read one value, managed_mcp_spec_entry, and differ only in the container they write it into; each seam's own tests pin its REPLACE against the same fixture, and test_identity_bound_set_is_every_managed_server pins the set. A harness-parity invariant spanning disk writer, ACP element, stub target and two provider configs is a new cross-module test surface, disproportional for a fix PR; a future projection meets IDENTITY_BOUND_SERVERS and those tests first.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 4, denial-reason plumbing rides along (span=4d4211581b61)

As the lane's own text says, the harm stands without the ticket: _deny_control_plane's reason reaches only mcp-gatewayd.stdout, and the repair leaves the other denial causes live (loader env, shadowed import, closed spec gate, unresolvable managed name). Each still produces a refusal whose generic text points at the token and the spec. One optional meta key, one backend field, one appended sentence; kept.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • acknowledged: item 10, IPv6-loopback probe in the dashboard port test (span=65a83c2efbf9)

Unrelated to MCP identity and declared under "CI:" in the body: the test landed on main in #6599 and reddened Backend Tests (3.12, 3) and the Coverage Gate on this PR twice, so the PR cannot go green without it. Shaped per GPT's ratchet finding: an independent probe, an uncaught bind when the host has ::1.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 24, 2026
… invocation

A spec authored outside Kiro Crew (an AIM package, a hand edit) cannot spell
the managed command for kirocrew-core / kirocrew-cron: it embeds the data home
and the installed version, so the one portable spelling is the bare Toolbox
launcher `kirocrew`, which resolves to the shared dispatcher (toolbox-exec), a
different file from the versioned binary. gatewayd._spawns_own_control_plane
compares the spawned binary by realpath against the managed entry and denied
the session token, so every control-plane tool refused `identity_unattested`
while the server looked mounted. A version-pinned path fails the same way one
upgrade later. Since 0.7.0.8 (which added the check) this stranded every such
spec.

The rewriter now re-derives a stubbed reserved name's command/args from
managed_mcp_spec_entry before it resolves, hashes or bakes anything, so the
stub target, KIROCREW_MCP_TARGET_* and the gate's expectation are one value;
the kiro ACP projection (kiro_control_plane_servers) repairs the same mismatch
instead of skipping the entry, as the codex/opencode projections already
REPLACE theirs. The repaired entry is composed from the managed launch
outward: the spec's restriction fields carry over, its env is held to the
managed-entry ownership rule, and a spec autoApprove or any other key is
dropped and named. The gate itself is unchanged: it still refuses the
declared launch, the repair is what closes the gap. The managed launch joins the
rewrite fingerprint (schema 9) so an upgrade regenerates kept overlays.

Diagnostics: the daemon's denial reason rides the forwarded frames as
CallerContext.identity_denial and is quoted by the identity_unattested
refusal.
@bolichen97
bolichen97 force-pushed the fix/toolbox-shim-control-plane branch from e1f2a9f to a8efc53 Compare September 24, 2026 06:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 24, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 24, 2026 07:33

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at a8efc53.

Verified: the daemon gate keeps all seven deny checks one-for-one (realpath, argv, loader-env, shadow and the rest) and only routes them through a local deny() that also records the reason. The repaired entry is built from the managed launch and keeps only type/timeout/disabled/disabledTools. Its env is filtered through the same ownership rule as the disk writer, and autoApprove is dropped. The repair runs after the muted pass-through, so it cannot unmute an entry. The refusal text is defanged and redacted. Passing env/autoApprove through reddens five named tests. 359 passed, 1 skipped.

Not verified: an override-home install end to end, where KIROCREW_HOME comes from the daemon env rather than the repaired entry.

@bolichen97
bolichen97 merged commit c5c014a into main Sep 24, 2026
95 of 101 checks passed
@bolichen97
bolichen97 deleted the fix/toolbox-shim-control-plane branch September 24, 2026 10:27
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 24, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
… invocation (kirodotdev#13155)

A spec authored outside Kiro Crew (an AIM package, a hand edit) cannot spell
the managed command for kirocrew-core / kirocrew-cron: it embeds the data home
and the installed version, so the one portable spelling is the bare Toolbox
launcher `kirocrew`, which resolves to the shared dispatcher (toolbox-exec), a
different file from the versioned binary. gatewayd._spawns_own_control_plane
compares the spawned binary by realpath against the managed entry and denied
the session token, so every control-plane tool refused `identity_unattested`
while the server looked mounted. A version-pinned path fails the same way one
upgrade later. Since 0.7.0.8 (which added the check) this stranded every such
spec.

The rewriter now re-derives a stubbed reserved name's command/args from
managed_mcp_spec_entry before it resolves, hashes or bakes anything, so the
stub target, KIROCREW_MCP_TARGET_* and the gate's expectation are one value;
the kiro ACP projection (kiro_control_plane_servers) repairs the same mismatch
instead of skipping the entry, as the codex/opencode projections already
REPLACE theirs. The repaired entry is composed from the managed launch
outward: the spec's restriction fields carry over, its env is held to the
managed-entry ownership rule, and a spec autoApprove or any other key is
dropped and named. The gate itself is unchanged: it still refuses the
declared launch, the repair is what closes the gap. The managed launch joins the
rewrite fingerprint (schema 9) so an upgrade regenerates kept overlays.

Diagnostics: the daemon's denial reason rides the forwarded frames as
CallerContext.identity_denial and is quoted by the identity_unattested
refusal.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants