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

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:

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

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

// 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	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. 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.

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