Workflow Modes (@gadhs/pi-modes)

The design rule behind everything here: simple checks are done by simple code, instantly. A fast, separate AI model (the "judge") is consulted only when a pattern cannot decide — and it answers exactly one question: is this action dangerous? Whether your code is good, in scope, or what was asked for is reviewed by people, not by a model watching over your shoulder.

Your personal overlay merges with the shipped defaults: cosmetic fields (model, effort, labels) simply override, but permission rules combine strictest-wins per pattern — where you name the same pattern as a shipped rule, the stricter action stands, so agency policy cannot be loosened head-on. A more specific pattern of yours is kept as written, and because evaluation is most-specific-wins it can carve an exception into a broader shipped rule (that is how the known_hosts recipe works). A carve-out written that way — as a narrower form of the shipped pattern — is named in a warning at session start, so a loosened baseline is not silent; write exceptions as refinements, since a sibling glob that merely overlaps a shipped rule carves the same hole unreported. Because the agency rules live inside the package, updating the package updates the rules; there is no copy on your disk to go stale.

Switch with /mode (a picker), /mode <id>, /mode next, or just press F2. The status line always shows the active mode and what it is doing; when something is blocked, a line appears in the transcript saying who blocked it (a fixed policy, the judge, or a workflow check) and why — expand it for the full reasoning and what to do about it. /gadhs-reset lists every local tuning file in force and, with --apply, moves them aside so the package defaults apply again (tuning).

Each mode may declare a judge. It registers as the gadhs-mode-judge link in the permission system’s authorizerChain and reviews only ask decisions that survived every deterministic layer.

The judge sees the action and nothing else — not your conversation. It answers one question: is this dangerous? (Running code it cannot read, deleting things, leaking secrets, weakening security, escalating privileges.) It is explicitly not a code reviewer: safe work that is oddly styled or bigger than expected sails through, because quality is your job and your reviewers' — not a model’s.

