# How the Codex Review Gate Works and When to Enable It

> Understand the Codex review gate, a safety feature stopping incomplete work before session end. Learn how it works and when to enable it in your repository for Claude sessions.

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

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) at the workspace level. According to the source code in `lib/state.mjs`, the default configuration disables the gate:

```js
// 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:

```js
// 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

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

```

**Expected output:**

```

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

```

### Disable the review gate

```bash
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

```js
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`:

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

```

### Check current status

```bash
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:

```bash
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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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