# What Is the Stop-Time Review Gate in the OpenAI Codex Plugin?

> Understand the stop-time review gate in the OpenAI Codex plugin. Learn when to enable this safety checkpoint for critical issue detection before session completion.

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

---

**The stop-time review gate is an optional safety checkpoint that runs a Codex-driven review of the immediately preceding Claude turn before a session is allowed to finish, blocking completion if critical issues are detected.**

The **stop-time review gate** is a configurable safety mechanism in the `openai/codex-plugin-cc` repository that prevents potentially problematic code changes from being finalized at session end. When enabled, this feature intercepts the session termination process to validate the last assistant response using a dedicated Codex review prompt. This architectural safeguard ensures that automated edits made by Claude undergo a final validation step before the workspace state is committed.

## How the Stop-Time Review Gate Works

The gate operates as a **pre-termination hook** that orchestrates a multi-step validation pipeline. When `config.stopReviewGate` is set to `true` in the plugin state, the system activates a controlled review workflow before allowing the session to close.

### Configuration and State Management

The gate's activation state persists in the plugin's **state JSON** managed by `state.mjs`. By default, the configuration defines `stopReviewGate: false`, requiring explicit opt-in via the `/codex:setup` command or direct configuration updates through `setConfig`.

### Review Execution Flow

When enabled, the hook performs the following sequence:

1. **Collects the last Claude assistant message** containing the final output and any edits performed.
2. **Builds a review prompt** by loading the template from [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md) via the `loadPromptTemplate()` utility in `prompts.mjs`.
3. **Spawns the Codex companion** (`codex-companion.mjs`) as a child process with a **15-minute timeout** to execute the review task.
4. **Parses the compact response**—if the first line begins with `ALLOW:`, the session proceeds; if it begins with `BLOCK:`, the hook emits a decision object that prevents session termination and provides a specific reason.
5. **Handles disabled states** by logging a note and exiting cleanly when the gate is off or Codex is not workspace-configured.

## Enabling the Stop-Time Review Gate

Users can activate this safety feature through the command-line interface or programmatic configuration updates.

To enable via CLI:

```bash

# Inside a Codex-enabled workspace

codex config set stopReviewGate true

```

This command updates the JSON configuration stored by `state.mjs`, immediately activating the gate for subsequent sessions.

## Programmatic Integration and Hook Interface

The stop-time review gate functions as a standalone hook script that accepts structured input and returns deterministic output decisions.

### Input Payload Structure

The hook at `plugins/codex/scripts/stop-review-gate-hook.mjs` expects a JSON payload via stdin:

```json
{
  "cwd": "/path/to/project",
  "last_assistant_message": "Added new API endpoint …",
  "session_id": "abc123"
}

```

### Output Decision Format

When the gate blocks a session, it writes a JSON decision object to stdout:

```json
{
  "decision": "block",
  "reason": "Codex stop-time review found issues ... "
}

```

If allowed, the hook exits silently with no stdout output.

### Using the Hook Programmatically

Integrate the gate into custom workflows using Node.js child process spawning:

```javascript
import { spawnSync } from "child_process";
import path from "path";

const hookPath = path.join(__dirname, "plugins/codex/scripts/stop-review-gate-hook.mjs");
const payload = JSON.stringify({ 
  last_assistant_message: "...", 
  cwd: process.cwd() 
});

const result = spawnSync("node", [hookPath], {
  input: payload,
  encoding: "utf8"
});

if (result.stdout) {
  const decision = JSON.parse(result.stdout);
  console.log(`Gate decision: ${decision.decision}`);
}

```

## Core Implementation Files

The stop-time review gate spans several critical files in the `openai/codex-plugin-cc` repository:

- **`plugins/codex/scripts/stop-review-gate-hook.mjs`** – Main orchestration hook that manages the review lifecycle and decision parsing.
- **`plugins/codex/scripts/lib/state.mjs`** – Persistent storage for the `stopReviewGate` configuration flag and session metadata.
- **[`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md)** – The prompt template instructing Codex to evaluate only the previous Claude turn's code changes.
- **`plugins/codex/scripts/lib/prompts.mjs`** – Template loading and interpolation utilities used by `buildStopReviewPrompt()`.
- **`plugins/codex/scripts/codex-companion.mjs`** – Child process executable that runs the actual Codex review task with a 15-minute timeout.

## Summary

- The **stop-time review gate** provides a final validation checkpoint before session termination in the Codex plugin.
- Activation requires setting `config.stopReviewGate = true` via CLI (`codex config set`) or direct state manipulation through `setConfig`.
- The gate specifically reviews only the **last Claude assistant message** for code changes, ignoring conversational content.
- **Binary decision parsing** relies on `ALLOW:` or `BLOCK:` prefixes in Codex's compact response format.
- A **15-minute timeout** protects against hanging review processes when spawning `codex-companion.mjs`.
- When disabled or misconfigured, the gate fails open, allowing sessions to terminate without interruption.

## Frequently Asked Questions

### What triggers the stop-time review gate to run?

The gate triggers automatically when a session attempts to terminate and `config.stopReviewGate` is enabled in the plugin state. It specifically activates only when Codex is properly configured for the workspace and a valid `last_assistant_message` exists in the session context.

### How does the gate determine whether to allow or block a session?

The gate parses the first line of Codex's response for mandatory prefixes. Lines beginning with `ALLOW:` permit immediate session closure, while `BLOCK:` prefixes trigger a blocking decision object containing the rejection reason. This parsing logic is implemented in the `parseStopReviewOutput` function within the hook script.

### Can I customize the review prompt used by the stop-time review gate?

Yes. The gate loads its evaluation criteria from [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md), which you can modify to adjust review strictness, focus areas, or output formatting requirements. The `loadPromptTemplate()` function in `prompts.mjs` handles template interpolation with the `CLAUDE_RESPONSE_BLOCK` variable.

### What happens if Codex is not configured for the workspace?

If Codex lacks proper workspace configuration, the gate logs a diagnostic note and exits cleanly without blocking the session. This fail-open behavior ensures that missing setup does not prevent legitimate session terminations, though it bypasses the safety check entirely.