Skip to content

fix(mcp): accept the Toolbox dispatcher shim as Crew's own control plane - #13288

Closed
bolichen97 wants to merge 1 commit into
mainfrom
fix/control-plane-token-toolbox-shim
Closed

bolichen97 wants to merge 1 commit into
mainfrom
fix/control-plane-token-toolbox-shim

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

On a Toolbox install (0.7.0.8, two independent reports), every call on kirocrew-core, kirocrew-cron and kirocrew-dashboard answers identity_unattested while the servers mount and list their tools normally. Only agents whose spec declares the server by its bare command -- "command": "kirocrew" -- are hit; the specs Kiro Crew writes itself carry the versioned path and keep working. A new session does not help. The daemon log names it:

mcp-gateway: backend 'kirocrew-core' spawned under a control-plane name but is denied the session token:
spawned '~/.local/bin/kirocrew' is not the spec's '~/.toolbox/tools/kirocrew/0.7.0.8/bin/kirocrew'

Why it matters

Every Crew capability that posts back for the calling session -- cron, subagents, lessons, memory, notifications, session control -- is dead on those agents, silently: the tools are listed, so the failure reads as the tool being broken rather than the identity being withheld. Roughly a hundred externally managed agent specs use that spelling.

What changed (motivation → approach → change)

Both identity gates compare the spawn command against agent.managed_mcp_spec_entry as one file: _spawns_own_control_plane in src/kiro_crew/mcp_gateway/gatewayd.py by realpath, kiro_control_plane_servers in src/kiro_crew/acp/session_mcp.py by string equality. The managed entry is the versioned binary. The bare kirocrew resolves on PATH to ~/.local/bin/kirocrew -> ~/.toolbox/bin/kirocrew -> tools/toolbox/<ver>/toolbox-exec -- one dispatcher shared by every Toolbox tool, which reads tools/kirocrew/info.json (current version) and tools/kirocrew/<ver>.json (Executables.kirocrew.BundlePath) and execs the versioned binary. A dispatcher is not a symlink, so realpath cannot see through it and the two never compare equal.

The fix reads what the dispatcher reads instead of executing it. Measured against the real toolbox-exec (1.1.9714.0) under an isolated BUILDER_TOOLBOX_HOME: it keys on argv[0]'s basename (a link under another name is "not associated with any tool"), reads ONE index -- <root>/tools/globalInfo.json, Commands.<name>.Path -- and execs that absolute path verbatim; the per-tool info.json / <ver>.json are not consulted. New leaf src/kiro_crew/managed_launcher.py: toolbox_dispatch_target() resolves a dispatcher shim to the file it would exec by reading that index, and same_managed_launcher() holds when the spawn is the managed file by realpath OR the trusted root's dispatcher whose index names that file. _spawns_own_control_plane in src/kiro_crew/mcp_gateway/gatewayd.py uses it and hands the DISPATCHED launcher, not the dispatcher, to the import-shadow check. kiro_control_plane_servers in src/kiro_crew/acp/session_mcp.py resolves a bare command on env.mcp_search_path (the composition the rewriter and the MCP probe already use) and applies the same predicate; the element it emits now carries the managed command/args, so kiro-cli launches the file that was judged rather than re-resolving a bare word against its own PATH.

