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

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, 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.

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.

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:

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 – Declares the subagent name, description, and forwarding rules
• plugins/codex/commands/rescue.md – Defines the user-facing /codex:rescue command and flag parsing logic
• 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

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

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

Resume Previous Thread in Background

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

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

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

Specify Model and Effort

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

Results in:

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, 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.

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