Feat/codex runtime controls

README.md

@@ -86,14 +86,15 @@ Use it when you want:
 - a review of your current uncommitted changes
 - a review of your branch compared to a base branch like `main`
 
-Use `--base <ref>` for branch review. It also supports `--wait` and `--background`. It is not steerable and does not take custom focus text. Use [`/codex:adversarial-review`](#codexadversarial-review) when you want to challenge a specific decision or risk area.
+Use `--base <ref>` for branch review. It also supports `--wait`, `--background`, `--model <model|spark>`, and `--effort <none|minimal|low|medium|high|xhigh|max>`. It is not steerable and does not take custom focus text. Use [`/codex:adversarial-review`](#codexadversarial-review) when you want to challenge a specific decision or risk area.
 
 Examples:
 
 ```bash
 /codex:review
 /codex:review --base main
 /codex:review --background
+/codex:review --effort high
 ```
 
 This command is read-only and will not perform any changes. When run in the background you can use [`/codex:status`](#codexstatus) to check on the progress and [`/codex:cancel`](#codexcancel) to cancel the ongoing task.
@@ -105,7 +106,7 @@ Runs a **steerable** review that questions the chosen implementation and design.
 It can be used to pressure-test assumptions, tradeoffs, failure modes, and whether a different approach would have been safer or simpler.
 
 It uses the same review target selection as `/codex:review`, including `--base <ref>` for branch review.
-It also supports `--wait` and `--background`. Unlike `/codex:review`, it can take extra focus text after the flags.
+It also supports `--wait`, `--background`, `--model`, and `--effort`. Unlike `/codex:review`, it can take extra focus text after the flags.
 
 Use it when you want:
 
@@ -135,9 +136,11 @@ Use it when you want Codex to:
 - take a faster or cheaper pass with a smaller model
 
 > [!NOTE]
-> Depending on the task and the model you choose these tasks might take a long time and it's generally recommended to force the task to be in the background or move the agent to the background.
+> Long or open-ended rescue tasks run in the background unless you request `--wait`. See [Task lifetime](#task-lifetime) for what happens when a task is stopped.
 
-It supports `--background`, `--wait`, `--resume`, and `--fresh`. If you omit `--resume` and `--fresh`, the plugin can offer to continue the latest rescue thread for this repo.
+It supports `--background`, `--wait`, `--resume`, `--fresh`, `--model`, `--effort`, and `--sandbox`. If you omit `--resume` and `--fresh`, the plugin can offer to continue the latest rescue thread for this repo.
+
+Before handing off, Claude asks once (in a single prompt) for anything you did not already specify: whether to continue the previous thread, the Codex model, the reasoning effort, and the sandbox mode. This also applies when you just ask Claude in plain words to delegate to Codex. Say "use the defaults" to skip the model, effort, and sandbox questions.
 
 Examples:
 
@@ -147,6 +150,8 @@ Examples:
 /codex:rescue --resume apply the top fix from the last run
 /codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
 /codex:rescue --model spark fix the issue quickly
+/codex:rescue --sandbox read-only explain why the cache is never invalidated
+/codex:rescue --sandbox danger-full-access install the missing toolchain and rerun the build
 /codex:rescue --background investigate the regression
 ```
 
@@ -160,6 +165,8 @@ Ask Codex to redesign the database connection to be more resilient.
 
 - if you do not pass `--model` or `--effort`, Codex chooses its own defaults.
 - if you say `spark`, the plugin maps that to `gpt-5.3-codex-spark`
+- `--sandbox` accepts `read-only`, `workspace-write`, or `danger-full-access`. Rescue runs default to `workspace-write` unless the request is read-only in nature. Codex never asks for approval inside the plugin, so the sandbox is the only guard rail: `danger-full-access` lets Codex touch files outside the repo and use the network without any confirmation, so only choose it for tasks you trust.
+- the sandbox mode is set by the plugin on every run, so `sandbox_mode` in `config.toml` does not apply to plugin runs; model and reasoning effort still fall back to your config
 - follow-up rescue requests can continue the latest Codex task in the repo
 
 ### `/codex:transfer`
@@ -285,6 +292,14 @@ Your configuration will be picked up based on:
 
 Check out the Codex docs for more [configuration options](https://developers.openai.com/codex/config-reference).
 
+### Task lifetime
+
+The companion process running a task or review owns its Codex turn. If that process exits before the turn finishes, the shared broker interrupts the turn, including after `SIGKILL`. Stopping a foreground Bash task therefore also stops the Codex work it owns.
+
+`SIGTERM`, `SIGINT`, and `SIGHUP` record the job as cancelled. After an abrupt exit, status, result, resume checks, and the stop hook repair active job records whose process is gone: completed results are preserved, and unfinished jobs become failed so they no longer block resuming work.
+
+Use Claude background execution for work that may exceed a foreground Bash timeout. The runtime's internal `task --background` mode instead launches a detached worker: the worker owns the turn and continues after its launcher exits, until it finishes or is cancelled.
+
 ### Moving The Work Over To Codex
 
 Delegated tasks and any [stop gate](#what-does-the-review-gate-do) run can also be directly resumed inside Codex by running `codex resume` either with the specific session ID you received from running `/codex:result` or `/codex:status` or by selecting it from the list.

plugins/codex/agents/codex-rescue.md

@@ -1,6 +1,6 @@
 ---
 name: codex-rescue
-description: Proactively use when Claude Code is stuck, wants a second implementation or diagnosis pass, needs a deeper root-cause investigation, or should hand a substantial coding task to Codex through the shared runtime
+description: Proactively use when Claude Code is stuck, wants a second implementation or diagnosis pass, needs a deeper root-cause investigation, or should hand a substantial coding task to Codex through the shared runtime. This subagent cannot ask the user questions, so before spawning it, unless the request already settles them or the user said to use defaults, ask the user once with AskUserQuestion for the Codex model (Codex default / gpt-5.4 / gpt-5.4-mini / spark), reasoning effort (Codex default / medium / high / xhigh), and sandbox (workspace-write / read-only / danger-full-access), then put the answers in the prompt as --model / --effort / --sandbox flags; "Codex default" means omit that flag.
 model: sonnet
 tools: Bash
 skills:
@@ -21,7 +21,8 @@ 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.
+- 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, use background execution with `Bash(..., run_in_background: true)`.
+- Foreground calls stop with their owning Bash task. See [Task lifetime](../../../README.md#task-lifetime) when choosing how to run a long task.
 - 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.
@@ -30,8 +31,10 @@ Forwarding rules:
 - Leave model unset by default. Only add `--model` when the user explicitly asks for a specific model.
 - If the user asks for `spark`, map that to `--model gpt-5.3-codex-spark`.
 - If the user asks for a concrete model name such as `gpt-5.4-mini`, pass it through with `--model`.
-- Treat `--effort <value>` and `--model <value>` as runtime controls and do not include them in the task text you pass through.
-- Default to a write-capable Codex run by adding `--write` unless the user explicitly asks for read-only behavior or only wants review, diagnosis, or research without edits.
+- Treat `--effort <value>`, `--model <value>`, and `--sandbox <value>` as runtime controls and do not include them in the task text you pass through.
+- If the forwarded request includes `--sandbox <read-only|workspace-write|danger-full-access>`, pass it through unchanged and do not also add `--write`.
+- Otherwise, default to a write-capable Codex run by adding `--write` unless the user explicitly asks for read-only behavior or only wants review, diagnosis, or research without edits.
+- Never choose `--sandbox danger-full-access` yourself. Only forward it when the request already contains it or the user explicitly asked for full access without a sandbox.
 - Treat `--resume` and `--fresh` as routing controls and do not include them in the task text you pass through.
 - `--resume` means add `--resume-last`.
 - `--fresh` means do not add `--resume-last`.

plugins/codex/commands/adversarial-review.md

@@ -1,6 +1,6 @@
 ---
 description: Run a Codex review that challenges the implementation approach and design choices
-argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [focus ...]'
+argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [--model <model|spark>] [--effort <none|minimal|low|medium|high|xhigh|max>] [focus ...]'
 disable-model-invocation: true
 allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion
 ---
@@ -37,6 +37,7 @@ Execution mode rules:
 Argument handling:
 - Preserve the user's arguments exactly.
 - Do not strip `--wait` or `--background` yourself.
+- `--model` and `--effort` select the Codex model and reasoning effort for the review; pass them through untouched. When omitted, the user's Codex config decides.
 - Do not weaken the adversarial framing or rewrite the user's focus text.
 - The companion script parses `--wait` and `--background`, but Claude Code's `Bash(..., run_in_background: true)` is what actually detaches the run.
 - `/codex:adversarial-review` uses the same review target selection as `/codex:review`.

plugins/codex/commands/rescue.md

@@ -1,6 +1,6 @@
 ---
 description: Delegate investigation, an explicit fix request, or follow-up rescue work to the Codex rescue subagent
-argument-hint: "[--background|--wait] [--resume|--fresh] [--model <model|spark>] [--effort <none|minimal|low|medium|high|xhigh>] [what Codex should investigate, solve, or continue]"
+argument-hint: "[--background|--wait] [--resume|--fresh] [--model <model|spark>] [--effort <none|minimal|low|medium|high|xhigh|max>] [--sandbox <read-only|workspace-write|danger-full-access>] [what Codex should investigate, solve, or continue]"
 allowed-tools: Bash(node:*), AskUserQuestion, Agent
 ---
 
@@ -15,35 +15,53 @@ 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.
+- If neither flag is present, default to foreground for a small, clearly bounded request. Use a background subagent for complicated, open-ended, multi-step, or long-running work.
 - `--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.
-- `--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.
-- Otherwise, before starting Codex, check for a resumable rescue thread from this Claude session by running:
-
-```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task-resume-candidate --json
-```
-
-- If that helper reports `available: true`, use `AskUserQuestion` exactly once to ask whether to continue the current Codex thread or start a new one.
-- The two choices must be:
-  - `Continue current Codex thread`
-  - `Start a new Codex thread`
-- If the user is clearly giving a follow-up instruction such as "continue", "keep going", "resume", "apply the top fix", or "dig deeper", put `Continue current Codex thread (Recommended)` first.
-- Otherwise put `Start a new Codex thread (Recommended)` first.
-- If the user chooses continue, add `--resume` before routing to the subagent.
-- If the user chooses a new thread, add `--fresh` before routing to the subagent.
-- If the helper reports `available: false`, do not ask. Route normally.
+- `--model`, `--effort`, and `--sandbox` are runtime-selection flags. Preserve them for the forwarded `task` call, but do not treat them as part of the natural-language task text.
+
+Pre-flight questions (ask at most once):
+
+The subagent cannot ask the user anything, so collect every open choice here and ask them together in a single `AskUserQuestion` call with one question per open choice. Skip the call entirely when nothing is open.
+
+1. Thread choice:
+   - 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.
+   - Otherwise, check for a resumable rescue thread from this Claude session by running:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task-resume-candidate --json
+   ```
+
+   - If that helper reports `available: true`, include a thread question with exactly these two choices:
+     - `Continue current Codex thread`
+     - `Start a new Codex thread`
+   - If the user is clearly giving a follow-up instruction such as "continue", "keep going", "resume", "apply the top fix", or "dig deeper", put `Continue current Codex thread (Recommended)` first.
+   - Otherwise put `Start a new Codex thread (Recommended)` first.
+   - If the helper reports `available: false`, do not include the thread question.
+2. Model: unless the request already names a model (`--model` or plain words such as "use spark" or "use gpt-5.4-mini"), include a model question with the choices `Codex default (Recommended)`, `gpt-5.4`, `gpt-5.4-mini`, and `spark`.
+3. Reasoning effort: unless the request already names a concrete level (`--effort` or plain words such as "high effort"), include an effort question with the choices `Codex default (Recommended)`, `medium`, `high`, and `xhigh`. Other levels (`none`, `minimal`, `low`, `max`) stay reachable through the free-text answer.
+4. Sandbox: unless the request already includes `--sandbox`, `--write`, or an explicit read-only / full-access instruction, include a sandbox question with these choices:
+   - `workspace-write`: Codex may edit files inside the workspace; no network by default.
+   - `read-only`: Codex can inspect but not change anything.
+   - `danger-full-access`: no sandbox at all, including files outside the workspace and network. Only for trusted tasks.
+   - Put `read-only (Recommended)` first when the request only asks for diagnosis, research, review, or a plan without edits. Otherwise put `workspace-write (Recommended)` first. Never mark `danger-full-access` as recommended.
+
+- Skip the model, effort, and sandbox questions when the user says to use the defaults or not to ask.
+- Applying the answers:
+  - If the user chooses continue, add `--resume` before routing to the subagent.
+  - If the user chooses a new thread, add `--fresh` before routing to the subagent.
+  - `Codex default` means leave that flag unset so the user's Codex config decides.
+  - Otherwise add `--model <choice>`, `--effort <choice>`, or `--sandbox <choice>` to the forwarded request. Map `spark` to `gpt-5.3-codex-spark`.
 
 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.
 - 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 `--effort` unset unless the user explicitly asks for a specific reasoning effort or picks one in the pre-flight question.
+- Leave the model unset unless the user explicitly asks for one or picks one in the pre-flight question. If they ask for `spark`, map it to `gpt-5.3-codex-spark`.
+- Never add `--sandbox danger-full-access` unless the user explicitly asked for it or picked it in the pre-flight question.
 - 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.

plugins/codex/commands/review.md

@@ -1,6 +1,6 @@
 ---
 description: Run a Codex code review against local git state
-argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch]'
+argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [--model <model|spark>] [--effort <none|minimal|low|medium|high|xhigh|max>]'
 disable-model-invocation: true
 allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion
 ---
@@ -34,6 +34,7 @@ Execution mode rules:
 Argument handling:
 - Preserve the user's arguments exactly.
 - Do not strip `--wait` or `--background` yourself.
+- `--model` and `--effort` select the Codex model and reasoning effort for the review; pass them through untouched. When omitted, the user's Codex config decides.
 - Do not add extra review instructions or rewrite the user's intent.
 - The companion script parses `--wait` and `--background`, but Claude Code's `Bash(..., run_in_background: true)` is what actually detaches the run.
 - `/codex:review` is native-review only. It does not support staged-only review, unstaged-only review, or extra focus text.