Skip to content

Commit 52bd80f

Browse files
axisrowclaude
andauthored
fix(rescue): default to --background, make Bash-tool timeout terminal (#8)
Closes #7 (rephrased from code, not the original misdiagnosis). The codex:codex-rescue subagent hung because it defaulted to a foreground `task` run; when Codex exceeded Claude's Bash-tool timeout the host auto- backgrounded the call, and the rescue model then violated its one-Bash-call rule by improvising `cat` / `sleep 60` / `until grep ...; do sleep 5; done` polling — which itself violates Claude Code's foreground-sleep restriction. The Codex turn had actually completed; the hang was the subagent's polling, not the companion. This was a behavioral-contract gap, not a broker bug (verified by code trace and the recorded transcript): the companion foreground path correctly blocks on state.completion, an explicit --cwd is preserved unchanged through to the broker process argv, and runtime SessionEnd already reaps brokers/sockets. The original issue's "wait pattern" and "wrong cwd" causes are refuted; the "no reaping" cause conflates a real test-harness leak (fixed in PR #5) with runtime behavior. Fix the contract that actually failed: - rescue now defaults to --background (rescue work is open-ended; a foreground run that the host auto-backgrounds at its Bash-tool timeout cannot be turned back into a foreground wait, so start in background). --wait still selects foreground explicitly. - terminal-on-timeout: if the single task Bash call returns by host Bash-tool timeout, the subagent makes no second call (no status/result/cat/sleep/ until-grep). The Codex turn keeps running and is recovered by the caller via /codex:status or /codex:result — never by the subagent. commands.test.mjs assertions updated to the new contract. Claude-Session: https://claude.ai/code/session_0189cGaohsYdpkB4otKZnpAt Co-authored-by: axisrow <[email protected]> Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 31f04b0 commit 52bd80f

3 files changed

Lines changed: 13 additions & 11 deletions

File tree

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ Selection guidance:
2020
Forwarding rules:
2121

2222
- Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...`.
23-
- If the user did not explicitly choose `--background` or `--wait`, prefer foreground for a small, clearly bounded rescue request.
24-
- If the user did not explicitly choose `--background` or `--wait` and the task looks complicated, open-ended, multi-step, or likely to keep Codex running for a long time, prefer background execution.
25-
- For any task expected to exceed a few minutes, add `--background` to the `task` invocation by default so a caller timeout cannot terminate it.
23+
- Default to `--background`. Rescue tasks are open-ended by nature and routinely exceed Claude's Bash-tool timeout; a foreground `task` that gets auto-backgrounded by the host at its timeout MUST be treated as terminal (see below) — it cannot be turned back into a foreground wait, so backgrounding from the start avoids the trap entirely. Only use foreground (no `--background`) when the caller passed `--wait` explicitly.
24+
- Add `--background` to the `task` invocation unless the caller explicitly chose `--wait`.
25+
- If the single `task` Bash call returns because it hit the host's Bash-tool timeout (foreground run that the host auto-backgrounded) — STOP. Do NOT issue a second Bash call. Do NOT poll `status`, `result`, `cat`, `sleep`, or `until grep`. Return the companion's stdout so far (possibly empty) as-is. The Codex turn keeps running in the background and is recovered later via `/codex:status` / `/codex:result` by the caller — never by this subagent.
2626
- Treat `--cwd <dir>` and `-C <dir>` as workspace routing controls. Pass `--cwd <dir>` explicitly on every `task` invocation, using the intended workspace root forwarded by the caller.
2727
- You may use the `gpt-5-4-prompting` skill only to tighten the user's request into a better Codex prompt before forwarding it.
2828
- 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.
@@ -41,7 +41,7 @@ Forwarding rules:
4141
- Otherwise forward the task as a fresh `task` run.
4242
- Preserve the user's task text as-is apart from stripping routing flags.
4343
- Return the stdout of the `codex-companion` command exactly as-is.
44-
- If the Bash call fails or Codex cannot be invoked, return nothing.
44+
- If the Bash call fails, returns by host Bash-tool timeout, or Codex cannot be invoked, return nothing (or the partial stdout captured so far) and make NO further Bash calls. A timed-out foreground run is terminal, not a signal to poll.
4545

4646
Response style:
4747

‎plugins/codex/commands/rescue.md‎

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

1616
- If the request includes `--background`, run the `codex:codex-rescue` subagent in the background.
1717
- If the request includes `--wait`, run the `codex:codex-rescue` subagent in the foreground.
18-
- If neither flag is present, default to foreground.
18+
- If neither flag is present, default to `--background`. Rescue tasks are open-ended and routinely exceed Claude's Bash-tool timeout; starting in background avoids the auto-background trap (see Operating rules).
1919
- `--background` and `--wait` are execution flags for Claude Code. Do not forward them to `task`, and do not treat them as part of the natural-language task text.
2020
- `--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.
2121
- `--cwd <dir>` and `-C <dir>` are workspace-routing flags. Preserve the directory for the resume preflight and the forwarded `task` call, but do not treat either form as part of the natural-language task text.
@@ -46,7 +46,8 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task-resume-candidate -
4646
Operating rules:
4747

4848
- The subagent is a thin forwarder only. It should use one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...` and return that command's stdout as-is.
49-
- Pass `--cwd <dir>` explicitly for the intended workspace root. For work expected to exceed a few minutes, have the subagent add the task command's own `--background` flag so a caller timeout cannot terminate it.
49+
- Pass `--cwd <dir>` explicitly for the intended workspace root. Add `--background` to the `task` invocation unless the caller explicitly chose `--wait`, so a caller Bash-tool timeout cannot terminate the run or force an auto-background.
50+
- Terminal-on-timeout: if the single `task` Bash call returns because the host auto-backgrounded it at the Bash-tool timeout, the subagent MUST make no second Bash call (no `status`, `result`, `cat`, `sleep`, or `until grep`). The Codex turn keeps running and is recovered later by the caller via `/codex:status` / `/codex:result`.
5051
- Return the Codex companion stdout verbatim to the user.
5152
- Do not paraphrase, summarize, rewrite, or add commentary before or after it.
5253
- Do not ask the subagent to inspect files, monitor progress, poll `/codex:status`, fetch `/codex:result`, call `/codex:cancel`, summarize output, or do follow-up work of its own.

‎tests/commands.test.mjs‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ test("rescue command absorbs continue semantics", () => {
133133
assert.match(rescue, /Continue current Codex thread/);
134134
assert.match(rescue, /Start a new Codex thread/);
135135
assert.match(rescue, /run the `codex:codex-rescue` subagent in the background/i);
136-
assert.match(rescue, /default to foreground/i);
136+
assert.match(rescue, /default to `--background`/i);
137137
assert.match(rescue, /Do not forward them to `task`/i);
138138
assert.match(rescue, /`--model` and `--effort` are runtime-selection flags/i);
139139
assert.match(rescue, /Leave `--effort` unset unless the user explicitly asks for a specific reasoning effort/i);
@@ -155,9 +155,10 @@ test("rescue command absorbs continue semantics", () => {
155155
assert.match(agent, /--resume/);
156156
assert.match(agent, /--fresh/);
157157
assert.match(agent, /thin forwarding wrapper/i);
158-
assert.match(agent, /prefer foreground for a small, clearly bounded rescue request/i);
159-
assert.match(agent, /If the user did not explicitly choose `--background` or `--wait` and the task looks complicated, open-ended, multi-step, or likely to keep Codex running for a long time, prefer background execution/i);
160-
assert.match(agent, /expected to exceed a few minutes.*`--background`/i);
158+
assert.match(agent, /Default to `--background`/i);
159+
assert.match(agent, /Add `--background` to the `task` invocation unless the caller explicitly chose `--wait`/i);
160+
assert.match(rescue, /Terminal-on-timeout/i);
161+
assert.match(agent, /A timed-out foreground run is terminal, not a signal to poll/i);
161162
assert.match(agent, /pass `--cwd <dir>` explicitly/i);
162163
assert.match(agent, /`--cwd <dir>` and `-C <dir>`.*workspace routing controls/i);
163164
assert.match(agent, /Use exactly one `Bash` call/i);
@@ -168,7 +169,7 @@ test("rescue command absorbs continue semantics", () => {
168169
assert.match(agent, /If the user asks for `spark`, map that to `--model gpt-5\.3-codex-spark`/i);
169170
assert.match(agent, /If the user asks for a concrete model name such as `gpt-5\.4-mini`, pass it through with `--model`/i);
170171
assert.match(agent, /Return the stdout of the `codex-companion` command exactly as-is/i);
171-
assert.match(agent, /If the Bash call fails or Codex cannot be invoked, return nothing/i);
172+
assert.match(agent, /If the Bash call fails, returns by host Bash-tool timeout, or Codex cannot be invoked, return nothing/i);
172173
assert.match(agent, /gpt-5-4-prompting/);
173174
assert.match(agent, /only to tighten the user's request into a better Codex prompt/i);
174175
assert.match(agent, /Do not use that skill to inspect the repository, reason through the problem yourself, draft a solution, or do any independent work/i);

0 commit comments

Comments
 (0)