[BUG] codex:codex-rescue hangs in worktrees when run_in_background is used

[mr-lee]

Summary

codex:codex-rescue tasks hang indefinitely when dispatched with isolation: "worktree" and the rescue agent uses run_in_background: true on the Bash call. The worktree is cleaned up before Codex finishes, leaving Codex running in a deleted directory.

Root Cause

1. Rescue agent calls codex-companion.mjs task --write with run_in_background: true
2. Bash returns immediately ("Command running in background...")
3. Rescue agent returns "Codex task dispatched in background" and exits
4. CC sees agent returned with no file changes → deletes the worktree
5. Codex is now running in a deleted directory → hangs at "Turn started"

The rescue agent uses run_in_background in two cases:

• Explicitly: --background flag in the task text is interpreted as run_in_background: true
• Implicitly: For large prompts with long timeouts, Claude sometimes independently decides to background the call

Repro

# SUCCEEDS — rescue agent waits for Codex to complete:
Agent(subagent_type="codex:codex-rescue", isolation="worktree",
      prompt="Create foo.txt with content hello")

# FAILS — rescue agent backgrounds, worktree cleaned before Codex finishes:
Agent(subagent_type="codex:codex-rescue", isolation="worktree",
      prompt="Create foo.txt with content hello. --background")

Parallel dispatch without --background works fine — three concurrent worktree tasks all succeed. The issue is purely about early worktree cleanup from backgrounding.

Suggested Fix

In codex-cli-runtime SKILL.md, change the --background handling from:

- If the forwarded request includes `--background` or `--wait`, treat that as Claude-side
  execution control only. Strip it before calling `task`, and do not treat it as part of
  the natural-language task text.

To:

- If the forwarded request includes `--background` or `--wait`, strip it before calling
  `task`. Do NOT set `run_in_background` on the Bash call. The rescue agent MUST wait for
  Codex to complete — backgrounding causes the parent worktree to be cleaned up before
  Codex finishes, silently orphaning the task.

Impact

Any codex:codex-rescue dispatched with isolation: "worktree" where the rescue agent backgrounds the Bash call will silently fail. No error, no timeout — just an indefinite hang at "Turn started" with Codex working in a deleted directory.

Environment

• Claude Code 2.1.89
• codex-plugin-cc (marketplace install)
• macOS Darwin 25.2.0

[mr-lee]

Corrected Root Cause

My initial analysis was wrong — resolveStateDir() is fine. The actual root cause is the interaction between codex:codex-rescue, run_in_background, and CC's worktree lifecycle.

What happens

1. codex:codex-rescue agent is dispatched with isolation: "worktree" (CC creates a temporary git worktree)
2. The rescue agent calls codex-companion.mjs task --write with run_in_background: true on the Bash tool
3. Bash returns immediately ("Command running in background...")
4. The rescue agent returns "Codex task dispatched in background" and exits
5. CC sees the agent returned with no file changes → deletes the worktree
6. Codex is now running in a deleted directory → hangs indefinitely at "Turn started"

When does the rescue agent use run_in_background?

Two cases:

• Explicitly: The codex-cli-runtime skill interprets --background in the task text as a signal to set run_in_background: true
• Implicitly: For large/complex prompts with long timeouts (600s), Claude sometimes independently decides to background the call

Confirmed repro

# This succeeds (no --background, rescue agent waits):
Agent(subagent_type="codex:codex-rescue", isolation="worktree", prompt="Create foo.txt with content hello")

# This fails (--background, rescue agent returns immediately, worktree cleaned):
Agent(subagent_type="codex:codex-rescue", isolation="worktree", prompt="Create foo.txt with content hello. --background")

Three parallel non-background dispatches all succeed — Codex handles concurrency fine. The issue is purely about early worktree cleanup.

Suggested fix

Add to codex-cli-runtime SKILL.md:

- NEVER use `run_in_background` on the task Bash call. The rescue agent must wait for Codex to complete and return its stdout. Backgrounding causes the parent worktree agent to exit early, which triggers worktree cleanup before Codex finishes.

And strip --background from the routing flags rather than converting it to run_in_background:

- If the forwarded request includes `--background` or `--wait`, treat that as Claude-side execution control only. Strip it before calling `task`, and do not treat it as part of the natural-language task text.

The skill already says "Strip it before calling task" but should add "and do NOT set run_in_background on the Bash call."

Impact

Any codex:codex-rescue dispatched with isolation: "worktree" where the rescue agent uses run_in_background will silently fail. The Codex task hangs in a deleted directory with no error.