rescue

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Claude Code Rescue

By default, hand this skill off through Codex's built-in `default` subagent.
Do not answer the request inline in the main Codex thread.
Spawn exactly one rescue forwarding subagent whose only job is to run one companion `task` command and return that stdout unchanged.
Foreground rescue responses must be that subagent's output verbatim.

Use this skill when the user wants Claude Code to investigate, implement, or continue substantial work in this repository.

Prefer `$cc:rescue` when the user wants Claude Code to diagnose the issue, validate a risky change by actually editing or testing, apply fixes from a prior review, or carry a task forward across multiple steps.
Do not use rescue for "just review this diff" unless the user also wants follow-through work beyond review findings.
Do not use rescue merely because the main Codex thread plans to fix things after combining its own review with a separate Claude review. Rescue is only the right delegation when Claude itself is supposed to investigate, edit, test, or otherwise own the follow-through work.

Resolve `<plugin-root>` as two directories above this `SKILL.md` file. Always run the companion from that active plugin root:
`node "<plugin-root>/scripts/claude-companion.mjs" task ...`

Raw slash-command arguments:
`$ARGUMENTS`

Supported arguments: `--background`, `--wait`, `--resume`, `--resume-last`, `--fresh`, `--write`, `--model <model>`, `--effort <low|medium|high|xhigh|max>`, `--prompt-file <path>`, plus free-text task text

Companion defaults: model=opus, and no effort. The companion forwards `--effort` only when the user passes it, so `fable`, `opus`, `sonnet`, and `haiku` each keep Claude Code's own effort default. Claude Code owns which effort levels each model supports.

Forward `--model` unchanged to the companion. The companion trims surrounding whitespace, canonicalizes the friendly aliases `fable`, `opus`, `sonnet`, and `haiku` to lowercase, then forwards every other `--model` value unchanged to Claude Code. Claude Code owns alias resolution and supported effort levels; `/model` is the authoritative picker for the current account and provider.

Main-thread routing rules:
- If the user explicitly invoked `$cc:rescue` or `Claude Code Rescue`, do not keep the work in the main Codex thread. Delegate it.
- If the user did not supply a task, ask what Claude Code should investigate or fix.
- Treat `--background` and `--wait` as execution controls, not task text.
- `--background` and `--wait` are Codex-side execution controls only. Never forward either flag to `claude-companion.mjs task`.
- The main Codex thread owns that execution-mode choice. It decides whether to wait for the subagent. The child subagent must never reinterpret those flags as companion flags.
- Treat `--model`, `--effort`, `--resume`, `--resume-last`, `--fresh`, and `--prompt-file` as runtime or routing controls, not task text.
- If the user task text itself begins with a slash command such as `/simplify`, `/fix`, or `/review`, treat that slash command as literal Claude Code task text to be forwarded unchanged. Do not execute or reinterpret it in the parent Codex thread.
- `--model` selects the Claude model for the companion `task` command only. It does not select the Codex subagent model.
- If the user explicitly passed `--background`, run the rescue subagent in the background.
- If the user explicitly passed `--wait`, run in the foreground.
- If neither flag is present and the rescue request is small, clearly bounded, or likely to finish quickly, prefer foreground.
- If neither flag is present and the request looks complicated, open-ended, multi-step, or likely to keep Claude Code running for a while, prefer background execution for the subagent.
- This size-and-scope heuristic belongs to the main Codex thread. The child subagent does not get to override it.
- If `--resume` or `--resume-last` is present without `--wait`, and the new instruction is substantial, open-ended, or likely to take more than a quick follow-up, the main thread should usually prefer background execution for the subagent. Keep that as a parent-side choice only. Do not inject `--background` into the child request or the companion command.
- Default to `--write` unless the user explicitly wants read-only behavior or only review, diagnosis, or research without edits.
- If `--resume` or `--resume-last` is present, continue the latest tracked Claude Code task. If `--fresh` is present, start a new task.
- If none of `--resume`, `--resume-last`, or `--fresh` is present, first run:
  `node "<plugin-root>/scripts/claude-companion.mjs" task-resume-candidate --json`
