chore: prepare 1.1.0 skill runtime docs

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cc",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "Claude Code Plugin for Codex. Delegate code reviews, investigations, and tracked tasks to Claude Code from inside Codex.",
   "author": {
     "name": "Sendbird, Inc.",

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v1.1.0
+
+- Restructure the internal Claude runtime and prompt-shaping guidance from pseudo-hidden `SKILL.md` files into plain internal reference documents, while keeping the public `review`, `adversarial-review`, and `rescue` skills self-sufficient on their critical invocation rules.
+- Add a shared internal runtime reference for review/adversarial-review and strengthen the contract tests so installed-root routing, exact `send_input` notification shape, and empty routing-placeholder guards stay locked in across future cleanup passes.
+- Tighten the built-in background forwarding contract so the child must run the companion command as one blocking foreground shell-tool call instead of spawning a background terminal/session of its own, and add E2E coverage for that regression.
+- Remove workstation-specific absolute internal-doc link targets from the public skill docs so source trees, installed copies, and marketplace snapshots all keep valid internal references.
+
 ## v1.0.9
 
 - Add marketplace-aware install foundation for Codex 0.121+: the installer can now prefer `marketplace/add` + `plugin/install` when an official marketplace source is available, while keeping the existing legacy fallback path for unsupported builds.

internal-skills/cli-runtime/SKILL.md → internal-skills/cli-runtime/runtime.md

@@ -1,22 +1,17 @@
----
-name: cli-runtime
-description: Internal execution contract for forwarding one tracked Claude Code rescue task through claude-companion.mjs.
-user-invocable: false
----
+# Claude Code Rescue Runtime Reference
 
-# Claude Code Runtime
-
-Use this skill only inside the rescue forwarding worker spawned by `$cc:rescue`.
-This skill owns execution and routing. It does not own prompt rewriting beyond deciding when to call `task-prompt-shaping`.
+Use this document only inside the rescue forwarding worker spawned by `$cc:rescue` as defined in `../../skills/rescue/SKILL.md`.
+This is an internal execution contract, not a public skill. It owns execution and routing. It does not own prompt rewriting beyond deciding when to consult the prompt-shaping reference.
+The public rescue skill already resolved the installed plugin root. Reuse that installed copy path here. Do not derive a new runtime path from this document, any cache directory, or the current working tree.
 
 Primary helper:
-- `node "<plugin-root>/scripts/claude-companion.mjs" task ...`
+- `node "<installed-plugin-root>/scripts/claude-companion.mjs" task ...`
 
 Execution rules:
 - The rescue subagent is a forwarder, not an operator. Launch exactly one `task` command and return that stdout unchanged.
 - Prefer the helper over hand-rolled Bash, direct Claude Code CLI strings, or any other orchestration path.
 - Never call `setup`, `review`, `adversarial-review`, `status`, `result`, or `cancel` from the rescue forwarder.
-- You may call `task-prompt-shaping` to rewrite the user's request into a tighter Claude Code prompt before the single `task` call.
+- You may consult `../task-prompt-shaping/prompt-shaping.md` to rewrite the user's request into a tighter Claude Code prompt before the single `task` call.
 - That prompt shaping is the only Claude-side work allowed. Do not inspect the repo, solve the task yourself, or add independent analysis.
 
 Command selection:
@@ -34,6 +29,7 @@ Routing controls:
 - `--view-state on-success` means the user will see this companion result in the current turn, so the companion may mark it viewed on success.
 - `--view-state defer` means the parent is not waiting, so the companion must leave the result unread until the user explicitly checks it.
 - `--owner-session-id <session-id>` is an internal parent-session routing control. Preserve it when present so tracked jobs remain visible to the parent session's `$cc:status` / `$cc:result`.
+- Never emit an empty routing placeholder such as `--owner-session-id  --job-id`.
 - Do not add `--quiet-progress` by default for built-in rescue forwarding. Let companion stderr progress remain available in the spawned agent thread.
 - If the free-text task begins with `/`, treat that slash command as literal Claude Code task text to forward unchanged. Do not execute it as a local Codex slash command or answer it inline.
 - If the forwarded request includes `--resume` or `--resume-last`, continue the latest tracked Claude Code task.
@@ -50,5 +46,13 @@ Task defaults:
 - Use a structured file-write path to create that prompt file when possible. Do not solve shell quoting by wrapping the same long task inside another brittle inline shell command.
 - If the tool output includes stderr progress chatter and a final stdout-style result, ignore the progress chatter and preserve only the final stdout-equivalent result text.
 - Return the stdout of the `task` command exactly as-is.
+- Run the companion command as one blocking foreground shell-tool call, not as a background terminal/session.
+- Do not request a shell session id, poll a shell session later, or return before the companion command exits.
+- If the available shell tool is `exec_command`, call it once in non-interactive mode and wait for command exit in that same call.
+- If the parent supplied a non-empty parent thread id for background completion, allow at most one success-only `send_input` notification before finishing.
+- Mention the tool name `send_input` literally when describing that notification path.
+- Use the exact tool shape `send_input({ target: <parent-thread-id>, message: <steering-message> })`.
+- Use steering messages that point the parent at `$cc:result` or `$cc:status` instead of embedding the raw Claude result.
+- For background rescue, use that same steering message as the child's own final assistant message instead of echoing the raw companion result.
 - Do not poll status, fetch results, cancel jobs, or add commentary after the companion output.
 - If the companion reports missing setup or authentication, tell the user to run `$cc:setup`.

internal-skills/review-runtime/runtime.md

@@ -0,0 +1,58 @@
+# Claude Code Review Runtime Reference
+
+Use this document only when the main Codex thread or a built-in forwarding child is executing a Claude Code `review` or `adversarial-review` command.
+This is an internal runtime reference, not a public skill. It captures the exact companion-command contract and the foreground/background execution boundary.
+The public skill already resolved the installed plugin root. Reuse that installed copy path here. Do not derive a new runtime path from this document, any cache directory, or the current working tree.
+
+Primary helper:
+- `node "<installed-plugin-root>/scripts/claude-companion.mjs" review ...`
+- `node "<installed-plugin-root>/scripts/claude-companion.mjs" adversarial-review ...`
+
+Execution boundary:
+- Foreground review stays on the main Codex thread. Do not satisfy foreground review through a review subagent, a generic review-runner role, or any background worker abstraction.
+- Background review uses exactly one built-in forwarding child through `spawn_agent`.
+- Never satisfy either mode with raw `claude`, `claude-code`, `claude review`, hand-rolled `bash -lc ...claude...`, or detached companion shell backgrounding.
+- If the installed companion command fails, surface that failure instead of improvising a different executor.
+
+Foreground contract:
+- Strip `--wait` and `--background` before building the companion command.
+- Foreground command:
+  - `review --view-state on-success ...`
+  - `adversarial-review --view-state on-success ...`
+- Return companion stdout faithfully and do not add review execution commentary around it.
+
+Background contract:
+- Use `background-routing-context --kind review --json` before spawning the forwarding child.
+- Preserve `--job-id` only when reserved by the parent helper.
+- Preserve `--owner-session-id` only when the parent helper returned a non-empty owner session id.
+- Preserve the parent notification path only when the helper returned a non-empty parent thread id.
+- Never emit an empty routing placeholder such as `--owner-session-id  --job-id`.
+- The built-in child runs exactly one shell command:
+  - `review --view-state defer ...`
+  - `adversarial-review --view-state defer ...`
+- The child must be a pure forwarder:
+  - return stdout only
+  - ignore stderr progress chatter such as `[cc] ...`
+  - do not inspect the repo or perform the review itself
+  - run the companion command as one blocking foreground shell-tool call, not as a background terminal/session
+  - do not request a shell session id, poll a shell session later, or return before the companion command exits
+  - if the available shell tool is `exec_command`, call it once in non-interactive mode and wait for command exit in that same call
+  - use at most one `send_input` completion notification on success
+  - mention the tool name `send_input` literally in the child instructions
+  - use the exact tool shape `send_input({ target: <parent-thread-id>, message: <steering-message> })`
+  - do not silently drop the completion notification path when the parent provided a non-empty parent thread id
+
+Spawn-agent defaults:
+- `agent_type: "default"`
+- `fork_context: false`
+- `model: "gpt-5.4-mini"`
+- `reasoning_effort: "medium"`
+- If that model is explicitly unavailable, retry once with `model: "gpt-5.4"` and the same effort.
+
+Completion steering:
+- When a reserved review job id exists, steer to:
+  - `Background Claude Code review finished. Open it with $cc:result <reserved-job-id>.`
+  - `Background Claude Code adversarial review finished. Open it with $cc:result <reserved-job-id>.`
+- Otherwise steer to `$cc:status` first, then `$cc:result`.
+- Use that same steering message as the child's own final assistant message for background mode.
+- Never inline raw review text in the notification or in the child's final assistant message for background mode.

internal-skills/task-prompt-shaping/SKILL.md → internal-skills/task-prompt-shaping/prompt-shaping.md

@@ -1,14 +1,7 @@
----
-name: task-prompt-shaping
-description: Internal prompt-rewriting contract for tightening a rescue request before one forwarded Claude Code task call.
-user-invocable: false
----
+# Claude Code Rescue Prompt Shaping Reference
 
-# Task Prompt Shaping
-
-Use this skill only when the rescue forwarding worker needs to turn the user's request into a tighter Claude Code task prompt before one companion `task` call.
-This skill owns prompt text only. It does not decide execution mode, resume/fresh routing, or any other runtime controls.
-Keep the prompt compact and block-structured. The reference file is optional depth, not required for normal use.
+Use this document only when the rescue forwarding worker needs to turn the user's request into a tighter Claude Code task prompt before one companion `task` call.
+This is an internal prompt-shaping reference, not a public skill. It owns prompt text only. It does not decide execution mode, resume/fresh routing, or any other runtime controls.
 
 Core rules:
 - Prefer one clear task per Claude Code run. Split unrelated asks into separate runs.
@@ -32,12 +25,12 @@ Hard limits:
 - Do not solve the task yourself.
 - Do not add long boilerplate that does not change behavior.
 
-When to use this skill:
+When to use this reference:
 - The raw request is vague, chatty, or underspecified.
 - The request needs a clearer output contract or follow-through default.
 - A follow-up should become a short delta prompt for resume.
 
-When not to use this skill:
+When not to use this reference:
 - The raw request is already clear and compact.
 - The request is so short that rewriting would add more words than value.
 - You would need to inspect the repository first to improve the prompt. Do not do that here.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-plugin-codex",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "Claude Code Plugin for Codex by Sendbird",
   "type": "module",
   "author": {

skills/adversarial-review/SKILL.md

@@ -52,15 +52,20 @@ Argument handling:
 - It does not support `--scope staged` or `--scope unstaged`.
 - Unlike `$cc:review`, it can still take extra focus text after the flags.
 - The companion review process itself always runs in the foreground. Background mode only changes how Codex launches that command.
+- For the detailed execution contract, treat the internal runtime reference at `../../internal-skills/review-runtime/runtime.md` as supporting guidance only. It is an internal reference document, not a public skill to invoke.
 
 Foreground flow:
 - Run:
   `node "<installed-plugin-root>/scripts/claude-companion.mjs" adversarial-review --view-state on-success <arguments with --wait/--background removed>`
+- Foreground adversarial review belongs to the main Codex thread. Do not spawn a review subagent, do not invoke a generic review-runner role, and do not proxy this foreground path through any background worker abstraction.
+- Do not fall back to raw `claude`, `claude-code`, `claude review`, `bash -lc ...claude...`, or any other direct Claude CLI syntax when the companion path is available. The foreground syntax contract here is the installed companion command above, not a hand-rolled Claude invocation.
+- If the installed companion command fails, surface that failure. Do not silently retry foreground adversarial review through a different CLI shape, a generic review runner, or a custom shell wrapper.
 - Present the companion stdout faithfully.
 - Do not fix anything mentioned in the review output.
 
 Background flow:
 - For background adversarial review, use Codex's built-in `default` subagent instead of a detached background shell command.
+- Do not satisfy background adversarial review by using a generic `claude_review_runner`-style helper role, raw Claude CLI, or any other review executor that bypasses the installed companion command.
 - Never satisfy background adversarial review by running the companion command itself with shell backgrounding such as `&`, `nohup`, detached `spawn`, or any equivalent direct background process launch.
 - Background here means "spawn the forwarding child via `spawn_agent` and do not wait in the parent turn." The companion adversarial-review command inside that child still runs once, in the foreground, inside the child thread.
 - Before spawning the built-in child, capture the review job id plus routing context in one call:
@@ -85,6 +90,9 @@ Background flow:
   - run exactly one shell command
   - execute:
     `node "<installed-plugin-root>/scripts/claude-companion.mjs" adversarial-review --view-state defer <arguments with --wait/--background removed>`
+  - run that command as one blocking foreground shell-tool call, not as a background terminal/session
+  - do not request a shell session id, poll a shell session later, or return before the companion command exits
+  - if the available shell tool is `exec_command`, call it once in non-interactive mode and wait for command exit in that same call
   - include `--owner-session-id <owner-session-id>` only when the parent resolved a non-empty owner session id
   - include `--job-id <reserved-job-id>` when the parent reserved one
   - never leave an empty routing placeholder such as `--owner-session-id  --job-id`

skills/rescue/SKILL.md

@@ -82,9 +82,10 @@ Subagent launch:
 - 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 `task-prompt-shaping` internal rules as guidance for that parent-side tightening:
+- 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>`
@@ -119,6 +120,9 @@ Subagent launch:
 - 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
+  - run that command as one blocking foreground shell-tool call, not as a background terminal/session
+  - do not request a shell session id, poll a shell session later, or return before the companion command exits
+  - if the available shell tool is `exec_command`, call it once in non-interactive mode and wait for command exit in that same call
   - for foreground rescue only, tell the child to return that command's stdout text exactly, with no preamble, summary, code fence, trimming, normalization, or punctuation changes
   - tell the child to ignore stderr progress chatter such as `[cc] ...` lines and preserve only the stdout-equivalent final result text
   - if a parent thread id is provided for experimental background notification, allow one extra `send_input` call after a successful shell result and before finishing