Repository navigation
docs(mcp): name identity_unattested in the tool-policy reason contract - #12461
Conversation
|
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. |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS The PR names the next-drift mechanism itself; a doc-pin test tying the reason enumeration to Suggestions
[DESIGN-REVIEWED] ed86713 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsEverything in the doc matches the implementation: the No findings. [OPUS-REVIEWED] ed86713 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
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.
a044c63 to
ed86713
Compare
bolichen97
left a comment
There was a problem hiding this comment.
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.
|
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.
Problem / Motivation
docs/architecture/mcp.mddescribes the unresolved reasons the tool-policy read produces and whattools/calldoes with each. #12445 added a second fail-closed reason for the409(identity_unattested) and changed how the409is mapped (by the body'scode, not by status), insrc/kiro_crew/mcp_shared.pyand its tests only. The doc still describes the single-reason behaviour, so two of its statements do not match the code onmain:policy_unreadableas the only reasontools/callrefuses on, "the gateway's409". The code refuses on two:_UNRESOLVED_REFUSES_CALL = frozenset({"policy_unreadable", "identity_unattested"}).identity_unattestedappears nowhere in the doc.409" topolicy_unreadable. The 409 arm reads the body'scodeand mapsmember_identity_unavailabletoidentity_unattested; only a body carryingpolicy_unreadable, or one that cannot be read or carries nocode, takes thepolicy_unreadablearm.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_unattestedin a refusal text, ortool_policy.unattestedin the audit log, finds no mention of either here, and the doc's statement that a409means 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 inmcp_shared.py); an enumeration that omits a value is what quietly goes wrong next time the code adds one.What changed (motivation -> approach -> change)
409disambiguated by its body code.tool_policy.unattestedaudit event, and the no-negative-cache rule. No history narration in the doc.docs/architecture/mcp.md.codeeach409carries, says how the MCP side tells them apart, says that a409whose body cannot be read or carries nocodetakes thepolicy_unreadablearm, and notes that a control-plane backend (CONTROL_PLANE_BACKENDSinmcp_gateway/gatewayd.py) is handed the token per frame in the caller block so its calls do not land onidentity_unattested."code": "policy_unreadable", not anerrorfield carrying the reason) and says neither409reason 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 --testand./scripts/docs-lint.shpass 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_coderead and its fallback to thepolicy_unreadablearm; thetool_policy.unattestedaudit call; the two refusal texts emitted underrejected_policy_unresolved; the not-negative-cached comment on both 409 answers.src/kiro_crew/dashboard/handlers/sessions.py: thepolicy_unreadable409 body carries"code": "policy_unreadable"beside a proseerror.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_BACKENDSis the set of backends handed the per-session token.Related Issues
no linked issue: the PR carries the context. Follows #12445, which added
identity_unattestedto the code and its comment block; this doc is the third enumeration of the reason values and did not receive it.