# What Happens When a Rescue Task Is Resumed vs Started Fresh

> Learn the difference between resuming a Codex rescue task with --resume and starting fresh with --fresh. Understand state restoration and new thread creation.

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

---

**When you invoke a Codex rescue task with the `--resume` flag, the system reuses the existing thread and restores all previous state and logs; with the `--fresh` flag, it creates a new thread with a clean job ID and empty history.**

In the `openai/codex-plugin-cc` repository, the rescue workflow manages persistent conversation threads through specific CLI flags that determine whether Codex continues from where it left off or starts from scratch. Understanding the distinction between a **resumed** and **fresh** rescue task is critical for maintaining context across multi-step debugging sessions.

## How Codex Decides: Resume, Fresh, or Prompt

The decision logic resides in `plugins/codex/scripts/codex-companion.mjs`, which parses command-line arguments via `plugins/codex/scripts/lib/args.mjs`. When you run the `task` command, the system checks for explicit flags:

- **`--resume`** – Forces continuation of the current rescue thread
- **`--fresh`** – Forces creation of a brand-new rescue thread
- **No flags** – Triggers automatic detection via the `task-resume-candidate` helper

If neither flag is provided and a resumable thread exists, the system prompts the user once to choose between continuing the current thread or starting new. The user's selection is then translated into the appropriate internal flag before forwarding the request to the `codex:codex-rescue` sub-agent.

## Resuming a Rescue Task: State Restoration

When the **`--resume`** flag is supplied (or the user selects "Continue current Codex thread"), the system performs three key actions:

1. **Thread Reuse** – The existing rescue thread identified by the persistent task thread name is reactivated rather than creating a new one.
2. **State Hydration** – The `plugins/codex/scripts/lib/state.mjs` module loads the stored job state, previous logs, and any partial results, allowing Codex to pick up exactly where it left off.
3. **Flag Isolation** – The `--resume` flag is consumed by the CLI parser and is **not** forwarded to the actual Codex prompt, ensuring the original user prompt remains unchanged. This behavior is verified in the test suite, specifically in the test *"task --resume acts like --resume-last without leaking the flag into the prompt"* found in `tests/runtime.test.mjs` and `tests/commands.test.mjs`.

This approach preserves the full context of previous debugging steps, including file modifications explored and error logs analyzed.

## Starting a Fresh Rescue Task: Clean Slate

When the **`--fresh`** flag is explicitly provided (or the user selects "Start a new Codex thread"), the system:

- Creates a **new rescue thread** with a unique job ID
- Initializes **empty logs** and zero previous state
- Ignores any existing persistent thread data managed by `state.mjs`

This is the equivalent of starting a completely independent debugging session. Use this when investigating a new issue unrelated to previous rescue attempts or when you want to eliminate potential context pollution from earlier steps.

## Command-Line Examples

The `codex-companion.mjs` script accepts these flags directly before your prompt text:

```bash

# Resume an existing rescue thread (continues previous context)

codex-companion.mjs task --resume "investigate the flaky test failure"

# Start a brand-new rescue thread (ignores previous context)

codex-companion.mjs task --fresh "analyze the new performance regression"

# Let the system decide - prompts once if resumable thread exists

codex-companion.mjs task "review the latest CI failure"

```

## Implementation Details and File References

The rescue task logic spans several key files in the repository:

- **[`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md)** – Documents the CLI contract and explains the `--resume`/`--fresh` flag semantics.
- **`plugins/codex/scripts/codex-companion.mjs`** – Implements the `task` command, orchestrates flag parsing, and routes requests to the rescue sub-agent.
- **`plugins/codex/scripts/lib/state.mjs`** – Persists job metadata and manages the "persistent task thread name" used for thread identification during resume operations.
- **`plugins/codex/scripts/lib/args.mjs`** – Normalizes command-line arguments, converting user inputs into standardized `--resume` or `--fresh` directives.

## Summary

- **`--resume`** reuses the existing Codex thread, hydrates previous state from `state.mjs`, and suppresses the resume prompt without leaking the flag into the actual prompt.
- **`--fresh`** creates a new thread with a unique job ID and empty history, ignoring any previous rescue context.
- When no flag is provided, the `task-resume-candidate` helper detects existing threads and prompts the user once to choose their preferred mode.
- The implementation ensures that resumed tasks maintain full continuity while fresh tasks eliminate legacy context that might confuse new investigations.

## Frequently Asked Questions

### What happens if I don't specify --resume or --fresh?

The system runs the `task-resume-candidate` helper to check for existing resumable threads. If one exists, you will be prompted once to choose between continuing the current thread or starting fresh. If no resumable thread exists, the command proceeds with a fresh task automatically.

### Is the --resume flag visible to the Codex AI model?

No. According to the source code in `codex-companion.mjs` and verified by tests in `tests/runtime.test.mjs`, the `--resume` flag is parsed and consumed by the CLI layer. It is not forwarded to the `codex:codex-rescue` sub-agent or included in the prompt text sent to the model, ensuring the AI receives only your actual query without metadata about the resume operation.

### Where is the rescue task state stored between sessions?

Persistent job metadata and thread identifiers are managed by `plugins/codex/scripts/lib/state.mjs`, which creates and maintains a "persistent task thread name" that allows the system to locate and reconnect to previous rescue sessions when the `--resume` flag is used.

### Can I resume a task after starting a fresh one?

Yes, but each fresh task creates a new thread with a new job ID. To resume a previous task, you must reference its specific thread. The `task-resume-candidate` helper typically identifies the most recent resumable thread, so starting a fresh task does not delete historical threads—it simply creates a parallel conversation history that won't interfere with previous rescue states.