Skip to content

fix(mcp-gateway): give a Bot's worker its own broker stubs - #37352

Closed
karashiiro wants to merge 1 commit into
kirodotdev:mainfrom
karashiiro:crew/mate/fix-36370-worker-stubs
Closed

karashiiro wants to merge 1 commit into
kirodotdev:mainfrom
karashiiro:crew/mate/fix-36370-worker-stubs

Conversation

@karashiiro

@karashiiro karashiiro commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Bot's worker sessions get their identity-bound tool servers on every host, so a Codex or Claude worker can report against its work item the way its KAS twin already does.

Codex and Claude worker sessions need broker stubs for tools such as work_report. The overlay writer omitted the stock worker spec. Looking up its replacement by the shared worker name would bypass the worker session's restrictions.

Why it matters

A worker must be able to report its result while keeping the limits set for its own work item. A shared agent name cannot establish that authority.

Not a goal

  • Adding Codex's missing tool_search engine built-in.
  • Changing Bot files, settings, or the KAS worker contract.
  • Widening the configured set of stubbed servers.

What changed (motivation → approach → change)

Worker tools were missing because the overlay writer covered the conductor spec alone. The writer includes both stock service specs, and the worker's session-key projection selects approved stub launches from the worker overlay.

Path Behavior
Overlay writer with_service_sources includes conductor and worker specs in the fingerprint and rewrite pass, using file stems as identity.
By-name lookup The shared worker name returns no stub without the KAS session key, preserving the guard requested in #37695.
Session projection session_mcp_projection uses the worker's session key and already-resolved merged spec to select worker stubs and bind its session token.
providers/mirrors/codex.py and providers/mirrors/claude_code.py Apply their existing grants, disabled-server, tool-limit and permission checks to the projected worker stubs.
Launch callers The client and shared runtime pass the overlay directory into the session projection.

The ACP, provider and MCP architecture specifications describe the session-key boundary.

Backwards compatibility

The conductor retains its by-name overlay. KAS retains its keyed worker lookup. Worker overlays supply approved launch definitions; each mirrored worker's merged spec supplies its own limits.

Reader: src/kiro_crew/mcp_gateway/rewriter.py:rewrite_agents -- chat|cron|subagent|app -- both source-enumeration calls use the renamed helper.
Reader: docs/architecture/mcp.md -- release docs -- describes the keyed worker projection.

Tests

Focused worker, overlay, Codex projection, client-seam and tool-refusal tests pass. Regressions cover a worker's own token and restrictions, unrelated or unknown sessions, unavailable overlays, registry policy, and Claude permission ownership. Repeated parallel and seeded shuffled runs pass with fresh fixture state.

Proof: PROVEN test/test_mcp_gateway_mate_overlays.py::TestTheRewritePass::test_the_worker_overlay_is_written_but_never_injected_by_name, test/test_mcp_gateway_mate_overlays.py::TestTheRewritePass::test_the_worker_files_own_name_is_not_its_identity, test/test_mcp_gateway_mate_overlays.py::TestTheWorkerLookup::test_without_a_kas_session_key_no_worker_stub_is_injected_by_name, test/test_worker_session_projection.py::test_worker_session_projection_mounts_its_bound_stub[codex], test/test_worker_session_projection.py::test_worker_wire_projection_keeps_session_binding[codex] (head 887b751)

Scoped import and lint checks pass. Formatting checks pass for the changed Python files except rewriter.py, whose reported formatting differences are present on main.

Manual verification

The tests exercise rewrite → worker-session projection → Codex/Claude mount, including the client and shared runtime callers. Live adapter invocation of work_report remains unverified.

Related Issues

Fixes #36370

Sibling sweep

Swept: git grep -nE "with_conductor_source|with_service_sources|session_mcp_projection|pooled_session_servers" -- src/kiro_crew

Sibling: src/kiro_crew/acp/runtime_session_setup.py -- changed here
Sibling: src/kiro_crew/acp/client_mcp_array.py -- changed here
Sibling: src/kiro_crew/mcp_gateway/mate_overlays.py -- not affected -- the worker_overlay_spec function retains KAS's keyed lookup.

