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

> Discover how the OpenAI Codex plugin for Claude Code review gate feature works. This optional safety tool intercepts sessions to ensure final Codex review of code changes, blocking issues before they impact your project.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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:

```bash
/codex:setup --enable-review-gate

```

Disable the gate when continuous monitoring is unnecessary:

```bash
/codex:setup --disable-review-gate

```

According to the [README.md](https://github.com/openai/codex-plugin-cc/blob/main/README.md#L225-L233), 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](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs#L40-L46)).

If Codex is not installed, the hook invokes `buildSetupNote` ([lines 59-66](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs#L59-L66)) 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`](https://github.com/openai/codex-plugin-cc/blob/main/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](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs#L48-L57)).

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](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs#L29-L31)) 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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```javascript
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.