pi-cli-runtime

pi-cli-runtime is an internal, non-user-invocable helper contract that defines exactly how Claude Code should call the pi-companion runtime from inside the pi:pi-rescue subagent. Rather than performing analysis itself, it turns the rescue subagent into a thin forwarder whose only job is to invoke a single companion command once and return that command's standard output unchanged. It solves a narrow orchestration problem: giving a subagent one precise, safe way to hand a rescue request off to an external Pi runtime without hand-rolling git commands or ad-hoc CLI strings.

The contract specifies the primary helper invocation (a Node script under the plugin root called with a single task command and the raw arguments) and a detailed set of execution, command-selection, and safety rules. It covers how to translate routing flags -- stripping Claude-side execution controls like background and wait, passing model and effort through unchanged, mapping resume to a resume-last run and fresh to a new run -- and defines the accepted effort levels. It defaults to a write-capable Pi run unless the user explicitly asks for read-only, review, diagnosis, or research only.

The intended audience is authors and operators of the pi plugin's rescue workflow, not end users; the skill is marked user-invocable false and is meant to run only inside the pi:pi-rescue subagent. Its safety posture is strict and self-limiting: the forwarder must preserve the user's task text apart from routing flags, must not inspect the repository, read files, grep, poll status, fetch results, or add its own analysis, and must return nothing if the underlying command fails. It is a routing and contract specification rather than a standalone tool.