Pattern harvest

Rule candidate: review-prompt
Pattern: a shared overlay name supplies launch definitions, but session authority and restrictions must come from the session-key projection.

Checklist

  • One Conventional Commits commit
  • Focused tests and regression coverage
  • Self-review completed
  • Owning documentation matches the behavior
  • No secrets or local environment references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@karashiiro
karashiiro requested review from a team and KiroCrewCaptain as code owners November 14, 2026 20:35
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 14, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own.

The PR generalizes the conductor-only source widening into with_service_sources, so the stock kirocrew-mate-worker spec in the crewmate folder gets its own by-name overlay. Both the fingerprint and the rewrite loop use it. The file stem stays the identity, and a same-stem ~/.kiro/agents file is ignored as before. The KAS worker path keeps going through worker_overlay_spec when a session key is present, and the non-key KAS path stays consistent between injection and subtraction. A Bot's whole-server disables and per-tool limits still apply to the stubs through the projection allowlist (muted) and the withhold/deny rules. The new tests would fail without the change, and nothing still refers to the old function name. No blocking issues found.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 04d95ee504 · 211 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97

Copy link
Copy Markdown
Contributor

@karashiiro heads-up on a maintainer call that changes the direction recorded on #36370 for this PR.

#37695 (Ray) adds a guard at session_servers.py:376: on a non-KAS host, looking up kirocrew-mate-worker by name returns no stub. This PR goes the other way on the same lines. We are keeping #37695's guard: a by-name lookup can hand the stub to a session that does not carry this session's restrictions.

So for the Codex/Claude worker fix here, please resolve the worker's stub through the session-key projection (session_mcp_projection, keyed by the worker's own session) rather than by name. That keeps work_report reachable for those workers, with the stub bound to the right session and its limits. Once it is reworked that way I'll review it right away.

AI-assisted, sent by Bolin Review bot

A Bot's worker sessions run the stock worker spec in ~/.kiro/mates/agents,
but the overlay pass rewrote only ~/.kiro/agents, the conductor spec and
the Bot files, so a worker session on a host that reads overlays by name
(Codex, Claude) found no stub for its own servers. On Codex, which mounts
Crew's own servers only as broker stubs, that left kirocrew-work withheld
even with it routed, so a dispatched worker could not report against its
own work item.

The agents half of the pass now also rewrites the stock worker spec under
its own name, with its signature in the fingerprint, so the worker gets
stubs carrying the worker's identity. The KAS path is unchanged: its
worker lookup is still the session's own crewmate overlay.

Refs kirodotdev#36370

Co-Authored-By: Claude Code <noreply@anthropic.com>
@karashiiro
karashiiro force-pushed the crew/mate/fix-36370-worker-stubs branch from 04d95ee to 887b751 Compare November 16, 2026 01:46
@karashiiro

Copy link
Copy Markdown
Contributor Author

@bolichen97 Reworked in the latest commit as requested. The by-name worker guard stays in place. Codex and Claude resolve the worker's broker stubs inside session_mcp_projection using that worker's session key, merged spec and session token.

The shared overlay supplies approved launch definitions; the session projection and each mirror enforce the worker's own grants, disabled servers, tool limits and permission ownership. The overlay writer remains necessary to supply those launch definitions.

Regression coverage exercises the actual client and shared-runtime mounting paths, separate workers with different restrictions and tokens, and refusal for missing or unrelated session authority. Focused tests, repeated and shuffled regressions, import/lint checks and the regression proof pass. The PR description and owning specifications describe the keyed path.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
@karashiiro

Copy link
Copy Markdown
Contributor Author

Closing — the same approach has landed on main in f1b575f89: the overlay pass now rewrites the stock worker spec and serves the worker its base-server stubs, which is the behavior this PR set out to add (option 2 discussed on issue #36370). If the ACP session-side wiring this variant additionally carried turns out to still be needed, happy to bring it back as a follow-up.

@karashiiro karashiiro closed this Nov 16, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) 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.

On Codex, a crewmate's worker sessions mount no identity-bound servers (kirocrew-mate/-work/-guide)

3 participants