feat(openai): complete MCP approval request/response round trip

[franciscojavierarceo]

Parent

Part of #26 and #93.

Problem

The Responses agentic loop can detect an MCP call that requires approval, but the approval lifecycle is not complete:

1. openai_mcp_dispatch appends an mcp_approval_request item to ResponsesState::accumulated_output during response processing, after agentic_loop has already finalized the client response body. The approval item can therefore be absent from the returned response.
2. No request path recognizes an OpenAI mcp_approval_response input item, correlates it to the pending approval request, and resumes the original MCP call.

The existing #558 covers argument double-encoding inside an approval request, but not visibility or resumption.

Scope

• Return the generated mcp_approval_request in the non-streaming Responses output before ending the loop.
• Parse mcp_approval_response input items and correlate approval_request_id with the pending call.
• On approval, execute the original MCP call exactly once and resume inference with its result.
• On denial, do not call the MCP server and return a Responses-compatible outcome preserving the denial reason when supplied.
• Reject unknown, stale, duplicated, or mismatched approval identifiers safely.
• Preserve the original tool name, server label, call ID, and arguments across the round trip.
• Keep future streaming event emission aligned with stream_events: synthesize SSE for locally executed tools #276.

Acceptance criteria

• An approval-required request returns an mcp_approval_request output item.
• A follow-up request containing an approving mcp_approval_response performs one tools/call and completes the model → tool → model loop.
• A denied approval performs zero tools/call requests.
• Replaying an approval response cannot execute the tool twice.
• Unit and end-to-end tests cover approve, deny, malformed ID, and argument preservation.

Related

• Filter 8: mcp_tool #27 — original MCP tool execution scope (closed)
• MCP approval requests double-encode string-valued tool arguments #558 — approval argument encoding
• Responses API integration tests and example configs #100 — Responses integration coverage
• stream_events: synthesize SSE for locally executed tools #276 — client-visible SSE for server-side tool activity

[niejingchuan]

One boundary may be worth making explicit in the acceptance tests: approval
should authorize one exact pending call, not merely a tool name or a UI action.

Would it be useful to bind the approval response to a stable tuple such as:

• original call ID;
• server and tool identity;
• canonical argument digest;
• approval expiry;
• policy version evaluated at the pause;
• a single-use consumption record?

The negative cases would then include edited arguments, a mismatched call ID,
approval replay, approval expiry before dispatch, and a policy-version change
while paused. In every case, the original call should either execute exactly
once or return to approval_required; it should never become a second business
request.

I have an implementation-neutral failure-matrix format for these cases and can
share the small scenario if that would help the test plan. I am not proposing a
replacement approval framework here, only a portable set of observable
invariants for this issue's existing round trip.

[leseb]

Current scheduled Clawpatch Codex/xhigh run re-reported this root cause.

Finding ID(s): fnd_sig-feat-custom-apis-openai-resp_af56463188
Prior overlap: No prior-run overlap in preserved Clawpatch snapshot, but this is covered by existing issue #637.

Clawpatch finding

• Severity: high
• Category: api-contract
• Confidence: high
• Feature(s): feat_custom_apis_openai_responses_mcp_tools_agentic
• Finding ID(s): fnd_sig-feat-custom-apis-openai-resp_af56463188
• Run reports: 20260810T070320-ef1253, 20260810T070811-31e99e, 20260810T071144-b067a0, 20260810T071621-ff9ceb, 20260810T071954-8437e6
• Prior-run overlap: No prior-run overlap in preserved Clawpatch snapshot, but this is covered by existing issue feat(openai): complete MCP approval request/response round trip #637.

Evidence

Approval-required MCP calls are added only to internal state and omitted from the returned response body

• apis/src/openai/responses/mcp_dispatch/mod.rs:117-145 (McpDispatchFilter::handle_approval_required)
• apis/src/openai/responses/mcp_dispatch/mod.rs:220-241 (McpDispatchFilter::on_response_body)
• apis/src/openai/responses/agentic_loop/mod.rs:476-496 (finalize_response_body)
• apis/src/openai/responses/mcp_dispatch/tests.rs:936-955 (on_response_body_approval_required_sets_done_metadata)

