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

> Discover how the stop hook integrates with Claude Code in OpenAI's Codex Plugin. Learn how it automatically adds a review task to vet generated artifacts before automation proceeds.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```javascript
// 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:

```javascript
// 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:

```javascript
// 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

```javascript
// 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.