Stop Review Gate Mechanism in the OpenAI Codex Plugin: Integration with Claude's Lifecycle

The stop review gate is a safety hook that automatically reviews code changes at the end of each Claude turn and emits an ALLOW or BLOCK decision to determine whether the session may terminate.

The stop review gate mechanism in the openai/codex-plugin-cc repository provides an automated code review checkpoint that intercepts Claude's session termination. This safety feature ensures that any code modifications produced during a Claude turn are vetted by Codex before the session officially closes. Understanding how this mechanism integrates with Claude's lifecycle is essential for developers configuring automated review pipelines.

What Is the Stop Review Gate?

The stop review gate is a deterministic checkpoint implemented in stop-review-gate-hook.mjs that runs as part of Claude's "stop-gate" step. Its purpose is to automatically perform a brief Codex-driven review of the code changes produced by the just-finished Claude turn. The gate decides whether the session may be terminated (ALLOW) or must be paused (BLOCK) based on the review outcome.

When active, the hook receives a JSON payload on STDIN containing the previous Claude message (last_assistant_message) and the current working directory (cwd). It then orchestrates a review task that must complete within 15 minutes (STOP_REVIEW_TIMEOUT_MS) before allowing the session to proceed toward termination.

How the Stop Review Gate Processes Code Changes

The mechanism follows a six-step pipeline to evaluate code changes before session termination.

Triggering the Hook via STDIN

Claude invokes the stop-review-gate-hook.mjs script as part of the stop-gate step that occurs just before a session would finish. The hook receives input data through standard input in the following format:

{
  "session_id": "abc123",
  "cwd": "/path/to/repo",
  "last_assistant_message": "Implemented foo() and added tests."
}

This payload provides the context necessary to associate the review with the correct session and working directory.

Configuration Validation with getConfig

Before executing the review, the hook loads the repository-wide configuration via getConfig from state.mjs. If config.stopReviewGate is disabled, the hook simply logs any running Codex task and returns immediately, allowing the session to end without a review.

This configuration check ensures that the gate respects user preferences and can be bypassed in environments where automated review is not required.

Building the Review Prompt

The hook constructs the review prompt by loading the stop-review-gate.md template and interpolating the previous Claude response into the {{CLAUDE_RESPONSE_BLOCK}} placeholder. The template instructs Codex to focus exclusively on code-changing statements from the prior turn and to emit a compact decision line using the ALLOW: or BLOCK: format.

This targeted approach ensures that the review concentrates on actual code modifications rather than conversational text.

Executing the Codex Review Task

The script launches codex-companion.mjs as a child process using spawnSync with the prepared prompt. The operation waits up to 15 minutes for completion, after which the child returns a JSON payload. The rawOutput field contains the textual answer from Codex.

During this phase, the gate leverages the Codex broker managed by broker-lifecycle.mjs to execute the review task asynchronously while blocking the session termination thread.

Parsing ALLOW and BLOCK Decisions

The parseStopReviewOutput function examines the first line of Codex's answer to determine the gate decision:

• ALLOW: → The gate passes, permitting the session to finish normally.
• BLOCK: → The gate blocks the session and returns the supplied reason.

Any missing, malformed, or timed-out output is treated as a failure, causing the gate to emit a block decision with a helpful error message.

Emitting the Decision to STDOUT

On a block decision, the script writes a JSON object to STDOUT in the following format:

{
  "decision": "block",
  "reason": "Codex stop-time review found issues that still need fixes before ending the session: Missing error handling in foo()."
}

On success, the script only logs any still-running Codex jobs and allows the normal Claude shutdown to proceed without emitting additional output.

Integration with Claude's Session Lifecycle

The stop review gate integrates deeply with Claude's lifecycle through the session-lifecycle-hook.mjs handler, which manages two critical events.

Session Lifecycle Hook Events

The session lifecycle hook handles SessionStart and SessionEnd events:

• SessionStart: Records the session ID and transcript path in the environment so that subsequent hooks, including the stop-review gate, can associate jobs with the correct session.
• SessionEnd: Shuts down the Codex broker, terminates any still-running Codex jobs, and clears session-specific state.

The Final Checkpoint Before Termination

Before the session is finally torn down, the stop-review-gate-hook is invoked via the Codex runtime to decide whether the session may close. If the gate returns BLOCK, the session end is aborted, giving the user a chance to address the highlighted issues.

Thus, the stop review gate serves as the final checkpoint in Claude's lifecycle: it runs after Claude has produced its last turn but before the session is officially terminated, ensuring that any code modifications are vetted by Codex before the session concludes.

Key Implementation Files

The stop review gate mechanism relies on the following components in the openai/codex-plugin-cc repository:

• stop-review-gate-hook.mjs: Core implementation that reads input, builds prompts, runs the Codex task, and parses results.
• session-lifecycle-hook.mjs: Manages Claude session start and end events; invokes the stop review gate as the final step before session termination.
• stop-review-gate.md: Prompt template instructing Codex how to perform the review and format its compact decision.
• state.mjs: Provides getConfig and job-listing utilities used to respect the stopReviewGate configuration flag.
• codex-companion.mjs: Runs the actual Codex review task; invoked by the gate via spawnSync.
• broker-lifecycle.mjs: Handles starting and stopping the Codex broker; cleanup is performed during SessionEnd.

Summary

The stop review gate mechanism provides a critical safety layer for Claude sessions by enforcing automated code reviews before termination:

• It acts as a final checkpoint that intercepts session termination via stop-review-gate-hook.mjs.
• The gate evaluates code changes using the stop-review-gate.md template and Codex review tasks.
• It supports ALLOW and BLOCK decisions, with the latter preventing session closure when issues are detected.
• Configuration via getConfig allows users to enable or disable the gate per repository.
• Integration with session-lifecycle-hook.mjs ensures the gate runs atomically between Claude's final turn and session cleanup.

Frequently Asked Questions

What happens if the stop review gate times out?

If the Codex review task exceeds the 15-minute timeout (STOP_REVIEW_TIMEOUT_MS), the gate treats the failure as a blocking condition. The parseStopReviewOutput function emits a block decision with a descriptive message explaining that the review timed out, preventing the session from closing until the issue is resolved or the configuration is adjusted.

How do I disable the stop review gate?

You can disable the gate by setting stopReviewGate to false in your repository configuration. When getConfig detects this flag, the hook in stop-review-gate-hook.mjs logs any running Codex tasks and returns immediately without invoking the review process, allowing sessions to terminate without automated review.

What is the difference between ALLOW and BLOCK decisions?

An ALLOW decision permits the Claude session to terminate normally, indicating that Codex found no blocking issues with the code changes. A BLOCK decision aborts the session termination, returning a JSON object with a specific reason (such as missing error handling or syntax issues) that must be addressed before the session can close.

Where does the stop review gate fit in Claude's lifecycle?

The stop review gate operates as the final checkpoint in the lifecycle managed by session-lifecycle-hook.mjs. It executes after Claude produces its last assistant message but before the SessionEnd event completes and the Codex broker shuts down. This positioning ensures that code is reviewed while the session context is still active and can be modified if the gate blocks termination.

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