Configuration Cookbook

You prefer Sonnet for everyday work in auto mode:

Only the fields you set change; everything else about auto (its rules, judge, guards) comes from the package.

The first entry in cycle is the startup mode. With applyOnStartup off (the default) a fresh session keeps whatever model you had; a mode you were in when you closed pi is always restored either way.

By default a mode applies its declared model — plan pairs deep reasoning with read-only investigation, and that pairing is part of what the mode is. The switch is announced, never silent — to you as a notice, and to the model as a message in its context (gadhs-mode-change, naming both modes and any model swap), because a model cannot tell a recomposed system prompt from its own assumptions and once insisted it was still in plan mode after a /mode auto. Startup is the exception: the mode a session opens in is applied quietly. If you would rather a model you chose in-session survive mode switches:

With sticky on, a model you picked (with /model, or your configured pi default) rides through mode switches, and the notice tells you what the mode default would have been. A model that a mode itself set still gives way to the next mode’s default — sticky protects choices, not defaults.

Set it to null to have no shortcut. (Shift+Tab is taken by pi itself.)

A "demo" mode: fast model, no thinking, judge on a short leash:

Remember to add the new id to cycle, or /mode next will skip it.

Your team never wants the agent touching Kubernetes:

deny is instant and final — no model, no prompt. The agent is told why.

ask means "let the judge look at it" (or you, in manual mode):

Rules are matched most-specific-wins, so a longer pattern can carve an exception out of a shorter one. The shipped rules refuse reads under /.ssh/; this lets the harmless known_hosts file through while keys stay refused:

Two rules for authoring patterns:

The shipped judge is Sonnet 4.6 at low; Haiku 4.5 reads within three verdicts of it on the battery’s corpus and is what shipped before #102, so it is the natural alternative. A judge block replaces the mode’s whole judge, so name every field you want kept.

With deny-only, anything the judge would have approved comes to you instead. Good while you are building trust in a new setup.

The prompt can be a file path or inline text. Keep it short and mechanical — rubric attention is finite, and a verbose clause spends it on the wrong cases: we have measured a five-line addition to one bullet flipping the verdict on an unrelated case, and halving the wording removing the regression. After any rubric change, re-run the whole corpus (task eval --repeat 3), not just the cases you were aiming at.

Valve patterns stay interactive in every mode, including yolo. The shipped list covers force pushes, pushes to main, tags, publishes, merges, and --no-verify.

If the agent gets refused 3 times in a row (or 20 in a session), everything starts coming to you instead — a sign something is off. Adjust or disable:

(0 disables that limit.)

Three provider ids from one package, one config file, the same ADC, no login: vertex-anthropic/… (Claude), vertex-gemini/… (Gemini 3.8, 3.7, 3.5 Flash, 3.1 Pro Preview, 2.5 Pro) and vertex-maas/… (gpt-oss 120B, Grok 4.20, Kimi K2 Thinking, Qwen3 Coder, Qwen3-Next Thinking, Qwen3 235B, MiniMax M2). /model lists them all on install. A model’s publisher kind in the catalog decides which id it lives under; you never configure Gemini one way and Claude another.

Any model, any time — with one rule: the context has to fit. Switching a long session into a model with a smaller window gets a warning with the numbers and an offer to compact where you came from first; /new is the clean slate. Details: modes.adoc#_switching_to_a_model_the_context_does_not_fit.

~/.pi/agent/vertex-models.json replaces the catalog. Run node probe.mjs (ships with the package; --publisher google|maas|anthropic for one kind) to discover which models your project can actually reach, and in which regions — it prints a ready-to-use catalog with the publisher kind filled in. An entry for a Gemini or MaaS model is three lines:

(That one moves 3.8 Flash from global to the us multi-region, which it also answers from — a US-residency posture in one edit.)

When your Google session expires mid-task, pi does not fail the task — it tells you to run gcloud auth application-default login and retries on a timer until you have, for as long as the turn is alive; pressing escape is what ends it. Tune the poll, cap the wait, or disable:

(Defaults: every 60 s, no cap. maxWaitMs is opt-in: set, the turn ends on the original error after that long and the notice says it gave up. intervalMs: 0 disables.)

Under pi --mode rpc — an IDE plugin, pi-web-ui, a daemon, the pivot client — there may be no one to answer a dialog, or someone on a phone who needs a minute. Two waits, in the modes overlay (~/.pi/agent/gadhs-pi-modes.json or GADHS_PI_MODES_CONFIG):

gateTimeoutMs (default 30 s) is how long the host gets to confirm a permission ask the gate deferred; silence denies. dialogTimeoutMs (default 10 min) is how long it gets to approve a plan or answer ask; silence refuses. Either at 0 means do not ask at all - the gate denies without the confirm, the approval and ask refuse without the dialog (pi itself would read a zero timeout as none). Neither applies in the terminal, where a human is at the keyboard and dialogs do not time out. See what changes at a headless host.

When the session’s provider refuses the summarization request - a policy classifier blocking it, not a model failing; Anthropic’s has done this to a long session full of quoted model output - retrying there is futile, and pi’s default compaction is the same call. The summary is then written once on a fallback from another provider family:

That is the default. null turns the fallback off; the warning then names the way out by hand (/model to another provider, /compact, /model back). Any provider/model the registry knows is accepted; the session’s own model is never used as its own fallback. A transport error or a length stop is not a refusal and does not reach this. See when the provider refuses the request.