- If that helper reports `available: true`, ask the user once whether to continue the current Claude Code thread or start a new one.
- Use exactly these two choices:
  - `Continue current Claude Code thread`
  - `Start a new Claude Code thread`
- If the user's wording is clearly a follow-up such as "continue", "keep going", "resume", "apply the top fix", or "dig deeper", recommend `Continue current Claude Code thread` first.
- Otherwise recommend `Start a new Claude Code thread` first.
- If the user chooses continue, add `--resume` before spawning the subagent.
- If the user chooses a new thread, add `--fresh` before spawning the subagent.
- If the helper reports `available: false`, do not ask. Delegate normally.
- Do not inspect the repo, do the task yourself, poll job status, or summarize the result in the same turn.
- If a legacy request still includes `--notify-parent-on-complete`, treat it as a compatibility alias. Background built-in rescue now attempts parent wake-up by default.

Subagent launch:
- By default, use Codex's `spawn_agent` tool. Omit `agent_type`; an omitted `agent_type` already selects the built-in default agent, and Codex only advertises that parameter when custom agents are configured.
- Never satisfy background rescue by launching `claude-companion.mjs task` itself as a detached shell process. Do not use `&`, `nohup`, detached `spawn`, or any equivalent direct background process launch from the parent.
- If a legacy request still includes `--builtin-agent`, treat it as a compatibility alias for the default built-in path. It should not change behavior.
- Prefer `fork_context: false` for the built-in rescue child. The parent should pass a self-contained forwarding message instead of replaying the full parent thread by default.
- Only consider `fork_context: true` as a last resort for a short follow-up where essential context truly cannot be summarized. Avoid it for large or long-lived threads because it can exhaust the child context window.
- The built-in rescue path must omit `model` on `spawn_agent` so the child inherits the parent model, and must set `reasoning_effort: "medium"` so the transient forwarding child stays cheap and predictable. Never pin a specific Codex model name here; the available catalog is owned by the host CLI and changes between releases.
- Before spawning the built-in child, emit one short commentary update that clearly says the parent is starting the built-in rescue child on the inherited model at `medium` effort.
- Remove `--background` and `--wait` before spawning the subagent. Those flags control only whether the main thread waits on the subagent.
- Pass only the routing and task arguments that actually belong to `claude-companion.mjs task`.
- If the free-text task begins with `/`, preserve it verbatim in the spawned subagent request. Do not strip the slash or rewrite it into a local Codex command.
- Before spawning the built-in child, capture the task job id plus routing context in one call:
  `node "<plugin-root>/scripts/claude-companion.mjs" background-routing-context --kind task --json`
- If that helper returns a non-empty `ownerSessionId`, include `--owner-session-id <owner-session-id>` in the companion command so tracked Claude Code jobs stay attached to the user-facing parent session for `$cc:status` / `$cc:result`.
- If it returns an empty `ownerSessionId`, omit `--owner-session-id` entirely. Never leave an empty routing placeholder such as `--owner-session-id  --job-id`.
- If that helper returns a non-empty `jobId`, pass it into the companion command as an internal `--job-id <reserved-job-id>` routing flag.
- Whenever forwarding that reserved `--job-id`, also pass `--cwd <workspace-root>` using `workspaceRoot` from the same helper response. Reserved job ids are workspace-scoped.
- Add an internal companion routing flag that reflects whether the user will see this result in the current turn:
  - Foreground rescue must add `--view-state on-success`
  - Background rescue must add `--view-state defer`
