# How the Rescue Subagent Functions in codex-plugin-cc: Complete Technical Guide

> Explore how the codex-plugin-cc rescue subagent functions. Learn how it translates commands into a Bash invocation for the Codex companion script, returning raw stdout.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-07

---

**The rescue subagent functions as a thin forwarding wrapper that translates `/codex:rescue` commands into a single Bash invocation of the Codex companion script, returning raw stdout without Claude performing any additional processing.**

The OpenAI codex-plugin-cc repository provides a bridge between Claude and the Codex runtime through specialized subagents. The **rescue subagent** (`codex:codex-rescue`) serves as a minimal coordination layer that delegates heavyweight debugging and implementation tasks to Codex while ensuring Claude performs no duplicate work.

## Architecture and Design Philosophy

The rescue subagent follows a strict **single-step forwarding pattern** that deliberately limits Claude-side operations to invocation and parameter routing. This design prevents duplication of effort between Claude and Codex, ensuring that complex debugging or implementation work happens exclusively within the Codex runtime.

### The Forwarding Wrapper Pattern

According to the agent definition in [`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md), the subagent acts as a declarative interface that accepts user requests and forwards them to the Codex companion script. The implementation enforces that **the only allowed operation** is a single Bash invocation of the runtime skill defined in [`plugins/codex/skills/codex-cli-runtime/SKILL.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-cli-runtime/SKILL.md).

### Safety Defaults and Constraints

The subagent defaults to write-capable operations (`--write`) unless explicitly configured otherwise. It **must not** perform repository inspection, reasoning, or solution drafting itself. Optional prompt tightening through the `gpt-5-4-prompting` skill is permitted, but the subagent cannot modify the fundamental request beyond flag parsing and routing.

## Execution Flow and Command Routing

When a user triggers the rescue flow, the subagent processes the request through a strict pipeline defined in the command specification at [`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md).

### 1. Invocation and Flag Parsing

Users trigger the subagent via the `/codex:rescue` command, optionally supplying execution flags:

- `--background` – Runs the subagent in the background
- `--wait` – Forces foreground execution with waiting
- `--model` – Specifies the Codex model (e.g., `spark` maps to `gpt-5.3-codex-spark`)
- `--effort` – Sets the effort level for the task
- `--resume` – Translates to `--resume-last` to continue a previous thread
- `--fresh` – Forces a new thread instead of resuming

These flags are stripped from the natural language task text and used only for the eventual `task` call.

### 2. The Bash Call to codex-companion.mjs

Inside the subagent, the execution executes exactly one Bash command:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task <args>

```

The arguments include the stripped routing flags and the sanitized task description. For example, a request with `--resume` automatically appends `--resume-last` to the command.

### 3. Result Handling

The subagent returns **exactly** the stdout from the `codex-companion.mjs` script without commentary, paraphrasing, or post-processing. If the Bash call fails, no output is returned to the user.

## Configuration Flags and Parameter Mapping

The rescue subagent handles several special parameter translations:

- `--resume` maps to `--resume-last` to continue previous rescue threads
- `--fresh` forces a new thread instead of resuming
- `spark` maps to `gpt-5.3-codex-spark` for model selection
- Default mode is `--write` unless read-only is explicitly requested

Background execution is controlled by the `--background` flag, which determines whether the subagent runs synchronously or asynchronously relative to the user session.

## Implementation Files and Source Code

The rescue subagent functionality spans four key files in the repository:

- **[`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md)** – Declares the subagent name, description, and forwarding rules
- **[`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md)** – Defines the user-facing `/codex:rescue` command and flag parsing logic
- **[`plugins/codex/skills/codex-cli-runtime/SKILL.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-cli-runtime/SKILL.md)** – Encapsulates the single Bash call to the companion script
- **`scripts/codex-companion.mjs`** – The Node.js entry point that actually executes the Codex `task` and returns stdout

## Practical Examples

### Basic Rescue Request

```bash
/codex:rescue investigate why the unit tests are failing

```

This command forwards the request to the subagent, which strips no flags (defaulting to `--write`) and executes:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --write "investigate why the unit tests are failing"

```

### Resume Previous Thread in Background

```bash
/codex:rescue --background --resume fix the flaky integration test

```

The subagent translates `--resume` to `--resume-last` and runs in the background:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --resume-last --write "fix the flaky integration test"

```

### Specify Model and Effort

```bash
/codex:rescue --model spark --effort low --wait generate a new helper function

```

Results in:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task \
  --model gpt-5.3-codex-spark --effort low --write \
  "generate a new helper function"

```

## Summary

- The **rescue subagent** (`codex:codex-rescue`) functions as a minimal forwarding wrapper that delegates complex tasks from Claude to the Codex runtime.
- It performs **exactly one Bash call** to `scripts/codex-companion.mjs` with the `task` command and configured arguments.
- **Execution flags** such as `--resume`, `--background`, and `--model` are stripped from user input and mapped to internal parameters (e.g., `--resume` becomes `--resume-last`, `spark` becomes `gpt-5.3-codex-spark`).
- The subagent **defaults to write mode** (`--write`) and returns raw stdout from the companion script without modification or commentary.
- All implementation logic is contained within [`plugins/codex/agents/codex-rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/agents/codex-rescue.md), [`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md), and the runtime skill definitions.

## Frequently Asked Questions

### What is the primary purpose of the rescue subagent in codex-plugin-cc?

The rescue subagent serves as a thin coordination layer that transfers heavyweight debugging, investigation, or implementation tasks from Claude to the Codex runtime. It ensures that Claude does not duplicate work by restricting itself to a single forwarding step while Codex handles the actual computational heavy lifting.

### How does the rescue subagent handle execution flags?

The subagent parses flags such as `--background`, `--resume`, `--model`, and `--effort` from the user's natural language command. These flags are removed from the task text and translated into arguments for the `codex-companion.mjs` script. For example, the `--resume` flag maps to `--resume-last`, and the model token `spark` expands to `gpt-5.3-codex-spark`.

### Can the rescue subagent analyze or modify code before forwarding to Codex?

No. The subagent is explicitly prohibited from performing repository inspection, reasoning, or solution drafting. It may optionally invoke the `gpt-5-4-prompting` skill to tighten the user's request, but it cannot analyze code or modify the task beyond routing flag processing.

### What happens if the codex-companion.mjs script fails during execution?

If the Bash call to `codex-companion.mjs` fails or returns no stdout, the rescue subagent returns nothing to the user. It does not provide error commentary, fallback processing, or additional diagnostics, maintaining its strict role as a transparent forwarding wrapper.