Anchored, not widened. The root is toolbox_root() -- the gateway's OWN $BUILDER_TOOLBOX_HOME, else ~/.toolbox -- never derived from where the command sits, so a tree merely shaped like Toolbox elsewhere is a foreign binary exactly as before. The managed entry must itself live under that root (only a Toolbox install has a launcher a Toolbox dispatcher can front). The index entry must name that file by realpath, so an index rewritten to point elsewhere denies. A child environment that could point its dispatcher anywhere else denies -- a BUILDER_TOOLBOX_HOME that is not the trusted root, or a HOME / USERPROFILE that is not this process's own home, each judged as the child would see it (a relative value resolves against the child's work_dir, not this process's cwd, so it denies unresolved) -- because the child dispatcher would read an index this verdict never saw. The measured dispatcher does not read HOME (it took the account's home), but a fence modelling one dispatcher version is a false grant waiting for the next, so home divergence denies regardless. The index sits in the same user-owned tree as the managed binary, so trusting it concedes no capability realpath equality did not already concede.

Version pinning of the emitted element: it is rebuilt at every session start from the running gateway's own launcher. If a Toolbox update reaps that launcher under a still-running gateway, kiro-cli's spawn of the element fails outright (No such file or directory, server absent, no token handed to anything) rather than half-launching -- the same shape every Crew-written spec already has today, and it clears with the gateway restart the update needs anyway.

Backwards compatibility

Compatible: every spawn the gates accepted before (realpath-equal, literal managed spelling) is still accepted; the only new acceptances are a Toolbox dispatcher shim whose declared target IS the managed launcher, and a bare/absolute spec command that resolves to that same file. The identity element now carries the managed command/args instead of echoing the spec's spelling -- for a declaration that passed the old string-equality gate those are the same values.

Tests

test/test_managed_launcher_toolbox_shim.py rebuilds the Toolbox layout under tmp_path (shim, dispatcher, globalInfo.json index, versioned launcher, the planted ~/.local/bin entry), points BUILDER_TOOLBOX_HOME at it, and pins:

  • both spellings -- the versioned path and the shim (and the planted link, and the bare name) -- pass _spawns_own_control_plane and earn the identity element, which carries the managed invocation;
  • the reviewed attacks: a forged Toolbox-shaped tree elsewhere whose index names the genuine launcher is denied by both gates (root anchoring); a child env re-rooting the dispatcher is denied whether through BUILDER_TOOLBOX_HOME (absolute-and-different, or relative), HOME or USERPROFILE (different from this process's home, or relative), while this process's own home in any spelling passes; an index dispatching elsewhere, foreign args, a managed entry outside the root, and a host with no Toolbox root (realpath only) all deny; the shadow check reads the dispatched launcher's bin/;
  • the resolver: non-dispatchers, a file merely named toolbox-exec (elsewhere, or under the root but outside the dispatcher directory), a link under another name, and every broken-index shape (not JSON, missing, not an object, entry not an object, relative or empty Path, name not declared) resolve to nothing; the same root spelled through a symlink is accepted.

Before the fix the shim/planted/bare cases fail in both gates (reproduced locally). Mutating toolbox_dispatch_target to return None fails the shim/planted/bare cases.

Manual verification

Against the REAL Toolbox dispatcher binary (a copy of this host's ~/.toolbox/tools/toolbox/1.1.9714.0/toolbox-exec) in an isolated root, BUILDER_TOOLBOX_HOME=/tmp/kc-tbx-probe/.toolbox, with bin/kirocrew -> tools/toolbox/1.1.9714.0/toolbox-exec, .local/bin/kirocrew -> bin/kirocrew, an index naming tools/kirocrew/0.0.1/bin/kirocrew (a script that prints its argv[0]), and the managed entry pinned to that script:

toolbox_root         = /tmp/kc-tbx-probe/.toolbox
dispatch_target(.toolbox/bin/kirocrew) = .../tools/kirocrew/0.0.1/bin/kirocrew | same_managed: True
dispatch_target(.local/bin/kirocrew)   = .../tools/kirocrew/0.0.1/bin/kirocrew | same_managed: True
dispatch_target(renamed)               = None                                  | same_managed: False
gate .local/bin/kirocrew -> True
gate renamed -> False   (WARNING ... spawned '.../renamed' is not the spec's ...)
real dispatcher exec'd: DISPATCHED argv0=/tmp/kc-tbx-probe/.toolbox/tools/kirocrew/0.0.1/bin/kirocrew args=mcp-core
matches expected realpath: True

The same probe established the dispatcher's semantics the resolver mirrors: with only info.json + <ver>.json present it answers Command "kirocrew" doesn't appear to be associated with any tool; with only globalInfo.json it dispatches; a Path outside the tree is still what runs; HOME is not what it reads, BUILDER_TOOLBOX_HOME is. No Toolbox-installed Kiro Crew gateway is available on the development host, so the session-level identity_unattested -> tools-working transition was not observed live; the gate the daemon log names is the one exercised above with the real dispatcher.

Related Issues

no linked issue: reported on the internal contributors channel (2026-09-23, two reporters); no GitHub issue was filed.

Pattern harvest

Rule candidate: review-prompt
Pattern: "identity by realpath equality" treats a run-time dispatcher (a shared launcher that execs by reading a pointer) as a foreign binary; any gate that pins a spawn to a file must state what it does with launchers that are not symlinks.

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

@bolichen97
bolichen97 requested review from a team and patrigao September 24, 2026 08:03
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] da0dd63

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

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of da0dd63c3462fa59519ff27071775948491b82be — 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

Verify the globalInfo.json dispatch model on Toolbox dispatcher versions actually deployed — the fence's premise is one measured binary (toolbox-exec 1.1.9714.0).

What this change ships

Inventory (7 items) — 7 justified

Intent: FIX — restore Crew's own tools (identity attestation) to agents whose spec names the server by its bare Toolbox command, denied because realpath cannot see through a dispatcher.

  1. Toolbox agents declaring "command": "kirocrew" get working Crew tools again; gateway token gate accepts the dispatcher shim — justified
  2. Session-side gate grants the identity element to bare/absolute spellings resolving to the managed launcher — justified
  3. The emitted identity element names the managed binary, never the spec's PATH-dependent spelling — justified
  4. New leaf module managed_launcher reads the dispatcher's index instead of executing it — justified
  5. A spawn environment re-rooting or re-homing the dispatcher is denied the token (denial inside the new grant only) — justified
  6. Import-shadow check inspects the dispatched launcher's directory, not the dispatcher's — justified
  7. docs/architecture/mcp.md updated in the same commit — justified

Provenance checked: the quoted deny log matches gatewayd._deny_control_plane; tests exercise the pre-existing gate and fail on base; kiro_prerequisite.py independently corroborates the argv[0]-basename dispatch. Duplicate check: env.is_toolbox_install() does install detection, not dispatch resolution — no existing mechanism. Sibling count: grepped realpath(command) / managed-command comparisons across src/; the only two identity gates are the two fixed (stub.py:511 is pool keying, gatewayd:414 is the shadow check this PR feeds correctly). Consumers of same_managed_launcher: 2 (gatewayd, session_mcp).

[FIRST-PRINCIPLES-REVIEWED] da0dd63

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Have one of the two 0.7.0.8 reporters confirm live that Crew tools attest after upgrade — the end-to-end transition was never observed, only the gate.

[DESIGN-REVIEWED] da0dd63

@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 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] da0dd63

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) September 24, 2026 08:19
@bolichen97
bolichen97 force-pushed the fix/control-plane-token-toolbox-shim branch from dcc4f94 to 5b0bb1d Compare September 24, 2026 08:38
@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 24, 2026
@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: managed_launcher.toolbox_root() anchors dispatcher recognition to the gateway's own Toolbox root; same_managed_launcher requires the managed entry under that root and refuses a child env re-rooting the dispatcher

  • Fabricated Toolbox dispatcher bypasses control-plane attestation span=9e82d5e6a87e — fixed in 5b0bb1d

Legitimate: the round-0 resolver derived the root from the command's own realpath, so a Toolbox-shaped tree anywhere could vouch for the genuine launcher while the forged toolbox-exec was what got exec'd with the token.
Fixed by anchoring: the root is the gateway's $BUILDER_TOOLBOX_HOME or ~/.toolbox (never the command's location); the dispatcher must be /tools/toolbox//toolbox-exec; the managed entry must live under that root; the index (globalInfo.json, the file the real dispatcher reads) must name that file by realpath; a child env naming another BUILDER_TOOLBOX_HOME denies.
Pinned by test_a_forged_dispatcher_tree_is_denied_and_says_so, test_a_dispatcher_outside_the_trusted_root_is_foreign, test_a_child_env_re_rooting_the_dispatcher_is_denied.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: managed_launcher.toolbox_root() anchors dispatcher recognition to the gateway's own Toolbox root

  • *_dispatcher_root accepts any tree shaped like /tools/toolbox//toolbox-exec span=18f1d94960bc — fixed in 5b0bb1d

