[PetrefiedThunder]

Stacked on #853. This PR's base is claude/objective-knuth-d05d5a, so the diff shows only the six commits below. Merge #853 first. This repo deletes merged head branches, so GitHub should retarget this PR to main when #853 merges. If #853 is squash-merged, expect this PR to show conflicts or extra files until it is rebased onto main; the real delta is the six commits listed here.

Summary

Follow-up to #853, which stopped a received, well-formed result from being signed delivery_uncertain. This PR closes the neighbouring case, fixes two classification gaps found in review, and corrects claims in the docs that did not hold.

1. An unparseable upstream result envelope is response_rejected

A tools/call response that the upstream sent but whose envelope the SDK cannot parse (content a string, isError not a bool, and similar) ended as delivery_uncertain (504 / -32005, counted by the circuit breaker) through a real SDK session. _call_tool_once intends response_rejected.

Cause: the SDK's anyio task group rewraps anything raised inside the async with self._session() block in an ExceptionGroup, so the adapter's ValidationError branch never matched and the generic handler classified the call by dispatch_started alone. Tests that fake the session do not enter the task group, which is why they passed.

Fix: _call_tool_once records the rejection at the call_tool await, where the SDK raises ValidationError only after the upstream's JSON-RPC result has arrived. The call ends as response_rejected with code upstream_response_invalid (502 / -32006): debit kept, never redispatched, replay returns the same receipt. A call with no response (timeout, dropped connection, a JSON-RPC error answering tools/call) and a malformed initialize answer keep their outcomes.

2. /mcp tells the model not to resend a rejected response

app/routers/mcp_standard.py returned the do-not-resend tool result only for delivery_uncertain. response_rejected is also charged (the call was dispatched and the debit stands), but it became a bare -32006, the same code that refunded, retry-safe failures use. A model that sees only the message could resend a call whose charge stands and whose tool probably ran.

response_rejected now returns the same guided result as delivery_uncertain: isError: true, text saying the upstream answered but the answer was unusable and the effect is unknown, the signed receipt, and _meta["io.agentmiddleware/outcome"] with status unknown and reason response_rejected. Refunded failures stay bare errors. /mcp/messages and REST are unchanged. Nothing the upstream wrote is relayed.

3. One parse-failure rule for both handlers

The ladder's ValidationError handlers could label a request-build error (for example arguments with a non-string key: the claim is committed and no tools/call reaches the upstream) as response_rejected, which asserts the upstream answered. Both handlers now use _is_unparseable_response: after dispatch, a CallToolResult validation error or a JSON decode error is response_rejected, and any other validation error is delivery_uncertain. The branch also gained the "a result is already in hand" guard its two sibling handlers have.

4. Docs: claims that did not hold

Four review passes, each correcting claims in docs/mcp-security-posture.md, docs/exit-and-export.md, docs/failure-semantics.md, docs/gateway-overhead.md, CHANGELOG.md and READMEs. The substantive ones:

• Endpoint decision recorded. POST /mcp/messages and the REST invoke route are the live governed path in the supported pilot. POST /mcp ships off (ENABLE_STANDARD_MCP_ENDPOINT defaults to false) and the runbook keeps it off.
• File:line citations re-pinned. Of 17, 15 had moved (the base was more than a thousand commits older). Each is re-pinned and the claim beside it re-read.
• idempotency_key_required is a refusal for a call that names a permit and sends no key, not for every governed call. mcp.py replaces a missing key with a server-derived act1- key before that check. The digest covers the action permit's identity only, not the payload.
• Deletes. The API-key DELETE route only revokes (status, revoked_at, revoke_reason) and keeps the row. In the default configuration no mounted DELETE route deletes anything.
• Opt-ins that exist. KMS and row-level security exist as opt-ins, default off. Optional tracing exists (OTEL_TRACING_ENABLED, default off).
• Still delivery_uncertain, now documented. A body that is not a JSON-RPC message at all (non-JSON text, jsonrpc 1.0, neither result nor error, unknown request id) is logged by the SDK transport, never raised, and ends delivery_uncertain after the call timeout.
• Gateway overhead re-measured twice on this base: first call p50 29.5-30.9 ms, replay p50 5.4-5.6 ms. Results are in docs/research/gateway-overhead-2026-10-23/. The public site's figure is not touched.

Behavior changes

• A malformed envelope no longer counts toward the optional circuit breaker, like the other response_rejected causes.
• POST /mcp returns response_rejected as an isError tool result with do-not-resend text. This is a change to what an MCP client sees on that endpoint, which ships off by default.
• docs/openapi.json is regenerated with scripts/export_openapi.py. It differs by the REST invoke and /mcp/messages descriptions only: no schema or path changes.

Deliberately unchanged

• The plugin's mcp.json, which targets /mcp on the first-party host. That is a product decision.
• The machine-read discovery labels legacy_project_transport and legacy_project_json_rpc.
• The public site's overhead figure.

Tests

• Real SDK session behind the real adapter, in memory and over the production Streamable HTTP client, including a fixture guard that proves the envelope reaches the client and fails there (a sender-side crash looks identical from the adapter's side).
• A non-wrapping session double covers both directions of the shared rule.
• /mcp end to end: an unparseable envelope, an oversized result, and a bearer echo each give a readable tool result, a receipt, one debit and no redispatch on replay, and relay nothing the upstream wrote.
• A spy test pins the gateway outcome recorded on /mcp (failed for a rejected response, unknown for an undelivered one).
• A test that POST /mcp honours a permit the caller names, enforcing forbidden_fields with a signed denied receipt.
• Governed-router receipt test: one debit, one dispatch, a response_rejected receipt, no redispatch on replay, breaker state.

CI is the gate for this PR. The author session did not re-run the full suite on this branch tip before opening it, and has no numbers to quote for it. The last two commits are text only: no .py file differs between 93aee1ab and 8c2b4428.

Not covered

• No real third-party MCP server.
• The "not a JSON-RPC message at all" case is documented but not fixed: it still waits out the call timeout and ends delivery_uncertain.

Open owner decisions (not made here)

• Discovery still labels the live path "legacy".
• REST invoke is not advertised in discovery.
• The plugin mcp.json URL.

🤖 Generated with Claude Code

---

Note

High Risk
Changes charged-call outcome semantics, circuit-breaker counting, and default-off POST /mcp client-visible errors; mistakes could cause double charges or unsafe retries.

Overview
Fixes misclassification of upstream tools/call responses the MCP SDK cannot parse: they now finalize as charged, terminal response_rejected (upstream_response_invalid, 502 / -32006) instead of delivery_uncertain. The adapter records CallToolResult validation failures at the call_tool await (before the SDK task group wraps them in ExceptionGroup) and applies _is_unparseable_response consistently so request-build errors stay uncertain while parse failures are rejected. Session-close errors no longer overwrite a known result or rejection.

On POST /mcp, response_rejected is returned like delivery_uncertain: an isError tool result with do-not-resend guidance and outcome metadata (refunded -32006 failures remain JSON-RPC errors). Malformed envelopes no longer feed the circuit breaker.

Docs and API copy record that /mcp/messages and REST invoke are the supported pilot paths (POST /mcp off by default), refresh security/failure/troubleshooting claims, re-pin citations, re-measure gateway overhead, and regenerate OpenAPI descriptions. Tests add real SDK sessions (memory + Streamable HTTP) and governed-router coverage for receipts, breaker behavior, and standard-endpoint tool results.

^{Reviewed by Cursor Bugbot for commit 8c2b442. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-24T05:25:40.886548Z	8c2b442	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.