Description

Approval-required MCP calls are added only to internal state and omitted from the returned response body

The documented filter order makes response hooks run through agentic_loop before MCP dispatch. AgenticLoopFilter serializes the current accumulated_output, after which McpDispatchFilter appends the mcp_approval_request only to state and signals done. Because MCP dispatch declares read-only body access and ignores the body parameter, the newly appended approval item never reaches the client. The client receives the earlier function_call response and has no approval request to answer. Additionally, extract_arguments uses Value::to_string, which double-encodes the normal string-valued function-call arguments when constructing the approval item.

Reproduction

Approval-required MCP calls are added only to internal state and omitted from the returned response body

Use a resolved MCP tool with require_approval absent or set to always and return its encoded function_call from the model. With the documented filter order and a single complete response chunk, inspect the returned response.output: it lacks the mcp_approval_request that exists in ResponsesState::accumulated_output.

Recommendation

Approval-required MCP calls are added only to internal state and omitted from the returned response body

Construct the approval item before final response serialization or give MCP dispatch read-write response access and reserialize response_object with the updated accumulated_output. Preserve an existing string-valued arguments field verbatim; serialize only object-valued arguments.

---

Reported from scheduled Clawpatch Codex/xhigh review after rebasing /Users/leseb/Documents/AI/ai to origin/main (1cc0a47). Please validate before assigning or starting implementation.

[leseb]

This issue requires human review before any work can begin. Do not self-assign and Do not submit a PR before the issue has been validated.

[leseb]

This issue requires human review before any work can begin. Do not self-assign and Do not submit a PR before the issue has been validated.

Current Clawpatch run update:

• Finding: fnd_sig-feat-custom-ai-openai-respon_4446283de3 — MCP approval handling is one-way and double-encodes canonical argument strings
• Severity/category/confidence: high / api-contract / high
• Feature/run: feat_custom_ai_openai_responses_tools_io / 20260810T074126-8d34f0
• Prior-run overlap: None detected.

Evidence

• apis/src/openai/responses/mcp_dispatch/mod.rs:128-143 (McpDispatchFilter::handle_approval_required) — The filter emits an mcp_approval_request, records done, and stores no pending approval state.
• apis/src/openai/responses/mcp_dispatch/mod.rs:189-215 (McpDispatchFilter::on_request_body) — Execution is driven only by state.tool_calls; no mcp_approval_response input is recognized.
• apis/src/openai/responses/mcp_dispatch/mod.rs:348-350 (extract_arguments) — tc.get("arguments").map(ToString::to_string).unwrap_or_default()
• apis/src/openai/responses/mcp_dispatch/tests.rs:937-955 (on_response_body_approval_required_sets_done_metadata) — The approval test verifies only the terminal done decision and does not submit a response.

Reproduction
Configure an MCP tool with require_approval: always. Let the model emit a function_call whose arguments field is the string "{"city":"Paris"}". The returned mcp_approval_request contains an arguments value representing ""{\"city\":\"Paris\"}"". Submit an mcp_approval_response approving that request with previous_response_id; no dispatch path consumes it and tools/call is never invoked.

[babyblueviper1]

On binding the approval response to one exact pending call rather than a tool name — this is the right boundary to hold, and it's the same one that matters for any approval-gate design, not just this integration.

The failure mode if you bind on tool name alone: two pending calls to the same tool (e.g. two concurrent write_file requests with different paths/contents) become interchangeable from the approver's point of view — an approval meant for call A can get consumed against call B if they race, because "approved: write_file" doesn't distinguish which write_file.

The concrete fix is binding the approval to a digest of the exact request fields the caller is being asked to authorize — not just the tool name, but the full call shape (target, args, and anything else that changes the real-world effect). If mcp_approval_response carries an id that's correlated 1:1 to the specific mcp_approval_request item (not just the tool), that already gets you most of the way there — the remaining question is whether that correlation id is derived from (or independently checkable against) the actual call contents, or is just an opaque sequence number the server trusts blindly. An opaque id is fine as long as nothing between request and response can substitute a different call under the same id; a content-derived id closes that gap even if something does.