/multi-cli-runtime

name: multi-cli-runtime
description: Internal helper contract for calling the multi-cli-companion runtime from any multi:* subagent
user-invocable: false

Multi-CLI Runtime

Use this skill only inside `multi:*` forwarding subagents (`codex-execute`, `cursor-delegate`, `cursor-research`, `cursor-explore`, `antigravity-researcher`, `antigravity-explorer`, `opencode-delegate`, `opencode-researcher`, `opencode-explorer`, etc.).

Primary helper

`node "${CLAUDE_PLUGIN_ROOT}/scripts/multi-cli-companion.mjs" task --cli <cli> --role <role> [flags] --prompt "<text>"`

Where `<cli>` is one of `codex|cursor|antigravity|opencode` (or any CLI added via the `multi-cli-anything` skill) and `<role>` is the subagent's logical role. Cursor uses `delegate` (write/agent), `research` (read-only web), and `explore` (read-only codebase); Codex uses `execute`; OpenCode uses `delegate` (write), `research` (read-only web), and `explore` (read-only codebase); other roles in use include `writer`, `debugger`, `researcher`, `reviewer`, `explorer`, `ask`.

Execution rules

• Each `multi:*` subagent is a forwarder, not an orchestrator. Its only job is to invoke the companion once and return that stdout unchanged.
• Prefer the helper over hand-rolled `git`, direct CLI strings (`cursor agent acp`, `codex exec`), or any other Bash activity.
• Use exactly one Bash call per subagent dispatch. Do not chain `cat`, `sleep`, polling loops, or follow-up `node` calls.

Routing flag handling

Treat these as runtime controls — strip them from the task text before forwarding, then re-add them as flags on the companion call:

• `--background` / `--wait` — `--wait`/foreground is the default and is what you should run: the companion blocks until the CLI finishes, so your Bash call returns the real result. For long-running work, the PARENT command schedules background execution by running this subagent as a harness background task (which notifies the main thread on completion/failure) — NOT by passing `--background`. The companion's `--background` detaches a worker the harness can't see (no notification) and is only for explicit user-requested fire-and-forget polled via `/multi:status`.
• `--model <name>` — pass through verbatim. Leave unset unless the user explicitly asked for a model. (Antigravity ignores `--model`: its headless `agy -p` path is fixed to Gemini 3.5 Flash.)
• `--effort <level>` — only Codex accepts this (`none|minimal|low|medium|high|xhigh`). Other adapters ignore it. Pass through verbatim if present.
• `--resume` — translate to `--resume-last`.
• `--fresh` — do not add `--resume-last`, even if the user's text sounds like a follow-up.
• `--write` — default to `--write` for execute/delegate/writer/debugger/reviewer roles (these need to edit files); for read-only roles (research/explore/planner/researcher/explorer/ask) pass `--read-only` instead (it forces write off even if `--write` is also present). Honor explicit user override either way.
• `--until-done` — Codex, Cursor, and OpenCode. Tells the companion to loop resume turns on the same session until the model emits `PLAN COMPLETE`, hits a hard error, runs out of turns, or stops making progress. Pass through verbatim when the user opts in. Default off — only set when the user explicitly asked for autonomous run-until-done behavior. Antigravity rejects this flag. **Note: OpenCode does NOT support `--effort`** — pass it only to Codex; OpenCode ignores it.
• **OpenCode role note:** OpenCode has no `--read-only` flag. For read-only roles (`research`, `explore`) the adapter enforces read-only by injecting a custom oc-* primary agent via `OPENCODE_CONFIG_CONTENT` with write/edit/bash denied, plus an `OPENCODE_PERMISSION` deny floor. Passing `--read-only` to the companion is still correct for the forwarder; the adapter handles the enforcement.
• `--max-turns <N>` — Codex and Cursor. Sets the autonomous-mode turn ceiling (default 30). Requires `--until-done`. Pass through verbatim if present.
• `--plan <path>` and `--prompt-file <path>` — both load the prompt body from a file. `--plan` is the user-facing alias; the companion's actual flag is `--prompt-file`. Translate `--plan` to `--prompt-file` on the Bash call. When either flag is present:

1. The file's bytes ARE the prompt — do NOT paste a framing block in front of them. Skip the role-specific preamble entirely. 2. Any positional task text the user provided is treated as an *addendum* and gets appended after the file content as a separate paragraph (the companion handles this via positional args after `--prompt-file`). 3. The path resolves relative to the companion's `--cwd` if set, else CWD. Absolute paths always work. See `multi-plan-handoff` skill for when Claude (the parent thread) should auto-add `--plan` based on conversation context.

Capturing diagnostics

Always append `2>&1` to the Bash call so the parent thread can see runtime diagnostics if the companion fails.

Safety rules

• Preserve the user's task text as-is apart from stripping routing flags and prepending the subagent's role-specific framing block.
• 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 the upstream CLI cannot be invoked, return a single short failure line: `<CLI> <role> failed: <one-line reason from stderr or "no output">`. Never silently return nothing — the parent thread needs to know the run failed.
• On failure, the failure line is your ENTIRE response. Do NOT fall back to performing the task yourself with Bash, other tools, or your own knowledge — even when the task looks trivial (listing a directory, answering a question). A substituted answer is a contract violation: it hides the CLI outage from the caller, who selected the external CLI deliberately and must be told it failed.
• If the user asks for `setu