pi-warden 0.1.1 → 0.2.0

package/README.md

@@ -1,10 +1,22 @@
 # pi-warden
 
-Harness guardrails for [Pi](https://pi.dev), built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe). Before the agent runs a `bash`, `write`, or `edit` call, pi-warden checks it twice: a fast offline pattern pass for the obvious hazards, then one TypeSafe (Jev) request that scores how **irreversible** and how **off-task** the action is relative to your latest request. High scores open a confirm dialog; you decide, and a declined call is blocked with a short reason the agent can act on.
+A second pair of eyes for [Pi](https://pi.dev) that makes the agent smarter instead of interrupting you. Before the agent runs a `bash`, `write`, or `edit` call, pi-warden asks [Jev](https://typesafe.ai) two questions about it in ~250 ms: *would this destroy something that cannot be recovered?* and *is this what the user actually asked for?* The answers are probabilities, so `rm -rf dist` after "rebuild from scratch" sails through while `npm run db:reset` after "add a column" is held, and the agent is told why so it re-plans or asks you in chat. Three more guards watch the run: a **stuck-loop** detector, a **done-check** for completion claims that no test backed up, and a **slop** note for stubs and filler. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
 
-Independent project. Not affiliated with TypeSafe AI or the Pi authors.
+![Real verdicts from pi-warden: the same command gets a different verdict depending on what the user asked for](https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png)
 
-![Pi asking for confirmation before a destructive command, with pi-warden's irreversible and off-task scores in the dialog](https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png)
+The verdicts above are real output from `npm run test:live`. Independent project; not affiliated with TypeSafe AI or the Pi authors.
+
+## Why a coding agent needs this
+
+Agents are good at picking the next command and bad at noticing when that command is out of proportion to the request. Pattern lists catch `rm -rf /` and force pushes; they cannot tell `db:reset` when you asked for a reset from `db:reset` when you asked for a column. A generative model can, but a second LLM call per tool call is slow and expensive. Jev is a System One model: it returns calibrated probabilities instead of text, in a quarter of a second, for a fraction of a cent. That makes it cheap enough to sit in front of **every** guarded call:
+
+- **Irreversible actions are held, not run**: history rewrites, deleted untracked work, dropped tables, overwritten files outside the project, publishes and deploys. The agent receives the judgment as its tool result — what was flagged, the scores, and two acceptable next moves: find a recoverable alternative, or explain the action to you and wait. If you approve in chat, the retry goes through; Jev reads your reply as the approval. No modal dialog unless you ask for one (`/warden mode confirm`).
+- **Scope drift gets flagged.** Poems in a bugfix, refactors nobody asked for, dependency installs unrelated to the task: warned to you at 0.6, held at 0.85 when Jev also calls the action `unrelated`.
+- **Loops get broken.** Three failures with the same strategy (same command with cosmetic changes, same error after each edit) earn the agent a steer: re-read the error, form a new hypothesis, or report the blocker. Exact repeats are caught offline; Jev tells "investigating between failures" from "flailing" — 0.32 vs 0.93 in the smoke run.
+- **"Done" gets checked.** When the final message reports completion after file changes and no test, build, or lint passed in that run, the agent is asked to verify before you read a false "all green". A claim that tests passed when none ran is called out as such. Once per prompt, so it cannot loop.
+- **Slop gets a note.** Stub functions, `TODO: implement later`, mocks returning fake data, filler comments: scored on the same request as the action guard (zero extra latency) and steered back to the agent after the write, never held.
+- **Nothing slows down the boring calls.** Read-only shell lines are skipped without a request; anything else costs one request of ~600 input tokens.
+- **It degrades gracefully.** Offline pattern checks and exact-repeat detection run with no account at all. On an API timeout or outage the call is allowed with a warning (configurable), and reasons never include your command text or upstream error bodies.
 
 ## Install
 
@@ -22,16 +34,33 @@ Requires Pi 0.85 or newer and Node.js 22.19 or newer. Pattern checks work with n
 
 A `TYPESAFE_API_KEY` environment variable takes precedence over the stored key. Without step 2, pi-warden still guards with offline pattern checks only.
 
-## What it does on each guarded call
+## How the guards work
+
+### Action guard (`tool_call`)
 
 1. **Skip** read-only tools, and read-only shell lines such as `git status && ls` (no network, no widget).
-2. **Pattern pass** (offline): force pushes, `git reset --hard`, `git clean -f`, recursive `rm` on absolute/home/variable/parent paths, SQL `DROP`/`TRUNCATE`/`DELETE FROM`, block-device writes, `chmod -R 777`, fork bombs, `curl | sh`, `kill -1`, shutdown, package publishing, infrastructure destroys → **confirm**. `rm -rf` on a project path, `git checkout -- .`, `git branch -D`, `git stash drop`, `find -delete`, `sudo` → **warn**. Reads or writes of `.env`, SSH, AWS, npm, kube, and other credential files → **warn**. A `write` that overwrites an existing file outside the project → **confirm**; creating or editing outside the project → **warn**.
-3. **Jev judgment** (with consent): one request with the state `{ task, action }` and three questions — `irreversible` (Noul), `off_task` (Noul), `scope` (Choice: expected step, plausible side step, unrelated, unclear). Defaults: irreversible ≥ 0.5 warns, ≥ 0.7 confirms; off-task ≥ 0.6 warns, ≥ 0.85 with `unrelated` confirms. Pattern results set the floor; Jev can only raise it.
-4. **Act**: allow silently, warn with a notification, or ask with `ctx.ui.confirm`. The widget above the editor shows the last verdict, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`.
+2. **Pattern pass** (offline): force pushes, `git reset --hard`, `git clean -f`, recursive `rm` on absolute/home/variable/parent paths, SQL `DROP`/`TRUNCATE`/`DELETE FROM`, block-device writes, `chmod -R 777`, fork bombs, `curl | sh`, `kill -1`, shutdown, package publishing, infrastructure destroys → **hold**. `rm -rf` on a project path, `git checkout -- .`, `git branch -D`, `git stash drop`, `find -delete`, `sudo` → **warn**. Reads or writes of `.env`, SSH, AWS, npm, kube, and other credential files → **warn**. A `write` that overwrites an existing file outside the project → **hold**; creating or editing outside the project → **warn**.
+3. **Jev judgment** (with consent): one request with the state `{ task, action }` and three questions — `irreversible` (Noul), `off_task` (Noul), `scope` (Choice: expected step, plausible side step, unrelated, unclear). Defaults: irreversible ≥ 0.5 warns, ≥ 0.7 holds; off-task ≥ 0.6 warns, ≥ 0.85 with `unrelated` holds. Pattern results set the floor; Jev can only raise it. For `write`/`edit`, two slop questions ride on the same request.
+4. **Act**, by mode:
+   - `steer` (default): a hold blocks the call and returns the judgment to the agent as the tool result, with the two acceptable next moves. You see a notification and the widget line; the agent keeps working. When the agent asks you and your reply approves the action (Jev: `approved` ≥ 0.7, or an offline yes/go-ahead heuristic without consent), the identical retry is allowed once.
+   - `confirm`: a hold opens a `ctx.ui.confirm` dialog; No blocks with a short reason. Without a UI this falls back to `steer`.
+   - `advise`: never holds; every judgment is reported to you only.
+
+   Warn-level verdicts notify you and continue in every mode. The widget above the editor shows the last verdict of each guard, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`.
+
+### Stuck detector (`tool_result`)
+
+Keeps the last 12 tool results for the current prompt. When the latest result failed and at least 3 failures have accumulated, it first checks for exact repeats offline (same call, same output with timings and addresses normalised). Otherwise one Jev request judges the sequence: `same_strategy` (Noul), `approach_change` (Score: identical / cosmetic / meaningfully different), `progress` (Noul). Same-strategy ≥ 0.7 counts as stuck: you get a notification, and with `nudge: true` (default) the agent gets a steer message asking for a new hypothesis or a blocker report. At most one Jev check per 3 results.
+
+### Done-check (`agent_end`)
+
+Tracks each run's evidence: code changes (`write`, `edit`) and check commands (`npm test`, `pytest`, `cargo test`, `tsc`, `eslint`, `go test`, `make test`, and similar) with pass/fail. When a run ends with a normal assistant message after code changes and no passing check, one Jev request judges the message: `claims_done`, `claims_verified`, `verification_applies` (Noul), `outcome` (Choice: complete / partial / blocked / other). A completion claim ≥ 0.7 that is not a blocker or question, for a task where checks would mean something (≥ 0.5; prose and file housekeeping score ~0.05), is reported as unverified; a verification claim with no check run is reported as a false claim. With `nudge: true` (default) the agent receives one follow-up turn asking it to run the checks or say plainly that nothing was verified — once per user prompt.
+
+### Slop (`write`/`edit`, same request as the action guard)
 
-Headless runs (`pi -p`, JSON mode) cannot ask, so a confirm-level call is **blocked** unless `PI_WARDEN_HEADLESS=allow` or `"headless": "allow"` is set. Consent in headless runs comes from `PI_WARDEN_ENABLED=1`.
+`slop_quality` (Score: focused / some filler / sloppy) and `slop_placeholder` (Noul: stub or placeholder where working code is needed). Quality ≥ 1.5 or placeholder ≥ 0.7 notifies you and steers the agent to replace stubs and remove filler. Never holds a call.
 
-If TypeSafe cannot answer (timeout after 5 s, outage, budget), the call is allowed with a warning (`failOpen: true`). Set `failOpen` to `false` to ask instead. When the per-session request budget is spent, pi-warden says so once and continues with pattern checks.
+If TypeSafe cannot answer (timeout after 5 s, outage, budget), an action-guard call is allowed with a warning (`failOpen: true`; set it to `false` to hold instead), and the other guards simply skip. When the per-session request budget is spent, pi-warden says so once and continues with offline checks. Consent in headless runs comes from `PI_WARDEN_ENABLED=1`; `PI_WARDEN_MODE` overrides the mode.
 
 ## Commands
 
@@ -40,8 +69,9 @@ If TypeSafe cannot answer (timeout after 5 s, outage, budget), the call is allow
 | `/warden status` | Guard state, consent source, key source, session counts, thresholds, config paths, last verdict |
 | `/warden enable` | Show the data notice, prompt for a key if none is stored, and save consent for Jev judgments |
 | `/warden disable` | Stop Jev judgments; pattern checks continue |
+| `/warden mode steer\|confirm\|advise` | Choose how holds are handled; without an argument, show the current mode |
 | `/warden config` | Edit the user config JSON in Pi's editor and save it |
-| `/warden test` | Evaluate one synthetic destructive action and show the verdict |
+| `/warden test` | Evaluate one synthetic destructive action and show the verdict and what the agent would be told |
 
 ## Configuration
 
@@ -51,27 +81,30 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
 {
   "enabled": true,
   "typesafe": false,
-  "headless": "block",
+  "mode": "steer",
+  "timeoutMs": 5000,
+  "maxRequests": 500,
   "action": {
     "enabled": true,
     "tools": ["bash", "write", "edit"],
     "failOpen": true,
-    "timeoutMs": 5000,
-    "maxRequests": 500,
     "irreversible": { "warn": 0.5, "confirm": 0.7 },
     "offTask": { "warn": 0.6, "confirm": 0.85 }
-  }
+  },
+  "stuck": { "enabled": true, "window": 12, "minFailures": 3, "cooldown": 3, "sameStrategy": 0.7, "nudge": true },
+  "done": { "enabled": true, "claimsDone": 0.7, "nudge": true },
+  "slop": { "enabled": true, "quality": 1.5, "placeholder": 0.7 }
 }
 ```
 
-A project may add `.pi/pi-warden.json` with `enabled` and `action` overrides (for example stricter thresholds or extra guarded tools). Project files are read only when Pi trusts the project, and they can never grant `typesafe` consent or change `headless`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_HEADLESS=allow|block`.
+A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides (for example stricter thresholds, extra guarded tools, or `"done": { "enabled": false }`). Project files are read only when Pi trusts the project, and they can never grant `typesafe` consent, change `mode`, or raise `timeoutMs`/`maxRequests`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_MODE=steer|confirm|advise`. Files from 0.1.x that set `action.timeoutMs`/`action.maxRequests` keep working.
 
 ## Data handling
 
-- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 600-character content excerpt for `write`, and the first three edit pairs (200 characters each) for `edit`. No other files, history, or telemetry.
+- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character content excerpt for `write`, and the first three edit pairs (400 characters each) for `edit`. The stuck detector sends the last 12 tool calls (300 characters each) with 400-character output tails; the done-check sends the agent's final message (2000 characters) and the run's check commands. No other files, history, or telemetry.
 - Obvious credentials in the action (`Authorization` headers, `TOKEN=`/`SECRET=` assignments, `sk-`, `ghp_`, `AKIA`, JWTs, URL passwords, PEM blocks) are replaced with `[redacted]` before sending. This is best-effort; do not rely on it for prompts that contain secrets.
-- The block reason returned to the agent names the tool and the reasons, not the command text. UI errors never include upstream response bodies or keys.
-- Judgments are model output. Thresholds are yours to tune; the dialog is the decision.
+- Text returned or steered to the agent names the tool, the reasons, and the scores, not the command text. UI errors never include upstream response bodies or keys.
+- Judgments are model output. Thresholds are yours to tune; a hold is information for the agent and for you, not a verdict on either.
 
 ## For extension authors
 
@@ -85,20 +118,22 @@ const verdict = await evaluateAction(
   { tool: "bash", input: { command: "git push --force" }, cwd: process.cwd(), task: "push my branch" },
   { config: defaultConfig().action, judge: createTypeSafe() },   // omit judge for pattern checks only
 );
-verdict.level;      // "allow" | "warn" | "confirm"
+verdict.level;      // "allow" | "warn" | "confirm"  (confirm = hold in steer mode)
 verdict.reasons;    // ["destructive: git force push", "irreversible 0.91"]
-verdict.judgment;   // { irreversible, offTask, scope, scopeConfidence, model, elapsedMs }
+verdict.judgment;   // { irreversible, offTask, scope, scopeConfidence, approved?, model, elapsedMs }
+steerReason(verdict, { canApprove: true });   // the text the agent receives for a hold
 ```
 
-Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`, `formatVerdict`, `questions`, and the config helpers.
+Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`, `formatVerdict`, the question sets, the stuck detector (`AttemptWindow`, `makeAttempt`, `evaluateStuck`, `stuckNudge`), the done-check (`classifyToolResult`, `recordOutcome`, `needsDoneCheck`, `evaluateDone`, `doneNudge`), and the config helpers.
 
 ## Development
 
 ```bash
 npm install
 npm run check        # typecheck, offline tests (mocked transport), build
-npm run test:live    # nine billable synthetic judgments against api.typesafe.ai (key from .env or the stored login)
+npm run test:live    # 28 billable synthetic judgments across all guards (key from .env or the stored login); pass action|slop|approval|stuck|done for one group
 npm run dev:pi       # start Pi with this working tree plus an installed pi-typesafe
+npm run preview      # re-render docs/preview.png from the recorded live verdicts (needs a Chrome binary)
 ```
 
 ## License

package/dist/config.d.ts

@@ -12,19 +12,56 @@ export interface ActionGuardConfig {
     failOpen: boolean;
     /** Per-request TypeSafe timeout. The call is judged as an error after this. */
     timeoutMs: number;
-    /** Maximum TypeSafe requests per session for this guard. */
-    maxRequests: number;
     irreversible: Threshold;
     offTask: Threshold;
 }
+export interface StuckGuardConfig {
+    enabled: boolean;
+    /** Tool results remembered per user prompt. */
+    window: number;
+    /** Failures in the window before Jev is asked. */
+    minFailures: number;
+    /** Tool results between two Jev checks. */
+    cooldown: number;
+    /** P(same strategy) at or above this reports the agent as stuck. */
+    sameStrategy: number;
+    /** Also steer the agent with a short message, not only the user. */
+    nudge: boolean;
+}
+export interface DoneGuardConfig {
+    enabled: boolean;
+    /** P(final message claims completion) at or above this warns when no check passed in the run. */
+    claimsDone: number;
+    /** Also send the agent a follow-up asking it to verify. Triggers one more LLM turn. */
+    nudge: boolean;
+}
+export interface SlopGuardConfig {
+    enabled: boolean;
+    /** Score (0 focused … 2 sloppy) at or above this warns. */
+    quality: number;
+    /** P(placeholder or stub code) at or above this warns. */
+    placeholder: number;
+}
+export type WardenMode = "steer" | "confirm" | "advise";
 export interface WardenConfig {
     /** Master switch. false disables every guard, including offline pattern checks. */
     enabled: boolean;
     /** Consent to send task and action summaries to api.typesafe.ai. Set by /warden enable; never by a project file. */
     typesafe: boolean;
-    /** Decision when confirmation is required and no UI can ask. PI_WARDEN_HEADLESS overrides it. */
-    headless: "block" | "allow";
+    /**
+     * steer (default): a confirm-level call is held and the agent receives the judgment as its tool result, so it re-plans or asks
+     * the user in chat. confirm: open a dialog and let the user decide (falls back to steer without a UI). advise: never hold; report only.
+     * PI_WARDEN_MODE overrides it.
+     */
+    mode: WardenMode;
+    /** Per-request TypeSafe timeout for every guard. */
+    timeoutMs: number;
+    /** Maximum TypeSafe requests per session across all guards. */
+    maxRequests: number;
     action: ActionGuardConfig;
+    stuck: StuckGuardConfig;
+    done: DoneGuardConfig;
+    slop: SlopGuardConfig;
 }
 export declare const PACKAGE_NAME = "pi-warden";
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
@@ -33,9 +70,10 @@ export declare function defaultConfig(): WardenConfig;
 export declare function userConfigPath(): string;
 export declare function projectConfigPath(cwd: string): string;
 type Json = Record<string, unknown>;
+export declare function isMode(value: unknown): value is WardenMode;
 /** Unknown keys and invalid values fall back to the base; nothing throws on a malformed file. */
 export declare function applyUserOverrides(base: WardenConfig, raw: unknown): WardenConfig;
-/** Project files may tune the guard but cannot grant TypeSafe consent or change headless policy. */
+/** Project files may tune the guards but cannot grant TypeSafe consent, change the mode, or raise budgets. */
 export declare function applyProjectOverrides(base: WardenConfig, raw: unknown): WardenConfig;
 export interface LoadOptions {
     cwd?: string;
@@ -47,5 +85,5 @@ export declare function loadConfig(options?: LoadOptions): WardenConfig;
 export declare function readUserConfig(): Json;
 export declare function writeUserConfig(raw: Json): string;
 /** Persists one top-level user setting without disturbing the rest of the file. */
-export declare function setUserSetting(key: "typesafe" | "enabled" | "headless", value: boolean | "block" | "allow"): string;
+export declare function setUserSetting(key: "typesafe" | "enabled" | "mode", value: boolean | WardenMode): string;
 export {};

package/dist/config.js

@@ -7,16 +7,20 @@ export function defaultConfig() {
     return {
         enabled: true,
         typesafe: false,
-        headless: "block",
+        mode: "steer",
+        timeoutMs: 5000,
+        maxRequests: 500,
         action: {
             enabled: true,
             tools: ["bash", "write", "edit"],
             failOpen: true,
             timeoutMs: 5000,
-            maxRequests: 500,
             irreversible: { warn: 0.5, confirm: 0.7 },
             offTask: { warn: 0.6, confirm: 0.85 },
         },
+        stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, nudge: true },
+        done: { enabled: true, claimsDone: 0.7, nudge: true },
+        slop: { enabled: true, quality: 1.5, placeholder: 0.7 },
     };
 }
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
@@ -58,36 +62,83 @@ function boolean(value, fallback) {
 function positiveInteger(value, fallback) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : fallback;
 }
-function applyAction(base, raw) {
+export function isMode(value) {
+    return value === "steer" || value === "confirm" || value === "advise";
+}
+function score(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 2 ? value : fallback;
+}
+function applyAction(base, raw, timeoutMs) {
+    const withTimeout = { ...base, timeoutMs };
     if (!isObject(raw))
-        return base;
+        return withTimeout;
     const tools = Array.isArray(raw.tools) ? raw.tools.filter((tool) => typeof tool === "string" && tool.trim().length > 0) : base.tools;
     return {
         enabled: boolean(raw.enabled, base.enabled),
         tools,
         failOpen: boolean(raw.failOpen, base.failOpen),
-        timeoutMs: positiveInteger(raw.timeoutMs, base.timeoutMs),
-        maxRequests: positiveInteger(raw.maxRequests, base.maxRequests),
+        timeoutMs,
         irreversible: threshold(raw.irreversible, base.irreversible),
         offTask: threshold(raw.offTask, base.offTask),
     };
 }
+function applyStuck(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const window = positiveInteger(raw.window, base.window);
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        window,
+        minFailures: Math.min(window, positiveInteger(raw.minFailures, base.minFailures)),
+        cooldown: positiveInteger(raw.cooldown, base.cooldown),
+        sameStrategy: probability(raw.sameStrategy, base.sameStrategy),
+        nudge: boolean(raw.nudge, base.nudge),
+    };
+}
+function applyDone(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return { enabled: boolean(raw.enabled, base.enabled), claimsDone: probability(raw.claimsDone, base.claimsDone), nudge: boolean(raw.nudge, base.nudge) };
+}
+function applySlop(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return { enabled: boolean(raw.enabled, base.enabled), quality: score(raw.quality, base.quality), placeholder: probability(raw.placeholder, base.placeholder) };
+}
+/** Shared request settings; `action.timeoutMs`/`action.maxRequests` from 0.1.x files are still honoured. */
+function applyShared(base, raw) {
+    const legacy = isObject(raw.action) ? raw.action : {};
+    return {
+        timeoutMs: positiveInteger(raw.timeoutMs ?? legacy.timeoutMs, base.timeoutMs),
+        maxRequests: positiveInteger(raw.maxRequests ?? legacy.maxRequests, base.maxRequests),
+    };
+}
+function applyGuards(base, raw, timeoutMs) {
+    return {
+        action: applyAction(base.action, raw.action, timeoutMs),
+        stuck: applyStuck(base.stuck, raw.stuck),
+        done: applyDone(base.done, raw.done),
+        slop: applySlop(base.slop, raw.slop),
+    };
+}
 /** Unknown keys and invalid values fall back to the base; nothing throws on a malformed file. */
 export function applyUserOverrides(base, raw) {
     if (!isObject(raw))
         return base;
+    const shared = applyShared(base, raw);
     return {
         enabled: boolean(raw.enabled, base.enabled),
         typesafe: boolean(raw.typesafe, base.typesafe),
-        headless: raw.headless === "allow" || raw.headless === "block" ? raw.headless : base.headless,
-        action: applyAction(base.action, raw.action),
+        mode: isMode(raw.mode) ? raw.mode : base.mode,
+        ...shared,
+        ...applyGuards(base, raw, shared.timeoutMs),
     };
 }
-/** Project files may tune the guard but cannot grant TypeSafe consent or change headless policy. */
+/** Project files may tune the guards but cannot grant TypeSafe consent, change the mode, or raise budgets. */
 export function applyProjectOverrides(base, raw) {
     if (!isObject(raw))
         return base;
-    return { ...base, enabled: boolean(raw.enabled, base.enabled), action: applyAction(base.action, raw.action) };
+    return { ...base, enabled: boolean(raw.enabled, base.enabled), ...applyGuards(base, raw, base.timeoutMs) };
 }
 export function loadConfig(options = {}) {
     let config = applyUserOverrides(defaultConfig(), readJson(userConfigPath()));

package/dist/done.d.ts

@@ -0,0 +1,86 @@
+import type { DoneGuardConfig } from "./config.js";
+import type { Judge } from "./guard.js";
+export type ToolOutcome = "read" | "mutation" | "check-pass" | "check-fail" | "unknown";
+/**
+ * What a finished tool call contributes to the run's evidence. Only write/edit count as code changes: shell side effects
+ * (deleting a temp dir, installing a package) are too varied to demand a test run for. Custom tools are unknown.
+ */
+export declare function classifyToolResult(tool: string, input: Record<string, unknown>, failed: boolean): ToolOutcome;
+export interface RunEvidence {
+    mutations: number;
+    checks: Array<{
+        call: string;
+        passed: boolean;
+    }>;
+}
+export declare function emptyEvidence(): RunEvidence;
+export declare function recordOutcome(evidence: RunEvidence, outcome: ToolOutcome, input: Record<string, unknown>): void;
+interface MessageLike {
+    role: string;
+    content?: unknown;
+    stopReason?: unknown;
+}
+/** Text of the run's final assistant message, when it ended normally with text (not a tool call, error, or abort). */
+export declare function finalAssistantText(messages: ReadonlyArray<MessageLike>): string | undefined;
+/** The check only makes sense when something changed and nothing proved it works. */
+export declare function needsDoneCheck(evidence: RunEvidence): boolean;
+export declare const doneQuestions: {
+    claims_done: import("pi-typesafe").NoulQuestion;
+    claims_verified: import("pi-typesafe").NoulQuestion;
+    verification_applies: import("pi-typesafe").NoulQuestion;
+    outcome: import("pi-typesafe").ChoiceQuestion<{
+        readonly complete: "The work is finished";
+        readonly partial: "Progress was made and remaining work is named";
+        readonly blocked: "A blocker is reported or the user is asked something";
+        readonly other: "None of these";
+    }>;
+};
+export interface DoneJudgment {
+    claimsDone: number;
+    claimsVerified: number;
+    verificationApplies: number;
+    outcome: "complete" | "partial" | "blocked" | "other";
+    model: string;
+    elapsedMs: number;
+}
+export interface DoneVerdict {
+    unverified: boolean;
+    /** The message says checks passed but none ran: stronger than an unverified claim. */
+    falseClaim: boolean;
+    reasons: string[];
+    evidence: RunEvidence;
+    judgment?: DoneJudgment;
+    error?: string;
+}
+export declare function buildDoneRequest(task: string | undefined, finalMessage: string, evidence: RunEvidence): {
+    state: {
+        task: string;
+        final_message: string;
+        run: {
+            file_changes: number;
+            checks_run: string[];
+        };
+    };
+    questions: {
+        claims_done: import("pi-typesafe").NoulQuestion;
+        claims_verified: import("pi-typesafe").NoulQuestion;
+        verification_applies: import("pi-typesafe").NoulQuestion;
+        outcome: import("pi-typesafe").ChoiceQuestion<{
+            readonly complete: "The work is finished";
+            readonly partial: "Progress was made and remaining work is named";
+            readonly blocked: "A blocker is reported or the user is asked something";
+            readonly other: "None of these";
+        }>;
+    };
+};
+export interface DoneOptions {
+    config: DoneGuardConfig;
+    judge: Judge;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function evaluateDone(task: string | undefined, finalMessage: string, evidence: RunEvidence, options: DoneOptions): Promise<DoneVerdict>;
+/** Follow-up for the agent: verify or say plainly that nothing was verified. */
+export declare function doneNudge(verdict: DoneVerdict): string;
+export declare function formatDone(verdict: DoneVerdict): string;
+export {};

package/dist/done.js

@@ -0,0 +1,121 @@
+import { choice, noul, TypeSafeIntegrationError } from "pi-typesafe";
+import { isReadOnlyCommand } from "./guard.js";
+import { redact } from "./redact.js";
+/** Commands whose success is evidence that the work was verified. */
+const CHECK_COMMAND = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|check|lint|typecheck|build|verify|ci)\b|(?:npx|pnpm|bunx)\s+(?:tsc|jest|vitest|mocha|eslint|biome|prettier\s+--check)\b|pytest|jest|vitest|mocha|tsc|eslint|biome\s+check|ruff|mypy|flake8|pylint|black\s+--check|cargo\s+(?:test|check|build|clippy)|go\s+(?:test|vet|build)|make\s+(?:test|check|lint|build)|mvn\s+(?:test|verify)|gradle\w*\s+(?:test|check|build)|dotnet\s+(?:test|build)|node\s+--test|deno\s+(?:test|check|lint)|rspec|rake\s+test|mix\s+test|phpunit|swift\s+(?:test|build)|xcodebuild\s+test|ctest|zig\s+(?:test|build))\b/;
+/**
+ * What a finished tool call contributes to the run's evidence. Only write/edit count as code changes: shell side effects
+ * (deleting a temp dir, installing a package) are too varied to demand a test run for. Custom tools are unknown.
+ */
+export function classifyToolResult(tool, input, failed) {
+    if (tool === "write" || tool === "edit")
+        return "mutation";
+    if (tool === "read" || tool === "grep" || tool === "find" || tool === "ls")
+        return "read";
+    if (tool !== "bash" || typeof input.command !== "string")
+        return "unknown";
+    if (CHECK_COMMAND.test(input.command))
+        return failed ? "check-fail" : "check-pass";
+    return isReadOnlyCommand(input.command) ? "read" : "unknown";
+}
+export function emptyEvidence() {
+    return { mutations: 0, checks: [] };
+}
+export function recordOutcome(evidence, outcome, input) {
+    if (outcome === "mutation")
+        evidence.mutations++;
+    if (outcome === "check-pass" || outcome === "check-fail") {
+        const call = typeof input.command === "string" ? redact(input.command.length > 200 ? `${input.command.slice(0, 200)}…` : input.command) : "check";
+        evidence.checks.push({ call, passed: outcome === "check-pass" });
+    }
+}
+/** Text of the run's final assistant message, when it ended normally with text (not a tool call, error, or abort). */
+export function finalAssistantText(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role !== "assistant")
+            continue;
+        if (message.stopReason !== undefined && message.stopReason !== "stop")
+            return undefined;
+        const content = message.content;
+        const text = typeof content === "string" ? content
+            : Array.isArray(content) ? content.filter(part => part.type === "text" && typeof part.text === "string").map(part => part.text).join("\n")
+                : "";
+        return text.trim() || undefined;
+    }
+    return undefined;
+}
+/** The check only makes sense when something changed and nothing proved it works. */
+export function needsDoneCheck(evidence) {
+    return evidence.mutations > 0 && !evidence.checks.some(check => check.passed);
+}
+export const doneQuestions = {
+    claims_done: noul("Does `final_message` present the requested work as finished or working?", {
+        true: "Yes: it says the task is done, fixed, implemented, complete, or working, or summarises the result as final.",
+        false: "No: it reports partial progress, names remaining work, reports a blocker, asks the user a question, or only describes a plan.",
+    }),
+    claims_verified: noul("Does `final_message` claim that tests, a build, or other checks were run and passed?"),
+    verification_applies: noul("Would running the project's tests, build, or lint be a meaningful way to check the work that `task` asks for?", {
+        true: "Yes: `task` changes or adds code, configuration, or build logic that such checks exercise.",
+        false: "No: `task` is about documentation, prose, file housekeeping, deleting or moving files, answering a question, or something the project's checks would not cover.",
+    }),
+    outcome: choice("What does `final_message` report about `task`?", {
+        complete: "The work is finished",
+        partial: "Progress was made and remaining work is named",
+        blocked: "A blocker is reported or the user is asked something",
+        other: "None of these",
+    }),
+};
+export function buildDoneRequest(task, finalMessage, evidence) {
+    return {
+        state: {
+            task: task?.trim() ? (task.trim().length > 1500 ? `${task.trim().slice(0, 1500)}…` : task.trim()) : "(no user request recorded in this session)",
+            final_message: redact(finalMessage.length > 2000 ? `${finalMessage.slice(0, 2000)}…` : finalMessage),
+            run: { file_changes: evidence.mutations, checks_run: evidence.checks.map(check => `${check.call} → ${check.passed ? "passed" : "failed"}`) },
+        },
+        questions: doneQuestions,
+    };
+}
+const APPLIES_THRESHOLD = 0.5;
+export async function evaluateDone(task, finalMessage, evidence, options) {
+    try {
+        const timeout = AbortSignal.timeout(options.timeoutMs);
+        const result = await options.judge.evaluate(buildDoneRequest(task, finalMessage, evidence), { signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout });
+        const judgment = {
+            claimsDone: result.answers.claims_done.noul,
+            claimsVerified: result.answers.claims_verified.noul,
+            verificationApplies: result.answers.verification_applies.noul,
+            outcome: result.answers.outcome.choice,
+            model: result.model,
+            elapsedMs: result.elapsedMs,
+        };
+        const unverified = judgment.claimsDone >= options.config.claimsDone && judgment.outcome !== "blocked" && judgment.verificationApplies >= APPLIES_THRESHOLD;
+        const falseClaim = unverified && judgment.claimsVerified >= 0.7 && evidence.checks.length === 0;
+        const reasons = [];
+        if (unverified) {
+            const failed = evidence.checks.filter(check => !check.passed).length;
+            reasons.push(`reports completion (${judgment.claimsDone.toFixed(2)}) after ${evidence.mutations} file change${evidence.mutations === 1 ? "" : "s"} with ${failed ? `${failed} failed check${failed === 1 ? "" : "s"} and no passing one` : "no test, build, or lint run"}`);
+        }
+        if (falseClaim)
+            reasons.push(`claims checks passed (${judgment.claimsVerified.toFixed(2)}) but none ran`);
+        return { unverified, falseClaim, reasons, evidence, judgment };
+    }
+    catch (error) {
+        return { unverified: false, falseClaim: false, reasons: [], evidence, error: error instanceof TypeSafeIntegrationError ? error.message : "TypeSafe request failed." };
+    }
+}
+/** Follow-up for the agent: verify or say plainly that nothing was verified. */
+export function doneNudge(verdict) {
+    const failed = verdict.evidence.checks.filter(check => !check.passed);
+    const detail = failed.length ? `The last check that ran failed: ${failed.at(-1).call}. Fix that first.` : "Run the project's tests, build, or lint (whatever exists) on what you changed.";
+    return `pi-warden: ${verdict.reasons.join("; ")}. ${detail} Then report the actual result. If no check exists or can run, say so explicitly instead of presenting the work as done.`;
+}
+export function formatDone(verdict) {
+    const parts = [`warden · done-check · ${verdict.evidence.mutations} changes · ${verdict.evidence.checks.filter(check => check.passed).length}/${verdict.evidence.checks.length} checks passed`];
+    if (verdict.judgment)
+        parts.push(`claims done ${verdict.judgment.claimsDone.toFixed(2)}`, `claims verified ${verdict.judgment.claimsVerified.toFixed(2)}`, `checks apply ${verdict.judgment.verificationApplies.toFixed(2)}`, verdict.judgment.outcome);
+    if (verdict.error)
+        parts.push("typesafe error");
+    parts.push(verdict.falseClaim ? "false claim" : verdict.unverified ? "unverified" : "ok");
+    return parts.join(" · ");
+}

package/dist/extension.d.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends the latest user request plus a redacted, truncated summary of each guarded bash, write, or edit call (command text, file path, content excerpt) to api.typesafe.ai before the tool runs. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+import type { Verdict } from "./guard.js";
+export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; and the agent's final message when it reports completion without running checks. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+export declare function confirmMessage(verdict: Verdict): string;
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi: ExtensionAPI): void;