How the Codex Review Gate Works: Enable, Disable, and Configure Stop-Time Safety Checks

The review gate is a boolean safety flag stored in state.json that forces Codex to run a final review before ending a session; enable it with /codex:setup --enable-review-gate and disable it with --disable-review-gate.

In the openai/codex-plugin-cc repository, the review gate acts as a critical safety mechanism that intercepts session termination to ensure code quality. When activated, this feature prevents a Claude session from ending until a final "stop-time" review validates that no critical issues remain. Understanding how to configure and toggle this gate is essential for teams that want automated quality checks without sacrificing workflow flexibility.

What Is the Codex Review Gate?

The review gate is a configurable safety check that executes automatically when you invoke codex:stop. Instead of immediately terminating the session, the system pauses to run a final review task against the current context. According to the source code in plugins/codex/scripts/stop-review-gate-hook.mjs, the hook only activates when the stopReviewGate configuration value is set to true. If the review detects problems, it returns a BLOCK: decision that prevents session termination until the issues are resolved.

Where the Review Gate Configuration Is Stored

Default State and Configuration File

The review gate state persists in the plugin's workspace-specific state file. In plugins/codex/scripts/lib/state.mjs, the default configuration explicitly sets stopReviewGate: false, meaning the gate is disabled out-of-the-box.

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

The configuration is read and written via helper functions getConfig(workspaceRoot) and setConfig(workspaceRoot, key, value). These functions abstract access to the underlying state.json file, ensuring thread-safe updates to the workspace configuration.

How to Enable or Disable the Review Gate

Using the Setup Command

Toggle the review gate using the /codex:setup command with explicit flags. The command parser in plugins/codex/scripts/codex-companion.mjs handles two specific options:

• --enable-review-gate: Sets stopReviewGate to true
• --disable-review-gate: Sets stopReviewGate to false

// 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);
}

Each operation appends the action to an actionsTaken array, which appears in the final setup report to confirm the change.

Verifying the Current State

Check the gate status anytime using codex:status. The rendering logic in plugins/codex/scripts/lib/render.mjs displays the current state and appends a descriptive note when the gate is active:

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

When enabled, the status report includes the additional line: "The stop‑time review gate is enabled."

Runtime Behavior When the Gate Is Active

The Stop-Review Hook Execution Flow

When you execute codex:stop, the system invokes plugins/codex/scripts/stop-review-gate-hook.mjs. The hook follows this strict execution path:

1. Configuration Check: Loads the workspace config using getConfig(workspaceRoot)
2. Early Exit: If config.stopReviewGate is false, logs any running task note and returns immediately
3. Setup Verification: Calls buildSetupNote to confirm Codex is properly configured; aborts with a hint if not
4. Review Execution: Invokes runStopReview to launch the companion script with the stop-review-gate prompt template
5. Decision Parsing: Evaluates the review task response for ALLOW: or BLOCK: directives

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

ALLOW vs BLOCK Responses

The review task must return a specific string prefix to determine the outcome:

• ALLOW: – The session terminates normally
• BLOCK: <reason> – The hook emits a block decision, prints the reason, and aborts the stop command, forcing you to address the reported issues before ending the session

The prompt template located at plugins/codex/prompts/stop-review-gate.md defines the expected response format and evaluation criteria for this final safety check.

Practical Code Examples

Enable the Review Gate

# Inside a workspace where the plugin is installed

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.

Check Current Gate Status

codex:status

Output when enabled:

# Codex Status

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

Output when disabled:

# Codex Status

Session runtime: …
Review gate: disabled
…

Stop Command Behavior with Gate Enabled

codex:stop

• If the review returns ALLOW: → Session ends normally
• If the review returns BLOCK: security vulnerability detected → Stop aborts, displaying the blocker reason

Summary

• The review gate is a boolean configuration value stopReviewGate stored in the plugin's state.json via lib/state.mjs
• Default state is false (disabled) to allow immediate session termination
• Enable with /codex:setup --enable-review-gate and disable with --disable-review-gate, both implemented in codex-companion.mjs
• When active, stop-review-gate-hook.mjs intercepts codex:stop to run a final review using the prompt template in plugins/codex/prompts/stop-review-gate.md
• The gate requires an explicit ALLOW: response to terminate; any BLOCK: response prevents session closure
• Current status is visible via codex:status rendered by lib/render.mjs

Frequently Asked Questions

What is the default state of the review gate?

The review gate is disabled by default. In plugins/codex/scripts/lib/state.mjs, the default configuration object sets stopReviewGate: false, allowing sessions to terminate immediately without a stop-time review.

Can I toggle the review gate without using the setup command?

While the /codex:setup command is the intended interface, you could manually edit the state.json file in the workspace root or call the setConfig(workspaceRoot, "stopReviewGate", boolean) function directly from lib/state.mjs. However, using the command-line flags ensures proper validation and logging to the actionsTaken array.

What happens if the review task fails or returns an unexpected response?

If the review task crashes, times out, or returns a malformed response (anything other than ALLOW:), the hook treats it as a blocking event. The stop-review-gate-hook.mjs logic defaults to safety: unless it receives an explicit ALLOW: prefix, the session stop will be aborted and the user will see the error or partial response output.

Is the review gate configuration workspace-specific?

Yes. The configuration is scoped to individual workspaces through the workspaceRoot parameter used in getConfig and setConfig calls. Each workspace maintains its own state.json file, allowing you to enable the review gate in production repositories while keeping it disabled in experimental or test environments.

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