1# Pi runner reference
 2
 3Treat examples as possibly outdated; inspect installed help first and prefer
 4observed behavior over this file.
 5
 6## Help surfaces
 7
 8- Top-level help: `pi --help`
 9- Model listing shape to verify: `pi --list-models [search]`
10- Non-interactive prompt shape to verify: `pi -p "..."`
11- Model target shape to verify: `--model provider/model`
12- Provider shape to verify: `--provider name`
13
14Record the exact help commands inspected and any differences from this file in
15`runner_capabilities`.
16
17## Eligibility
18
19Skip ordinary Pi by default unless the user indicates they have installed an
20extension or equivalent guardrail compatible with Crosscheck's current runner
21eligibility. Pi allows the LLM agent to do anything by default, so Crosscheck
22must not consider Pi safe without observed evidence.
23
24When the user claims an eligible Pi mode exists:
25
26- inspect help and extension/profile surfaces before use;
27- record the exact guardrail evidence;
28- record whether extensions or tools can widen capabilities;
29- prefer disabled extensions unless the eligible mode depends on one;
30- note that the extension may not register flags/env vars/additional help
31  output, so if the user doesn't describe the read-only guardrails and how to
32  use them, and you don't find them in any output, assume pi has full user
33  privileges and is not suitable.
34
35## Model availability
36
37- Use the model-listing command only after help confirms it exists.
38- Preserve exact model IDs and provider names accepted by Pi.
39- Record user-pinned IDs as candidates, not proof of availability, unless Pi
40  lists or accepts them.
41
42## Pi as the Prose VM or review runner
43
44Use Pi only after eligibility is established. Run from the repository being
45reviewed when Pi is the Prose VM, and from the lane or validator workspace copy
46when Pi is a runner. Capture stdout as the report.