Skip to content

Commit 93e29aa

Browse files
zknprclaude
andcommitted
fix(codex-rescue): default to --background; foreground inside the subagent is reaped at ~143s
Root cause (reproduced cleanly, not the daemon leak): a foreground (blocking) `node companion task` call running INSIDE the codex-rescue Agent subagent is auto-backgrounded by the harness and then reaped when the subagent ends — observed at ~143s — which kills the detached Codex worker mid-run and silently loses the work. Confirmed by lifetimes: foreground-via-subagent died at 142.1s / 143.3s (multiwarm) and 143.9s (controlled repro), while --background via the subagent survived 309s and via direct Bash 461s / 492s. --background returns immediately, so the worker reparents to launchd and survives. Fix: codex-rescue now defaults to `task --background` whenever the user did not explicitly pass `--wait`; foreground is reserved for short, clearly-bounded `--wait` requests (well under ~140s), and substantial/long/write/uncertain work always goes `--background`. The agent md and rescue.md document why (the subagent reaping at ~143s, not the ~600s direct-Bash cap that the docs wrongly cited). The main thread continues to arm the status --wait watcher for background completion — the pattern proven reliable across this work. Tests: assertions updated to the new default-background guidance + that the incorrect ~600s foreground-cap claim is gone. Suite 119/119. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 4de4d9c commit 93e29aa

3 files changed

Lines changed: 19 additions & 13 deletions

File tree

‎plugins/codex/agents/codex-rescue.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,9 @@ Forwarding rules:
2121

2222
- Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...`.
2323
- Explicit `--background` in the request means invoke `task --background`; strip the flag from the prompt text.
24-
- Explicit `--wait` in the request means invoke foreground `task`; strip the flag from the prompt text.
25-
- No explicit choice and the task is short and clearly bounded (quick fix, single-file edit, focused diagnosis) means foreground.
26-
- No explicit choice and the task is long, open-ended, multi-step, or likely to exceed the foreground cap means `task --background`. Prefer background for substantial work.
27-
- Foreground task runs are capped by the Bash tool at roughly 600 seconds; past that, they can be auto-backgrounded and orphaned.
24+
- Default to `task --background` whenever the user did NOT explicitly pass `--wait`. Background is the safe path: the companion returns immediately, the worker daemonizes and survives, and the result is recoverable via `status`/`result`.
25+
- Explicit `--wait` means invoke foreground `task` — but ONLY for a short, clearly bounded request (quick fix, single-file edit, focused diagnosis that finishes well under ~140s); strip the flag from the prompt text. If a `--wait` request is actually long, open-ended, multi-step, or write-capable, use `task --background` instead. When in doubt, `--background`.
26+
- Why background is the default: a foreground (blocking) `task` call running inside THIS subagent is auto-backgrounded by the harness and then reaped when the subagent ends (observed at ~143s), which kills the Codex worker mid-run and silently loses the work. `task --background` avoids this entirely, so never run substantial work foreground from here.
2827
- You may use the `gpt-5-4-prompting` skill only to tighten the user's request into a better Codex prompt before forwarding it.
2928
- Do not use that skill to inspect the repository, reason through the problem yourself, draft a solution, or do any independent work beyond shaping the forwarded prompt text.
3029
- Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.

‎plugins/codex/commands/rescue.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ Execution mode:
1515

1616
- If the request includes `--background`, pass `--background` to the `codex:codex-rescue` subagent so it invokes companion `task --background`.
1717
- If the request includes `--wait`, pass `--wait` to the `codex:codex-rescue` subagent so it invokes foreground `task`.
18-
- If neither flag is present, foreground stays for short, bounded rescues that return the result directly.
18+
- If neither flag is present, default to `--background` (the safe path: the worker daemonizes and survives; collect the result via `/codex:status` + `/codex:result`). Only stay foreground when `--wait` is explicit AND the rescue is short and clearly bounded.
1919
- For long, substantial, or open-ended rescues, pass `--background`; the companion returns `[[codex-task status=dispatched id=<jobId>]]`. A dispatched background job has no automatic push notification, so arm a watcher by running `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" status <jobId> --wait --timeout-ms 1800000` via the Bash tool with `run_in_background=true`; it exits and re-invokes Claude when the job reaches a terminal status. If it returns while the job is still running, re-arm the same command. Fetch `/codex:result <jobId>` only after the watcher reports a terminal status.
20-
- A foreground rescue is capped by the Bash tool at roughly 600 seconds and can be auto-backgrounded past that cap, which orphans the detached Codex result.
20+
- A foreground rescue running inside the subagent is auto-backgrounded by the harness and then reaped when the subagent ends (observed at ~143s — much sooner than the ~600s direct-Bash cap), which kills the Codex worker mid-run and loses the result. Route anything substantial to `--background`.
2121
- `--background` and `--wait` are execution flags for Claude Code and the rescue subagent. Preserve the execution choice, and strip them only from the natural-language task text before Codex sees the prompt.
2222
- `--model` and `--effort` are runtime-selection flags. Preserve them for the forwarded `task` call, but do not treat them as part of the natural-language task text.
2323
- If the request includes `--resume`, do not ask whether to continue. The user already chose.

