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

> Discover what triggers the stop-review-gate in the OpenAI Codex plugin. Learn how automatic safety checks halt the review pipeline before it starts.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-16

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md)** – The prompt template defining the JSON schema expected from the LLM.

- **[`plugins/codex/hooks/hooks.json`](https://github.com/openai/codex-plugin-cc/blob/main/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:

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

```javascript
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md)) instructs the LLM:

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