# How the Stop‑Time Review Gate Works and When to Enable It

> Learn how the stop-time review gate works in Codex Plugin CC. Automatically review code changes before session end, blocking completions with issues. Enable it for cleaner code.

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

---

**The stop‑time review gate is a hook that automatically runs a final review of code changes before a Codex session ends, blocking completion if issues are found.** It ensures Claude has one last chance to catch problems in the previous turn before the session terminates.

In the `openai/codex-plugin-cc` repository, this gate acts as a safety mechanism for critical code changes. Enabled via a simple configuration flag, it integrates into the Codex runtime lifecycle and can prevent problematic sessions from finishing undetected. This guide explains the execution flow, configuration options, and practical scenarios for enabling the gate.

## What the Stop‑Time Review Gate Does

The stop‑time review gate intercepts the session termination point in Codex. When active, it pauses closure to run a focused review of **only the code edits made in the previous Claude turn**.

The gate serves a single purpose: catch regressions, bugs, or incomplete work before a session is marked complete. It does not review the entire codebase—just the delta from the most recent turn.

## Configuration and Enablement

The gate is controlled by the `stopReviewGate` boolean in your workspace configuration. This flag lives in the state management layer at `plugins/codex/scripts/lib/state.mjs`.

To enable the gate, set the flag in your `.codexrc` or equivalent workspace config:

```json
{
  "stopReviewGate": true
}

```

When `false` or undefined, the hook exits early after logging any running task note (lines 54‑57 in `plugins/codex/scripts/stop-review-gate-hook.mjs`).

## Execution Flow of the Review Hook

The core implementation resides in `plugins/codex/scripts/stop-review-gate-hook.mjs`. The hook follows this sequence:

1. **Read hook input** – parses the JSON payload from the Codex runtime via `readHookInput`
2. **Resolve workspace** – determines the project root and loads configuration via `getConfig`
3. **Check prerequisites** – validates that Codex is set up for reviews; emits a helper note via `buildSetupNote` if not (lines 59‑66)
4. **Build review prompt** – loads [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md) and interpolates the previous Claude response via `buildStopReviewPrompt` (lines 48‑57)
5. **Execute review task** – spawns `codex-companion.mjs` with a **15‑minute timeout** (`STOP_REVIEW_TIMEOUT_MS`, line 16)
6. **Parse and decide** – interprets the companion output and emits allow/block decision

### Manual Invocation for Debugging

You can trigger the hook manually to test configuration:

```bash
echo '{"cwd":"/my/project","session_id":"abc123","last_assistant_message":"..."}' \
| node plugins/codex/scripts/stop-review-gate-hook.mjs

```

## How Review Results Are Interpreted

The companion task must return a compact, single‑line verdict starting with either `ALLOW:` or `BLOCK:`. The parser `parseStopReviewOutput` (lines 69‑95) handles this:

- **`ALLOW:`** → Session finishes normally
- **`BLOCK:`** → Hook emits a decision payload with `"decision": "block"` and a descriptive reason via `emitDecision` (lines 68‑72)

The implementation enforces strict formatting to minimize parsing overhead and ensure deterministic outcomes.

## What the Review Prompt Asks

The prompt 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) (lines 1‑26) instructs:

> "Run a stop‑gate review of the previous Claude turn."

Key constraints hardcoded in the prompt:

- Review limited to **code edits from that turn only**
- Return a **single‑line verdict**: `ALLOW:` or `BLOCK:`
- Reason required when blocking

This narrow scope keeps the 15‑minute timeout feasible while maintaining focus on immediate changes.

## When to Enable the Stop‑Time Review Gate

### Enable When:

- **Production‑like environments** – Any codebase where errors carry significant cost
- **Critical code paths** – Changes to authentication, payments, or data integrity layers
- **Multi‑turn sessions** – Long conversations where context drift increases error risk
- **Team workflows** – Shared repositories where session completion signals review readiness

### Disable When:

- **Rapid prototyping** – Early exploration where speed outweighs safety
- **Trivial edits** – Documentation, comments, or cosmetic changes
- **Resource constraints** – The 15‑minute review overhead is unacceptable

### Decision Logic Example

```js
// Simplified snippet from the hook's block path
if (!review.ok) {
  emitDecision({
    decision: "block",
    reason: review.reason
  });
}

```

The gate automatically blocks when a previous turn performed edits and the review surfaces blocking issues. Otherwise, it permits normal session completion.

## Key Files Reference

| File | Role |
|------|------|
| `plugins/codex/scripts/stop-review-gate-hook.mjs` | Main hook implementation with decision logic |
| [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md) | Review prompt template with scope constraints |
| `plugins/codex/scripts/lib/state.mjs` | Workspace configuration loader including `stopReviewGate` |
| `plugins/codex/scripts/lib/codex.mjs` | Codex availability checker |
| `plugins/codex/scripts/codex-companion.mjs` | Review task executor with 15‑minute timeout |

## Summary

- The **stop‑time review gate** is a termination hook that reviews only the previous turn's code edits
- Enable via **`stopReviewGate: true`** in workspace configuration
- The hook runs **`codex-companion.mjs`** with a **15‑minute timeout** and expects `ALLOW:` or `BLOCK:` responses
- **Enable** for production safety; **disable** for rapid prototyping where overhead is unwelcome
- Gate blocks session completion only when the review explicitly finds blocking issues

## Frequently Asked Questions

### What happens if the review times out?

The hook enforces a hard timeout of **15 minutes** (`STOP_REVIEW_TIMEOUT_MS`). If the companion task exceeds this limit, the hook treats the review as inconclusive and typically logs the timeout without blocking—though behavior may vary based on wrapper error handling.

### Can I customize the review prompt?

The prompt template lives at [`plugins/codex/prompts/stop-review-gate.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/prompts/stop-review-gate.md). You can modify this file directly, but changes affect all sessions using that workspace. The template uses simple interpolation for the previous Claude response.

### Does the gate review multiple turns?

No. The scope is intentionally limited to **the single previous Claude turn** only. This constraint keeps reviews fast and focused, as defined in the prompt template lines 1‑26.

### Is the stop‑time gate related to other review gates?

The stop‑time gate is distinct from per‑turn or pre‑commit gates. It serves specifically as a **final checkpoint before session termination**, complementing earlier review stages rather than replacing them.