# Pi runner reference

Treat examples as possibly outdated; inspect installed help first and prefer
observed behavior over this file.

## Help surfaces

- Top-level help: `pi --help`
- Model listing shape to verify: `pi --list-models [search]`
- Non-interactive prompt shape to verify: `pi -p "..."`
- Model target shape to verify: `--model provider/model`
- Provider shape to verify: `--provider name`

Record the exact help commands inspected and any differences from this file in
`runner_capabilities`.

## Eligibility

Skip ordinary Pi by default unless the user indicates they have installed an
extension or equivalent guardrail compatible with Crosscheck's current runner
eligibility. Pi allows the LLM agent to do anything by default, so Crosscheck
must not consider Pi safe without observed evidence.

When the user claims an eligible Pi mode exists:

- inspect help and extension/profile surfaces before use;
- record the exact guardrail evidence;
- record whether extensions or tools can widen capabilities;
- prefer disabled extensions unless the eligible mode depends on one;
- note that the extension may not register flags/env vars/additional help
  output, so if the user doesn't describe the read-only guardrails and how to
  use them, and you don't find them in any output, assume pi has full user
  privileges and is not suitable.

## Model availability

- Use the model-listing command only after help confirms it exists.
- Preserve exact model IDs and provider names accepted by Pi.
- Record user-pinned IDs as candidates, not proof of availability, unless Pi
  lists or accepts them.

## Pi as the Prose VM or review runner

Use Pi only after eligibility is established. Run from the repository being
reviewed when Pi is the Prose VM, and from the lane or validator workspace copy
when Pi is a runner. Capture stdout as the report.