From 82ec7206db216814329b157535021ea5aae2d028 Mon Sep 17 00:00:00 2001 From: Scott Compel Date: Tue, 4 Aug 2026 17:00:01 -0600 Subject: [PATCH] docs(codex): document --cwd routing, deterministic --wait/--background stripping, non-interactive resume guard - Document --cwd as a routing control on the rescue path in the agent, skill, and command docs: strip from task text, forward to task, scoping parallel rescue runs and --resume-last threads per worktree - State explicitly that --background/--wait are Claude-side execution controls that are always stripped and never forwarded to task - Skip the resume-candidate AskUserQuestion in non-interactive sessions or when --cwd is present; route as --fresh unless --resume was given Co-Authored-By: Claude Fable 5 --- plugins/codex/agents/codex-rescue.md | 2 ++ plugins/codex/commands/rescue.md | 6 ++++-- plugins/codex/skills/codex-cli-runtime/SKILL.md | 3 ++- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/plugins/codex/agents/codex-rescue.md b/plugins/codex/agents/codex-rescue.md index 7009ec86a..429ff19fc 100644 --- a/plugins/codex/agents/codex-rescue.md +++ b/plugins/codex/agents/codex-rescue.md @@ -31,6 +31,8 @@ Forwarding rules: - 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 ` and `--model ` as runtime controls and do not include them in the task text you pass through. +- `--background` and `--wait` are Claude-side execution controls. Always strip them from the task text and never forward them to `task`. +- Treat `--cwd ` as a routing control: strip it from the task text and pass it through to `task` as `--cwd `. It targets the Codex run at a specific working tree (typically an isolated git worktree) so parallel rescue runs never collide; the companion's job state and `--resume-last` threads are scoped per `--cwd` repository root. - 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 `--resume` and `--fresh` as routing controls and do not include them in the task text you pass through. - `--resume` means add `--resume-last`. diff --git a/plugins/codex/commands/rescue.md b/plugins/codex/commands/rescue.md index 56de9555d..dc65e8bd4 100644 --- a/plugins/codex/commands/rescue.md +++ b/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 ] [--effort ] [what Codex should investigate, solve, or continue]" +argument-hint: "[--background|--wait] [--resume|--fresh] [--cwd ] [--model ] [--effort ] [what Codex should investigate, solve, or continue]" allowed-tools: Bash(node:*), AskUserQuestion, Agent --- @@ -16,10 +16,12 @@ 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. +- `--background` and `--wait` are execution flags for Claude Code. Always strip them. 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. +- `--cwd ` is a routing flag. Preserve it for the forwarded `task` call as `--cwd `, but do not treat it as part of the natural-language task text. It targets the Codex run at a specific working tree (typically an isolated git worktree) so parallel rescue runs never collide; the companion's job state and `--resume-last` threads are scoped per `--cwd` repository root. - 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. +- If the session is non-interactive (no human available to answer a question) or the request includes `--cwd`, do not ask whether to continue. Route as `--fresh` unless `--resume` was given. - Otherwise, before starting Codex, check for a resumable rescue thread from this Claude session by running: ```bash diff --git a/plugins/codex/skills/codex-cli-runtime/SKILL.md b/plugins/codex/skills/codex-cli-runtime/SKILL.md index 0e91bfb50..1d59f93c1 100644 --- a/plugins/codex/skills/codex-cli-runtime/SKILL.md +++ b/plugins/codex/skills/codex-cli-runtime/SKILL.md @@ -25,7 +25,8 @@ Execution rules: Command selection: - Use exactly one `task` invocation per rescue handoff. -- 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. +- If the forwarded request includes `--background` or `--wait`, treat that as Claude-side execution control only. Always strip it before calling `task` — never forward either flag to `task` — and do not treat it as part of the natural-language task text. +- If the forwarded request includes `--cwd `, treat that as a routing control: strip it from the task text and pass it through to `task` as `--cwd `. It targets the Codex run at a specific working tree (typically an isolated git worktree) so parallel rescue runs never collide; the companion's job state and `--resume-last` threads are scoped per `--cwd` repository root. - If the forwarded request includes `--model`, normalize `spark` to `gpt-5.3-codex-spark` and pass it through to `task`. - If the forwarded request includes `--effort`, pass it through to `task`. - If the forwarded request includes `--resume`, strip that token from the task text and add `--resume-last`.