What Happens When a Rescue Task Is Resumed vs Started Fresh

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:

# 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 – 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.

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