pi-warden 0.9.0 → 0.10.0

package/README.md

@@ -6,6 +6,8 @@ A second pair of eyes for [Pi](https://pi.dev). It watches what the agent does,
 
 The verdicts above are real output from `npm run test:live`. Independent project; not affiliated with TypeSafe AI or the Pi authors. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
 
+Default configs and a starter rules file are in [`examples/`](examples/).
+
 ## What it does
 
 | Guard | Watches | Does |
@@ -42,6 +44,8 @@ Requires Pi 0.85 or newer and Node.js 22.19 or newer. Pattern checks work with n
 
 `TYPESAFE_API_KEY` in the environment takes precedence over the stored key. Headless runs give consent with `PI_WARDEN_ENABLED=1`.
 
+The [examples README](examples/README.md) walks through the starter `pi-warden.md`, the project `.pi/pi-warden.json`, and the user `config.json`.
+
 ## Philosophy
 
 pi-warden is a harness for the agent, not a gate for you. Three jobs:
@@ -70,9 +74,11 @@ Runs on `tool_call`, before the tool executes.
 
 The action guard receives your latest message plus up to eight earlier user and assistant messages (750 redacted characters each) so follow-ups and side comments do not replace the task. Sibling tool calls in one assistant message are judged together in one round trip. If TypeSafe cannot answer, the call is allowed with a warning (`failOpen: true`; set it to `false` to hold instead).
 
+**Hold feedback.** What you do next labels each judgment, so hold precision is measured on your sessions rather than assumed. A hold your reply releases (or the confirm dialog allows) was a false positive; a hold you decline, or that nobody approves after you replied and the next turn ended, stood. An allowed call your next message tells the agent to stop, undo, or revert was a miss: one `regretted` question rides the first action request after your reply, with the redacted summaries of last turn's allowed calls (a locator names the one when there are several); offline, a stop-word heuristic stands in. `/warden status` shows the counts and the precision, the trace entry of each call gets its outcome, and every judged call is written with its scores and outcome to an owner-only per-session file under `~/.pi/agent/pi-warden/holds/` (tool, pattern ids, scores, level, mode, outcome; never the command). `"action": { "feedbackLog": false }` keeps the counts and skips the file.
+
 ### Rules
 
-Write your project's rules as Markdown headings in `pi-warden.md` at the project root:
+Write your project's rules as Markdown headings in `pi-warden.md` at the project root (a starter file with a dozen rules is in [`examples/pi-warden.md`](examples/pi-warden.md)):
 
 ```markdown
 # No console statements
@@ -149,7 +155,7 @@ Nudges from the rules, slop, stuck, done, and prose guards are custom messages i
 
 | Command | Effect |
 | --- | --- |
-| `/warden status` | Guard state, consent and key source, session counts, thresholds, rules source, config paths, last verdicts |
+| `/warden status` | Guard state, consent and key source, session counts, thresholds, hold precision and feedback log, rules source, config paths, last verdicts |
 | `/warden enable` | Data notice, key prompt if none is stored, consent saved |
 | `/warden disable` | Stop Jev judgments; pattern checks continue |
 | `/warden mode steer\|confirm\|advise` | How holds are handled; without an argument, show the current mode |
@@ -196,7 +202,8 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
     "tools": ["bash", "powershell", "ctx_execute", "ctx_batch_execute", "ctx_execute_file", "write", "edit"],
     "failOpen": true,
     "irreversible": { "warn": 0.5, "confirm": 0.7 },
-    "offTask": { "warn": 0.6, "confirm": 0.85 }
+    "offTask": { "warn": 0.6, "confirm": 0.85 },
+    "feedbackLog": true
   },
   "rules": {
     "enabled": true,
@@ -226,7 +233,7 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
 
 A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides: stricter thresholds, extra guarded tools, `rules.files`, `rules.skip`, `rules.sensitivePaths`, or `"done": { "enabled": false }`. Project files are read only when Pi trusts the project. They can never grant `typesafe` consent, change `mode`, raise `timeoutMs` or `maxRequests`, or set `notify.command`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_MODE=steer|confirm|advise`.
 
-A wince-style setup for a backend repo:
+A wince-style setup for a backend repo (the full version is [`examples/pi-warden.json`](examples/pi-warden.json)):
 
 ```json
 {
@@ -245,18 +252,20 @@ A wince-style setup for a backend repo:
 
 With consent, requests go to `https://api.typesafe.ai`. What is sent:
 
-- **Action guard**: your latest prompt (1500 characters), up to eight earlier user and assistant messages (750 redacted characters each), the tool name, the command (2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character head/middle/tail sample of a `write`, the first three edit pairs (400 characters each) of an `edit`.
+- **Action guard**: your latest prompt (1500 characters), up to eight earlier user and assistant messages (750 redacted characters each), the tool name, the command (2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character head/middle/tail sample of a `write`, the first three edit pairs (400 characters each) of an `edit`. On the first guarded call after your reply, the tool names and commands (300 characters) or paths of up to six calls allowed in the previous turn, for the regret question.
 - **Rules**: the project-relative path, a 6000-character sample of a `write` or each edit's new text (1500 characters) with about 40 lines of the current file around the replaced text, and the rule text from your rules file or the condensed fallback document (`rules.maxChars`). No task text. Files under `rules.exclude` are never sent.
 - **Stuck**: the last 12 tool calls (300 characters each) with 400-character output tails.
 - **Done-check and prose**: the agent's final message (2000 and 2500 characters), the run's check commands, the audience description.
 - **Output checks**: a redacted head/tail sample up to 6000 characters plus size, line counts, and tool name.
 - **Nothing** for duplicate detection, the runaway guard, sensitive-path notes, or pattern checks.
 
+The hold feedback log under `~/.pi/agent/pi-warden/holds/` stays on this machine, owner-only: one JSON line per judged call with tool, pattern ids, scores, level, mode, and outcome; never the command, path, or prompt.
+
 Obvious credentials (`Authorization` headers, `TOKEN=` and `SECRET=` assignments, `sk-`, `ghp_`, `AKIA`, JWTs, URL passwords, PEM blocks) are replaced with `[redacted]` before sending. Best-effort; do not rely on it for prompts that contain secrets. Text steered to the agent names the tool, the reasons, and the scores, not the command. UI errors never include upstream response bodies or keys. Judgments are model output; thresholds are yours to tune.
 
 ## After updating the package
 
-Run `/reload` in each open Pi session after an update. If a session reports `Cannot read properties of undefined (reading 'enabled')` while a fresh session works, restart it: the loaded modules do not match the files on disk. Since 0.5.2 the extension checks the shape of the config it receives; a missing section (an extension module and a config module from different versions in one process) switches that guard off and prints one warning naming the sections and the schema numbers. If you see it, restart Pi.
+Restart Pi after an update; `/reload` re-imports the entry module but can leave older modules of the same package in memory. Since 0.5.2 the extension checks the shape of the config it receives; a section that an older module does not know (the symptom of two package versions in one process) switches that guard off and prints one warning naming the sections and the schema numbers. 0.9.0 crashed instead when the shape-check module itself was the stale one; since 0.9.1 the extension guards the sections it reads in its own module, so the warning appears and everything else keeps working. If you see the warning, restart Pi.
 
 ## For extension authors
 
@@ -286,7 +295,7 @@ What spans calls in a session lives in `ActionGuard` (hold, reply, retry approva
 ```bash
 npm install
 npm run check                    # typecheck, offline tests (mocked transport), build
-npm run test:live                # billable synthetic judgments across the guards; pass action|slop|approval|stuck|done|security|context for one group
+npm run test:live                # billable synthetic judgments across the guards; pass action|slop|approval|regret|stuck|done|security|context for one group
 node scripts/rules-cases.mjs     # 13 billable cases against an 8-rule fixture file
 node scripts/slop-cases.mjs      # 22 billable cases for the slop and prose questions
 node scripts/security-cases.mjs  # 9 output-security and task-continuity cases

package/dist/action-guard.d.ts

@@ -1,5 +1,5 @@
 import type { ActionGuardConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
-import type { TaskMessage, Verdict } from "./guard.js";
+import type { PreviousAction, TaskMessage, Verdict } from "./guard.js";
 import type { Judge } from "./jev.js";
 /** One tool call as the agent proposed it. `id` is Pi's tool call id, stable across hooks and retries. */
 export interface ToolCallRef {
@@ -23,6 +23,8 @@ export interface InspectOptions {
     signal?: AbortSignal | undefined;
     slop?: SlopGuardConfig | undefined;
     security?: SecurityConfig | undefined;
+    /** Calls allowed in the previous turn; the regret question about them rides this call's request, never a sibling's. */
+    previousActions?: readonly PreviousAction[] | undefined;
 }
 /**
  * The Action guard for one session. `evaluateAction` judges a single call; this module owns what spans calls:

package/dist/action-guard.js

@@ -20,7 +20,7 @@ export class ActionGuard {
         const { task } = conversation;
         // A hold happened under an earlier prompt and the user has since replied: ask whether the reply approves this action.
         const retryAfterHold = this.holdPending && this.lastHoldPrompt !== task;
-        const judgeCall = (tool, input) => evaluateAction({ tool, input, cwd: options.cwd, task, context: conversation.context }, { config: options.config, judge: options.judge, signal: options.signal, slop: options.slop, security: options.security, retryAfterHold });
+        const judgeCall = (tool, input, previousActions) => evaluateAction({ tool, input, cwd: options.cwd, task, context: conversation.context }, { config: options.config, judge: options.judge, signal: options.signal, slop: options.slop, security: options.security, retryAfterHold, previousActions });
         // A retry after a hold stays sequential because an approval consumed by one sibling changes the question for the next.
         if (options.judge && !retryAfterHold) {
             for (const sibling of conversation.siblings ?? []) {
@@ -33,7 +33,7 @@ export class ActionGuard {
         }
         const key = JSON.stringify(call.input);
         const ready = this.prejudged.get(call.id);
-        const pending = ready && !ready.used && ready.key === key && !retryAfterHold ? ready.verdict : judgeCall(call.tool, call.input);
+        const pending = ready && !ready.used && ready.key === key && !retryAfterHold ? ready.verdict : judgeCall(call.tool, call.input, options.previousActions);
         this.prejudged.set(call.id, { key, verdict: pending, used: true });
         const verdict = await pending;
         if (retryAfterHold && !options.judge && verdict.level === "confirm" && textApproves(task)) {

package/dist/config.d.ts

@@ -15,6 +15,8 @@ export interface ActionGuardConfig {
     timeoutMs: number;
     irreversible: Threshold;
     offTask: Threshold;
+    /** Write each judged call and what the user did next (approved, declined, re-planned, regretted) to an owner-only per-session file under the agent directory; redacted, never the command. */
+    feedbackLog: boolean;
 }
 export interface StuckGuardConfig {
     enabled: boolean;

package/dist/config.js

@@ -25,6 +25,7 @@ export function defaultConfig() {
             timeoutMs: 5000,
             irreversible: { warn: 0.5, confirm: 0.7 },
             offTask: { warn: 0.6, confirm: 0.85 },
+            feedbackLog: true,
         },
         stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, nudge: true },
         done: { enabled: true, claimsDone: 0.7, nudge: true },
@@ -92,6 +93,7 @@ function applyAction(base, raw, timeoutMs) {
         timeoutMs,
         irreversible: threshold(raw.irreversible, base.irreversible),
         offTask: threshold(raw.offTask, base.offTask),
+        feedbackLog: boolean(raw.feedbackLog, base.feedbackLog),
     };
 }
 function applyStuck(base, raw) {

package/dist/extension.d.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ToolCallRef } from "./action-guard.js";
 import type { SlopSymptom, Verdict } from "./guard.js";
-export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. 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 { ShapeResult } from "./shape.js";
+export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; redacted tool-output samples for security and context saving (retention and output format); and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 /**
  * Tool calls of the assistant message being preflighted. Pi runs `tool_call` hooks for sibling calls one after another,
  * so judging them one request at a time costs one round trip per call; judging them together costs one round trip.
@@ -10,5 +11,11 @@ export declare function siblingToolCalls(ctx: ExtensionContext): ToolCallRef[];
 export declare function confirmMessage(verdict: Verdict): string;
 /** Names each symptom and its fix; repeats in the session turn the note into a standing rule. */
 export declare function slopSteer(where: string, symptoms: readonly SlopSymptom[], counts: Record<SlopSymptom, number>): string;
+/**
+ * `completeConfig` in shape.ts fills sections an older config module lacks, but shape.ts can be the stale module too: the
+ * 0.8 version knew nothing of `rules`, so a 0.9 extension read `config.rules.enabled` on undefined and every tool call
+ * failed until Pi was restarted. The sections this build reads are therefore checked here as well, in the module that reads them.
+ */
+export declare function guardCurrentSections(result: ShapeResult): ShapeResult;
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -6,6 +6,7 @@ import * as configModule from "./config.js";
 import { applyUserOverrides, defaultConfig, isMode, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
 import { classifyToolResult, doneNudge, emptyEvidence, evaluateDone, finalAssistantText, formatDone, needsDoneCheck, recordOutcome } from "./done.js";
 import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason } from "./guard.js";
+import { formatHolds, HoldLedger, HoldLog, holdLogPath, outcomeNote, regretsAt, textRegrets } from "./holds.js";
 import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
 import { compressOutput, duplicateNote, evaluateOutput, outputKey, saveOutput, securityNotice } from "./output.js";
 import { classifyRecall, detectSearchTool, recallInstruction } from "./recall.js";
@@ -18,8 +19,8 @@ import { openTracePanel } from "./panel.js";
 import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
 import { actionDetails, doneDetails, proseDetails, rulesDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
-import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
-export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. 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 { DEFAULT_TEMPLATES, proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
+export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; redacted tool-output samples for security and context saving (retention and output format); and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
 const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, ruleChecks: 0, ruleViolations: 0, pathNotes: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, runaway: 0, errors: 0 });
@@ -115,6 +116,28 @@ export function slopSteer(where, symptoms, counts) {
     const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
     return `pi-warden: the content just written to ${where} has ${named}. Fix it in your next edit: ${fixes}.${standing}`;
 }
+/**
+ * `completeConfig` in shape.ts fills sections an older config module lacks, but shape.ts can be the stale module too: the
+ * 0.8 version knew nothing of `rules`, so a 0.9 extension read `config.rules.enabled` on undefined and every tool call
+ * failed until Pi was restarted. The sections this build reads are therefore checked here as well, in the module that reads them.
+ */
+export function guardCurrentSections(result) {
+    const { config } = result;
+    const missing = [...result.missing];
+    if (typeof config.rules !== "object" || config.rules === null || !Array.isArray(config.rules.exclude)) {
+        if (!missing.includes("rules"))
+            missing.push("rules");
+        config.rules = { enabled: false, threshold: 1, files: [], fallback: false, maxChars: 500, exclude: [], skip: [], sensitivePaths: {} };
+    }
+    if (typeof config.widget !== "object" || config.widget === null) {
+        if (!missing.includes("widget"))
+            missing.push("widget");
+        config.widget = { ...defaultConfig().widget, enabled: false };
+    }
+    if (typeof config.widget.rules !== "string")
+        config.widget = { ...config.widget, rules: DEFAULT_TEMPLATES.rules };
+    return { config, missing };
+}
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi) {
     let client;
@@ -126,6 +149,12 @@ export default function wardenExtension(pi) {
     let lastUi;
     const actionGuard = new ActionGuard();
     const rulesGuard = new RulesGuard();
+    // Hold feedback: what the user did after each judged call, the trace entry each label lands on, and the per-session log.
+    const holds = new HoldLedger();
+    const traceOf = new WeakMap();
+    let holdLog;
+    // Allowed calls of the turn the user just replied to; the regret question about them rides the next action request.
+    let regretCandidates = [];
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
@@ -144,7 +173,7 @@ export default function wardenExtension(pi) {
     // A partially updated module graph can hand this build a config without the sections it expects; see shape.ts.
     let shapeReported = false;
     const configFor = (ctx) => {
-        const { config, missing } = completeConfig(loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }));
+        const { config, missing } = guardCurrentSections(completeConfig(loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() })));
         if (missing.length && !shapeReported) {
             shapeReported = true;
             // A namespace read stays undefined (not a link error) when an older config module lacks the export.
@@ -202,8 +231,25 @@ export default function wardenExtension(pi) {
     };
     const record = (ctx, config, guard, line, details) => {
         widget.set(guard, line);
-        trace.push({ at: Date.now(), guard, line, details });
+        const entry = { at: Date.now(), guard, line, details };
+        trace.push(entry);
         paint(ctx, config);
+        return entry;
+    };
+    /** Labels landed on earlier calls: their trace entries say so and the session log is rewritten. */
+    const noteOutcomes = (config, records) => {
+        for (const item of records) {
+            const entry = traceOf.get(item);
+            if (entry)
+                trace.amend(entry, outcomeNote(item));
+        }
+        if (config.action.feedbackLog && holds.records().length)
+            void holdLog?.save(holds.records());
+    };
+    /** The user's reply was read for regret, by Jev or by the offline heuristic; the candidates are labelled once. */
+    const settleRegret = (config, result) => {
+        regretCandidates = [];
+        noteOutcomes(config, holds.regret(result));
     };
     const steer = (config, content, options = { deliverAs: "steer" }) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: config.steerVisible }, options);
     /**
@@ -233,6 +279,9 @@ export default function wardenExtension(pi) {
         panel?.close();
         actionGuard.reset();
         rulesGuard.reset();
+        holds.reset();
+        regretCandidates = [];
+        holdLog = new HoldLog(holdLogPath(typeof ctx.sessionManager.getSessionId === "function" ? ctx.sessionManager.getSessionId() : String(process.pid)));
         attempts.reset();
         evidence = emptyEvidence();
         doneNudged = false;
@@ -250,14 +299,20 @@ export default function wardenExtension(pi) {
             ctx.ui.setWidget(WIDGET, undefined);
     });
     // A new user prompt starts a new attempt history and a new done-check budget.
-    pi.on("before_agent_start", async (_event, ctx) => {
-        attempts = new AttemptWindow(configFor(ctx).stuck.window);
+    pi.on("before_agent_start", async (event, ctx) => {
+        const config = configFor(ctx);
+        attempts = new AttemptWindow(config.stuck.window);
         doneNudged = false;
         runaway.reset();
         runawayStops = 0;
         pendingRunaway = undefined;
         actionGuard.turnEnd();
         rulesGuard.turnEnd();
+        // Holds the user never approved are re-plans now; last turn's allowed calls wait for the regret question.
+        noteOutcomes(config, holds.promptArrived());
+        regretCandidates = holds.candidates();
+        if (regretCandidates.length && !judgeFor(config))
+            settleRegret(config, { regretted: textRegrets(event.prompt), via: "text" });
     });
     // Each assistant message is judged on its own; Pi does not forward the stream's own "start" event, so this is the reset.
     pi.on("message_start", async (event) => {
@@ -323,9 +378,12 @@ export default function wardenExtension(pi) {
             ? rulesGuard.inspect(call, siblings, { cwd: ctx.cwd, config: config.rules, judge, timeoutMs: config.timeoutMs, signal: ctx.signal })
             : undefined;
         rulesCheck?.catch(() => undefined);
-        const verdict = await actionGuard.inspect(call, { task, context: recentTaskContext(ctx), siblings }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security });
+        const verdict = await actionGuard.inspect(call, { task, context: recentTaskContext(ctx), siblings }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security, previousActions: regretCandidates.length ? regretCandidates : undefined });
         if (verdict.source === "skipped")
             return;
+        if (regretCandidates.length && verdict.judgment?.regretted !== undefined) {
+            settleRegret(config, { regretted: regretsAt(verdict.judgment.regretted), target: verdict.judgment.regretTarget, probability: verdict.judgment.regretted, via: "jev" });
+        }
         // Notes for the agent about the content it just wrote: slop, rule violations, and sensitive paths arrive as one message.
         const notes = [];
         if (verdict.judgment?.securityRisk !== undefined && verdict.judgment.securityRisk >= config.security.threshold) {
@@ -335,12 +393,23 @@ export default function wardenExtension(pi) {
             stats.judged++;
         if (verdict.source === "error")
             noteError(ctx, verdict.error ?? "TypeSafe request failed.", verdict.errorCode);
-        if (verdict.approvedByUser)
-            stats.approved++;
         const mode = activeMode(config, ctx.hasUI);
+        if (verdict.approvedByUser) {
+            stats.approved++;
+            const released = holds.approved(event.toolName);
+            if (released)
+                noteOutcomes(config, [released]);
+        }
         const told = verdict.level === "confirm" && mode === "steer" ? steerReason(verdict, { canApprove: judge !== undefined }) : undefined;
-        if (verdict.source !== "read-only")
-            record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode, ...(told ? { told } : {}) }));
+        const entry = verdict.source !== "read-only" ? record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode, ...(told ? { told } : {}) })) : undefined;
+        // What happens to this call is the label for its scores; a decision made in the dialog lands at once, a steer-mode hold waits for the user.
+        const track = (held, outcome, via) => {
+            if (!entry)
+                return;
+            const item = holds.record(verdict, { held, mode, outcome, via });
+            traceOf.set(item, entry);
+            noteOutcomes(config, outcome ? [item] : []);
+        };
         if (verdict.slopSymptoms?.length && verdict.slopReasons) {
             stats.slop++;
             for (const symptom of verdict.slopSymptoms)
@@ -381,27 +450,35 @@ export default function wardenExtension(pi) {
             stats.warned++;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · ${event.toolName}: ${verdict.reasons.join("; ")}`, "warning");
+            track(false);
             return undefined;
         }
-        if (verdict.level !== "confirm")
+        if (verdict.level !== "confirm") {
+            track(false);
             return undefined;
+        }
         const reasons = verdict.reasons.join("; ");
         if (mode === "advise") {
             stats.warned++;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · ${event.toolName} (advise mode, not held): ${reasons}`, "warning");
+            track(false);
             return undefined;
         }
         if (mode === "confirm") {
             notifyDesktop(ctx, config, `Waiting for you: allow this ${event.toolName} call? ${reasons}`);
             const allowed = await ctx.ui.confirm(`warden: allow this ${event.toolName} call?`, confirmMessage(verdict), ctx.signal ? { signal: ctx.signal } : {});
-            if (allowed)
+            if (allowed) {
+                track(true, "approved", "dialog");
                 return undefined;
+            }
             stats.held++;
+            track(true, "declined", "dialog");
             return { block: true, reason: `pi-warden: the user declined this ${event.toolName} call (${reasons}). Do not retry it unchanged; ask the user how to proceed.` };
         }
         stats.held++;
         actionGuard.hold(task);
+        track(true);
         if (ctx.hasUI)
             ctx.ui.notify(`warden · held ${event.toolName}: ${reasons}. The agent was told why and asked to re-plan or ask you.`, "warning");
         notifyDesktop(ctx, config, `Held ${event.toolName}: ${reasons}. The agent will re-plan or ask you in chat.`);
@@ -528,6 +605,9 @@ export default function wardenExtension(pi) {
         const config = configFor(ctx);
         if (!config.enabled)
             return;
+        // No guarded call carried the regret question this run (the agent only replied): the offline heuristic reads the prompt.
+        if (regretCandidates.length)
+            settleRegret(config, { regretted: textRegrets(latestUserPrompt(ctx)), via: "text" });
         if (pendingRunaway) {
             const { nudge, recover } = pendingRunaway;
             pendingRunaway = undefined;
@@ -625,6 +705,7 @@ export default function wardenExtension(pi) {
                         `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.ruleViolations}/${stats.ruleChecks} rule violations, ${stats.pathNotes} sensitive-path notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.runaway} runaway stops, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
                         `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, rules ${config.rules.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; runaway ${config.runaway.repeats} repeats (thinking ${config.runaway.thinkingRepeats}), recover ${config.runaway.recover}; failOpen ${config.action.failOpen}.`,
                         formatLedger(ledger.snapshot()),
+                        `${formatHolds(holds.snapshot(), config.action.feedbackLog ? holdLog?.path : undefined)}${holdLog?.lastFailure ? ` Log write failed: ${holdLog.lastFailure}.` : ""}`,
                         `Rules: ${config.rules.enabled ? `${rulesGuard.describe(ctx.cwd, config.rules)}${Object.keys(config.rules.sensitivePaths).length ? `; ${Object.keys(config.rules.sensitivePaths).length} sensitive path${Object.keys(config.rules.sensitivePaths).length === 1 ? "" : "s"}` : ""}` : "off"}.`,
                         `Desktop notifications: ${config.notify.enabled ? `on (${config.notify.command.length ? `command ${config.notify.command[0]}` : (await (notifier ??= detectNotifier())) ?? "no notifier found on this machine"}; cooldown ${config.notify.cooldownMs} ms)` : "off"}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,

package/dist/guard.d.ts

@@ -48,6 +48,10 @@ export interface Judgment {
     scopeConfidence: number;
     /** P(the latest user message approves this exact action); only asked when a previously held call is retried. */
     approved?: number;
+    /** P(the latest user message regrets an allowed call of the previous turn); asked once per prompt, on its first action request. */
+    regretted?: number;
+    /** The id of the regretted previous action when several were offered. */
+    regretTarget?: string;
     securityRisk?: number;
     /** P(the action changes files, state, or external systems). Off-task alone holds only actions that can change something. */
     mutates?: number;
@@ -63,6 +67,13 @@ export interface SlopJudgment {
 }
 export type SlopSymptom = keyof SlopJudgment;
 export declare const SLOP_SYMPTOMS: readonly SlopSymptom[];
+/** A call the guard allowed in the previous turn, as the regret question sees it: redacted summary fields only. */
+export interface PreviousAction {
+    id: string;
+    tool: string;
+    command?: string;
+    path?: string;
+}
 export interface Verdict {
     level: Level;
     source: "skipped" | "read-only" | "pattern" | "typesafe" | "error";
@@ -92,6 +103,8 @@ export interface EvaluateOptions {
     security?: SecurityConfig | undefined;
     /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
     retryAfterHold?: boolean | undefined;
+    /** Calls allowed in the previous turn: ask whether the user's latest message regrets one of them (rides this request). */
+    previousActions?: readonly PreviousAction[] | undefined;
 }
 export interface ScannedCommand {
     /** The command with data text blanked; what the pattern rules read. */
@@ -131,13 +144,33 @@ export declare const securityQuestion: {
 export declare const approvalQuestion: {
     approved: import("pi-typesafe").NoulQuestion;
 };
+/**
+ * One yes/no on whether the user's reply regrets what the agent did last turn; with several candidates a Choice names the
+ * one. Labels the allowed calls for hold calibration and never changes the verdict on the current call.
+ */
+export declare function regretQuestions(actions: readonly PreviousAction[]): {
+    regretted: import("pi-typesafe").NoulQuestion;
+    regret_target?: never;
+} | {
+    regretted: import("pi-typesafe").NoulQuestion;
+    regret_target: import("pi-typesafe").ChoiceQuestion<{
+        [k: string]: string;
+    }>;
+};
 export declare function buildRequest(summary: ActionSummary, task: string | undefined, extras?: {
     slop?: boolean;
     approval?: boolean;
     security?: boolean;
     context?: readonly TaskMessage[] | undefined;
+    previousActions?: readonly PreviousAction[] | undefined;
 }): {
     state: {
+        previous_actions?: {
+            command?: string;
+            id: string;
+            tool: string;
+            path?: string;
+        }[];
         task: string;
         action: Record<string, string | number | boolean>;
         context: {
@@ -146,6 +179,44 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
         }[];
     };
     questions: {
+        regretted: import("pi-typesafe").NoulQuestion;
+        regret_target?: never;
+        security_risk?: import("pi-typesafe").NoulQuestion;
+        approved?: import("pi-typesafe").NoulQuestion;
+        slop_stub?: import("pi-typesafe").NoulQuestion;
+        slop_comments?: import("pi-typesafe").NoulQuestion;
+        slop_dead?: import("pi-typesafe").NoulQuestion;
+        slop_hedging?: import("pi-typesafe").NoulQuestion;
+        irreversible: import("pi-typesafe").NoulQuestion;
+        off_task: import("pi-typesafe").NoulQuestion;
+        mutates: import("pi-typesafe").NoulQuestion;
+        scope: import("pi-typesafe").ChoiceQuestion<{
+            readonly expected_step: "Required implementation, bug fix, regression test, or verification for the active task";
+            readonly plausible_side_step: "Reasonable supporting work whose necessity is not yet established";
+            readonly unrelated: "No useful connection to the active task, or contrary to the user's current direction";
+            readonly unclear: "The supplied conversation or action gives too little information to establish scope; this is not itself a violation";
+        }>;
+    } | {
+        regretted: import("pi-typesafe").NoulQuestion;
+        regret_target: import("pi-typesafe").ChoiceQuestion<{
+            [k: string]: string;
+        }>;
+        security_risk?: import("pi-typesafe").NoulQuestion;
+        approved?: import("pi-typesafe").NoulQuestion;
+        slop_stub?: import("pi-typesafe").NoulQuestion;
+        slop_comments?: import("pi-typesafe").NoulQuestion;
+        slop_dead?: import("pi-typesafe").NoulQuestion;
+        slop_hedging?: import("pi-typesafe").NoulQuestion;
+        irreversible: import("pi-typesafe").NoulQuestion;
+        off_task: import("pi-typesafe").NoulQuestion;
+        mutates: import("pi-typesafe").NoulQuestion;
+        scope: import("pi-typesafe").ChoiceQuestion<{
+            readonly expected_step: "Required implementation, bug fix, regression test, or verification for the active task";
+            readonly plausible_side_step: "Reasonable supporting work whose necessity is not yet established";
+            readonly unrelated: "No useful connection to the active task, or contrary to the user's current direction";
+            readonly unclear: "The supplied conversation or action gives too little information to establish scope; this is not itself a violation";
+        }>;
+    } | {
         security_risk?: import("pi-typesafe").NoulQuestion;
         approved?: import("pi-typesafe").NoulQuestion;
         slop_stub?: import("pi-typesafe").NoulQuestion;

package/dist/guard.js

@@ -64,7 +64,8 @@ const GIT_MESSAGE_SUBCOMMANDS = new Set(["commit", "tag", "notes", "merge", "sta
 /** Interpreters whose stdin script can still run shell commands; their heredoc bodies stay in scope when they do. */
 const INTERPRETERS = /^(?:python[\d.]*|node|ruby|perl|php|deno|bun|tsx|Rscript|lua[\d.]*)$/;
 const EXEC_CALLS = /\b(?:os\.system|os\.popen|os\.exec\w*|subprocess|child_process|execSync|spawnSync|execFileSync|spawn\(|exec\(|system\(|popen\(|shell_exec|passthru|proc_open|Open3|IO\.popen|Deno\.run|Deno\.Command|Bun\.spawn|Bun\.\$|%x[\[{(]|`[^`\n]*\b(?:rm|git|dd|mkfs|kubectl|terraform)\b)/;
-const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|\\?(\w+))/;
+const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|(\\)?(\w+))/;
+const SUBSTITUTION = /\$\(|`/;
 function headOf(segment) {
     const tokens = segment.trim().split(/\s+/);
     let index = 0;
@@ -73,7 +74,10 @@ function headOf(segment) {
     const head = tokens[index];
     return head ? head.replace(/^.*\//, "") : undefined;
 }
-/** Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything. */
+/**
+ * Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything.
+ * A double-quoted string that substitutes a command (`"$(...)"`, backticks) executes it, so that string stays visible.
+ */
 function blankQuotes(segment) {
     let out = "";
     for (let index = 0; index < segment.length; index++) {
@@ -89,7 +93,8 @@ function blankQuotes(segment) {
             out += segment.slice(index);
             break;
         }
-        out += `${char}[text]${char}`;
+        const inner = segment.slice(index + 1, end);
+        out += char === "\"" && SUBSTITUTION.test(inner) ? `${char}${inner}${char}` : `${char}[text]${char}`;
         index = end;
     }
     return out;
@@ -111,8 +116,6 @@ function isDataSegment(segment) {
  * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
  */
 export function stripDataText(command) {
-    if (/\$\(|`/.test(command))
-        return { text: command, stripped: false };
     const lines = command.split("\n");
     const out = [];
     let stripped = false;
@@ -123,14 +126,18 @@ export function stripDataText(command) {
             out.push(line);
             continue;
         }
-        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[3];
-        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[4];
+        // 'EOF', "EOF", and \EOF make the body literal; a bare EOF body is expanded, so a substitution inside it runs.
+        const literal = heredoc[4] === undefined || heredoc[3] !== undefined;
         const body = [];
         let close = index + 1;
         while (close < lines.length && lines[close].replace(/^\t+/, "") !== delimiter)
             body.push(lines[close]), close++;
         const bodyText = body.join("\n");
-        const executed = SHELL_SINKS.has(consumer) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText));
+        // The whole pipeline on the heredoc line counts: `cat <<EOF | bash` executes the body as much as `bash <<EOF` does.
+        const heads = splitShell(line).map(segment => headOf(segment) ?? "");
+        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const executed = heads.some(head => SHELL_SINKS.has(head)) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText)) || (!literal && SUBSTITUTION.test(bodyText));
         out.push(line);
         if (executed)
             out.push(...body);
@@ -144,10 +151,11 @@ export function stripDataText(command) {
     }
     const joined = out.join("\n");
     const segments = splitShell(joined);
+    // A shell sink anywhere may run text written earlier in the same command (`cat <<EOF > run.sh` then `bash run.sh`), so nothing is treated as data.
     if (segments.some(segment => { const head = headOf(segment); return head !== undefined && SHELL_SINKS.has(head); }))
-        return { text: joined, stripped };
+        return { text: command, stripped: false };
     if (/\b(?:ba|z|da|k)?sh\s+-[a-zA-Z]*c\b/.test(joined))
-        return { text: joined, stripped };
+        return { text: command, stripped: false };
     let text = joined;
     for (const segment of segments) {
         if (!isDataSegment(segment) || !/["']/.test(segment))
@@ -162,13 +170,13 @@ export function stripDataText(command) {
 }
 /**
  * rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are
- * risky. A quote before `rm` is allowed so `bash -c "rm -rf /"` is read; data quotes were blanked before this runs.
+ * risky. A quote or parenthesis before `rm` is allowed so a quoted or substituted command is read; data quotes were blanked before this runs.
  */
 function classifyRm(segment, cwd) {
-    const match = /(?:^|[\s"'])rm\s+(.*)$/.exec(segment);
+    const match = /(?:^|[\s"'(])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
-    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["']$/, ""));
+    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["')]+$/, ""));
     const flags = tokens.filter(token => token.startsWith("-"));
     const targets = tokens.filter(token => !token.startsWith("-"));
     const recursive = flags.some(flag => flag === "--recursive" || (/^-[a-zA-Z]+$/.test(flag) && /[rR]/.test(flag)));
@@ -374,22 +382,42 @@ export const approvalQuestion = {
         false: "No: the message declines, asks for something else, changes the approach, or does not address this action.",
     }),
 };
+/**
+ * One yes/no on whether the user's reply regrets what the agent did last turn; with several candidates a Choice names the
+ * one. Labels the allowed calls for hold calibration and never changes the verdict on the current call.
+ */
+export function regretQuestions(actions) {
+    const regretted = noul("Does `task` (the user's latest message) tell the agent to stop, undo, revert, or not do one of the calls in `previous_actions`, which the agent ran in its previous turn? Judge only `task`; `context` explains what the agent was doing.", {
+        true: "Yes: the user says wait, stop, don't, undo, revert, or roll back, objects that a call should not have run, or asks why the agent did it.",
+        false: "No: the user continues, approves, asks for something new, reports a result, or the message does not address those calls.",
+    });
+    if (actions.length < 2)
+        return { regretted };
+    return {
+        regretted,
+        regret_target: choice("If `task` regrets one of `previous_actions`, which one does it most likely mean?", Object.fromEntries(actions.map(action => [action.id, `${action.tool}: ${action.command ?? action.path ?? "(no detail)"}`]))),
+    };
+}
 function hasContent(summary) {
     return (summary.excerpt?.trim().length ?? 0) > 0 || (summary.edits?.some(edit => edit.newText.trim().length > 0) ?? false);
 }
 export function buildRequest(summary, task, extras = {}) {
     const wantSlop = extras.slop && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary);
+    const previous = (extras.previousActions ?? []).slice(-PREVIOUS_ACTIONS_LIMIT).map(action => ({ ...action, ...(action.command !== undefined ? { command: truncate(action.command, PREVIOUS_COMMAND_LIMIT) } : {}) }));
     return {
         state: {
             task: task?.trim() ? truncate(redact(task.trim()), TASK_LIMIT) : "(no user request recorded in this session)",
             action: summary,
             context: (extras.context ?? []).slice(-8).map(message => ({ role: message.role, text: truncate(redact(message.text), 750) })),
+            ...(previous.length ? { previous_actions: previous } : {}),
         },
-        questions: { ...questions, ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}), ...(extras.security && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary) ? securityQuestion : {}) },
+        questions: { ...questions, ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}), ...(extras.security && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary) ? securityQuestion : {}), ...(previous.length ? regretQuestions(previous) : {}) },
     };
 }
 const percent = (value) => value.toFixed(2);
 const APPROVAL_THRESHOLD = 0.7;
+const PREVIOUS_ACTIONS_LIMIT = 6;
+const PREVIOUS_COMMAND_LIMIT = 300;
 // ---------------------------------------------------------------------------
 export async function evaluateAction(action, options) {
     const { config, judge } = options;
@@ -425,7 +453,7 @@ export async function evaluateAction(action, options) {
     }
     if (!judge)
         return { level, source: "pattern", summary, patterns, reasons };
-    const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context });
+    const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context, previousActions: options.previousActions });
     const result = await askJev(judge, request, { timeoutMs: config.timeoutMs, signal: options.signal });
     if (!result.ok) {
         if (!config.failOpen) {
@@ -450,6 +478,11 @@ export async function evaluateAction(action, options) {
         judgment.approved = answers.approved.noul;
     if (typeof answers.mutates?.noul === "number")
         judgment.mutates = answers.mutates.noul;
+    if (typeof answers.regretted?.noul === "number") {
+        judgment.regretted = answers.regretted.noul;
+        if (typeof answers.regret_target?.choice === "string")
+            judgment.regretTarget = answers.regret_target.choice;
+    }
     if (deferSensitive) {
         for (const hit of patterns) {
             if (hit.severity !== "sensitive")

package/dist/holds.d.ts

@@ -0,0 +1,120 @@
+import type { WardenMode } from "./config.js";
+import type { Level, PreviousAction, ScopeLabel, Verdict } from "./guard.js";
+/**
+ * Hold feedback loop. Every hold is a prediction ("this call should not run as it stands") and every allowed call the
+ * opposite one; what the user does next labels them, so hold precision can be measured on real sessions instead of the
+ * synthetic cases the thresholds came from:
+ *
+ * - **approved**: the user's reply released the hold (steer mode) or the confirm dialog allowed it. False positive.
+ * - **declined**: the confirm dialog refused it. True positive.
+ * - **replanned**: the user replied, the following turn ended, and nobody approved the call. True positive.
+ * - **regretted**: the user's next message tells the agent to stop, undo, or not do an allowed call. False negative.
+ * - **accepted**: the user's next message was checked and does not regret the allowed calls of the last turn.
+ *
+ * Approval, decline, and re-plan are code only. Regret is one question that rides the first action request under the
+ * new prompt (no extra request); offline a stop-word heuristic stands in. Calls the guard skipped as read-only are not
+ * recorded: they could never have been held. Records are redacted for the log: tool, pattern ids, scores, level,
+ * outcome, never the command or path. The in-memory summary serves the regret question and stays in memory.
+ */
+export type CallOutcome = "pending" | "approved" | "declined" | "replanned" | "regretted" | "accepted";
+export type OutcomeVia = "retry" | "dialog" | "next prompt" | "jev" | "text";
+export interface CallScores {
+    irreversible: number;
+    offTask: number;
+    scope: ScopeLabel;
+    mutates?: number;
+    approved?: number;
+    securityRisk?: number;
+}
+export interface CallRecord {
+    /** Sequence number within the session; the regret question names candidates by it. */
+    id: number;
+    at: number;
+    tool: string;
+    level: Level;
+    source: Verdict["source"];
+    mode: WardenMode;
+    held: boolean;
+    patterns: string[];
+    /** Reason labels as shown to the user; they name patterns and scores, never the command. */
+    reasons: string[];
+    scores?: CallScores;
+    outcome: CallOutcome;
+    outcomeAt?: number;
+    outcomeVia?: OutcomeVia;
+    /** P(regret) from the question that labelled this call, when Jev answered it. */
+    regret?: number;
+}
+export interface HoldSnapshot {
+    holds: number;
+    approved: number;
+    declined: number;
+    replanned: number;
+    /** Holds without a label yet: the user has not replied, or the turn after the reply is still running. */
+    awaiting: number;
+    allowed: number;
+    regretted: number;
+    accepted: number;
+    /** Labelled holds: approved + declined + replanned. */
+    labels: number;
+    /** (declined + replanned) / labels; undefined without labels. */
+    precision: number | undefined;
+}
+export declare class HoldLedger {
+    private readonly tracked;
+    private nextId;
+    /** One inspected call. `outcome` is set at once when the confirm dialog decided; a steer-mode hold starts pending. */
+    record(verdict: Verdict, options: {
+        held: boolean;
+        mode: WardenMode;
+        outcome?: CallOutcome | undefined;
+        via?: OutcomeVia | undefined;
+        at?: number;
+    }): CallRecord;
+    /**
+     * The user's reply released a hold: the pending hold of the same tool is the false positive, the latest one when the
+     * tools differ (the retry rarely repeats the held call byte for byte, and a hold can be released through another tool).
+     */
+    approved(tool: string, via?: OutcomeVia, at?: number): CallRecord | undefined;
+    /**
+     * A new user prompt. Every pending record has seen one more prompt. A hold still pending after the prompt that could
+     * have approved it (the reply) and the turn that followed is a re-plan: the agent found another way or the user said no.
+     */
+    promptArrived(at?: number): CallRecord[];
+    /** Allowed calls of the turn the user just replied to, oldest first: the calls the reply could regret. */
+    candidates(): PreviousAction[];
+    /**
+     * The reply was read. With regret, the located call (or the latest candidate) is the miss and the rest are accepted;
+     * without it, every candidate is accepted. Returns the records that changed.
+     */
+    regret(result: {
+        regretted: boolean;
+        target?: string | undefined;
+        probability?: number | undefined;
+        via: OutcomeVia;
+    }, at?: number): CallRecord[];
+    records(): readonly CallRecord[];
+    snapshot(): HoldSnapshot;
+    reset(): void;
+    private label;
+}
+/** Whether P(regret) from the question counts as regret. */
+export declare function regretsAt(probability: number): boolean;
+/** Offline stand-in for the regret question: the reply opens by stopping, undoing, or forbidding what was just done. */
+export declare function textRegrets(prompt: string | undefined): boolean;
+/** One line for the trace entry of a call whose outcome landed. */
+export declare function outcomeNote(record: CallRecord): string;
+/** One line for /warden status. */
+export declare function formatHolds(snapshot: HoldSnapshot, logPath?: string): string;
+/** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
+export declare function holdLogPath(sessionId: string, at?: Date): string;
+/** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */
+export declare class HoldLog {
+    readonly path: string;
+    private queue;
+    private failure;
+    constructor(path: string);
+    save(records: readonly CallRecord[]): Promise<void>;
+    /** The last write error, if the most recent save failed. */
+    get lastFailure(): string | undefined;
+}

package/dist/holds.js

@@ -0,0 +1,193 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { userConfigPath } from "./config.js";
+const REGRET_THRESHOLD = 0.7;
+function scoresOf(verdict) {
+    const { judgment } = verdict;
+    if (!judgment)
+        return undefined;
+    const scores = { irreversible: judgment.irreversible, offTask: judgment.offTask, scope: judgment.scope };
+    if (judgment.mutates !== undefined)
+        scores.mutates = judgment.mutates;
+    if (judgment.approved !== undefined)
+        scores.approved = judgment.approved;
+    if (judgment.securityRisk !== undefined)
+        scores.securityRisk = judgment.securityRisk;
+    return scores;
+}
+export class HoldLedger {
+    tracked = [];
+    nextId = 1;
+    /** One inspected call. `outcome` is set at once when the confirm dialog decided; a steer-mode hold starts pending. */
+    record(verdict, options) {
+        const at = options.at ?? Date.now();
+        const record = {
+            id: this.nextId++,
+            at,
+            tool: verdict.summary.tool,
+            level: verdict.level,
+            source: verdict.source,
+            mode: options.mode,
+            held: options.held,
+            patterns: verdict.patterns.map(hit => hit.id),
+            reasons: [...verdict.reasons],
+            outcome: options.outcome ?? "pending",
+        };
+        const scores = scoresOf(verdict);
+        if (scores)
+            record.scores = scores;
+        if (options.outcome && options.outcome !== "pending") {
+            record.outcomeAt = at;
+            if (options.via)
+                record.outcomeVia = options.via;
+        }
+        this.tracked.push({ record, summary: verdict.summary, prompts: 0 });
+        return record;
+    }
+    /**
+     * The user's reply released a hold: the pending hold of the same tool is the false positive, the latest one when the
+     * tools differ (the retry rarely repeats the held call byte for byte, and a hold can be released through another tool).
+     */
+    approved(tool, via = "retry", at = Date.now()) {
+        const pending = this.tracked.filter(item => item.record.held && item.record.outcome === "pending");
+        const match = pending.filter(item => item.record.tool === tool).at(-1) ?? pending.at(-1);
+        if (!match)
+            return undefined;
+        return this.label(match, "approved", via, at);
+    }
+    /**
+     * A new user prompt. Every pending record has seen one more prompt. A hold still pending after the prompt that could
+     * have approved it (the reply) and the turn that followed is a re-plan: the agent found another way or the user said no.
+     */
+    promptArrived(at = Date.now()) {
+        const changed = [];
+        for (const item of this.tracked) {
+            if (item.record.outcome !== "pending")
+                continue;
+            item.prompts++;
+            if (item.record.held && item.prompts >= 2)
+                changed.push(this.label(item, "replanned", "next prompt", at));
+        }
+        return changed;
+    }
+    /** Allowed calls of the turn the user just replied to, oldest first: the calls the reply could regret. */
+    candidates() {
+        return this.tracked
+            .filter(item => !item.record.held && item.record.outcome === "pending" && item.prompts === 1)
+            .map(item => ({
+            id: `a${item.record.id}`,
+            tool: item.summary.tool,
+            ...(item.summary.command !== undefined ? { command: clip(item.summary.command, 300) } : {}),
+            ...(item.summary.path !== undefined ? { path: item.summary.path } : {}),
+        }));
+    }
+    /**
+     * The reply was read. With regret, the located call (or the latest candidate) is the miss and the rest are accepted;
+     * without it, every candidate is accepted. Returns the records that changed.
+     */
+    regret(result, at = Date.now()) {
+        const candidates = this.tracked.filter(item => !item.record.held && item.record.outcome === "pending" && item.prompts === 1);
+        if (!candidates.length)
+            return [];
+        const target = result.regretted ? candidates.find(item => `a${item.record.id}` === result.target) ?? candidates.at(-1) : undefined;
+        return candidates.map(item => {
+            const record = this.label(item, item === target ? "regretted" : "accepted", result.via, at);
+            if (result.probability !== undefined)
+                record.regret = result.probability;
+            return record;
+        });
+    }
+    records() {
+        return this.tracked.map(item => item.record);
+    }
+    snapshot() {
+        const records = this.records();
+        const holds = records.filter(record => record.held);
+        const allowed = records.filter(record => !record.held);
+        const count = (list, outcome) => list.filter(record => record.outcome === outcome).length;
+        const approved = count(holds, "approved");
+        const declined = count(holds, "declined");
+        const replanned = count(holds, "replanned");
+        const labels = approved + declined + replanned;
+        return {
+            holds: holds.length, approved, declined, replanned, awaiting: count(holds, "pending"),
+            allowed: allowed.length, regretted: count(allowed, "regretted"), accepted: count(allowed, "accepted"),
+            labels, precision: labels ? (declined + replanned) / labels : undefined,
+        };
+    }
+    reset() {
+        this.tracked.length = 0;
+        this.nextId = 1;
+    }
+    label(item, outcome, via, at) {
+        item.record.outcome = outcome;
+        item.record.outcomeAt = at;
+        item.record.outcomeVia = via;
+        return item.record;
+    }
+}
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit)}…`);
+/** Whether P(regret) from the question counts as regret. */
+export function regretsAt(probability) {
+    return probability >= REGRET_THRESHOLD;
+}
+/** Offline stand-in for the regret question: the reply opens by stopping, undoing, or forbidding what was just done. */
+export function textRegrets(prompt) {
+    const text = (prompt ?? "").trim();
+    if (!text)
+        return false;
+    const opening = text.slice(0, 160);
+    return /^(?:wait(?! (?:for|until|till)\b)|stop\b|nope\b|hold on\b|don[’']t\b|do not\b|undo\b|revert\b|roll ?back\b|why did you\b|you (?:shouldn[’']t|should not) have\b|that (?:was|is) (?:wrong|not what)\b|no[,.!])/i.test(opening)
+        || /\b(?:undo|revert|roll ?back) (?:that|this|it|the last|those|what you)\b/i.test(opening)
+        || /\b(?:don[’']t|do not|never) (?:do|run|touch|push|delete|remove|commit) that\b/i.test(opening);
+}
+/** One line for the trace entry of a call whose outcome landed. */
+export function outcomeNote(record) {
+    switch (record.outcome) {
+        case "approved": return `outcome: approved by the user (${record.outcomeVia === "dialog" ? "confirm dialog" : "released on retry"}); the hold was a false positive`;
+        case "declined": return "outcome: declined by the user in the confirm dialog; the hold stood";
+        case "replanned": return "outcome: never approved after the user replied; the agent re-planned, the hold stood";
+        case "regretted": return `outcome: the user's next message regrets this call${record.regret !== undefined ? ` (${record.regret.toFixed(2)})` : ""}; it should have been held`;
+        case "accepted": return `outcome: the user's next message does not regret this call${record.regret !== undefined ? ` (${record.regret.toFixed(2)})` : ""}`;
+        default: return "outcome: pending";
+    }
+}
+/** One line for /warden status. */
+export function formatHolds(snapshot, logPath) {
+    if (snapshot.holds === 0 && snapshot.allowed === 0)
+        return "Holds: no guarded call judged yet this session.";
+    const parts = [`${snapshot.holds} hold${snapshot.holds === 1 ? "" : "s"}`];
+    if (snapshot.holds)
+        parts.push(`${snapshot.approved} approved by you, ${snapshot.declined} declined, ${snapshot.replanned} re-planned, ${snapshot.awaiting} awaiting your reply`);
+    parts.push(snapshot.precision === undefined ? "precision not yet measurable" : `precision ${Math.round(snapshot.precision * 100)}% over ${snapshot.labels} label${snapshot.labels === 1 ? "" : "s"}`);
+    parts.push(`${snapshot.allowed} allowed (${snapshot.regretted} regretted by you, ${snapshot.accepted} accepted)`);
+    return `Holds: ${parts.join("; ")}.${logPath ? ` Log: ${logPath}.` : ""}`;
+}
+/** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
+export function holdLogPath(sessionId, at = new Date()) {
+    const day = at.toISOString().slice(0, 10);
+    const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || String(process.pid);
+    return join(dirname(userConfigPath()), "holds", `${day}-${safe}.jsonl`);
+}
+/** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */
+export class HoldLog {
+    path;
+    queue = Promise.resolve();
+    failure;
+    constructor(path) {
+        this.path = path;
+    }
+    save(records) {
+        const text = records.map(record => JSON.stringify(record)).join("\n") + (records.length ? "\n" : "");
+        this.queue = this.queue.then(async () => {
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+            await writeFile(this.path, text, { mode: 0o600 });
+            this.failure = undefined;
+        }).catch(error => { this.failure = error instanceof Error ? error.message : String(error); });
+        return this.queue;
+    }
+    /** The last write error, if the most recent save failed. */
+    get lastFailure() {
+        return this.failure;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScannedCommand, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion, regretQuestions } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, PreviousAction, ScannedCommand, ScopeLabel, Severity, Verdict } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.js";
@@ -22,6 +22,8 @@ export { RunawayMonitor, repeatedBlock, repeatedTail, findRepeats, runawayNudge,
 export type { RunawayVerdict, RepeatSignal, StreamKind } from "./runaway.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
+export { HoldLedger, HoldLog, holdLogPath, formatHolds, outcomeNote, regretsAt, textRegrets } from "./holds.js";
+export type { CallOutcome, CallRecord, CallScores, HoldSnapshot, OutcomeVia } from "./holds.js";
 export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion, regretQuestions } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
@@ -12,6 +12,7 @@ export { detectNotifier, notifierCommand, sendNotification, candidates as notifi
 export { RunawayMonitor, repeatedBlock, repeatedTail, findRepeats, runawayNudge, formatRunaway, BLOCK_MIN_CHARS, PHRASE_CHARS, CHECK_EVERY } from "./runaway.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
+export { HoldLedger, HoldLog, holdLogPath, formatHolds, outcomeNote, regretsAt, textRegrets } from "./holds.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";

package/dist/shape.js

@@ -26,7 +26,7 @@ export function completeConfig(loaded) {
         timeoutMs: source.timeoutMs ?? 5000,
         maxRequests: source.maxRequests ?? 500,
         steerVisible: source.steerVisible ?? false,
-        action: section("action", { ...off, tools: [], failOpen: true, timeoutMs: 5000, irreversible: { warn: 1, confirm: 1 }, offTask: { warn: 1, confirm: 1 } }),
+        action: section("action", { ...off, tools: [], failOpen: true, timeoutMs: 5000, irreversible: { warn: 1, confirm: 1 }, offTask: { warn: 1, confirm: 1 }, feedbackLog: false }),
         stuck: section("stuck", { ...off, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 1, nudge: false }),
         done: section("done", { ...off, claimsDone: 1, nudge: false }),
         slop: section("slop", { ...off, threshold: 1, prose: proseOff() }),
@@ -48,6 +48,9 @@ export function completeConfig(loaded) {
     }
     if (typeof config.widget.panelWidth !== "string" && typeof config.widget.panelWidth !== "number")
         config.widget = { ...config.widget, panelWidth: "40%" };
+    // The feedback log flag was added inside the action section later than the section itself; an older config module leaves it undefined and the log stays on.
+    if (typeof config.action.feedbackLog !== "boolean")
+        config.action = { ...config.action, feedbackLog: true };
     // The runaway guard added its template later than the other sections; an older widget section renders the default line.
     if (typeof config.widget.runaway !== "string")
         config.widget = { ...config.widget, runaway: DEFAULT_TEMPLATES.runaway };

package/dist/trace.d.ts

@@ -20,6 +20,8 @@ export declare class Trace {
     private readonly listeners;
     constructor(limit?: number);
     push(entry: TraceEntry): void;
+    /** Appends a detail line to an entry that is still in the trace, for an outcome that lands after the event. */
+    amend(entry: TraceEntry, line: string): boolean;
     entries(): readonly TraceEntry[];
     clear(): void;
     subscribe(listener: () => void): () => void;

package/dist/trace.js

@@ -13,6 +13,15 @@ export class Trace {
         for (const listener of this.listeners)
             listener();
     }
+    /** Appends a detail line to an entry that is still in the trace, for an outcome that lands after the event. */
+    amend(entry, line) {
+        if (!this.items.includes(entry))
+            return false;
+        entry.details.push(line);
+        for (const listener of this.listeners)
+            listener();
+        return true;
+    }
     entries() {
         return this.items;
     }
@@ -40,7 +49,7 @@ export function actionDetails(verdict, extra = {}) {
     if (verdict.patterns.length)
         lines.push(`patterns: ${verdict.patterns.map(hit => `${hit.id} (${hit.severity})`).join(", ")}`);
     if (judgment) {
-        lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""}${judgment.mutates !== undefined ? ` · mutates ${percent(judgment.mutates)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
+        lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""}${judgment.mutates !== undefined ? ` · mutates ${percent(judgment.mutates)}` : ""}${judgment.regretted !== undefined ? ` · regret of last turn ${percent(judgment.regretted)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
     }
     if (judgment?.securityRisk !== undefined)
         lines.push(`security risk: ${percent(judgment.securityRisk)}`);

package/examples/README.md

@@ -0,0 +1,45 @@
+# Get started with pi-warden
+
+Three files, each optional. Copy what you need and edit it.
+
+| File in this folder | Copy it to | What it does |
+| --- | --- | --- |
+| `pi-warden.md` | `<your project>/pi-warden.md` | Your project's rules. Each `#` heading is one rule; Jev judges every write and edit against them and tells the agent which rule it broke. |
+| `pi-warden.json` | `<your project>/.pi/pi-warden.json` | Project settings: which files the rules skip, which are never sent to Jev, sensitive paths that give the agent a note, tuned thresholds. Read only when Pi trusts the project. |
+| `config.json` | `~/.pi/agent/pi-warden/config.json` | Your personal settings: consent, mode, whether steers show in the transcript, the audience for reply checks, notifications. `/warden config` opens it in Pi's editor. |
+
+## Step by step
+
+1. Install and enable:
+
+   ```bash
+   pi install npm:pi-warden
+   ```
+
+   Then in Pi run `/warden enable`, read the notice, and paste a key from [console.typesafe.ai](https://console.typesafe.ai) if you have none stored. Without a key pi-warden still runs its offline pattern checks; the rules guard needs Jev.
+
+2. Copy `pi-warden.md` to your project root. Delete the rules you do not want, write your own. Run `/warden status`; the `Rules:` line should say `pi-warden.md (N rules)`.
+
+3. Ask the agent to write something that breaks a rule, for example "add a console.log to src/index.ts". The write goes through, the status line shows `warden · rules · write src/index.ts · N rules · No console output in library code 0.9x · violation`, and the agent gets the rule text as a steer. Open the trace (`ctrl+shift+w`) to read exactly what it was told.
+
+4. Optional: copy `pi-warden.json` to `.pi/pi-warden.json` for path scoping and sensitive-path notes, and `config.json` to `~/.pi/agent/pi-warden/config.json` for your own defaults.
+
+## Writing rules that work
+
+- One heading, one rule. Jev answers one question per rule, so a heading that bundles three things gets one blurry answer.
+- Say what a violation looks like. "A bare `TODO` without a ticket" beats "TODOs should be tidy".
+- Scope with `paths:` when a rule is language-specific or does not apply to tests. Globs: `**` any depth, `*` within one segment, a pattern without a slash matches at any depth.
+- Code fences inside a rule are fine; a `#` inside a fence is not read as a heading.
+- Rules cost tokens: one request per write or edit, roughly 600 tokens plus about 150 per rule plus the content sample. At most 31 rules are asked per request.
+- No `pi-warden.md`? pi-warden falls back to `README.md`, `CLAUDE.md`, or `AGENTS.md` and asks one question about the whole document (cut to `rules.maxChars`, headings kept). It works, but a dedicated rules file gives sharper answers and names the rule. Set `"rules": { "fallback": false }` to turn the fallback off.
+
+## Checking the rules from the command line
+
+```bash
+node -e '
+import("pi-warden").then(({ RuleStore, defaultConfig }) => {
+  const set = new RuleStore().load(process.cwd(), defaultConfig().rules);
+  for (const rule of set?.rules ?? []) console.log(rule.id, rule.paths.length ? rule.paths.join(",") : "(all files)");
+  if (set?.dropped) console.log(`${set.dropped} rules beyond the cap are ignored`);
+});'
+```

package/examples/config.json

@@ -0,0 +1,26 @@
+{
+  "typesafe": true,
+  "mode": "steer",
+  "steerVisible": false,
+  "rules": {
+    "fallback": true,
+    "maxChars": 8000
+  },
+  "slop": {
+    "prose": { "audience": "a founder without a programming background" }
+  },
+  "context": {
+    "confidence": 0.8,
+    "recallTool": "auto"
+  },
+  "notify": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "command": []
+  },
+  "widget": {
+    "placement": "aboveEditor",
+    "shortcut": "ctrl+shift+w",
+    "panelWidth": "40%"
+  }
+}

package/examples/pi-warden.json

@@ -0,0 +1,22 @@
+{
+  "rules": {
+    "threshold": 0.7,
+    "skip": ["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "docs/**", "**/*.md"],
+    "exclude": ["secrets/**", "**/*.pem", "**/*.key", "fixtures/**"],
+    "sensitivePaths": {
+      "**/migrations/**": "This touches a database migration: tell the user in your reply and make sure there is a rollback path",
+      "**/permissions*": "Access control changed: tell the user and ask for a security review before this is merged",
+      "**/auth/**": "Authentication code changed: tell the user; do not weaken any check without saying so",
+      ".github/workflows/**": "CI configuration changed: tell the user what the pipeline will now do differently"
+    }
+  },
+  "action": {
+    "tools": ["bash", "powershell", "ctx_execute", "ctx_batch_execute", "ctx_execute_file", "write", "edit"],
+    "irreversible": { "warn": 0.5, "confirm": 0.7 },
+    "offTask": { "warn": 0.6, "confirm": 0.85 }
+  },
+  "slop": {
+    "prose": { "audience": "technical" }
+  },
+  "done": { "enabled": true }
+}

package/examples/pi-warden.md

@@ -0,0 +1,53 @@
+Copy this file to the root of your project as `pi-warden.md` and edit it. Every `#` heading below is one rule. The text
+under a heading is what Jev reads when it judges a write or an edit. A `paths:` line right under a heading limits that rule
+to matching files. Text above the first heading, like this paragraph, is ignored, so keep the intro heading-free.
+
+Keep rules short and concrete. Say what a violation looks like. Jev is good at "must not contain X" and "every X needs a Y";
+it is worse at taste ("code should be clean").
+
+# No console output in library code
+paths: src/**
+Code under `src/` must not call `console.log`, `console.debug`, or `console.info`. Use the project logger or remove the
+call before committing. Tests and scripts may print.
+
+# TODO comments need a reference
+A `TODO` or `FIXME` comment must name a ticket or issue, for example `TODO(APP-123): ...`. A bare `TODO` is a violation.
+
+# No explicit any
+paths: **/*.ts, **/*.tsx
+Do not use the `any` type. Use a precise type, `unknown` with a runtime check, or a generic parameter.
+
+# Exported functions declare their return type
+paths: src/**/*.ts
+Every exported function or method declares its return type instead of relying on inference.
+
+# Errors are not swallowed
+A `catch` block must handle the error, log it with context, or rethrow it. An empty `catch`, or one that only has a comment
+such as `// ignore`, is a violation.
+
+# Switch statements have a default case
+Every `switch` has a `default` branch, even if it only throws on an unexpected value.
+
+# No hardcoded secrets
+Source code must not contain passwords, API keys, or tokens. They come from configuration or a secrets manager. A test fixture
+with an obviously fake value such as `test-key` is fine.
+
+# Boolean names read as a question
+A boolean variable or property starts with `is`, `has`, `should`, `can`, or a similar predicate prefix, for example
+`isEnabled`, not `enabled`.
+
+# New exported functions get a test
+paths: src/**
+A newly added exported function or class comes with at least one test that exercises its main behaviour. Changing an
+existing function does not require a new test by itself.
+
+# Comments explain why, not what
+A comment states a reason, a constraint, a workaround, or a non-obvious invariant. A comment that restates what the next line
+plainly does is a violation.
+
+# No commented-out code
+Delete code that is no longer used. Do not leave it behind as comments.
+
+# Migrations are reversible
+paths: **/migrations/**
+Every migration has a down step (or an explicit note in the file that the change cannot be reversed and why).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Guardrails for Pi built on pi-typesafe that steer the agent instead of interrupting you: Jev judges irreversible and off-task tool calls before they run, checks written code against your project rules, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
   "files": [
     "dist",
     "extensions",
+    "examples",
     "README.md",
     "LICENSE"
   ],