codex-cli-runtime

name	codex-cli-runtime
preamble-tier	4
version	1.0.0
description	Internal helper contract for calling the codex-companion runtime from the codex-rescue subagent. Not user-invocable.
user-invocable	false
allowed-tools	["Bash"]

Preamble (run first)

# === RKstack Preamble (codex-cli-runtime) ===

# Read detection cache (written by session-start via rkstack detect)
if [ -f .rkstack/settings.json ]; then
  cat .rkstack/settings.json
else
  echo "WARNING: .rkstack/settings.json not found — detection cache missing"
fi

# Session-volatile checks (can change mid-session)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_HAS_CLAUDE_MD=$([ -f CLAUDE.md ] && echo "yes" || echo "no")
echo "BRANCH: $_BRANCH"
echo "CLAUDE_MD: $_HAS_CLAUDE_MD"

Use the detection cache and preamble output to adapt your behavior:

• TypeScript/JavaScript — see detection.flowType (web or default). If web: check React/Vue/Svelte patterns, responsive design, component architecture. If default: CLI tools, MCP servers, backend scripts.
• Python — backend/ML/scripts. Check PEP8 conventions, pytest for testing.
• Go — backend/infra. Check error handling patterns, go test.
• Rust — systems. Check ownership patterns, cargo test.
• Java/C# — enterprise. Check build tool (Maven/Gradle/.NET), framework conventions.
• Ruby — web/scripting. Check Gemfile, Rails conventions if present.
• Terraform/HCL — infrastructure as code. Plan before apply, extra caution with state.
• Ansible — configuration management. Check inventory, role conventions, vault usage.
• Docker/Compose — containerized. Check service dependencies, .env patterns.
• justfile — task runner present. Use just commands instead of raw shell.
• mise — tool version manager. Versions are pinned — don't suggest global installs.
• CLAUDE.md exists — read it for project-specific commands and conventions.
• Read detection.stack for what's in the project and detection.stats for scale (files, code, complexity).
• Read detection.repoMode for solo vs collaborative.
• Read detection.services for Supabase and other service integrations.

AskUserQuestion Format

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, the current branch (use the _BRANCH value from preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work.
4. Options: Lettered options: A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Completeness Principle

AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with AI. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.

Effort reference — always show both scales:

Task type	Human team	CC + AI	Compression
Boilerplate	2 days	15 min	~100x
Tests	1 day	15 min	~50x
Feature	1 week	30 min	~30x
Bug fix	4 hours	15 min	~20x

Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).

Repo Ownership

REPO_MODE (from preamble) controls how to handle issues outside your branch:

• solo — You own everything. Investigate and offer to fix proactively.
• collaborative / unknown — Flag via AskUserQuestion, don't fix (may be someone else's).

Always flag anything that looks wrong — one sentence, what you noticed and its impact.

Search Before Building

Before building anything unfamiliar, search first.

• Layer 1 (tried and true) — standard patterns, built-in to the runtime/framework. Don't reinvent.
• Layer 2 (new and popular) — blog posts, trending approaches. Scrutinize — people follow hype.
• Layer 3 (first principles) — your own reasoning about the specific problem. Prize above all.

When first-principles reasoning contradicts conventional wisdom, name the insight explicitly.

Completion Status

When completing a skill workflow, report status using one of:

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."

Bad work is worse than no work. You will not be penalized for escalating.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

Escalation format:

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

Codex Runtime

Use this skill only inside the codex-rescue subagent.

Primary helper

node "${CLAUDE_PLUGIN_ROOT}/scripts/codex/codex-companion.mjs" task "<raw arguments>"

Execution rules

• The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke task once and return that stdout unchanged.
• Prefer the helper over hand-rolled git, direct codex CLI strings, or any other Bash activity.
• Do not call setup, review, adversarial-review, status, result, or cancel from codex-rescue.
• Use task for every rescue request, including diagnosis, planning, research, and explicit fix requests.
• You may use the gpt-5-4-prompting skill to rewrite the user's request into a tighter Codex prompt before the single task call.
• That prompt drafting is the only Claude-side work allowed. Do not inspect the repo, solve the task yourself, or add independent analysis outside the forwarded prompt text.
• Leave --effort unset unless the user explicitly requests a specific effort.
• Leave model unset by default. Add --model only when the user explicitly asks for one.
• Map spark to --model gpt-5.3-codex-spark.
• 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.

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 --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.
• If the forwarded request includes --fresh, strip that token from the task text and do not add --resume-last.
• --resume: always use task --resume-last, even if the request text is ambiguous.
• --fresh: always use a fresh task run, even if the request sounds like a follow-up.
• --effort: accepted values are none, minimal, low, medium, high, xhigh.
• task --resume-last: internal helper for "keep going", "resume", "apply the top fix", or "dig deeper" after a previous rescue run.

Safety rules

• Default to write-capable Codex work in codex-rescue unless the user explicitly asks for read-only behavior.
• Preserve the user's task text as-is apart from stripping routing flags.
• 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.
• Return the stdout of the task command exactly as-is.
• If the Bash call fails or Codex cannot be invoked, return nothing.