# Review Gate Feature in the Codex Plugin: How It Blocks Claude Stop Commands

> Discover the Codex plugin review gate feature. Learn how it automatically reviews and blocks Claude stop commands, ensuring uninterrupted sessions. Read our in-depth analysis.

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

---

**The review gate feature intercepts Claude's stop command by running an automated safety review that emits a `block` decision, preventing session termination until the review explicitly returns `ALLOW` or the gate is disabled.**

The **review gate feature** in the `openai/codex-plugin-cc` repository adds a mandatory approval step before Claude can end a conversation. When enabled via the `stopReviewGate` configuration flag, the plugin injects a hook into the stop command pipeline that evaluates the session's final state using automated Codex analysis before allowing termination.

## Configuring the Review Gate

The review gate is controlled by the `stopReviewGate` boolean stored in [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) under `config.stopReviewGate` (default: `false`). You toggle this setting using the `/codex:setup` command with explicit flags.

To enable the gate:

```bash
!codex setup --enable-review-gate

```

To disable the gate:

```bash
!codex setup --disable-review-gate

```

Internally, these commands invoke `setConfig(workspaceRoot, "stopReviewGate", true)` or `false` in `plugins/codex/scripts/codex-companion.mjs` (lines 29‑34). This writes the value to persistent storage via `plugins/codex/scripts/lib/state.mjs`, ensuring the setting survives across sessions.

## Intercepting Stop Commands with the Hook

When a user issues a stop request, the **stop-review-gate-hook** (`plugins/codex/scripts/stop-review-gate-hook.mjs`) executes before Claude terminates the session. The hook reads the incoming JSON payload, resolves the `workspaceRoot`, and retrieves the current configuration.

If `config.stopReviewGate` is disabled, the hook logs and exits without interference (lines 54‑57). When enabled, the hook builds a review prompt using the template at [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md) and spawns a synchronous review task:

```javascript
const result = spawnSync(process.execPath,
    [scriptPath, "task", "--json", prompt], { … });

```

This execution at lines 99‑106 of the hook script triggers the **stop-time Codex review**, analyzing the conversation context to determine if termination is safe.

## Parsing the Review Decision

The hook parses the review task's stdout using `parseStopReviewOutput` (lines 80‑95). This function examines the first line of output to determine the verdict:

- **`ALLOW:`** → Review passes, permitting the stop command to proceed
- **`BLOCK:`** → Review fails; the function extracts the reason string after the colon
- **Other** → Treated as an unexpected failure, defaulting to a block state

The parsing logic strictly differentiates between explicit permission and denial based on the prefix format, ensuring no ambiguous states pass through to the runtime.

## Blocking Mechanism Implementation

When the review returns a non-allow verdict, the hook constructs a block decision JSON object:

```javascript
emitDecision({
  decision: "block",
  reason: review.reason 
});

```

This executes at lines 66‑71 of `stop-review-gate-hook.mjs`. The `emitDecision` function outputs a structured JSON response that the Codex Plugin runtime consumes. When the runtime detects `decision: "block"`, it prevents Claude from terminating the session and surfaces the explanatory reason to the user.

The block persists until the user resolves the flagged issue or disables the review gate via configuration. Additionally, `plugins/codex/scripts/lib/job-control.mjs` marks jobs requiring review when the gate is active, providing visibility into which sessions are under enforcement.

## Summary

- The **review gate feature** adds a mandatory safety review before Claude can execute a stop command.
- Configuration persists in [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) via `setConfig` in `codex-companion.mjs`, toggled through `--enable-review-gate` or `--disable-review-gate` flags.
- The **stop-review-gate-hook** intercepts every stop request and runs a Codex review task when enabled at the workspace level.
- Reviews parse output for `ALLOW:` or `BLOCK:` prefixes in `parseStopReviewOutput`; any non-allow result triggers `emitDecision` with `decision: "block"`.
- The block prevents session termination until explicitly cleared or the gate is disabled by the user.

## Frequently Asked Questions

### How do I know if the review gate is blocking my stop command?

When blocked, the plugin emits a JSON decision object containing `decision: "block"` and a specific reason string extracted from the review output. This surfaces in the interface as a termination prevention message with details about why the review flagged the session, such as unfinished tasks or safety concerns.

### Can the review gate be enabled per workspace or only globally?

The configuration is scoped to a `workspaceRoot` via `setConfig(workspaceRoot, "stopReviewGate", value)`, allowing individual workspaces to maintain separate gate states. Each workspace's [`state.json`](https://github.com/openai/codex-plugin-cc/blob/main/state.json) stores its own boolean flag independently, so you can enforce the gate on specific projects while leaving others unrestricted.

### What happens if the review task crashes or returns unexpected output?

The `parseStopReviewOutput` function in `stop-review-gate-hook.mjs` treats any output not starting with `ALLOW:` or `BLOCK:` as an unexpected failure, which defaults to a blocking state. This fail-safe design ensures that malformed reviews, process errors, or crashes prevent potentially unsafe session terminations rather than allowing them to slip through unchecked.

### Where can I customize the prompt used for stop-time reviews?

The review prompt template lives in [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md). Modifying this file changes the instructions and context provided to Codex during the stop-time review, although the parsing logic in the hook still expects `ALLOW:` or `BLOCK:` prefixes in the response to determine the final decision.