- Any user-supplied `--model` flag is for the Claude companion only and must be forwarded unchanged to `task`.
- If that helper returns a non-empty `parentThreadId`, pass it into the child prompt as the parent thread id for one-shot completion notification.
- If it returns an empty `parentThreadId`, continue without parent wake-up instead of blocking the rescue.
- This parent wake-up attempt is now the default for background built-in rescue on persistent Codex/Desktop threads. It is still best-effort and should silently degrade on one-shot `codex exec` runs.
- For the built-in rescue path, the parent thread owns prompt shaping. The built-in child should stay a pure executor.
- For the built-in rescue path, treat the internal runtime reference at `../../internal-skills/cli-runtime/runtime.md` as the command-building contract for the forwarding worker. It is an internal reference document, not a public skill to invoke.
- If the built-in rescue request is vague, chatty, or a follow-up, the parent may tighten only the task text before composing the exact companion command.
- Prefer passing a small structured `<parent_context>` block instead of forked thread history when the child needs a little prior context.
- Use the internal prompt-shaping reference at `../../internal-skills/task-prompt-shaping/prompt-shaping.md` as deeper guidance for that parent-side tightening. It is an internal reference document, not a public skill to invoke.
  - preserve user intent and add no new repo facts
  - prefer a short delta instruction for resume follow-ups
  - when helpful, use compact blocks such as `<task>`, `<output_contract>`, and `<default_follow_through_policy>`
  - do not add more words than value for already-clear requests
- Parent-side shaping should be conservative and specific:
  - If the request is already concrete, keep it literal.
  - If the request names a concrete file, path, or artifact such as `README.md`, and also includes explicit source/style/installation constraints, keep the full task text literal apart from stripping routing flags. Do not compress it into a shorter delta.
  - If the request refers to earlier work, rewrite it into a short delta that names the next thing Claude Code should change or inspect.
  - If the user asks for "fix it", "keep going", or similar follow-ups, make the next objective explicit without inventing repo facts.
  - If the user asks in mixed language, preserve the language mix and only tighten the execution intent.
  - If the user implies an output format, make that output contract explicit instead of broadening the task.
- For `--resume`, `--resume-last`, vague follow-ups, or ambiguous continuation requests, prefer adding a compact `<parent_context>` block before the task command instead of relying on inherited history.
- Keep `<parent_context>` small and structured. Good fields include:
  - `mode` (`fresh` or `resume`)
  - `job_id` when the parent reserved one
  - `claude_session` when a resumable Claude session is already known
  - `previous_summary` only when the parent can state it tersely from tracked metadata
  - `next_delta` for the exact next objective
  - `constraints` only when they are explicit and still binding
- Do not use `<parent_context>` for already-clear fresh tasks unless it adds real value.
- Keep `<parent_context>` deterministic and short. Do not turn it into a free-form summary of the whole parent thread.
- For the built-in rescue path, parent-side shaping must happen before the command is handed to the child. The child must not do an additional interpretation pass.
- If the resolved rescue task text is shell-hostile or likely to break a single inline shell string, materialize it into a temporary prompt file first and use `--prompt-file` instead of embedding the task directly in the command.
- Treat any of the following as prompt-file triggers unless the user already supplied `--prompt-file`:
  - multi-line task text
  - single quotes, backticks, or XML-style blocks such as `<task>` / `<output_contract>`
  - long concrete requests where inline shell quoting would be brittle
- When using a prompt file, preserve the exact resolved task text byte-for-byte in that file and point the companion command at that file with an absolute `--prompt-file` path.
- Prefer a temporary path outside the repository checkout, for example under the OS temp directory such as `/tmp` on POSIX systems, so rescue prompt staging does not dirty the repo.
- Materialize that prompt file with a normal file-write tool or other structured write path. Do not try to generate it by re-embedding the long task text inside another fragile one-line shell string.
- If the user is not satisfied with a built-in rescue result, the parent should treat the next rescue request as a follow-up and prefer `--resume` or `--resume-last` with a short delta instruction when a resumable Claude Code session exists.
- The built-in rescue path must use a compact strict forwarding message. It must:
  - identify the child as a transient forwarding worker for Claude Code rescue
  - include exactly one shell command to run

From sendbird/cc-plugin-codex, Apache-2.0.

More from sendbird/cc-plugin-codex