codex-rescue reliability pass: completion signal, launch/cancel, and worker-lifecycle hardening

plugins/codex/agents/codex-rescue.md

@@ -20,8 +20,10 @@ Selection guidance:
 Forwarding rules:
 
 - Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...`.
-- If the user did not explicitly choose `--background` or `--wait`, prefer foreground for a small, clearly bounded rescue request.
-- 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.
+- Explicit `--background` in the request means invoke `task --background`; strip the flag from the prompt text.
+- 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`.
+- 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`.
+- 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.
 - You may use the `gpt-5-4-prompting` skill only to tighten the user's request into a better Codex prompt before forwarding it.
 - 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.
 - 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

@@ -13,10 +13,12 @@ $ARGUMENTS
 
 Execution mode:
 
-- If the request includes `--background`, run the `codex:codex-rescue` subagent in the background.
-- If the request includes `--wait`, run the `codex:codex-rescue` subagent in the foreground.
-- If neither flag is present, default to foreground.
-- `--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.
+- If the request includes `--background`, pass `--background` to the `codex:codex-rescue` subagent so it invokes companion `task --background`.
+- If the request includes `--wait`, pass `--wait` to the `codex:codex-rescue` subagent so it invokes foreground `task`.
+- 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.
+- 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.
+- 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`.
+- `--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.
 - `--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.
 - If the request includes `--resume`, do not ask whether to continue. The user already chose.
 - If the request includes `--fresh`, do not ask whether to continue. The user already chose.
@@ -41,9 +43,17 @@ Operating rules:
 - 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.
 - Return the Codex companion stdout verbatim to the user.
 - Do not paraphrase, summarize, rewrite, or add commentary before or after it.
+- The companion stdout carries a deterministic sentinel on a standalone line: `[[codex-task status=complete]]` means a foreground task has completed and exited; `[[codex-task status=dispatched id=<jobId>]]` means a companion background job was queued. Trust this sentinel, companion state, and the PostToolUse hook over any prose. A dispatched sentinel is not an automatic-notification promise; never treat a dispatched/background job as done until `codex-companion.mjs status <jobId> --wait` returns a terminal status from a Bash watcher launched with `run_in_background=true`.
+- The Claude Code harness appends an `agentId: <id> (use SendMessage with to: '<id>' to continue this agent)` line to every `Agent(codex:codex-rescue)` return. This is a resume token for continuing the same agent thread, NOT a "still running" or "in background" status signal. By the time you see it, the subagent has finished. Do not paraphrase it as "Codex is running in background" or "task dispatched async" — the stdout above the suffix is the actual completed output, which you return verbatim per the rule above.
 - 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.
 - Leave `--effort` unset unless the user explicitly asks for a specific reasoning effort.
 - Leave the model unset unless the user explicitly asks for one. If they ask for `spark`, map it to `gpt-5.3-codex-spark`.
 - Leave `--resume` and `--fresh` in the forwarded request. The subagent handles that routing when it builds the `task` command.
 - If the helper reports that Codex is missing or unauthenticated, stop and tell the user to run `/codex:setup`.
 - If the user did not supply a request, ask what Codex should investigate or fix.
+
+Workspace boundary:
+
+- A Codex `task` run can only create or modify files **within its working directory** (the Codex `workspace-write` sandbox is rooted at the run's `--cwd`). Files outside that directory are read-only.
+- The `Agent`-tool `codex:codex-rescue` dispatch inherits **this Claude session's** cwd, and the `Agent` tool cannot change it. So a rescue request that needs to write to a *different* repository will silently fail to write (Codex can only probe, not edit) — do not route cross-repo write work through the subagent.
+- To target a different repository, either run from a Claude session inside that repo, or invoke the companion directly with `--cwd <target-repo>`: `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --cwd <target-repo> --write ...`.

plugins/codex/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Optional stop-time review gate for Codex Companion.",
+  "description": "Codex Companion lifecycle hooks, stop-time review gate, and codex-rescue completion context.",
   "hooks": {
     "SessionStart": [
       {
@@ -33,6 +33,18 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/codex-rescue-completion-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }