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

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

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

{
  "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:

{
  "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:

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 – 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, 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.

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