Skip to content

fix(tools): narrow every managed server to its per-tool refs under honourToolRefs - #23322

Merged
iamwhatever merged 1 commit into
mainfrom
fix/server-tool-refs-narrow-managed-server
Oct 29, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/server-tool-refs-narrow-managed-server

Conversation

@JLargent42

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A spec that grants one of Kiro Crew's managed servers tool by tool, with managedToolPolicy.honourToolRefs: true, gets only those tools from that server, for every managed server and not only kirocrew-core.

A spec that granted kirocrew-dashboard through @kirocrew-dashboard/<tool> refs got the server's whole tool list in the session. On the kiro backend a managed server's tools arrive through Crew's per-session identity element, which @server/tool refs do not narrow, and disabledTools on a managed server withholds that element so every call is refused. The honourToolRefs include list was the one narrowing that works on that path, and it was only derived for kirocrew-core.

Why it matters

An operator who wants a session that may use some dashboard tools but not others had no spelling that both keeps the server usable and withholds the rest, only a prompt rule plus the approval card.

Not a goal

  • Narrowing a server without the honourToolRefs opt-in; the default answer is unchanged.
  • Changing how disabledTools withholds a managed server's identity element.
  • Narrowing a third-party server; its tools are gated by the spec and kiro-cli as before.

What changed (motivation → approach → change)

Every managed server already enforces an include list keyed by its own name in the shared dispatcher (mcp_shared_dispatch), so the gap was only in the gateway's policy answer. _policy_answer in dashboard/handlers/sessions_parts/tool_policy.py now derives an include entry for each server in INCLUDE_LIST_SERVERS, which is every Kiro Crew managed server (KIROCREW_BIN_MCP_SERVERS), instead of kirocrew-core alone. Each server is read on its own, so a whole-server grant on one does not stop another from being narrowed.

The spec-field reference (src/kiro_crew/docs/agent-spec-fields.md) and the MCP architecture doc describe the opt-in for every managed server.

Backwards compatibility

Compatible: a spec without honourToolRefs: true, and an opted-in spec that grants every server whole, answer exactly as before; an opted-in spec's kirocrew-core entry is unchanged.

Reader: src/kiro_crew/dashboard/handlers/sessions.py:INCLUDE_LIST_SERVER -- dashboard facade -- renamed to INCLUDE_LIST_SERVERS (a tuple); no in-repo reader used the old name, and its facade inventory drops it.

Tests

In test/test_managed_tool_policy_include.py:

  • test_per_tool_refs_to_an_opt_in_managed_server_answer_its_include — per-tool refs to kirocrew-dashboard answer its include list.
  • test_each_managed_server_is_read_on_its_own — a whole-server grant on kirocrew-core beside per-tool refs to kirocrew-dashboard narrows only the dashboard server, and a third-party server is never narrowed.
  • test_every_managed_server_is_eligible — the eligible set is the managed-server set.

The existing tests for the server's own tools/list / tools/call handling already cover enforcement by server name. Revert proof: restoring INCLUDE_LIST_SERVERS to kirocrew-core alone turns the three new tests red.

Manual verification

N/A — unit coverage sufficient: the change is the gateway's policy answer, and the dispatcher's enforcement of an include list is already tested per server name.

Related Issues

Closes #21610

Sibling sweep

Swept: git grep -n "per_tool_grants|INCLUDE_LIST_SERVER" -- src/
Sibling: src/kiro_crew/dashboard/handlers/sessions_parts/tool_policy.py -- changed here
Siblings: none -- per_tool_grants has no other caller, and enforcement already reads the include map per server name

Pattern harvest

Not generalizable: the defect was one hard-coded server name in a single policy answer.

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

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners October 23, 2026 04:03
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 69624407563aba00c7b73794f7463a12447bf6e6 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6962440

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 69624407563aba00c7b73794f7463a12447bf6e6 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 69624407563aba00c7b73794f7463a12447bf6e6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6962440

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 69624407563aba00c7b73794f7463a12447bf6e6 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 69624407563aba00c7b73794f7463a12447bf6e6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The PR replaces one hard-coded server name with the managed-server set that the shared dispatcher already enforces by name. Every server in that set imports the shared dispatch, and nothing outside the patch reads the renamed INCLUDE_LIST_SERVER.

Notes

  • INCLUDE_LIST_SERVERS now reuses KIROCREW_BIN_MCP_SERVERS, which mcp_cleanup.py defines as the list of names to purge from the user's global mcp.json. If a server is ever added there that doesn't go through mcp_shared_dispatch, specs that opted in would have their per-tool refs silently ignored for it. A pin test saying "every eligible server enforces include" would catch that drift.

[DESIGN-REVIEWED] 6962440

Description read

[DESCRIPTION-READ] 1d9154f2694fc8f4002c1ee6fe378345003ef51739209655fe261a5fa1ee6d63

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 69624407563aba00c7b73794f7463a12447bf6e6 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. Linked issue #21610 is the source of the defect. The fix is a change to the gateway's policy answer behind the default-off honourToolRefs opt-in. Every managed server already enforces an include list (mcp_shared_dispatch.py:900).

What this change ships

Inventory (5 items) — 4 justified

