How the Stop Hook Integrates with Claude Code in OpenAI’s Codex Plugin

The stop hook integrates with Claude Code by automatically registering a post-turn callback that injects a mandatory review task, ensuring every generated artifact is vetted before subsequent automation proceeds.

The stop-review-gate hook in the openai/codex-plugin-cc repository creates a critical safety checkpoint within Claude Code workflows. This integration intercepts the session transcript after each assistant turn, extracts the generated content, and forces a review cycle before the next command executes. By plugging into the Codex plugin’s lifecycle, the hook guarantees deterministic validation of AI-generated code.

Hook Registration and Lifecycle Management

The integration begins with explicit registration in the plugin manifest. The hook is listed in plugins/codex/hooks/hooks.json, where the Codex plugin loads all available hooks during initialization. When Claude Code starts a session, the plugin iterates through this registry and attaches the stop-review-gate script to run automatically after each turn completes.

This registration mechanism ensures the hook executes consistently without manual intervention, creating a persistent gate between Claude’s response generation and the next user or system command.

Detecting the Previous Turn

The core logic resides in plugins/codex/scripts/stop-review-gate-hook.mjs, which inspects the current Claude session state to identify the last assistant message. The script accesses the session transcript via state.lastTurnStart.prompt and extracts the assistant’s final response from the previous turn.

At line 19, the script defines a constant marker that signals the review requirement:

// Line 19 of stop-review-gate-hook.mjs
const STOP_GATE_MARKER = "Run a stop‑gate review of the previous Claude turn.";

At line 52, the hook constructs the review prompt by concatenating this marker with the extracted content:

// Line 52 - Building the review context
const reviewPrompt = `Previous Claude response:\n${assistantLastMessage}`;

This constructed payload preserves the full context of the generated artifact, ensuring the subsequent review examines the exact output produced by Claude.

Creating the Review Task

Once the previous turn is captured, the hook creates a new task using the same internal API that powers the standard review command. The task payload contains two critical elements:

1. The constructed prompt combining the marker and the previous assistant message
2. A special stop‑gate flag that downstream components recognize as a mandatory blocking step

This task is injected into the queue with highest priority, ensuring it surfaces before any subsequent automation commands can execute. The stop‑gate flag distinguishes this review from optional user-generated reviews, enforcing that Claude Code cannot proceed until the gate clears.

Claude Code Session Handling

On the Claude Code side, the companion script in plugins/codex/scripts/codex-companion.mjs manages the review lifecycle. The function filterJobsForCurrentClaudeSession (defined at line 298) ensures session isolation by filtering the task queue to show only jobs belonging to the current Claude session.

At line 73, the companion matches the stop-gate marker to trigger the specialized review flow:

// Line 73 of codex-companion.mjs - Matching the stop-gate marker
if (task.metadata.marker === "Run a stop‑gate review of the previous Claude turn.") {
  // Trigger stop-gate review workflow
}

When the companion identifies a stop-gate task, it performs two critical operations:

1. Imports the session context using the transfer function (lines 618‑626), which synchronizes the Claude session state into Codex
2. Posts a summary notification at line 544 stating "Stop‑gate review of previous Claude turn", alerting the user that a mandatory review is in progress

// Lines 618-626 - Session transfer logic
async function transfer(sessionId) {
  const session = await codexClient.importSession(sessionId);
  return session.sync();
}

// Line 544 - User notification
console.log("Stop‑gate review of previous Claude turn");

User Workflow and Safety Guarantees

After the hook executes, Claude Code automatically surfaces the review task within the user interface. The review presents the previous turn’s content with options to approve, request changes, or reject the output. Because the hook inserts this review task before the next command processes, the workflow maintains strict determinism—no subsequent automation can execute against unvetted code.

This tight coupling between the hook’s task creation and the companion’s session filtering ensures that every generated artifact undergoes Claude’s examination before the conversation continues.

Summary

• The stop hook registers in plugins/codex/hooks/hooks.json to execute after every Claude turn.
• It extracts the last assistant message from state.lastTurnStart.prompt and constructs a review payload at line 52 of the hook script.
• The companion’s filterJobsForCurrentClaudeSession function (line 298) isolates reviews to the correct session.
• The transfer function (lines 618‑626) imports Claude sessions into Codex for review.
• This integration guarantees deterministic safety by blocking subsequent commands until Claude reviews the previous turn.

Frequently Asked Questions

How does the stop hook know which Claude session to monitor?

The hook accesses the current session state through state.lastTurnStart.prompt, which contains the transcript of the active Claude session. The companion script then uses filterJobsForCurrentClaudeSession to ensure the review task appears only for the session that generated it, preventing cross-contamination between multiple concurrent Claude Code instances.

What happens if the stop hook fails to create a review task?

If the hook fails to inject the review task, the stop‑gate flag will not be present in the task queue, and the Claude Code companion will not trigger the blocking review flow at line 73. This would cause the system to proceed to the next command without vetting, which is why the hook script includes error handling to ensure the marker constant is always injected when the transcript is accessible.

Can the stop hook be disabled or bypassed?

The hook can be disabled by removing its entry from plugins/codex/hooks/hooks.json before starting the Codex plugin. However, because the hook creates tasks with a specific stop‑gate marker that the companion expects at line 73, bypassing the hook would require also modifying the companion script to ignore the missing marker check, as the system is designed to enforce the review gate by default.

Where does the actual review logic execute in Claude Code?

The review logic executes in plugins/codex/scripts/codex-companion.mjs, specifically within the job filtering and transfer functions. At line 544, the companion posts the review summary, and the transfer function (lines 618‑626) handles importing the session context so Claude can perform the actual code examination before the user proceeds.

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