Skip to content

fix(mcp): one explanation for an externally spawned kirocrew-core - #13690

Merged
bolichen97 merged 1 commit into
mainfrom
fix/external-mcp-client-identity-text
Sep 25, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/external-mcp-client-identity-text

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A kirocrew-core started outside a Kiro Crew session -- listed in an editor's own MCP config -- shows three different errors for one missing identity. With KIROCREW_SESSION_KEY copied into that config every tool answers identity_unattested. Without it, memory_recall says "No identity channel on this install" and learn_add echoes the gateway's bare missing X-Session-Key. None of the three says the two things the reader needs: that server has no identity channel and its identity-bearing tools are not supported there, and the env var is a gateway-injected fallback, not a credential. The reader bounces between the two errors.

Why it matters

Anyone who wires kirocrew-core into Kiro IDE (a leftover from older installs) hits this on every memory write, reads the header name as a missing setting, and copies a live session key into their config -- which makes it worse. The refusal is correct; the words leave no next step.

What changed (motivation → approach → change)

Where Refusal Change
mcp_shared.py tool-policy gate identity_unattested appends the shared note when no gateway caller, no session token and no launcher pid are present
mcp_core.py strict_identity_diagnosis "No identity channel on this install" (memory_recall and every reflexive tool) appends the same note under the same condition
mcp_tools/learn.py learn_add, learn_remove HTTP 400 missing_session_key echoed as missing X-Session-Key answered as "requires an established session" plus the same diagnosis, keyed on the code; learn_remove keeps saying nothing was removed

One shared string, mcp_shared.external_client_identity_note, says it once: a server not started by a Kiro Crew session has no identity channel and its identity-bearing tools are not supported from it; KIROCREW_SESSION_KEY is not a credential and set by hand refuses every call; the read-only tools work without it; use a Kiro Crew session; the supported editor direction is connecting into one rather than spawning the server, and that server's entry in ~/.kiro/settings/mcp.json is leftover install state. The note names the refusing server throughout; the "leftover from an older install" clause appears only for the names Kiro Crew itself once wrote into the shared config (mcp_cleanup.STALE_MANAGED_MCP_SERVERS), since an opt-in server found there is the user's own wiring, and the read-only tool list appears only for kirocrew-core, whose tools they are. It names no pull request: the gateway-backed ACP server (PR #7415) is the direction in progress and is cited here, not in shipped text. mcp_shared.spawned_without_gateway_identity gates it on the process environment alone, so a server the gateway did start (token on the element, or a launcher host pid) keeps its existing wording -- its problem is a trust root or a quoted spawn denial, not an editor config. docs/architecture/mcp.md documents the shared note beside the identity_unattested wording it extends.

Existing-user visible behaviour: unchanged for every server the gateway spawns (dashboard, Slack, cron, subagent, sandboxed) -- pinned by tests that assert the old text byte-for-byte and the note absent with a gateway caller or a token on the element. Changed only for a process with neither, where the three refusals gain the appended note and the lesson writers' wording changes from the HTTP body to the established-session refusal. No refusal decision moves: what is allowed and what is refused is identical before and after.

Backwards compatibility

Compatible: no gate, header, route or accepted input changes; only the text of three refusals that already refused grows, and only for a process the gateway did not spawn.

Tests

  • test_strict_identity_diagnostics.py::TestExternalClientNote -- the note is actionable and names no machine path; strict_identity_diagnosis appends it with no spawn evidence and keeps its wording byte-identical with a token or host pid; memory_recall carries it; learn_add and learn_remove map missing_session_key onto it while every other error passes through unchanged; the note names only the refusing server, carries the leftover clause only for always-on names and the read-only list only for kirocrew-core, and names no pull request; all three refusals share one string.
  • test_mcp_shared.py -- the identity_unattested refusal appends the note for a caller-less process with only KIROCREW_SESSION_KEY, and stays unchanged with a gateway caller (existing test extended) or with a token on the element.
  • prove.py --base origin/main: PROVEN (tests fail with the production hunks reverted).

Manual verification

N/A -- unit coverage sufficient: the three refusal texts are exercised end to end through the stdio loop harness and the tool functions; the gate decisions are untouched.

Related Issues

no linked issue: reported in an internal support thread; the supported editor direction is tracked by PR #7415.

Pattern harvest

Rule candidate: review-prompt
Pattern: one missing precondition surfaced through several tools with per-tool wording, none naming the shared cause or the next step -- check that sibling refusals for the same condition share their explanation.

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 Zedmor September 25, 2026 04:54
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 25, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Intent: Make the three refusals a kirocrew-core started outside a Kiro Crew session can hit (identity_unattested, the strict no-identity-channel diagnosis, learn_add's missing X-Session-Key) say one thing: identity-bearing tools are unsupported from such a process and KIROCREW_SESSION_KEY is not a credential.
Not a goal: Changing any refusal decision, attestation rule, header or route; adding a credential path for external MCP clients; changing the text a gateway-spawned server sees.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0e5eba0

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

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Confirm nothing downstream matches on the lesson writers' old missing X-Session-Key error text, since that wording is replaced for all callers hitting that code.

[DESIGN-REVIEWED] 0e5eba0

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 0e5eba04a5a8f9b65ead3781f100b2b7d46282f1 — 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 note's promise on a real unspawned server: tests pin the wording, not that learn_list/local_knowledge_search actually succeed once KIROCREW_SESSION_KEY is removed.

What this change ships

Inventory (7 items) — 7 justified

Intent: give a person who wired kirocrew-core into an editor's own MCP config one actionable explanation for the one missing identity, instead of three divergent refusals — a FIX (refusal text only; base wording verified: bare Error: missing X-Session-Key pass-through at learn.py:340, no external-spawn clause in strict_identity_diagnosis).

  1. identity_unattested refusal gains the shared explanation when nothing spawned the server — justified
  2. memory_recall and every reflexive-tool strict refusal (incl. cron's, via strict_identity_diagnosis) appends the same note — justified
  3. learn_add answers the gateway 400 as an established-session refusal instead of echoing the header name — justified
  4. learn_remove same mapping, still says nothing was removed — justified
  5. New env-only helper spawned_without_gateway_identity — justified (2 consumers: mcp_core.py:975, mcp_shared.py:1792)
  6. New shared string external_client_identity_note with per-server clauses — justified (3 consuming sites; sibling sweep: grepped missing X-Session-Key echoes in mcp_tools/ — the two lesson writers were the only bare echoes, both fixed; other reflexive tools refuse first via require_strict_session_key, 0 unfixed siblings)
  7. docs/architecture/mcp.md documents the note beside the wording it extends — justified

[FIRST-PRINCIPLES-REVIEWED] 0e5eba0

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 0e5eba0

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) September 25, 2026 05:12
@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 25, 2026
@bolichen97
bolichen97 force-pushed the fix/external-mcp-client-identity-text branch from 50dfbe0 to 4d12185 Compare September 25, 2026 05:19
@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 25, 2026
@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Item 3 — learn_remove still echoes the bare header (span=bcb7c28ce1dd)

fixed in 4d12185: learn_remove maps the DELETE route's 400 missing_session_key onto the same established-session refusal and diagnosis as learn_add, keeping its "No lessons were removed" lead; every other delete error still passes through unchanged.
Test: TestExternalClientNote::test_learn_remove_maps_the_same_code_and_says_nothing_was_removed.

@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Item 5 — the note names a server that is not on main (span=0c654f852d51)

fixed in 4d12185: the ACP-server / PR clause is removed from shipped text. The note now says the supported editor direction is to connect INTO a Kiro Crew session rather than spawn the server, which holds today; the in-progress server is cited in the PR description only.
Test: test_the_note_names_only_the_refusing_server asserts no "PR #" in the note.

@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Remediation clause hardcodes kirocrew-core (span=2ed88f864efd)

fixed in 4d12185: the final clause interpolates {server} ("not to spawn kirocrew-cron itself, and a kirocrew-cron entry in ~/.kiro/settings/mcp.json is leftover"), and the read-only tool list is qualified "for kirocrew-core" so it is not misread as another server's tools.
Test: test_the_note_names_only_the_refusing_server over kirocrew-cron / kirocrew-dashboard / kirocrew-panel.

@bolichen97

bolichen97 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • in-function import of STUB_SESSION_TOKEN_ENV (span=783125b0a4a5)

rebutted: the deferral is deliberate and mirrors session_token_sig.py's read of the same name (session_key_from_env_token, comment in place). mcp_gateway.claim imports the executor and transport graph at module scope; mcp_shared has no top-level mcp_gateway import and runs inside every stdio server, so a top-level import would add that graph to each server's startup for one env-var name. 4d12185 adds the explanatory comment at the import.

@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 and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 25, 2026
A kirocrew-core started outside a Kiro Crew session (an editor's own
MCP config) has no identity channel, and the same missing identity
surfaced as three unrelated errors: identity_unattested on every tool
when KIROCREW_SESSION_KEY was copied into that config, the strict
"no identity channel" diagnosis from memory_recall without it, and
learn_add echoing the gateway's bare "missing X-Session-Key". None of
them said that the server is unsupported there or that the env var is
not a credential, so the reader bounced between the two errors.

All three refusals now append one shared note when the process carries
neither the session token nor a launcher host pid, so nothing the
gateway does at spawn happened to it. learn_add maps the 400
missing_session_key code onto the same established-session refusal
memory_recall uses. Which calls are refused is unchanged; a server the
gateway did spawn keeps its existing wording.
@bolichen97
bolichen97 force-pushed the fix/external-mcp-client-identity-text branch from 4d12185 to 0e5eba0 Compare September 25, 2026 05:51
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in files this PR also touches (by import / same directory) since this head went green (9b4ff83 -> 75f949b); CI re-running on 0e5eba0.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • "leftover from an older install" asserted for opt-in server names (span=2ed88f864efd)

fixed in 0e5eba0: the leftover clause is emitted only when server is in mcp_cleanup.STALE_MANAGED_MCP_SERVERS (kirocrew-core / kirocrew-cron / kirocrew-computer); an opt-in server gets the same explanation without it, so the reader is never told their own wiring is residue. The read-only tool list (learn_list, local_knowledge_search) is emitted only for kirocrew-core, whose tools they are.
Test: test_the_note_names_only_the_refusing_server iterates STALE_MANAGED_MCP_SERVERS and OPT_IN_BIN_MCP_SERVERS and asserts each clause's presence/absence.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 25, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@bolichen97
bolichen97 merged commit 7c26ecc into main Sep 25, 2026
94 checks passed
@bolichen97
bolichen97 deleted the fix/external-mcp-client-identity-text branch September 25, 2026 06:48
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 25, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…rodotdev#13690)

A kirocrew-core started outside a Kiro Crew session (an editor's own
MCP config) has no identity channel, and the same missing identity
surfaced as three unrelated errors: identity_unattested on every tool
when KIROCREW_SESSION_KEY was copied into that config, the strict
"no identity channel" diagnosis from memory_recall without it, and
learn_add echoing the gateway's bare "missing X-Session-Key". None of
them said that the server is unsupported there or that the env var is
not a credential, so the reader bounced between the two errors.

All three refusals now append one shared note when the process carries
neither the session token nor a launcher host pid, so nothing the
gateway does at spawn happened to it. learn_add maps the 400
missing_session_key code onto the same established-session refusal
memory_recall uses. Which calls are refused is unchanged; a server the
gateway did spawn keeps its existing wording.

Co-authored-by: w <w@k.local>
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