What Happens When the Review Gate Blocks a Claude Stop Operation

When the review gate blocks a Claude stop operation, the plugin intercepts the stop request, runs a Codex review of the previous Claude turn, and prevents the session from ending if issues are found.

The stop-review-gate hook in the openai/codex-plugin-cc repository adds a safety layer that reviews Claude's recent work before allowing a session to terminate. This feature ensures code quality by catching unresolved problems that might otherwise be dismissed when a user tries to exit.

How the Stop-Review-Gate Hook Intercepts Claude Stop Requests

The review gate mechanism begins with the hook defined in plugins/codex/scripts/stop-review-gate-hook.mjs. When enabled, this script automatically triggers whenever Claude receives a stop command.

The hook's primary responsibilities include:

• Launching a stop-time Codex review using the prompt from plugins/codex/prompts/stop-review-gate.md
• Spawning codex-companion.mjs to execute the review task
• Parsing Codex output to determine whether to allow or block the stop

If a Codex task is already running when the hook fires, it records this status (e.g., "Codex task <id> is still running…") before proceeding.

Parsing the Codex Review Output: ALLOW vs BLOCK

After the review task completes, the hook calls parseStopReviewOutput to examine Codex's response. The first line of output determines the outcome:

Output prefix	Result
ALLOW:	Review passes; stop proceeds normally
BLOCK:	Issues remain; stop is prevented

When Codex returns BLOCK:, the hook constructs and emits a blocking decision. The relevant implementation from lines 66-71 of stop-review-gate-hook.mjs:

emitDecision({
  decision: "block",
  reason: <explanatory-message>
});

This explicit "block" decision is what prevents Claude from terminating the session.

What Claude Displays When a Stop Is Blocked

Emitting a block decision causes Claude's stop-handler to halt the session termination. The user sees the reason supplied by the hook—typically formatted as:

"Codex stop-time review found issues that still need fixes before ending the session: ..."

At this point, the user must either address the reported problems or bypass the gate using flags like --disable-review-gate.

Graceful Degradation When Codex Is Unavailable

The hook includes fallback logic for environments where Codex isn't configured. In this case:

• The hook logs a notification about Codex being unavailable
• The stop proceeds without blocking
• No review is performed

This ensures the review gate doesn't create a hard dependency that would prevent normal Claude operation.

Example: Enabling and Triggering the Review Gate

Enable the review gate with the setup command:

/codex:setup --enable-review-gate

When you subsequently attempt to end a Claude session, the hook runs automatically. If issues are detected, Claude displays the blocking message and refuses to terminate until resolved.

The minimal blocking path from the source:

// Excerpt from stop-review-gate-hook.mjs
if (!review.ok) {
  emitDecision({
    decision: "block",
    reason: runningTaskNote ? `${runningTaskNote} ${review.reason}` : review.reason
  });
  return;
}

Key Source Files

• plugins/codex/scripts/stop-review-gate-hook.mjs — Core hook implementation that runs stop-time reviews and emits block decisions
• plugins/codex/scripts/lib/prompts.mjs — Loads the stop-review prompt template
• plugins/codex/scripts/codex-companion.mjs — Executes the actual Codex review task
• plugins/codex/prompts/stop-review-gate.md — Defines the review criteria and instructions
• README.md — Documents enable/disable configuration for the review gate

Summary

• The stop-review-gate hook intercepts Claude stop commands when the review gate is enabled
• It spawns codex-companion.mjs to run a stop-time review of the previous Claude turn
• Codex output starting with BLOCK: triggers emitDecision({ decision: "block", ... })
• Claude surfaces the blocking reason and prevents session termination
• If Codex is unavailable, the hook logs a note and allows the stop to proceed
• Users can bypass the gate with --disable-review-gate when needed

Frequently Asked Questions

How do I enable the review gate in codex-plugin-cc?

Run /codex:setup --enable-review-gate in your Claude session. This configures the stop-review-gate hook to intercept future stop commands. The setting persists across sessions according to the plugin's configuration storage.

What prompt does Codex use for stop-time reviews?

The review uses plugins/codex/prompts/stop-review-gate.md, loaded via plugins/codex/scripts/lib/prompts.mjs. This prompt instructs Codex to evaluate the previous Claude turn for unresolved issues, security concerns, or incomplete tasks that should block session termination.

Can I bypass a blocked stop operation?

Yes. The review gate can be disabled at setup time or bypassed with flags like --disable-review-gate. This allows immediate session termination when you're confident the Codex review is overly cautious or when working in trusted environments.

What happens if Codex is slow or hangs during a stop review?

The hook checks for running Codex tasks and records their status. While the source doesn't show explicit timeout handling in the analyzed lines, the note-taking behavior suggests the system tracks task state to inform the user without indefinite blocking.

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