Legitimate: same defect class as the GPT finding — an unanchored root let a forged tree vouch for the genuine launcher.
Fixed: _dispatcher_root is replaced by _is_dispatcher_under(dispatcher, trusted_root) with the root from toolbox_root() (gateway env / home, as env.is_toolbox_install does); the managed entry must be under that root; the version/manifest chain is gone — the resolver reads globalInfo.json Commands..Path, the one index the real dispatcher was measured to read, and requires realpath equality with the managed entry, so lexical '..' checks no longer carry the guarantee.
Pinned by test_a_dispatcher_outside_the_trusted_root_is_foreign and the gate-level forged-tree tests.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Manual verification: N/A for a Toolbox-only branch CI cannot exercise span=2ff2066f0cf3 — fixed in 5b0bb1d

The Manual verification section now carries evidence from the REAL toolbox-exec (1.1.9714.0) run under an isolated BUILDER_TOOLBOX_HOME: the gate accepts the shim and the planted ~/.local/bin link, refuses a renamed link, and the dispatcher's actual exec target equals the managed entry's realpath.
The same probe measured the dispatcher's semantics (argv[0] basename, globalInfo.json, Path exec'd verbatim, BUILDER_TOOLBOX_HOME not HOME), and the resolver was rewritten to mirror exactly that. A live Toolbox-installed gateway is not available on the development host; that residual is stated in the body.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author
  • The emitted element pins the version current at judgment time span=64c4d79b1312 — fixed in 5b0bb1d