The cold review is an upper-bounded call. The default bound is ten minutes — a backstop against a dead connection, not a budget: a reviewer thinking hard over a large diff is doing its job, and a model with a real problem returns an error rather than hanging. If the bound ever fires, the commit proceeds with no cold read (the block message says so), which is why the default is generous. Milliseconds, positive integer:

Every review logs its duration and outcome (git_guard.reflection_done in the debug log), so tune from evidence: if reviews of your typical diffs take three minutes, the bound should not be four.

While a review runs you can see it: a notice when it starts ("Cold review: plan draft + 8 files (180 KB) by claude-fable-5-1 — bound 10 min"), the working row and the footer carrying the same while it runs, and a notice with the verdict and the elapsed time when it lands. Pressing escape ends the review at once; nothing is decided, no attempt is spent, and the next commit or exit_plan_mode reviews in full.

When the cold review returns FLAGS and you re-run the same commit, the message must carry the disposition of each flagged question (#96):

One line per question; disputed or accepted; the reason after a dash or colon, never empty. Write it in the message body (-m, or -F on a file) — not with git’s --trailer, and not in an editor the guard cannot read. fixed is not an answer here: change the diff, and the fresh review says whether it is fixed. The lines are stripped before the review key is hashed and before the reviewer reads the message, so adding them does not cost a second review; they land in git history with the commit.

Review-Context: (commits) and reviewPaths (plans) let the author hand the reviewer unchanged files. The guard caps that list, and the shipped caps were sized against a few thousand lines of TypeScript. A million-line Rust tree is not that: its files are bigger and it takes more of them to explain a change. All three caps are yours.

(Defaults: 80 000 bytes per file, 200 000 total, 12 files. Each is a positive integer; a refusal always quotes your number, not the default.)

What raising them costs. The reviewer’s input context is finite. Past some size the provider refuses the call, or the reviewer’s answer stops before its VERDICT: line. Neither is silent: both become an unreviewed outcome with the reason attached, the attempt is counted, and the commit or plan is told it has no cold read. So a cap set too high buys a visible non-review rather than an invisible bad one — raise it, watch reflection_done, and lower it if reviews start coming back unreviewed.

Beyond the declared files the reviewer may read the candidate snapshot itself (#97) — read_file, grep, list_files over the index, the worktree under -a, or the disk for a plan. Two caps bound it per review; the per-result cap is reviewContextMaxFileBytes.

(Defaults: 12 calls, 200 000 bytes. Positive integers.) Past the budget every call answers "budget exhausted … answer from what you have"; a reviewer that keeps asking is stopped two rounds later and the pause is unreviewed with that reason. reflection_done and plan_review.done carry snapshotCalls and snapshotBytes: a repository whose reviews routinely exhaust the calls wants a higher cap; one whose reviewer reads nothing wants none. Each read is a provider round trip on top of the review’s own, so the calls cap is also a latency cap.

Create <repo>/.pi/gadhs-guidance.md:

It is injected into the system prompt for anyone working in that repo with the package installed (trusted repos only).

This replaces the packaged digest wholesale — most teams should add a project block instead and leave the global one alone.

In a repo with no AGENTS.md yet:

creates the standard skeleton (tech stack, build commands, architecture notes, project overrides). It refuses to overwrite an existing file.

/settings → Theme → gadhs-human-services-dark (or -light, or the gadhs-foundation-* pair). To follow your terminal’s light/dark automatically, put this in ~/.pi/agent/settings.json:

An empty (or missing) list means no delegation at all in that mode.

The seeded helpers ship with Explore and Verify on Gemini 3.8 Flash (both argued on the model-battery page) and Research on Sonnet. To run one elsewhere without owning its file, name the model in ~/.pi/agent/gadhs-pi-agents.json:

The seed is rendered with your model in place of the packaged one; the file keeps its gadhs_managed marker, so the next package update still lands its prompt and only the model: line is yours. Remove the entry and the packaged model comes back on the next start. Keys must name packaged helpers and values must be provider/model; a malformed file, or a key naming a helper the package does not ship, is reported at start and the whole file ignored — never obeyed in part.

Why you might: the read-heavy helpers want a large window and adequate reasoning, not adversarial rigour, and Gemini 3.8 Flash offers a 1M-token window at Flash prices. It measured Sonnet-class on the agency’s review corpus and is not used for the reviewer or the auto-mode judge — see Reviewer evaluation: does a second vendor add value? for the numbers and the reasons.

There is nothing to configure for the model itself: vertex-gemini is the agency’s own Vertex provider, on the same ADC and project as Claude, and its models are in /model from the first start (Models on Vertex AI (@gadhs/pi-vertex)).

One thing to know about the fallback: pi-subagents resolves a helper’s model against the models available in the session and, when it cannot, runs the helper on the session’s own model without saying so. The seeding extension checks every configured model at session start and warns by name — "Explore is configured for vertex-gemini/gemini-3.8-flash, which is not available in this session" — so a missing project or expired login is a visible line, not a quiet bill on the frontier model.

In the helper’s definition file (<repo>/.pi/agents/Verify.md), declare what its final answer must look like:

If the helper’s answer does not match, you are told the result is unverified — instead of silently trusting a confident-sounding summary.

Overriding an agency helper in your repo (a .pi/agents/Verify.md of your own) replaces its prompt and its model, but not its contract unless you declare one: leave output_schema out and the agency’s schema still applies, and any violation message tells you that and which file to change.