PR #68807: fix(codex): bridge MCP tool approval elicitations

• Repository: openclaw/openclaw
• Author: kesslerio
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68807

Description (problem / solution / changelog)

Summary

• Problem: native Codex app-server sessions let MCP tool approval elicitations fall through to the fail-closed client fallback, which surfaced Codex Apps GitHub writes as immediate user rejected MCP tool call failures.
• Why it matters: Codex Apps connector writes could not reach the existing OpenClaw approval UX even though plugin approvals, Control UI handling, and chat /approve flows already existed.
• What changed: targeted mcpServer/elicitation/request handling now bridges _meta.codex_approval_kind = "mcp_tool_call" through plugin.approval.request / plugin.approval.waitDecision, clamps approval payload lengths to gateway schema limits, and adds focused regression coverage.
• What did NOT change (scope boundary): generic item/tool/requestUserInput, non-approval elicitations, connector auth, and GitHub permission behavior all remain unchanged and fail closed outside this targeted MCP approval path.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #68784
• Related #68721
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: extensions/codex/src/app-server/run-attempt.ts only bridged native approval request families and item/tool/call, so MCP tool approvals arriving on mcpServer/elicitation/request fell through to client.ts's default { action: "decline" } fallback.
• Missing detection / guardrail: there was no targeted bridge for _meta.codex_approval_kind = "mcp_tool_call", and no regression test proving the native Codex bridge had to intercept that request family before fallback.
• Contributing context (if known): the Codex app-server protocol carries MCP tool approvals on the elicitation path rather than on the older approval request methods.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • extensions/codex/src/app-server/elicitation-bridge.test.ts
  • extensions/codex/src/app-server/run-attempt.test.ts
  • extensions/codex/src/app-server/client.test.ts
• Scenario the test should lock in: an MCP tool approval elicitation tagged with _meta.codex_approval_kind = "mcp_tool_call" routes through plugin approval request/wait, unsupported generic prompts still fail closed, and long approval payloads are clamped before gateway validation.
• Why this is the smallest reliable guardrail: the bug lives at the native Codex bridge boundary, so the tightest durable coverage is one bridge-level test plus one run-attempt routing test.
• Existing test that already covers this (if any): none before this PR.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Native Codex app-server sessions can now surface MCP tool approval prompts for Codex Apps writes through the existing OpenClaw approval flow instead of immediately declining them as fake user rejections.
• Unsupported generic item/tool/requestUserInput and non-approval elicitation flows still fail closed exactly as before.

Diagram (if applicable)

Before:
Codex Apps MCP write -> mcpServer/elicitation/request -> client fallback decline -> "user rejected MCP tool call"

After:
Codex Apps MCP write -> mcpServer/elicitation/request -> native elicitation bridge
-> plugin.approval.request / waitDecision -> existing approval UX -> accept/decline response

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes
• Data access scope changed? No
• If any Yes, explain risk + mitigation: this changes how an existing MCP tool approval request is routed, not what the tool can access. The bridge is gated to _meta.codex_approval_kind = "mcp_tool_call", leaves unsupported flows fail-closed, and clamps payloads to existing gateway validation limits.

Repro + Verification

Environment

• OS: NixOS
• Runtime/container: local OpenClaw repo checkout, native Codex app-server path
• Model/provider: codex/gpt-5.4
• Integration/channel (if any): Codex Apps GitHub connector via native app-server
• Relevant config (redacted): native Codex app-server enabled; existing plugin approval flow available

Steps

1. Start a native Codex app-server session with Codex Apps available.
2. Trigger a GitHub connector mutation that asks for MCP tool approval.
3. Observe the request path returned by the native bridge.

Expected

• The approval prompt routes into the existing plugin approval flow and returns an accept/decline response instead of auto-declining.

Actual

• Before this patch, the request fell through to the client fallback and returned an immediate decline, which surfaced as user rejected MCP tool call.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • focused Codex app-server tests for approval bridge, elicitation bridge, run-attempt routing, and client fallback behavior
  • payload-length clamp so long elicitation prompts still pass gateway validation
• Edge cases checked:
  • unavailable approval route declines cleanly
  • non-approval elicitation requests stay unhandled
  • generic item/tool/requestUserInput still fails closed
• What you did not verify:
  • a live end-to-end GitHub connector mutation through the Control UI or chat approval surface

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: the approval-content synthesis may miss a future schema shape for MCP tool approvals.
  • Mitigation: the bridge is narrowly gated to _meta.codex_approval_kind = "mcp_tool_call", only accepts form-mode object schemas, and fails closed when required fields cannot be satisfied.
• Risk: rich approval prompts could exceed gateway schema limits and get rejected before reaching the approval UX.
  • Mitigation: the shared plugin approval helper now clamps title and description lengths before calling plugin.approval.request, with regression coverage.

AI Assistance

• Investigation, implementation, and test authoring were done with Codex.
• Human verification was limited to focused local test execution and code inspection in this checkout.

Tests

• pnpm exec vitest run extensions/codex/src/app-server/approval-bridge.test.ts extensions/codex/src/app-server/elicitation-bridge.test.ts extensions/codex/src/app-server/run-attempt.test.ts extensions/codex/src/app-server/client.test.ts

Changed files

• extensions/codex/src/app-server/approval-bridge.ts (modified, +15/-96)
• extensions/codex/src/app-server/client.test.ts (modified, +22/-1)
• extensions/codex/src/app-server/elicitation-bridge.test.ts (added, +284/-0)
• extensions/codex/src/app-server/elicitation-bridge.ts (added, +345/-0)
• extensions/codex/src/app-server/plugin-approval-roundtrip.ts (added, +106/-0)
• extensions/codex/src/app-server/run-attempt.test.ts (modified, +78/-0)
• extensions/codex/src/app-server/run-attempt.ts (modified, +10/-0)