Stated in the PR body and docs/architecture/mcp.md: the element is rebuilt at every session start from the running gateway's own launcher; if a Toolbox update reaps that launcher under a still-running gateway, kiro-cli's spawn fails outright (ENOENT, server absent, no token handed to anything) rather than half-launching — the same shape every Crew-written spec already has, cleared by the gateway restart the update needs anyway.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Item 6 — resolved_managed_launcher undeclared, zero consumers span=c5358265f36a — fixed in 5b0bb1d

Deleted. The gateway passes expected_command to the shadow check inline, which was the only intended caller.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Item 7 — oversized fallback scan over tools/ directories span=83ba15afa671 — fixed in 5b0bb1d

Deleted, and the claim it rested on was measured instead of assumed: the real toolbox-exec does not read tools//info.json or .json at all — it reads /tools/globalInfo.json Commands..Path (probe transcript in the PR body). The resolver now reads that one index, so there is no tool-directory walk and no multi-claimant rule to justify.

@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 24, 2026
Both identity gates -- gatewayd._spawns_own_control_plane (pooled token)
and acp.session_mcp.kiro_control_plane_servers (identity element) --
compared the spawn command against agent.managed_mcp_spec_entry as one
file: realpath equality in the gateway, string equality in the session
projection. A Toolbox install fails both. The managed entry is the
versioned ~/.toolbox/tools/kirocrew/<ver>/bin/kirocrew; a spec that names
the server by its bare "kirocrew" (every externally managed agent spec
does) resolves on PATH to ~/.local/bin/kirocrew -> ~/.toolbox/bin/kirocrew
-> one shared toolbox-exec dispatcher, whose realpath is never that
binary. So no identity element, no token, and every kirocrew-core /
-cron / -dashboard call answered identity_unattested while the servers
mounted and listed their tools. Reported twice on 0.7.0.8; ~100 specs
across teams carry that spelling.