Intent: let an operator give a session only some tools of any Kiro Crew managed server (not only kirocrew-core) through per-tool refs. FIX.

  1. An opted-in spec that grants kirocrew-dashboard (or any managed server) tool by tool now lists and allows only those tools — justified
  2. Each managed server is read on its own, so a whole-server grant on one does not cancel narrowing on another — justified
  3. The facade constant INCLUDE_LIST_SERVER becomes the tuple INCLUDE_LIST_SERVERS, aliasing the existing KIROCREW_BIN_MCP_SERVERS — justified
  4. The sessions facade re-exports KIROCREW_BIN_MCP_SERVERS under TYPE_CHECKING — undeclared, rides along, follows the facade's existing mirror-the-parts-imports convention
  5. The spec-field reference and the MCP architecture doc describe the opt-in for every managed server — justified

[FIRST-PRINCIPLES-REVIEWED] 6962440

Description read

[DESCRIPTION-READ] 267d507cbf04b5bd6d846328e2185c01f821d61b96f73ae04abf18856cdf18f6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@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 Oct 23, 2026
@JLargent42
JLargent42 force-pushed the fix/server-tool-refs-narrow-managed-server branch from 41e723e to b8f587e Compare October 23, 2026 05:25
@JLargent42

Copy link
Copy Markdown
Contributor Author

CI note for head 41e723e, fixed in b8f587e: Backend Tests (3.12, 5) and Backend Tests (Windows) (5) failed on test_sessions_parts_facade.py::test_every_project_name_an_owner_serves_is_named_for_type_checkers. The new KIROCREW_BIN_MCP_SERVERS import in tool_policy was not named in the sessions facade's TYPE_CHECKING block; it is now. Coverage Gate failed only because backend tests did not pass. Backend Tests (Windows) (5) also failed test_security_sensitive_paths.py::TestHomeDirTargetsCache::test_cache_dict_is_bounded on a stalled symlink resolution of the runner's home directory, which this diff does not touch. Backend Tests (Windows) (7) is the main-side failure tracked in #23259.

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

Copy link
Copy Markdown
Contributor Author

Rebased once onto main for the #23264 Windows fix.

@JLargent42
JLargent42 force-pushed the fix/server-tool-refs-narrow-managed-server branch from b8f587e to 62e452e Compare October 23, 2026 07:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 23, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author

CI note for 62e452e: Backend Tests (Windows) (1), (3) and (4) fail in test_workspace_file_transactions.py, test_coder_archive_write_races.py and test_remote_workspace_file_integrity.py, which this diff does not touch. All are #23392 (os.path.commonpath across the C: temp dir and the D: checkout in remote_session/workspace_tools.py, #19833), inherited through the merge ref. Backend Tests (3.12, 7) failed in test_remote_session_client.py::test_link_through_a_worker_attach_dial_delivers_and_finishes (child exit 255), the flake tracked in #23402; that one job has been rerun once, and Coverage Gate failed only because of it.

@JLargent42
JLargent42 force-pushed the fix/server-tool-refs-narrow-managed-server branch from 62e452e to e5e8095 Compare October 27, 2026 16:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 27, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 27, 2026
@JLargent42
JLargent42 force-pushed the fix/server-tool-refs-narrow-managed-server branch from e5e8095 to 6962440 Compare October 27, 2026 21:20
@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: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 27, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Holding for human review.

This PR changes what a managed-tool policy allows. _policy_answer now emits an include list for every Kiro Crew managed server, not only kirocrew-core (tool_policy.py#L260, #L321-L324). Permission and containment changes are reserved for a maintainer. I found no defect: the change only narrows, only behind the default-off honourToolRefs, and the shared dispatcher already enforces include by server name. CI and every AI lane are green.

One unanswered note on this head: Design Review suggests a pin test that every server in INCLUDE_LIST_SERVERS enforces include, so a future server outside mcp_shared_dispatch cannot silently ignore per-tool refs. A reply (add the test, or say why not) would close it.

Reviewed head: 69624407563aba00c7b73794f7463a12447bf6e6.

— crew-pr-reviewer (r131)

@iamwhatever iamwhatever 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.

APPROVE (security-sensitive scope, maintainer-accepted)

This PR tightens a security rule, so it was held for a human decision. A maintainer reviewed the deep check and a separate regression check for this exact head (69624407563a) and accepted it. This approval supersedes the earlier HOLD from crew-pr-reviewer.

Regression check: per-tool narrowing under honourToolRefs now applies to every managed server, but only when a spec opts in and lists per-tool refs for that server. No shipped spec, template, builtin agent or app sets honourToolRefs, and bare @server, * and glob grants still get the whole server.

Tests on this head: test_managed_tool_policy_include.py 49 passed; test_app_mcp_tool_policy_scope.py, test_session_tool_policy_cache.py, test_session_tool_policy_off_loop.py 101 passed; no existing assertion changed.

CI is green on this head, the base is main, and there is no conflict.

— crew-pr-reviewer (r133)

@iamwhatever
iamwhatever merged commit 58523b8 into main Oct 29, 2026
109 checks passed
@iamwhatever
iamwhatever deleted the fix/server-tool-refs-narrow-managed-server branch October 29, 2026 01:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

2 participants