‎tests/commands.test.mjs‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,16 @@ test("rescue command absorbs continue semantics", () => {
113113
assert.match(rescue, /status <jobId> --wait --timeout-ms 1800000/);
114114
assert.match(rescue, /run_in_background=true/);
115115
assert.match(rescue, /`\/codex:result <jobId>`/);
116-
assert.match(rescue, /Foreground stays for short, bounded rescues/i);
117-
assert.match(rescue, /foreground rescue is capped by the Bash tool/i);
118-
assert.match(rescue, /auto-backgrounded past that cap/i);
116+
// Fix: a foreground task call inside the subagent is auto-backgrounded and
117+
// reaped at ~143s (kills the worker mid-run). Default must be --background.
118+
assert.match(rescue, /default to `--background`/i);
119+
assert.match(rescue, /Only stay foreground when `--wait` is explicit/i);
120+
assert.match(rescue, /running inside the subagent is auto-backgrounded by the harness and then reaped/i);
121+
assert.match(rescue, /observed at ~143s/i);
122+
assert.doesNotMatch(rescue, /foreground rescue is capped by the Bash tool at roughly 600 seconds/i);
123+
assert.match(agent, /Default to `task --background` whenever the user did NOT explicitly pass `--wait`/i);
124+
assert.match(agent, /reaped when the subagent ends \(observed at ~143s\)/i);
125+
assert.doesNotMatch(agent, /capped by the Bash tool at roughly 600 seconds/i);
119126
assert.match(rescue, /Preserve the execution choice/i);
120127
assert.match(rescue, /strip them only from the natural-language task text/i);
121128
assert.match(rescue, /`--model` and `--effort` are runtime-selection flags/i);
@@ -137,10 +144,10 @@ test("rescue command absorbs continue semantics", () => {
137144
assert.match(agent, /--fresh/);
138145
assert.match(agent, /thin forwarding wrapper/i);
139146
assert.match(agent, /Explicit `--background` in the request means invoke `task --background`/i);
140-
assert.match(agent, /Explicit `--wait` in the request means invoke foreground `task`/i);
141-
assert.match(agent, /No explicit choice and the task is short and clearly bounded .* means foreground/i);
142-
assert.match(agent, /No explicit choice and the task is long, open-ended, multi-step, or likely to exceed the foreground cap means `task --background`/i);
143-
assert.match(agent, /Prefer background for substantial work/i);
147+
assert.match(agent, /Explicit `--wait` means invoke foreground `task`/i);
148+
assert.match(agent, /ONLY for a short, clearly bounded request/i);
149+
assert.match(agent, /Default to `task --background` whenever the user did NOT explicitly pass `--wait`/i);
150+
assert.match(agent, /never run substantial work foreground from here/i);
144151
assert.match(agent, /Use exactly one `Bash` call/i);
145152
assert.match(agent, /Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own/i);
146153
assert.match(agent, /Do not call `review`, `adversarial-review`, `status`, `result`, or `cancel`/i);

0 commit comments

Comments
 (0)