codex-approval-gate-plugin

# Codex Approval Gate Plugin Approval Gate is a small Codex plugin that gives Codex native MCP approval and decision checkpoints before risky actions. It exposes two MCP tools: - `request_approval`: ask the user to approve or reject a risky next step. - `request_decision`: ask the user to choose exactly one option through MCP elicitation, then return the selected branch. Both tools are configured with `approval_mode: "prompt"`. When Codex calls them, Codex CLI or Codex App can show native MCP approval UI before the tool runs. `request_decision` can then use native MCP elicitation to collect a structured choice. If the user declines or cancels, Codex should not continue. ## What It Is For - Deployments and releases - Deletes, migrations, overwrites, and data changes - Messages, emails, comments, posts, forms, and other external communications - API keys, OAuth apps, access grants, and permission changes - Uploading private files or sensitive data - Paid, irreversible, or high-blast-radius operations - Multi-option decisions such as choosing test/pre/prod, selecting a rollout path, or deciding whether to stop ## How It Works The included skill tells Codex to call `approval-gate.request_approval` immediately before a risky action, or `approval-gate.request_decision` when the user must choose one of several branches. The plugin's `.mcp.json` marks both tools as approval-gated: ```json { "default_tools_approval_mode": "prompt", "tools": { "request_approval": { "approval_mode": "prompt" }, "request_decision": { "approval_mode": "prompt" } } } ``` The MCP server itself does not perform the risky action. It returns an approval receipt or decision receipt only after Codex has allowed the tool call to execute. ## Requirements - Codex CLI or Codex App with plugin and MCP support - Node.js 18 or newer - An approval mode that permits prompts, such as `on-request` - A client with MCP form elicitation support for `request_decision` Native prompts can be suppressed if Codex is launched with `approval_policy = "never"` or a bypass mode. ## Known Client Limitation `request_decision` sends a standards-aligned MCP `elicitation/create` request with `mode: "form"` and a titled single-choice schema. Some Codex App versions may render that request as a binary Allow/Cancel prompt and return `content: {}` instead of the selected choice. In that case the plugin returns a clear error and stops instead of guessing. Use a client version that supports form elicitation, or fall back to explicit chat confirmation. ## Local Development Run the MCP server directly: ```bash node ./mcp-server/index.mjs ``` The server speaks newline-delimited MCP JSON-RPC over stdio. A quick smoke test: ```bash printf '%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"request_approval","arguments":{"action":"Deploy task-center to production","risk":"Production release","target":"task-center/prod","data":"none","next_step":"npm run deploy:prod"}}}' \ | node ./mcp-server/index.mjs ``` For a full approval plus decision smoke test: ```bash npm run smoke ``` ## Using With Codex Install or enable this directory as a Codex plugin. The same plugin layout is intended for Codex CLI and Codex App: ```text .codex-plugin/plugin.json .mcp.json skills/approval-gate/SKILL.md mcp-server/index.mjs ``` After enabling it, ask Codex to use Approval Gate before a risky action, or mention the `approval-gate` skill directly. Other skills can reuse the same tools by adding instructions such as: ```md Before risky actions, call `approval-gate.request_approval`. When the user must choose between branches, call `approval-gate.request_decision` and only execute the returned `selected_option_id` branch. ``` ## Privacy This plugin runs locally. It does not call external services. Approval details are returned to Codex as the tool result. ## Terms Use at your own risk. This plugin is a workflow guardrail; it does not replace Codex sandboxing, repository permissions, production controls, or human review.