How the Review Gate Feature Works in the OpenAI Codex Plugin for Claude Code

The review gate feature is an optional safety mechanism that intercepts Claude Code session stop events to force a final Codex review of code changes, blocking the session if issues are found.

The review gate feature in the openai/codex-plugin-cc repository creates a synchronous quality checkpoint between Claude Code and OpenAI Codex. This feature ensures that every code-modifying turn undergoes automated review before a session terminates, preventing accidental merges of unchecked changes.

Enabling and Disabling the Review Gate

Users control the review gate feature via the /codex:setup command in Claude Code. This configuration persists per project and determines whether the safety mechanism is active.

Enable the gate to enforce reviews on every code-changing turn:

/codex:setup --enable-review-gate

Disable the gate when continuous monitoring is unnecessary:

/codex:setup --disable-review-gate

According to the README.md, these commands update the project configuration to register or remove the stop hook that triggers the review process.

How the Review Gate Intercepts Session Stops

When enabled, the review gate operates through a dedicated stop hook that synchronously evaluates code changes before allowing a session to terminate.

Stop Hook Registration

When active, the plugin registers the Stop hook implemented in plugins/codex/scripts/stop-review-gate-hook.mjs. This hook fires each time Claude Code attempts to end a session, creating a blocking checkpoint that must resolve before the stop event completes.

Input Gathering and Job Filtering

The hook first reads the hook payload containing the session's last assistant message, current working directory, and metadata. It then filters for running Codex jobs belonging to the same session using the filterJobsForCurrentSession function (lines 40-46).

If Codex is not installed, the hook invokes buildSetupNote (lines 59-66) to log a configuration warning and aborts the review process, allowing the stop to proceed without blocking.

Prompt Construction and Template Injection

For valid sessions, the hook loads the stop-review-gate.md prompt template from plugins/codex/prompts/. It injects the previous Claude response into the template using interpolateTemplate within the buildStopReviewPrompt function (lines 48-57).

The template instructs Codex to:

• Review only code-changing turns
• Return ALLOW if no issues are found
• Return BLOCK with a concise reason if problems are detected

Running the Review and Processing Results

The constructed prompt is sent to the Codex companion via runStopReview in codex-companion.mjs. This operation runs as a one-off task with a hard timeout of 15 minutes (STOP_REVIEW_TIMEOUT_MS).

Decision Parsing and Session Control

The hook parses Codex's JSON output using parseStopReviewOutput. If the first line begins with ALLOW:, the session stop proceeds normally. If it begins with BLOCK:, the hook invokes emitDecision (lines 29-31) to emit a blocking decision payload that surfaces the reason to the user.

When blocking occurs, the decision returns to Claude Code so the assistant can address the reported issues before the session ends. If no review is needed or the review passes, the hook logs any running job notices and permits the stop to proceed.

Key Implementation Files

The review gate feature spans several critical files in the codebase:

File	Function
plugins/codex/scripts/stop-review-gate-hook.mjs	Implements the Stop hook, manages the review lifecycle, and handles ALLOW/BLOCK decisions
plugins/codex/prompts/stop-review-gate.md	Template defining review criteria and required output format
plugins/codex/scripts/lib/codex.mjs	Provides getCodexAvailability to verify Codex installation
plugins/codex/scripts/lib/state.mjs	Supplies getConfig and listJobs for configuration and job tracking

Code Example: Decision Logic

The following JavaScript demonstrates the core decision flow used by the stop hook:

import { readHookInput, emitDecision } from './stop-review-gate-hook.mjs';

const input = readHookInput();               // receives {last_assistant_message, cwd, …}
const review = runStopReview(process.cwd(), input);

if (!review.ok) {
  emitDecision({
    decision: 'block',
    reason: review.reason
  });
}

This pattern ensures that code modifications receive final validation before the Claude Code session terminates, creating a Claude↔Codex feedback loop that enforces quality standards.

Summary

• The review gate feature creates a synchronous safety checkpoint that intercepts Claude Code session stop events to enforce final code reviews.
• Users enable or disable the gate via /codex:setup --enable-review-gate or /codex:setup --disable-review-gate.
• The stop-review-gate-hook.mjs file implements the core logic, filtering jobs, constructing prompts, and parsing Codex responses.
• Reviews timeout after 15 minutes (STOP_REVIEW_TIMEOUT_MS) and require Codex to return either ALLOW: or BLOCK: in the first line of output.
• When blocking occurs, the emitDecision function prevents session termination and surfaces issues to the user for resolution.

Frequently Asked Questions

What triggers the review gate feature?

The review gate triggers on every stop event in a Claude Code session when the feature is enabled via /codex:setup --enable-review-gate. The stop-review-gate-hook.mjs hook intercepts the termination attempt and initiates a review of the immediately preceding turn's code changes.

How does the review gate decide to block a session?

The gate parses Codex's JSON output using parseStopReviewOutput. If the first line begins with BLOCK:, the hook calls emitDecision to prevent session termination and return the blocking reason to Claude. If the line begins with ALLOW: or no code changes were made, the stop proceeds normally.

Can the review gate function without Codex installed?

No. The hook checks for Codex availability using getCodexAvailability from lib/codex.mjs. If Codex is not installed, buildSetupNote logs a configuration warning and the hook aborts without blocking the stop event, allowing the session to end normally.

What is the timeout duration for review gate operations?

The review gate enforces a 15-minute timeout defined by STOP_REVIEW_TIMEOUT_MS. If the Codex review task in codex-companion.mjs does not complete within this window, the operation times out, potentially allowing the stop to proceed or logging an error depending on the implementation's error handling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}