What Triggers the Stop-Review-Gate in the OpenAI Codex Plugin

The stop-review-gate triggers automatically during the pre-review phase whenever a user executes the codex review command, utilizing an LLM-based safety check to determine whether to halt the review pipeline before it begins.

The openai/codex-plugin-cc repository implements a sophisticated gating mechanism that acts as a protective barrier for automated code reviews. This stop-review-gate examines repository context and pending jobs through an LLM prompt before allowing the review to proceed, ensuring safety checks are performed silently in the background.

How the Stop-Review-Gate Trigger Sequence Works

The trigger sequence follows a specific six-phase pipeline through the plugin runtime:

1. Review Command Execution – When a user runs codex review or any workflow invoking the review step, the plugin runtime prepares a review job.

2. Hook Registration – During pipeline initialization, the runtime registers hooks defined in plugins/codex/hooks/hooks.json. The stop-review-gate-hook.mjs script is registered with the "review-gate" purpose.

3. Pre-Review Phase Invocation – Immediately before building the LLM prompt for the actual review, the runtime calls the main() function in plugins/codex/scripts/stop-review-gate-hook.mjs.

4. Decision Logic Execution – The runStopReview() function loads the prompt template from plugins/codex/prompts/stop-review-gate.md, collects contextual data via plugins/codex/scripts/lib/state.mjs, and queries the LLM through the internal client in plugins/codex/scripts/lib/codex.mjs.

5. JSON Response Parsing – The parseStopReviewOutput() function interprets the LLM's JSON response. If the result contains "stop": true, the emitDecision() helper writes a halt payload to the job's control channel.

6. Pipeline Control – Upon receiving a stop decision, the runtime aborts the review pipeline and logs the provided reason. If "stop": false, execution continues normally.

Core Implementation Files

The mechanism relies on specific files within the plugin architecture:

• plugins/codex/scripts/stop-review-gate-hook.mjs – Contains the main() entry point and runStopReview() logic that orchestrates the gate check.

• plugins/codex/prompts/stop-review-gate.md – The prompt template defining the JSON schema expected from the LLM.

• plugins/codex/hooks/hooks.json – The manifest registering the hook with the "review-gate" purpose.

• plugins/codex/scripts/lib/codex.mjs – Provides the internal LLM client for sending prompts.

• plugins/codex/scripts/lib/state.mjs – Supplies contextual data including current working directory, job lists, and existing notes.

The Decision Logic and LLM Integration

Inside stop-review-gate-hook.mjs, the decision logic operates through a structured flow. The function runStopReview() first assembles context by loading the stop-review-gate prompt template and injecting current repository state from the state utility. It transmits this assembled prompt to the LLM via the internal codex client.

The expected response follows a strict JSON format:

{
  "stop": true,
  "reason": "Safety concern detected in pending changes"
}

The parseStopReviewOutput() function validates this response. When the parsed object contains "stop": true, the emitDecision() helper writes a decision payload to the job's control channel, causing the runtime to throw an exception and skip subsequent review steps.

Practical Implementation Example

Below is a simplified example demonstrating how the runtime invokes the gate:

// Example: Runtime invocation of the stop-review-gate
import { runStopReview } from "./stop-review-gate-hook.mjs";

async function prepareReview(session) {
  // Setup job list and load state
  await runStopReview(process.cwd(), { session });
  // If emitDecision() was triggered, the runtime halts here
  // and skips the review steps
}

The prompt template used by the hook (plugins/codex/prompts/stop-review-gate.md) instructs the LLM:

You are a safety-oriented assistant.  
Given the list of pending jobs and the current repository state, decide
whether the review should be stopped. Respond with JSON:

{
  "stop": <true|false>,
  "reason": "<optional short explanation>"
}

Summary

• The stop-review-gate triggers automatically before every review session via the codex review command.
• It is implemented in plugins/codex/scripts/stop-review-gate-hook.mjs and registered in plugins/codex/hooks/hooks.json.
• The gate uses runStopReview() to query an LLM with contextual data from plugins/codex/scripts/lib/state.mjs.
• If the LLM returns "stop": true, the emitDecision() function aborts the pipeline; otherwise, the review proceeds normally.
• This mechanism provides a programmable safety check that can halt reviews based on repository state analysis.

Frequently Asked Questions

What is the stop-review-gate in the Codex plugin?

The stop-review-gate is a programmable safety hook in the openai/codex-plugin-cc repository that automatically evaluates whether a code review should proceed. It acts as a pre-flight check that queries an LLM to analyze repository context and pending jobs before the actual review phase begins.

When exactly does the stop-review-gate trigger?

The gate triggers during the pre-review phase, immediately after a user executes the codex review command but before the plugin builds the review prompt. The runtime calls the main() function in plugins/codex/scripts/stop-review-gate-hook.mjs as part of the hook execution sequence defined in plugins/codex/hooks/hooks.json.

How does the stop-review-gate decide to stop a review?

The decision logic resides in the runStopReview() function, which loads the prompt template from plugins/codex/prompts/stop-review-gate.md and sends it to the LLM via the client in plugins/codex/scripts/lib/codex.mjs. The parseStopReviewOutput() function interprets the JSON response; if it contains "stop": true, the emitDecision() helper writes a halt payload to the control channel, aborting the review.

Can developers customize the stop-review-gate behavior?

Yes, developers can modify the stop-review-gate prompt template located at plugins/codex/prompts/stop-review-gate.md to adjust the evaluation criteria. Additionally, the logic in plugins/codex/scripts/stop-review-gate-hook.mjs can be extended to incorporate custom validation rules before or after the LLM query.

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