A dispatcher is not a symlink, so realpath cannot see through it. The
new leaf managed_launcher reads the one index the real dispatcher reads
(measured against toolbox-exec 1.1.9714.0 under an isolated
BUILDER_TOOLBOX_HOME: it keys on argv[0]'s basename, reads
<root>/tools/globalInfo.json Commands.<name>.Path and execs it verbatim)
without executing anything, and same_managed_launcher() holds when the
spawn is the managed file by realpath OR the trusted root's dispatcher
whose index names that file. Anchored, not widened: the root is the
gateway's own $BUILDER_TOOLBOX_HOME or ~/.toolbox, never the command's
location, so a tree merely shaped like Toolbox elsewhere stays a foreign
binary; the managed entry must live under that root; an index naming
another file denies; and a child environment re-rooting the dispatcher
denies. The index sits in the same user-owned tree as the managed
binary, so trusting it concedes no capability realpath equality did not.

The gateway passes the dispatched launcher (not the dispatcher) to the
import-shadow check. The session gate resolves a bare command on
env.mcp_search_path -- the composition the rewriter and the MCP probe
use -- and the element it emits carries the managed command/args, so
kiro-cli launches the file that was judged rather than re-resolving a
bare word against its own PATH.
@bolichen97
bolichen97 force-pushed the fix/control-plane-token-toolbox-shim branch from 5b0bb1d to da0dd63 Compare September 24, 2026 09:29
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: managed_launcher._child_root_diverges judges every root-deciding child env value as the child would see it

  • Relative Toolbox root bypasses control-plane attestation span=9e82d5e6a87e — fixed in da0dd63

Legitimate: the round-1 fence realpath'd a declared BUILDER_TOOLBOX_HOME against the judging process's cwd while the child runs under its own work_dir, so a relative value could pass here and re-root there.
Fixed: a root-deciding child env value must be absolute (a relative one denies unresolved, even when it happens to resolve to the trusted root from here) and realpath-equal to what it must name; pinned by test_a_relative_child_root_is_refused_not_resolved_here.

@bolichen97

bolichen97 commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: managed_launcher._child_root_diverges also denies a child HOME/USERPROFILE that is not this process's home

  • A spec-declared HOME re-roots the Toolbox dispatcher the child execs span=18f1d94960bc — fixed in da0dd63

Legitimate as a class even though the measured dispatcher (toolbox-exec 1.1.9714.0) did not follow HOME: a fence modelling one dispatcher version is a false grant waiting for the next, and a forwarded spec HOME is an ordinary input on this path.
Fixed: the child's home (HOME / USERPROFILE, case-insensitive) must be absolute and realpath-equal to this process's own home or the dispatcher clause denies; the inherited daemon HOME passes. Pinned by test_a_child_home_that_is_not_this_processes_home_is_refused, test_a_child_env_re_homing_the_dispatcher_is_denied and test_a_declared_home_earns_nothing_through_the_dispatcher.

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

Copy link
Copy Markdown
Contributor Author

Closing as superseded by #13155 (merged 2026-09-24 10:27 UTC while this PR was in review), which fixes the same defect from the other side: the rewriter and the kiro ACP projection now REPLACE a reserved name's declared launch with the managed invocation, so the Toolbox shim is never what gets spawned or judged, and the gate deliberately stays realpath-only (test_a_hand_authored_control_plane_launches_the_managed_binary_and_passes_the_gate covers the exact bare-kirocrew case). Teaching the gate to see through the dispatcher on top of that would be a second, redundant acceptance path -- the two security rounds here showed what it costs to fence -- and it contradicts the decision #13155 records. Branch left in place for the dispatcher measurements in the body (globalInfo.json, argv[0] keying, BUILDER_TOOLBOX_HOME), which stay accurate.

@bolichen97 bolichen97 closed this Sep 24, 2026
auto-merge was automatically disabled September 24, 2026 11:10

Pull request was closed

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant