Skip to content

docs(mcp): name identity_unattested in the tool-policy reason contract - #12461

Merged
bolichen97 merged 1 commit into
mainfrom
docs/mcp-tool-policy-identity-unattested
Sep 21, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/mcp-tool-policy-identity-unattested

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

docs/architecture/mcp.md describes the unresolved reasons the tool-policy read produces and what tools/call does with each. #12445 added a second fail-closed reason for the 409 (identity_unattested) and changed how the 409 is mapped (by the body's code, not by status), in src/kiro_crew/mcp_shared.py and its tests only. The doc still describes the single-reason behaviour, so two of its statements do not match the code on main:

  • It names policy_unreadable as the only reason tools/call refuses on, "the gateway's 409". The code refuses on two: _UNRESOLVED_REFUSES_CALL = frozenset({"policy_unreadable", "identity_unattested"}). identity_unattested appears nowhere in the doc.
  • It says the MCP side maps "that 409" to policy_unreadable. The 409 arm reads the body's code and maps member_identity_unavailable to identity_unattested; only a body carrying policy_unreadable, or one that cannot be read or carries no code, takes the policy_unreadable arm.

Why it matters

This section is the written contract a reader consults to learn why a tool call was refused and which audit event to look for. A reader who sees identity_unattested in a refusal text, or tool_policy.unattested in the audit log, finds no mention of either here, and the doc's statement that a 409 means an unreadable spec sends them to the agents directory when the actual condition is a missing session token. The doc is also the third enumeration of these reason values (the other two are in mcp_shared.py); an enumeration that omits a value is what quietly goes wrong next time the code adds one.

What changed (motivation -> approach -> change)

  • Motivation: the doc lags the code on one contract point: two refusing reasons, and a 409 disambiguated by its body code.
  • Approach: state the current contract in the doc's own present-tense style, drawing each claim from the code it describes: the reason names, the body codes, the refusal audit outcome, the per-reason error text, the tool_policy.unattested audit event, and the no-negative-cache rule. No history narration in the doc.
  • Change: two paragraphs of docs/architecture/mcp.md.
    1. The fail-closed paragraph names both refusing reasons, gives the body code each 409 carries, says how the MCP side tells them apart, says that a 409 whose body cannot be read or carries no code takes the policy_unreadable arm, and notes that a control-plane backend (CONTROL_PLANE_BACKENDS in mcp_gateway/gatewayd.py) is handed the token per frame in the caller block so its calls do not land on identity_unattested.
    2. The unreadable-spec paragraph gives the body shape the gateway sends ("code": "policy_unreadable", not an error field carrying the reason) and says neither 409 reason is negative-cached.

Docs only. No code, test or behaviour change.

Backwards compatibility

Compatible: documentation only; nothing that works today changes.

Tests

N/A -- no code change. python3 scripts/docs_lint.py --test and ./scripts/docs-lint.sh pass on the branch.

Manual verification

Each claim in the two edited paragraphs was checked against main @ cd85b01cb0:

  • src/kiro_crew/mcp_shared.py: the members of _UNRESOLVED_REFUSES_CALL; the 409 arm's _http_error_code read and its fallback to the policy_unreadable arm; the tool_policy.unattested audit call; the two refusal texts emitted under rejected_policy_unresolved; the not-negative-cached comment on both 409 answers.
  • src/kiro_crew/dashboard/handlers/sessions.py: the policy_unreadable 409 body carries "code": "policy_unreadable" beside a prose error.
  • src/kiro_crew/dashboard/handlers/_shared.py: the identity 409 body carries "code": "member_identity_unavailable".
  • src/kiro_crew/mcp_gateway/gatewayd.py: CONTROL_PLANE_BACKENDS is the set of backends handed the per-session token.

Related Issues

no linked issue: the PR carries the context. Follows #12445, which added identity_unattested to the code and its comment block; this doc is the third enumeration of the reason values and did not receive it.

@chenmingwei23
chenmingwei23 requested review from a team and patrigao September 21, 2026 05:36
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Make the tool-policy section of docs/architecture/mcp.md state the contract mcp_shared.py enforces on main: tools/call refuses on two reasons (policy_unreadable, identity_unattested), and the two 409 conditions are told apart by the body code, with an unreadable or code-less body taking the refusing policy_unreadable arm.
Not a goal: Changing any behaviour. No code, test or reason value changes; the doc only follows the code. Whether identity_unattested should refuse or permit is settled in the code and not reopened here.

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

The PR names the next-drift mechanism itself; a doc-pin test tying the reason enumeration to _UNRESOLVED_REFUSES_CALL is worth a follow-up.

Suggestions

  • The description correctly diagnoses that "an enumeration that omits a value is what quietly goes wrong next time" — a small test asserting each member of _UNRESOLVED_REFUSES_CALL appears in docs/architecture/mcp.md would fix the mechanism, not just this instance (follow-up, not this PR).

[DESIGN-REVIEWED] ed86713

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

Everything in the doc matches the implementation: the member_identity_unavailable→identity_unattested mapping (mcp_shared.py:720,738), the tool_policy.unattested SEL op (:733), the code-less/unparseable 409 body taking the policy_unreadable arm (:739-760), and both reasons in _UNRESOLVED_REFUSES_CALL (:956). The change is doc-only, accurate, and markdown matches no AUTOSDE file-patterns.

No findings.

[OPUS-REVIEWED] ed86713

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

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

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ed86713

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

@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 21, 2026
docs/architecture/mcp.md enumerates the unresolved reasons the tool-policy
read produces and what tools/call does with each. Two of its statements
do not match src/kiro_crew/mcp_shared.py:

  * tools/call refuses on two reasons, not one. identity_unattested is
    the 409 whose body code is member_identity_unavailable -- the
    declared session key reached the gateway without the token that
    vouches for it -- and it sits in _UNRESOLVED_REFUSES_CALL beside
    policy_unreadable, with its own audit event (tool_policy.unattested)
    and an error text that names the missing token.
  * the two 409 conditions are told apart by the body's code, not mapped
    by status. A 409 whose body cannot be read or carries no code takes
    the policy_unreadable arm.

The passage states both, gives the body shape the gateway sends
("code": "policy_unreadable" rather than an "error" field carrying the
reason), and notes that neither 409 reason is negative-cached.

Docs only. No code change.
@chenmingwei23
chenmingwei23 force-pushed the docs/mcp-tool-policy-identity-unattested branch from a044c63 to ed86713 Compare September 21, 2026 06:07
@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 21, 2026

@bolichen97 bolichen97 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. Docs-only, 1 file, and every claim in the two edited paragraphs is checkable against the code it describes — two refusing reasons in _UNRESOLVED_REFUSES_CALL, the 409 disambiguated by the body's code with policy_unreadable as the fallback arm, and CONTROL_PLANE_BACKENDS handed the token per frame so its calls do not land on identity_unattested.

Correcting a third enumeration that the code change skipped is exactly the kind of drift worth a PR of its own.

Note: the head moved to ed86713adb after the review lanes ran on a044c6300e, so a fresh round is in flight. Arming auto-merge rather than merging by hand, so it lands on its own green.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=3c8475d16cfb -- docs/architecture/mcp.md:1069 -- FIXED in ed86713

Fixed. The sentence described only the missing-token cause of the 409 with code member_identity_unavailable.
Checked against member_request_scope in src/kiro_crew/dashboard/handlers/_shared.py: verified=False, which is what internal_memory_scope turns into that 409, also results from an attested key whose execution record cannot be read (read_session_execution raising OSError/ValueError) and from a cron: key the scheduler has no record for.
The doc now says the gateway could not establish the execution identity behind the declared X-Session-Key, names the missing or mismatched token as the usual cause, lists the other two, and says the identity_unattested refusal text names the token as that usual cause. Code, tests and the reason value are unchanged.

@bolichen97
bolichen97 enabled auto-merge (squash) September 21, 2026 06:14
@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 21, 2026
@bolichen97
bolichen97 merged commit 34fe0de into main Sep 21, 2026
93 checks passed
@bolichen97
bolichen97 deleted the docs/mcp-tool-policy-identity-unattested branch September 21, 2026 06:31
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 21, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
kirodotdev#12461)

docs/architecture/mcp.md enumerates the unresolved reasons the tool-policy
read produces and what tools/call does with each. Two of its statements
do not match src/kiro_crew/mcp_shared.py:

  * tools/call refuses on two reasons, not one. identity_unattested is
    the 409 whose body code is member_identity_unavailable -- the
    declared session key reached the gateway without the token that
    vouches for it -- and it sits in _UNRESOLVED_REFUSES_CALL beside
    policy_unreadable, with its own audit event (tool_policy.unattested)
    and an error text that names the missing token.
  * the two 409 conditions are told apart by the body's code, not mapped
    by status. A 409 whose body cannot be read or carries no code takes
    the policy_unreadable arm.

The passage states both, gives the body shape the gateway sends
("code": "policy_unreadable" rather than an "error" field carrying the
reason), and notes that neither 409 reason is negative-cached.

Docs only. No code change.
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