How the Codex Review Gate Works and When to Enable It

The Codex review gate is a safety mechanism that forces a final "stop-time" review before a Claude session can end, preventing incomplete or erroneous work from being finalized.

The review gate is implemented in the openai/codex-plugin-cc repository as a configurable boolean flag stored in plugin state. When enabled, it intercepts the codex:stop command, runs a Codex review task, and blocks session termination if the review detects problems. This article explains the implementation details, configuration methods, and recommended usage scenarios.

Review Gate Configuration and Storage

The review gate state persists in state.json at the workspace level. According to the source code in lib/state.mjs, the default configuration disables the gate:

// plugins/codex/scripts/lib/state.mjs
// default configuration
// ─────────────────────
//   config: {
//     stopReviewGate: false
//   },
// ─────────────────────

The key configuration parameter is config.stopReviewGate. The lib/state.mjs module provides setConfig() and getConfig() helpers to read and modify this value programmatically.

Enabling and Disabling the Review Gate

Use the /codex:setup command with explicit flags to toggle the gate. The implementation in codex-companion.mjs parses these flags and updates persistent state:

// plugins/codex/scripts/codex-companion.mjs
if (options["enable-review-gate"]) {
  setConfig(workspaceRoot, "stopReviewGate", true);
} else if (options["disable-review-gate"]) {
  setConfig(workspaceRoot, "stopReviewGate", false);
}

Enable the review gate

codex:setup --enable-review-gate

Expected output:

Enabled the stop-time review gate for /path/to/workspace.

Disable the review gate

codex:setup --disable-review-gate

Expected output:

Disabled the stop-time review gate for /path/to/workspace.

The setup command records configuration changes in an actionsTaken array that appears in the final setup report.

Runtime Behavior: How the Stop-Time Review Gate Blocks Sessions

The stop-review-gate-hook.mjs file implements the actual interception logic. This hook executes on every codex:stop command.

When the gate is disabled

// plugins/codex/scripts/stop-review-gate-hook.mjs
if (!config.stopReviewGate) {
  logNote(runningTaskNote);
  return;
}

The session ends immediately.

When the gate is enabled

The hook performs three critical checks:

1. Setup verification — calls buildSetupNote() to confirm Codex is properly configured; aborts with a helpful hint if not
2. Review execution — calls runStopReview() which launches the companion script with the stop-review-gate template prompt
3. Decision parsing — requires explicit ALLOW: response to proceed; BLOCK: (or any failure) emits a block decision preventing session termination

The review prompt template lives at plugins/codex/prompts/stop-review-gate.md. It processes the previous Claude response to evaluate whether work is complete and correct.

Verifying Review Gate Status

The codex:status command surfaces configuration through renderStatusReport in lib/render.mjs:

// plugins/codex/scripts/lib/render.mjs
`Review gate: ${report.config.stopReviewGate ? "enabled" : "disabled"}`

Check current status

codex:status

Enabled gate output:

# Codex Status

Session runtime: …
Review gate: enabled
…
The stop-time review gate is enabled.

Disabled gate output:

Review gate: disabled

The additional note (lines 69-71 of render.mjs) only appears when the gate is active.

When to Enable the Review Gate

Enable the review gate in these scenarios:

• High-stakes code changes — when modifications affect production systems, security-critical paths, or shared libraries
• Complex multi-step tasks — when Claude sessions involve lengthy reasoning chains where intermediate errors compound
• Team or compliance requirements — when organizational policies mandate human or automated review checkpoints
• Unfamiliar codebases — when working in new repositories where the risk of incomplete analysis is elevated

Disable the gate for rapid iteration, exploratory work, or when review latency disrupts development flow.

What Happens During a Blocked Stop

With the gate enabled, codex:stop triggers this sequence:

codex:stop

Review Response	Outcome
ALLOW:	Session ends normally
BLOCK: <reason>	Stop aborted; reason printed; user must address issues

The hook's block decision preserves session state, allowing fixes without losing context.

Summary

• The review gate is a boolean in config.stopReviewGate, defaulting to false in lib/state.mjs
• Toggle via codex:setup --enable-review-gate or --disable-review-gate, implemented in codex-companion.mjs
• The stop-review gate hook (stop-review-gate-hook.mjs) intercepts codex:stop when enabled
• Requires ALLOW: response from the Codex review task; BLOCK: prevents termination
• Monitor status through codex:status output rendered by lib/render.mjs
• Enable for safety-critical work; disable for speed-sensitive iteration

Frequently Asked Questions

How do I check if the review gate is enabled in my workspace?

Run codex:status and examine the "Review gate" line. The status report in lib/render.mjs explicitly states "enabled" or "disabled" and adds explanatory text when active. This reads directly from config.stopReviewGate in your workspace's state.json.

Can I enable the review gate for one session only?

No. The gate is a persistent workspace configuration stored via setConfig() in lib/state.mjs. You must explicitly disable it with codex:setup --disable-review-gate to turn it off. There is no session-scoped override in the current implementation.

What criteria does the stop-time review use to block a session?

The review logic is determined by plugins/codex/prompts/stop-review-gate.md. The hook passes the previous Claude response into this template, and Codex evaluates completeness, correctness, and potential risks. The specific criteria are prompt-defined rather than hardcoded—the template instructs Codex to return BLOCK: with a reason when problems exist.

Where can I find the source files for the review gate implementation?

The four key files are:

• plugins/codex/scripts/lib/state.mjs — state management
• plugins/codex/scripts/codex-companion.mjs — setup command
• plugins/codex/scripts/stop-review-gate-hook.mjs — stop interception
• plugins/codex/scripts/lib/render.mjs — status display

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