Secret material is a deny on every rubric, including plan mode’s, whose question is otherwise "does this mutate anything?": a read-only command whose output would print credential values — cat or git show of a .env file or a key, the process environment filtered for a credential term, a container’s environment through docker inspect, a pod’s secret through kubectl get secret -o yaml, sops -d, vault kv get, a token printer — is refused, and the reason names the names-only or count-only alternative (printenv | cut -d= -f1, grep -rl, test -f). Plain env is allowed (#120). The read tool’s path rules deny the credential locations (~/.ssh, ~/.aws, gcloud, kube and docker configs) before any judge; the rubric covers the routes a path rule cannot see.

Which model. Both shipped judges run on Sonnet 4.6 at low (#102, 2026-09-12), argued on the Model battery: every shipped model, per role, as permutations page’s judge table: over the corpus as it then stood (122 cases) three times, Haiku low and Sonnet low are within three verdicts of each other (352 and 349 of 366 exact) and neither produced an unsafe verdict; Sonnet answers in 1.5 s median against Haiku’s 4.2 s at the same price per call; on the battery’s shipped-stack coder cells the faster judge took a Haiku lane from 91 s to 69 s and its cost level with the bare lane (an Opus lane, whose commands are almost all rule-allowed, did not move - its shipped overhead is the larger prompt). Haiku was cleaner on one critical case Sonnet deferred once; a defer is friction, not a breach. A different judge is a per-user overlay (Configuration Cookbook).

An unknown key in a judge block is refused by name when the config loads (mandateTurns and mandateCharsPerTurn, left over from the deleted mandate axis, were accepted and read by nothing until #62; delete them from any overlay that still sets them).

Every failure mode — missing model, missing credentials, timeout, transport error, unparseable output — resolves to defer, never allow. The verdict contract is strict JSON, property-tested against arbitrary output.

Denial-loop guard: after 3 consecutive or 20 total denials the session stops consulting the judge and defers to the human — a looping agent stops burning judge calls, and the human finds out something is wrong.

safetyValve (global) or judge.alwaysAsk (per-mode) name actions that stay interactive everywhere, including yolo: publishes, force pushes, pushes to main/master, tags, hard resets, --no-verify, merges, releases. The valve caps an allow to defer — it never short-circuits adjudication, so a deterministic deny still denies. Twelve patterns ship. yolo’s own alwaysAsk list is empty by default — yolo means yolo — but adding patterns there is the one way to keep specific actions interactive even in yolo (see the cookbook).

Patterns - the valve’s, highConsequence’s and every rule’s - are globs, not regexes: ` spans anything, everything else is literal, case does not matter. *Anything includes a newline (#156): a bash unit is often several lines - a heredoc, a quoted multi-line message - and production matches terraform apply <<'EOF' … production … EOF the same as its one-line form. Before this fix it did not, and a multi-line unit matched nothing at all.

Shipped in @gadhs/pi-workflow since ADR-004 — mode-independence is their design, so the package whose organizing concept is per-mode variation was the wrong home. They are documented here because this page is where the enforcement story reads as one piece; their traces render through pi-modes' status line and inline widgets when both are loaded, and their decisions do not change when it is absent.

These run in every mode, yolo included, before any permission ask exists. They are not permissions and cannot be opted out of: yolo answers “can I run this command”, never “do the coding standards apply to me”. A mode that auto-approves asks still attributes its commits, still reflects on each staged diff, and still writes SPDX headers.

All plain code — never the judge — and each completes an action where the correct completion is unambiguous, rather than failing it:

Three tools let the agent involve you deliberately instead of guessing or stopping. They ship with the extension and need no configuration.

The round trip is model-neutral, however you entered. Plan mode applies its own model on entry (deep reasoning is part of what the mode is), but approval hands you back the model you were on when planning started — or, if you switched models during planning, that one — and returns you to the mode you actually left, whether you entered through enter_plan_mode, /mode plan, the picker, or the cycle shortcut. Only choices are restored: entering from a mode’s own default lands you on the destination mode’s default, with no notice. The restore lands inside the switch and is what the transcript’s one mode-change message names — "Model is <yours> (your choice before planning, restored; the mode’s default was not applied)" — never a default that was applied and then replaced (#109: the first version announced the default into the transcript and restored yours with a UI notice only, so the agent believed it was on a model it was not). It does not depend on stickyModel being on; the two agree by construction, because both decide “yours or the mode’s” by the same rule (the model is yours when it is not the last one a mode applied). One residual: a session resumed while already in plan mode has no record of the pre-plan model, so approval there falls back to auto and cannot hand that model back — the swap to the destination default is announced, never silent — while a model you switch to during the resumed planning is still restored, since that half of the rule reads the live session. Pinned with the two records pi persists and we re-read at start (our mode entry and the last model_change; pi itself replays neither): test/wiring-lifecycle.test.ts "a resumed session cannot hand back the pre-plan model (#49)" — both halves: the pre-plan choice lost, the mid-plan choice kept.

The asymmetry is the whole design, and it is enforced by failing closed: no UI, a dismissed dialog, an unrecognised answer, or an error inside the dialog all mean keep planning. pi’s headless UI returns undefined from a dialog, which is indistinguishable from you pressing escape — so anything that is not an explicit, offered approval reads as “no”.

ask deliberately fails the other way: nothing is authorized by a question, so a dismissed one degrades to “no answer” and the agent proceeds on its own judgement, stating the assumption it made. Same primitive, opposite defaults; conflating them would turn a dismissed dialog into consent.

Subagents get none of these three. Their asks are adjudicated by the parent’s chain, and you could not tell which child was asking.

A subagent finishes by calling yield with a result matching the contract in its profile. If the payload does not match, the tool returns every problem at once rather than one per attempt, and the child retries in the same turn (up to three times) before the harness accepts prose. Every accepted payload (there is no size threshold) is written to a sidecar beside the child’s session record and collected by the parent, foreground or background alike, then placed in the result the parent reads — appended to the subagent tool’s result, or to the get_subagent_result report — as "returned a checked result" (#161), and traced for the human. That matters because yield ends the child’s turn: the prose the tool returns is whatever the child said before yielding, and the checked data is nowhere in it; before #161 the payload arrived as a separate gadhs-contract message and the fetched report itself showed a header and nothing, which read as an agent that had returned nothing. (The message path remains for a result the tool_result pass did not see.) A child whose session has no file is told its result was accepted but not delivered, and keeps its turn to restate it in prose.

How the parent finds the sidecar decides whether five children of one agent type get their own results. A fetched background report names the child’s transcript ("Full transcript available at: …"), and the sidecar beside that file is the child’s and no other’s — the exact join; a child that did not yield yields nothing, never a sibling’s. A result that names no transcript — the foreground result, or a report from a pi-subagents that does not print the path — falls back to the join that was the only one before #161: (agent name, written after this spawn started), newest first; foreground spawns do not overlap, so it holds there. A five-agent hunt on the old join delivered one child’s payload for another’s fetch and lost a third.

While a backgrounded child runs, its trace line says so — "is running in the background — id …" (#160); "finished" comes with its fetched report, not with the launch acknowledgment, which used to read "finished — 0.0s".

yield confers no capability — it is a child’s exit door, not a power — so parents are never granted it.

The retry ladder is a safety net, not the plan: each packaged agent’s body shows the exact data object its schema declares, field names included, because the first battery run (#82) found every model’s first yield rejected when the body said only "put your complete result in data`" - one sent prose, one named the array after the body’s own heading (`evidence for citations). A test in @gadhs/pi-agents fails if a body ever stops naming a schema field. Measured after the change: retries per successful yield fell from 1.5 to 0.17 on Haiku, 1.0 to 0.25 on Sonnet, 2.0 to 0 on Gemini 3.7.

canSpawn lists which helper agents a mode may launch (plan mode, for example, may launch read-only explorers but nothing that writes). The gate is deterministic: the agent must be on the mode’s list, must have a declared tool profile, and that profile must not include tools the mode itself lacks — and an unrecognisable spawn request is refused outright. (Set subagentPolicy.enforce: false to turn the gate off entirely.) Anything a helper then tries to do is checked by your session’s rules, in your current mode — a helper never gets looser permissions than you have.

Each helper runs on its own model, independent of the session’s: Explore and Verify on Gemini 3.8 Flash, Research on Sonnet 4.6, as shipped in @gadhs/pi-agents and argued on the Model battery: every shipped model, per role, as permutations page; tuning shows the per-user override. A helper’s model is a routing choice, not a permission one — the gate above applies whatever it runs on.

What a helper cost. pi’s footer prices the main session only; a helper is its own session and its spend appeared nowhere in dollars. Now each finished helper’s trace line carries it — Explore finished — 31.8s · 30,683 tok · $0.0137 (gemini-3.8-flash) — and the status line keeps a running total, helpers $0.419 (3), beside pi’s own figure. Since 0.37 the spend is in pi’s figure too: the subagent tool result (or the get_subagent_result that fetched a background report) carries the helper’s usage field by field, which pi persists on the result and counts in its footer, /session and RPC totals — so it survives a restart, and the status line’s breakdown is rebuilt from the result’s details.gadhsHelper when a session is resumed (#124). The figure is exact when it has no tilde: this extension runs inside every helper session too and ledgers the usage pi-ai priced on each of the helper’s messages, cache reads included; when a spawn ends, the parent claims the child session that started after the launch and has itself ended — a still-running helper cannot be claimed, so a fast one finishing takes only its own entry. Attribution is by start time, so two helpers launched in the same second could still swap figures between them; the total is the sum either way. A ~$ figure is a floor - pi-subagents' own token record priced at the catalog rate, which omits cache reads - used only when the ledger has no entry to claim; the status total carries the tilde once any such figure is in it. A helper that could not be matched is traced without a figure, never with a guess.

What the safety gate cost. Every ask that reaches the judge is a model call pi’s footer did not include either. Each call’s usage and price go to the permission system’s review log as a gadhs_mode_judge.call event, and the status line keeps judge $0.012 (7) - the spend and the number of calls, with the last long pause beside them (judge $0.012 (7, last 12.4s)) in place of the separate "last safety check" note. Since 0.37 a call’s usage also rides on the tool result of the call it gated, stamped details.gadhsJudge, so it is in pi’s total and the breakdown survives a restart; in parallel-tool mode two gated calls can swap per-call figures, the total is exact either way (#124). A call the provider did not price counts but adds nothing.

Subagents may also declare an output_schema (JSON Schema) in their .pi/agents/<name>.md frontmatter; the result is validated on completion and a violation is stated to the parent as fact ("treat its conclusion as unverified"), naming the file the contract came from. One validator serves runtime and tests.

Precedence between a global definition (~/.pi/agent/agents/<name>.md, where @gadhs/pi-agents seeds the agency’s) and a trusted project’s (<repo>/.pi/agents/<name>.md) follows what each line is (#134). pi-subagents runs the project file whole, and a project file that names no model: runs on the parent’s model — so the project file’s model replaces the global’s, present or absent, and pricing follows what ran. The contract is agency policy: a project file replaces it only by declaring its own output_schema; omission leaves the global contract in force, and a violation then says so — "the definition that ran declares no contract of its own; declare output_schema there to replace it" — so the project’s author can see the source of a contract their file never mentions.

The system prompt is composed per turn, most specific last:

Nothing is written to disk, so nothing drifts — pi extension update is the sync. /gadhs-init scaffolds a project-owned AGENTS.md skeleton (refuses to overwrite). With no blocks configured the system prompt is returned byte-identical (the no-op contract, pinned by tests).

pi summarizes a session on the session’s own model, at the session’s own thinking level, inside a budget of 0.8 x compaction.reserveTokens (13 107 tokens by default). On a reasoning model at a high effort the thinking spends that budget before the summary is finished; pi sees a length stop and - correctly - refuses to persist a partial summary, so compaction fails with "generation hit the token cap and the summary is incomplete." Observed live on claude-fable-5-1 at high; lowering the level fixed it. The variable was thinking, not the model.

pi-modes therefore handles session_before_compact by running pi’s own compact() - its prompt, its update-summary flow, its split-turn handling, its fail-closed rule on length - with two inputs changed: the thinking level is off, and the reserve pi sizes the summary budget from is floored at 65 536 tokens (a 52k summary budget; a larger operator setting is kept, and pi still caps at the model’s own maxTokens). The floor came from the second way the cap bites: a days-long session’s update summary - the previous summary re-emitted with everything since - did not fit 13 107 tokens with thinking off or on, and both attempts failed. The model stays the session’s: the summary is the session’s memory and it is written by the model that made it. The stream goes through the composed provider (extension, built-in, or api) with auth resolved the way pi resolves it, so the request differs from pi’s own only in the missing reasoning and the larger output budget.

When the hook hands back undefined, pi’s default runs: the model has no thinking to turn off (then the two paths are identical), the provider or its auth is missing (pi reports that itself), or our attempt failed - one warning names the reason, and pi’s own attempt surfaces its own error rather than ours masking it. A cancelled compaction is silent.

pi’s answer to a context that no longer fits is a compact-and-retry on the current model. Switch a long session from a 1M-window model to a 262k one and that answer is the problem: the turn is a 400, the recovery’s summary request carries the same context and is a 400, /compact is the same call, and the session is stuck on that model. Nothing in pi warns at the switch - model_select is notification-only, and pi does not compare the context to the new window. (Two further gaps made it worse on the agency’s own providers and are fixed in @gadhs/pi-vertex: messages stamped with the wire’s model name rather than the session’s id, which made pi skip the recovery as "a different model’s error", and catalog windows larger than what Vertex accepts - see Models on Vertex AI (@gadhs/pi-vertex).)

pi-modes hears the switch the moment after it happened. When the context does not fit - the line is pi’s own compaction threshold, tokens > contextWindow - 16 384 (pi’s default reserve), because above it pi compacts on arrival and that compaction is the deadlock - it says so by name:

Two ways out, and it names both. /new is the clear command - pi’s own, a fresh context - and stays yours to type (a fresh session needs a command context pi does not give an event handler). Compact first it can do for you: after a /model switch from a model the context fits, a dialog offers "Compact on <previous> first, then switch to <next>`" or "Keep `<next>`"; the first switches back, runs `/compact there (where the summary can be written), and switches again when it completes. A compaction that fails leaves you on the previous model and says why; a switch back that fails leaves you where you are. Model cycling (Ctrl+P) and session restore only warn - a dialog on every cycle step is worse than the 400 - and a context pi cannot yet estimate (right after a compaction) is not judged.

Pins: test/context-fit.test.ts (the fit line, the dialog’s presence per source and previous model, each route’s calls and its failure handling). Observed live 2026-09-07 over pi’s RPC: 121k tokens on Haiku, set_model to vertex-maas/gpt-oss-120b (131k): the warning, the dialog, the switch back, compaction_end without error, the switch forward, and the next turn answered on gpt-oss at 43k input.

Everything lands in the permission review log, stamped with mode and session identity (pid, started, cwd):

On first load the extension seeds a minimal permission-system config (only when absent — never overwriting, even an invalid one):

This file is deliberately tiny: it just routes every permission question to the mode system, which is where all the real policy lives (and updates with the package): agency rules ship in modes.json and are enforced by the extension’s authorizer, precisely so that policy reaches every developer on update — anything written to disk is seeded once and never migrates. The seeded file must also stay strictly schema-valid: a // comment key silently clamps the entire permission config, chain included. If you have edited yours and want to know how it differs from the current default, node tools/task.mjs policy-diff will tell you, and --write will repair it (it only ever tightens, and asks first).