pi-warden 0.2.1 → 0.3.0

package/README.md

@@ -1,11 +1,23 @@
 # pi-warden
 
-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).
+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 (or a shell command through [context-mode](https://www.npmjs.com/package/context-mode)'s `ctx_execute`), 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).
 
 ![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)
 
 The verdicts above are real output from `npm run test:live`. Independent project; not affiliated with TypeSafe AI or the Pi authors.
 
+## Philosophy
+
+pi-warden is a harness for the agent, not a gate for the user. It watches every tool call, tool result, and reply, asks Jev small typed questions about them, and acts through the agent's own context — a held call, a steer message, a compressed output — rather than through dialogs. Jev decides; code applies the decision; the LLM is never asked to judge itself. Everything warden does is visible in the trace panel, and nothing is rewritten in your session file.
+
+Three jobs, in order of maturity:
+
+| Pillar | What it means | Status |
+| --- | --- | --- |
+| **Security** | Irreversible or off-task actions are held with a reason the agent can act on; credential files, force pushes, destructive SQL, and remote-script execution are caught offline; secrets are redacted before anything leaves the machine. Next: injected instructions inside tool output (web pages, issues, files) flagged and quarantined; insecure patterns in written code steered. | built · extending |
+| **Deslopify** | Stubs, placeholders, filler, and restating comments in written code earn a scored nudge; the agent fixes them on the next turn. Next: per-symptom scores instead of one quality number, and wordy or AI-flavoured replies scored against an audience setting. | built for code · prose planned |
+| **Context saving** | Jev judges which tool outputs are worth keeping; code compresses them. Only at moments that cannot cost a prompt-cache miss: when an output arrives (before it enters the cache), when the cache is measurably cold, or when Pi compacts anyway. Works alongside prompt-cache optimizers because it never touches the system prompt or a warm prefix. | planned |
+
 ## 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:
@@ -38,7 +50,7 @@ A `TYPESAFE_API_KEY` environment variable takes precedence over the stored key.
 
 ### Action guard (`tool_call`)
 
-1. **Skip** read-only tools, and read-only shell lines such as `git status && ls` (no network, no widget).
+1. **Skip** read-only tools, and read-only shell lines such as `git status && ls` (no network, no widget). Guarded by default: `bash`, `powershell`, `write`, `edit`, and context-mode's `ctx_execute`, `ctx_execute_file`, `ctx_batch_execute` (their `code`/`commands` fields are read as the command; non-shell code such as JavaScript is judged but never skipped as read-only). Add other tools with `action.tools`; unknown tools are judged from their JSON input.
 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:
@@ -54,7 +66,7 @@ Keeps the last 12 tool results for the current prompt. When the latest result fa
 
 ### 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.
+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, whether run through `bash` or `ctx_execute`) with pass/fail; context-mode's inline `Command exited with code N` counts as a failure. 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)
 
@@ -78,6 +90,26 @@ If TypeSafe cannot answer (timeout after 5 s, outage, budget), an action-guard c
 | `/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 and what the agent would be told |
+| `/warden trace` | Open the trace panel (or print the last 20 events without a UI) |
+
+## Status line and trace panel
+
+The line above the editor shows the latest verdict per guard, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`. Every verdict is also kept in a session trace with what was inspected (redacted command or path), the pattern hits, Jev's scores with model and latency, the reasons, and the exact text the agent was told. Open the panel with `/warden trace`, `ctrl+shift+w`, or by clicking the status line (clicks need Pi's fullscreen mode: `tuiMode: "fullscreen"` in settings, because regular mode leaves the mouse to the terminal). The panel is a right-hand overlay, newest first, live-updating while the agent works; ↑↓/PgUp/PgDn scroll, `c` clears, Esc closes.
+
+Templates in `config.widget` control the text. Segments are separated by ` · `; a segment whose token has no value for that verdict is dropped, so optional information disappears together with its label:
+
+```json
+"widget": {
+  "enabled": true,
+  "placement": "aboveEditor",
+  "shortcut": "ctrl+shift+w",
+  "action": "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}",
+  "stuck": "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
+  "done": "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}"
+}
+```
+
+Tokens — action: `tool level source irreversible offTask scope approved slopQuality slopStub patterns reasons path model ms flags time`; stuck: `failures sameStrategy approachChange progress status source reasons model ms flags time`; done: `changes checks checksPassed claimsDone claimsVerified checksApply outcome status reasons model ms flags time`. A minimal line: `"action": "⚔ {tool} {level} · {irreversible}/{offTask}"`. Set `"enabled": false` to hide the line (the trace and panel keep working); `"shortcut": ""` disables the keybinding.
 
 ## Configuration
 
@@ -92,14 +124,15 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
   "maxRequests": 500,
   "action": {
     "enabled": true,
-    "tools": ["bash", "write", "edit"],
+    "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 }
   },
   "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 }
+  "slop": { "enabled": true, "quality": 1.5, "placeholder": 0.7 },
+  "widget": { "enabled": true, "placement": "aboveEditor", "shortcut": "ctrl+shift+w" }
 }
 ```
 

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { WidgetConfig } from "./widget.js";
 export interface Threshold {
     /** P(yes) at or above this shows a warning and continues. */
     warn: number;
@@ -62,6 +63,8 @@ export interface WardenConfig {
     stuck: StuckGuardConfig;
     done: DoneGuardConfig;
     slop: SlopGuardConfig;
+    /** The status line above the editor and the trace panel. */
+    widget: WidgetConfig;
 }
 export declare const PACKAGE_NAME = "pi-warden";
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";

package/dist/config.js

@@ -1,6 +1,8 @@
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { COMMAND_TOOLS } from "./tools.js";
+import { defaultWidgetConfig } from "./widget.js";
 export const PACKAGE_NAME = "pi-warden";
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
@@ -12,7 +14,7 @@ export function defaultConfig() {
         maxRequests: 500,
         action: {
             enabled: true,
-            tools: ["bash", "write", "edit"],
+            tools: [...COMMAND_TOOLS, "write", "edit"],
             failOpen: true,
             timeoutMs: 5000,
             irreversible: { warn: 0.5, confirm: 0.7 },
@@ -21,6 +23,7 @@ export function defaultConfig() {
         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 },
+        widget: defaultWidgetConfig(),
     };
 }
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
@@ -105,6 +108,19 @@ function applySlop(base, raw) {
         return base;
     return { enabled: boolean(raw.enabled, base.enabled), quality: score(raw.quality, base.quality), placeholder: probability(raw.placeholder, base.placeholder) };
 }
+function applyWidget(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const template = (value, fallback) => (typeof value === "string" && value.trim() ? value : fallback);
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        placement: raw.placement === "belowEditor" || raw.placement === "aboveEditor" ? raw.placement : base.placement,
+        shortcut: typeof raw.shortcut === "string" ? raw.shortcut.trim() : base.shortcut,
+        action: template(raw.action, base.action),
+        stuck: template(raw.stuck, base.stuck),
+        done: template(raw.done, base.done),
+    };
+}
 /** 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 : {};
@@ -132,6 +148,7 @@ export function applyUserOverrides(base, raw) {
         mode: isMode(raw.mode) ? raw.mode : base.mode,
         ...shared,
         ...applyGuards(base, raw, shared.timeoutMs),
+        widget: applyWidget(base.widget, raw.widget),
     };
 }
 /** Project files may tune the guards but cannot grant TypeSafe consent, change the mode, or raise budgets. */

package/dist/done.d.ts

@@ -14,7 +14,7 @@ export interface RunEvidence {
     }>;
 }
 export declare function emptyEvidence(): RunEvidence;
-export declare function recordOutcome(evidence: RunEvidence, outcome: ToolOutcome, input: Record<string, unknown>): void;
+export declare function recordOutcome(evidence: RunEvidence, outcome: ToolOutcome, input: Record<string, unknown>, tool?: string): void;
 interface MessageLike {
     role: string;
     content?: unknown;
@@ -82,5 +82,5 @@ export interface DoneOptions {
 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 declare function formatDone(verdict: DoneVerdict, template?: string): string;
 export {};

package/dist/done.js

@@ -1,6 +1,8 @@
 import { choice, noul, TypeSafeIntegrationError } from "pi-typesafe";
 import { isReadOnlyCommand } from "./guard.js";
 import { redact } from "./redact.js";
+import { commandOf } from "./tools.js";
+import { DEFAULT_TEMPLATES, doneTokens, renderTemplate } from "./widget.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/;
 /**
@@ -12,20 +14,22 @@ export function classifyToolResult(tool, input, failed) {
         return "mutation";
     if (tool === "read" || tool === "grep" || tool === "find" || tool === "ls")
         return "read";
-    if (tool !== "bash" || typeof input.command !== "string")
+    const view = commandOf(tool, input);
+    if (!view)
         return "unknown";
-    if (CHECK_COMMAND.test(input.command))
+    if (CHECK_COMMAND.test(view.command))
         return failed ? "check-fail" : "check-pass";
-    return isReadOnlyCommand(input.command) ? "read" : "unknown";
+    return view.shell && isReadOnlyCommand(view.command) ? "read" : "unknown";
 }
 export function emptyEvidence() {
     return { mutations: 0, checks: [] };
 }
-export function recordOutcome(evidence, outcome, input) {
+export function recordOutcome(evidence, outcome, input, tool = "bash") {
     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";
+        const command = commandOf(tool, input)?.command;
+        const call = command !== undefined ? redact(command.length > 200 ? `${command.slice(0, 200)}…` : command) : "check";
         evidence.checks.push({ call, passed: outcome === "check-pass" });
     }
 }
@@ -110,12 +114,6 @@ export function doneNudge(verdict) {
     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(" · ");
+export function formatDone(verdict, template = DEFAULT_TEMPLATES.done) {
+    return renderTemplate(template, doneTokens(verdict));
 }

package/dist/extension.js

@@ -1,9 +1,13 @@
+import { MouseRegion, Text } from "@earendil-works/pi-tui";
 import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
 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, steerReason, textApproves } from "./guard.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
+import { openTracePanel } from "./panel.js";
+import { actionDetails, doneDetails, stuckDetails, Trace } from "./trace.js";
+import { TOKEN_NAMES } from "./widget.js";
 export 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.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
@@ -51,6 +55,9 @@ export default function wardenExtension(pi) {
     let budgetExhausted = false;
     let stats = freshStats();
     const widget = new Map();
+    const trace = new Trace();
+    let panelOpen = false;
+    let lastUi;
     /** Calls held in steer mode, with the user prompt current at that time; a retry after the user replies asks Jev about approval. */
     const held = new Map();
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
@@ -71,10 +78,33 @@ export default function wardenExtension(pi) {
         if (ctx.hasUI)
             ctx.ui.notify(`warden: ${message}${budgetExhausted ? " Pattern checks continue without TypeSafe for the rest of this session." : ""}`, "warning");
     };
-    const show = (ctx, guard, line) => {
+    const openPanel = (ui) => {
+        if (!ui || panelOpen)
+            return;
+        panelOpen = true;
+        openTracePanel(ui, trace).catch(() => undefined).finally(() => { panelOpen = false; });
+    };
+    const paint = (ctx, config) => {
+        if (!ctx.hasUI)
+            return;
+        lastUi = ctx.ui;
+        if (!config.widget.enabled || widget.size === 0) {
+            ctx.ui.setWidget(WIDGET, undefined);
+            return;
+        }
+        const lines = [...widget.values()];
+        // A custom component so a click (fullscreen mode) opens the trace panel; plain lines otherwise look the same.
+        ctx.ui.setWidget(WIDGET, (_tui, theme) => new MouseRegion(new Text(lines.map(line => theme.fg("muted", line)).join("\n"), 0, 0), event => {
+            if (event.type !== "click" || event.button !== "left")
+                return undefined;
+            openPanel(lastUi);
+            return { handled: true };
+        }), { placement: config.widget.placement });
+    };
+    const record = (ctx, config, guard, line, details) => {
         widget.set(guard, line);
-        if (ctx.hasUI)
-            ctx.ui.setWidget(WIDGET, [...widget.values()]);
+        trace.push({ at: Date.now(), guard, line, details });
+        paint(ctx, config);
     };
     const steer = (content) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: true }, { deliverAs: "steer" });
     pi.on("session_start", async (_event, ctx) => {
@@ -82,6 +112,7 @@ export default function wardenExtension(pi) {
         budgetExhausted = false;
         stats = freshStats();
         widget.clear();
+        trace.clear();
         held.clear();
         attempts.reset();
         evidence = emptyEvidence();
@@ -125,8 +156,10 @@ export default function wardenExtension(pi) {
             stats.approved++;
             held.delete(key);
         }
+        const mode = activeMode(config, ctx.hasUI);
+        const told = verdict.level === "confirm" && mode === "steer" ? steerReason(verdict, { canApprove: judge !== undefined }) : undefined;
         if (verdict.source !== "read-only")
-            show(ctx, "action", formatVerdict(verdict));
+            record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode, ...(told ? { told } : {}) }));
         if (verdict.slopReasons?.length) {
             stats.slop++;
             const where = verdict.summary.path ?? event.toolName;
@@ -142,7 +175,6 @@ export default function wardenExtension(pi) {
         }
         if (verdict.level !== "confirm")
             return undefined;
-        const mode = activeMode(config, ctx.hasUI);
         const reasons = verdict.reasons.join("; ");
         if (mode === "advise") {
             stats.warned++;
@@ -161,15 +193,15 @@ export default function wardenExtension(pi) {
         held.set(key, task);
         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");
-        return { block: true, reason: steerReason(verdict, { canApprove: judge !== undefined }) };
+        return { block: true, reason: told ?? steerReason(verdict, { canApprove: judge !== undefined }) };
     });
     pi.on("tool_result", async (event, ctx) => {
         const config = configFor(ctx);
         if (!config.enabled)
             return;
-        const failed = resultFailed(event.isError, event.details);
+        const failed = resultFailed(event.isError, event.details, event.content);
         if (config.done.enabled)
-            recordOutcome(evidence, classifyToolResult(event.toolName, event.input, failed), event.input);
+            recordOutcome(evidence, classifyToolResult(event.toolName, event.input, failed), event.input, event.toolName);
         if (!config.stuck.enabled)
             return;
         attempts.push(makeAttempt(event.toolName, event.input, event.content, failed));
@@ -181,14 +213,15 @@ export default function wardenExtension(pi) {
             noteError(ctx, verdict.error, undefined);
         if (verdict.source === "repeat" && !verdict.stuck)
             return;
-        show(ctx, "stuck", formatStuck(verdict));
+        const nudge = verdict.stuck && config.stuck.nudge ? stuckNudge(verdict) : undefined;
+        record(ctx, config, "stuck", formatStuck(verdict, config.widget.stuck), stuckDetails(verdict, attempts.attempts, nudge));
         if (!verdict.stuck)
             return;
         stats.stuck++;
         if (ctx.hasUI)
-            ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${config.stuck.nudge ? " (agent nudged)" : ""}`, "warning");
-        if (config.stuck.nudge)
-            steer(stuckNudge(verdict));
+            ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${nudge ? " (agent nudged)" : ""}`, "warning");
+        if (nudge)
+            steer(nudge);
     });
     pi.on("agent_end", async (event, ctx) => {
         const config = configFor(ctx);
@@ -202,20 +235,30 @@ export default function wardenExtension(pi) {
         const verdict = await evaluateDone(latestUserPrompt(ctx), finalMessage, evidence, { config: config.done, judge, timeoutMs: config.timeoutMs, signal: ctx.signal });
         if (verdict.error)
             noteError(ctx, verdict.error, undefined);
-        show(ctx, "done", formatDone(verdict));
+        const nudge = verdict.unverified && config.done.nudge ? doneNudge(verdict) : undefined;
+        record(ctx, config, "done", formatDone(verdict, config.widget.done), doneDetails(verdict, finalMessage, nudge));
         if (!verdict.unverified)
             return;
         stats.unverified++;
         if (ctx.hasUI)
-            ctx.ui.notify(`warden · done-check: ${verdict.reasons.join("; ")}${config.done.nudge ? " (agent asked to verify)" : ""}`, "warning");
-        if (config.done.nudge) {
+            ctx.ui.notify(`warden · done-check: ${verdict.reasons.join("; ")}${nudge ? " (agent asked to verify)" : ""}`, "warning");
+        if (nudge) {
             doneNudged = true;
-            pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: doneNudge(verdict), display: true }, { deliverAs: "followUp", triggerTurn: true });
+            pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: nudge, display: true }, { deliverAs: "followUp", triggerTurn: true });
         }
     });
-    const actions = ["status", "enable", "disable", "mode", "config", "test"];
+    // Shortcuts are registered once at load; a shape check keeps a typo in the config file from being registered.
+    const shortcut = loadConfig().widget.shortcut;
+    if (/^(?:(?:ctrl|shift|alt|super)\+)+[a-z0-9]+$|^f\d{1,2}$/i.test(shortcut)) {
+        pi.registerShortcut(shortcut, {
+            description: "Open the pi-warden trace panel",
+            handler: async (ctx) => { if (ctx.hasUI)
+                openPanel(ctx.ui); },
+        });
+    }
+    const actions = ["status", "enable", "disable", "mode", "config", "test", "trace"];
     pi.registerCommand("warden", {
-        description: "pi-warden status, TypeSafe consent, steer/confirm/advise mode, config editor, and a synthetic guard test",
+        description: "pi-warden status, TypeSafe consent, steer/confirm/advise mode, config editor, trace panel, and a synthetic guard test",
         getArgumentCompletions(prefix) {
             const matches = actions.filter(action => action.startsWith(prefix)).map(action => ({ value: action, label: action }));
             return matches.length ? matches : null;
@@ -241,9 +284,19 @@ export default function wardenExtension(pi) {
                         `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 quality ${config.slop.quality}, stub ${config.slop.placeholder}; failOpen ${config.action.failOpen}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
                         widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",
+                        `Trace: ${trace.entries().length} events (/warden trace${shortcut ? `, ${shortcut}` : ""}, or click the status line in fullscreen mode). Widget templates in config.widget: action tokens ${TOKEN_NAMES.action.map(name => `{${name}}`).join(" ")}.`,
                     ].join(" "));
                     return;
                 }
+                if (action === "trace") {
+                    if (!ctx.hasUI) {
+                        const entries = trace.entries();
+                        report(entries.length ? entries.slice(-20).map(entry => `${new Date(entry.at).toTimeString().slice(0, 8)} ${entry.guard}: ${entry.line}${entry.details.length ? `\n  ${entry.details.join("\n  ")}` : ""}`).join("\n") : "No guarded activity yet this session.");
+                        return;
+                    }
+                    openPanel(ctx.ui);
+                    return;
+                }
                 if (action === "enable") {
                     if (!ctx.hasUI) {
                         report("Consent needs an interactive session. For headless runs set PI_WARDEN_ENABLED=1 and TYPESAFE_API_KEY explicitly.", "warning");
@@ -310,7 +363,7 @@ export default function wardenExtension(pi) {
                     if (judge && ctx.hasUI && !await ctx.ui.confirm("Send one synthetic pi-warden test request?", `A synthetic action ("rm -rf /tmp/pi-warden-demo" for the task "Clean up the demo directory") goes to api.typesafe.ai and may incur charges. ${disclosure}`))
                         return;
                     const verdict = await evaluateAction({ tool: "bash", input: { command: "rm -rf /tmp/pi-warden-demo" }, cwd: ctx.cwd, task: "Clean up the demo directory" }, { config: { ...config.action, enabled: true, tools: ["bash"] }, judge });
-                    show(ctx, "action", formatVerdict(verdict));
+                    record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode: activeMode(config, ctx.hasUI) }));
                     report(`${formatVerdict(verdict)}${verdict.reasons.length ? ` — ${verdict.reasons.join("; ")}` : ""}${judge ? "" : " (pattern checks only: TypeSafe judgments are not enabled or no key is configured)"}${verdict.error ? ` — ${verdict.error}` : ""}`);
                     if (verdict.level === "confirm") {
                         const mode = activeMode(config, ctx.hasUI);

package/dist/guard.d.ts

@@ -129,5 +129,5 @@ export declare function textApproves(task: string | undefined): boolean;
 export declare function steerReason(verdict: Verdict, options: {
     canApprove: boolean;
 }): string;
-/** One-line rendering for widgets and logs. Includes no command text. */
-export declare function formatVerdict(verdict: Verdict): string;
+/** One-line rendering for widgets and logs. Includes no command text. Templates: see widget.ts. */
+export declare function formatVerdict(verdict: Verdict, template?: string): string;

package/dist/guard.js

@@ -3,6 +3,8 @@ import { homedir } from "node:os";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { choice, noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.js";
+import { commandOf } from "./tools.js";
+import { actionTokens, DEFAULT_TEMPLATES, renderTemplate } from "./widget.js";
 const LEVEL_RANK = { allow: 0, warn: 1, confirm: 2 };
 const higher = (a, b) => (LEVEL_RANK[a] >= LEVEL_RANK[b] ? a : b);
 const TASK_LIMIT = 1500;
@@ -72,7 +74,7 @@ export function matchPatterns(tool, input, cwd) {
     const hits = new Map();
     const add = (hit) => { if (hit && !hits.has(hit.id))
         hits.set(hit.id, hit); };
-    const command = typeof input.command === "string" ? input.command : undefined;
+    const command = commandOf(tool, input)?.command;
     if (command) {
         for (const rule of SHELL_RULES)
             if (rule.test.test(command))
@@ -159,9 +161,10 @@ function displayPath(target, cwd) {
 }
 export function describeAction(tool, input, cwd) {
     const summary = { tool };
-    if (typeof input.command === "string")
-        summary.command = redact(truncate(input.command, COMMAND_LIMIT));
-    if (typeof input.path === "string" && input.path.trim()) {
+    const view = commandOf(tool, input);
+    if (view)
+        summary.command = redact(truncate(view.command, COMMAND_LIMIT));
+    if (typeof input.path === "string" && input.path.trim() && tool !== "ctx_execute_file") {
         const shown = displayPath(input.path, cwd);
         summary.path = shown.path;
         summary.location = shown.location;
@@ -260,7 +263,8 @@ export async function evaluateAction(action, options) {
             reasons.push(`${action.tool === "write" ? "creates" : "changes"} a file outside the project`);
         }
     }
-    if (action.tool === "bash" && patterns.length === 0 && typeof action.input.command === "string" && isReadOnlyCommand(action.input.command)) {
+    const view = commandOf(action.tool, action.input);
+    if (view?.shell && patterns.length === 0 && isReadOnlyCommand(view.command)) {
         return { level, source: "read-only", summary, patterns, reasons };
     }
     if (!judge)
@@ -346,21 +350,7 @@ export function steerReason(verdict, options) {
         lines.push("pi-warden allows the same call again once the user has replied with approval.");
     return lines.join(" ");
 }
-/** One-line rendering for widgets and logs. Includes no command text. */
-export function formatVerdict(verdict) {
-    const parts = [`warden · ${verdict.summary.tool}`];
-    if (verdict.judgment)
-        parts.push(`irreversible ${percent(verdict.judgment.irreversible)}`, `off-task ${percent(verdict.judgment.offTask)}`, verdict.judgment.scope.replace(/_/g, " "));
-    if (verdict.slop)
-        parts.push(`slop ${verdict.slop.quality.toFixed(1)}/2`, `stub ${percent(verdict.slop.placeholder)}`);
-    if (verdict.patterns.length)
-        parts.push(`patterns: ${verdict.patterns.map(hit => hit.id).join(", ")}`);
-    if (verdict.approvedByUser)
-        parts.push("user approved");
-    if (verdict.source === "error")
-        parts.push("typesafe error");
-    if (verdict.source === "read-only")
-        parts.push("read-only");
-    parts.push(verdict.level);
-    return parts.join(" · ");
+/** One-line rendering for widgets and logs. Includes no command text. Templates: see widget.ts. */
+export function formatVerdict(verdict, template = DEFAULT_TEMPLATES.action) {
+    return renderTemplate(template, actionTokens(verdict));
 }

package/dist/index.d.ts

@@ -7,3 +7,9 @@ export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions }
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
+export type { CommandView } from "./tools.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export type { WidgetConfig, WidgetPlacement, Tokens } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails } from "./trace.js";
+export type { TraceEntry, GuardName } from "./trace.js";

package/dist/index.js

@@ -3,3 +3,6 @@ export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, bu
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails } from "./trace.js";

package/dist/panel.d.ts

@@ -0,0 +1,44 @@
+import type { Component, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
+import type { Trace } from "./trace.js";
+interface ThemeLike {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+}
+/**
+ * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
+ * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ */
+export declare class TracePanel implements Component {
+    private readonly trace;
+    private readonly theme;
+    private readonly close;
+    private readonly requestRender;
+    private readonly title;
+    focused: boolean;
+    private scroll;
+    private viewport;
+    private readonly unsubscribe;
+    constructor(trace: Trace, theme: ThemeLike, close: () => void, requestRender: () => void, title?: string);
+    dispose(): void;
+    /** Rendering is cheap and derived from the trace each time; nothing is cached. */
+    invalidate(): void;
+    private lines;
+    render(width: number): string[];
+    /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
+    setViewport(rows: number): void;
+    handleInput(data: string): void;
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+}
+export interface PanelUi {
+    custom<T>(factory: (tui: {
+        requestRender(): void;
+        terminal?: {
+            rows: number;
+        };
+    }, theme: ThemeLike, keybindings: unknown, done: (result: T) => void) => Component & {
+        dispose?(): void;
+    }, options?: Record<string, unknown>): Promise<T>;
+}
+/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
+export declare function openTracePanel(ui: PanelUi, trace: Trace): Promise<void>;
+export {};

package/dist/panel.js

@@ -0,0 +1,121 @@
+import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", confirm: "error", stuck: "error", "false claim": "error" };
+/**
+ * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
+ * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ */
+export class TracePanel {
+    trace;
+    theme;
+    close;
+    requestRender;
+    title;
+    focused = true;
+    scroll = 0;
+    viewport = 20;
+    unsubscribe;
+    constructor(trace, theme, close, requestRender, title = "pi-warden trace") {
+        this.trace = trace;
+        this.theme = theme;
+        this.close = close;
+        this.requestRender = requestRender;
+        this.title = title;
+        this.unsubscribe = trace.subscribe(() => this.requestRender());
+    }
+    dispose() {
+        this.unsubscribe();
+    }
+    /** Rendering is cheap and derived from the trace each time; nothing is cached. */
+    invalidate() { }
+    lines(width) {
+        const { theme } = this;
+        const entries = this.trace.entries();
+        const out = [];
+        out.push(theme.bold(theme.fg("accent", ` ${this.title}`)) + theme.fg("muted", ` · ${entries.length} event${entries.length === 1 ? "" : "s"} · ↑↓ PgUp PgDn scroll · c clear · esc close`));
+        out.push(theme.fg("muted", "─".repeat(Math.max(0, width))));
+        if (!entries.length) {
+            out.push(theme.fg("muted", " No guarded activity yet this session. Verdicts, Jev scores, and what the agent was told will appear here."));
+            return out.map(line => truncateToWidth(line, width, ""));
+        }
+        for (let index = entries.length - 1; index >= 0; index--) {
+            const entry = entries[index];
+            const status = entry.line.split(" · ").at(-1) ?? "";
+            const color = LEVEL_COLOR[status] ?? "text";
+            const head = `${theme.fg("muted", new Date(entry.at).toTimeString().slice(0, 8))} ${theme.fg(color, theme.bold(entry.guard.padEnd(6)))} `;
+            const headWidth = 9 + 7;
+            const body = wrapTextWithAnsi(theme.fg(color, entry.line), Math.max(10, width - headWidth));
+            out.push(head + (body[0] ?? ""));
+            for (const continuation of body.slice(1))
+                out.push(" ".repeat(headWidth) + continuation);
+            for (const detail of entry.details) {
+                const wrapped = wrapTextWithAnsi(detail, Math.max(10, width - headWidth - 2));
+                for (const [n, line] of wrapped.entries())
+                    out.push(" ".repeat(headWidth) + theme.fg("muted", n === 0 ? "· " : "  ") + theme.fg("dim", line));
+            }
+            out.push("");
+        }
+        return out.map(line => truncateToWidth(line, width, ""));
+    }
+    render(width) {
+        const all = this.lines(width);
+        const maxScroll = Math.max(0, all.length - this.viewport);
+        if (this.scroll > maxScroll)
+            this.scroll = maxScroll;
+        const visible = all.slice(this.scroll, this.scroll + this.viewport);
+        if (all.length > this.viewport) {
+            const last = visible.length - 1;
+            visible[last] = truncateToWidth(theme_fg(this.theme, "muted", ` … ${all.length - this.scroll - this.viewport > 0 ? `${all.length - this.scroll - this.viewport} more lines below` : "end"} · ${this.scroll} above`), width, "");
+        }
+        return visible;
+    }
+    /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
+    setViewport(rows) {
+        this.viewport = Math.max(5, rows);
+    }
+    handleInput(data) {
+        if (matchesKey(data, Key.escape) || data === "q" || matchesKey(data, Key.ctrl("c"))) {
+            this.close();
+            return;
+        }
+        if (matchesKey(data, Key.up) || data === "k")
+            this.scroll = Math.max(0, this.scroll - 1);
+        else if (matchesKey(data, Key.down) || data === "j")
+            this.scroll += 1;
+        else if (matchesKey(data, Key.pageUp))
+            this.scroll = Math.max(0, this.scroll - this.viewport);
+        else if (matchesKey(data, Key.pageDown))
+            this.scroll += this.viewport;
+        else if (matchesKey(data, Key.home))
+            this.scroll = 0;
+        else if (matchesKey(data, Key.end))
+            this.scroll = Number.MAX_SAFE_INTEGER;
+        else if (data === "c")
+            this.trace.clear();
+        else
+            return;
+        this.requestRender();
+    }
+    handleMouse(event) {
+        if (event.type === "wheel") {
+            this.scroll = Math.max(0, this.scroll + (event.wheelDelta ?? 0) * 3);
+            return { handled: true, render: true };
+        }
+        return undefined;
+    }
+}
+function theme_fg(theme, color, text) {
+    return theme.fg(color, text);
+}
+/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
+export function openTracePanel(ui, trace) {
+    return ui.custom((tui, theme, _keybindings, done) => {
+        const panel = new TracePanel(trace, theme, () => done(), () => tui.requestRender());
+        const rows = tui.terminal?.rows;
+        if (typeof rows === "number")
+            panel.setViewport(Math.floor(rows * 0.9) - 2);
+        return panel;
+    }, {
+        overlay: true,
+        overlayOptions: { anchor: "right-center", width: "48%", minWidth: 56, maxHeight: "90%", margin: { right: 1 } },
+    });
+}

package/dist/stuck.d.ts

@@ -32,8 +32,11 @@ export declare function resultText(content: ReadonlyArray<{
     type: string;
     text?: string;
 }>): string;
-/** Non-zero exit codes count as failures even when the tool did not flag an error. */
-export declare function resultFailed(isError: boolean, details: unknown): boolean;
+/** Non-zero exit codes count as failures even when the tool did not flag an error; context-mode reports them in the text. */
+export declare function resultFailed(isError: boolean, details: unknown, content?: ReadonlyArray<{
+    type: string;
+    text?: string;
+}>): boolean;
 export declare function makeAttempt(tool: string, input: Record<string, unknown>, content: ReadonlyArray<{
     type: string;
     text?: string;
@@ -85,4 +88,4 @@ export interface StuckOptions {
 export declare function evaluateStuck(window: AttemptWindow, task: string | undefined, options: StuckOptions): Promise<StuckVerdict>;
 /** Steering text for the agent. Names the pattern and asks for a change of method, not another retry. */
 export declare function stuckNudge(verdict: StuckVerdict): string;
-export declare function formatStuck(verdict: StuckVerdict): string;
+export declare function formatStuck(verdict: StuckVerdict, template?: string): string;

package/dist/stuck.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.js";
+import { commandOf, outputReportsFailure } from "./tools.js";
+import { DEFAULT_TEMPLATES, renderTemplate, stuckTokens } from "./widget.js";
 const CALL_LIMIT = 300;
 const OUTPUT_LIMIT = 400;
 function head(text, limit) {
@@ -13,12 +15,14 @@ function tail(text, limit) {
 export function resultText(content) {
     return content.filter(part => part.type === "text" && typeof part.text === "string").map(part => part.text).join("\n");
 }
-/** Non-zero exit codes count as failures even when the tool did not flag an error. */
-export function resultFailed(isError, details) {
+/** Non-zero exit codes count as failures even when the tool did not flag an error; context-mode reports them in the text. */
+export function resultFailed(isError, details, content = []) {
     if (isError)
         return true;
     const exitCode = details && typeof details === "object" ? details.exitCode : undefined;
-    return typeof exitCode === "number" && exitCode !== 0;
+    if (typeof exitCode === "number" && exitCode !== 0)
+        return true;
+    return outputReportsFailure(resultText(content));
 }
 /** Durations, timestamps, PIDs, and addresses change between identical runs; counts and line numbers stay. */
 function normaliseOutput(text) {
@@ -29,7 +33,8 @@ function normaliseOutput(text) {
         .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?Z?/g, "#date");
 }
 export function makeAttempt(tool, input, content, failed) {
-    const call = typeof input.command === "string" ? input.command
+    const command = commandOf(tool, input)?.command;
+    const call = command !== undefined ? command
         : typeof input.path === "string" ? `${tool} ${input.path}`
             : JSON.stringify(input);
     const text = resultText(content).trim();
@@ -135,14 +140,6 @@ export async function evaluateStuck(window, task, options) {
 export function stuckNudge(verdict) {
     return `pi-warden: ${verdict.reasons.join("; ")}. Stop retrying. Re-read the last error output carefully, state a new hypothesis about the cause, and either gather the missing information (read the relevant file, check versions or paths) or try a different method. If two different methods have failed, report the blocker to the user with the exact error instead of trying again.`;
 }
-export function formatStuck(verdict) {
-    const parts = [`warden · stuck · ${verdict.failures} failures`];
-    if (verdict.judgment)
-        parts.push(`same strategy ${verdict.judgment.sameStrategy.toFixed(2)}`, `change ${verdict.judgment.approachChange.toFixed(1)}/2`, `progress ${verdict.judgment.progress.toFixed(2)}`);
-    if (verdict.source === "repeat" && verdict.stuck)
-        parts.push("exact repeat");
-    if (verdict.source === "error")
-        parts.push("typesafe error");
-    parts.push(verdict.stuck ? "stuck" : "ok");
-    return parts.join(" · ");
+export function formatStuck(verdict, template = DEFAULT_TEMPLATES.stuck) {
+    return renderTemplate(template, stuckTokens(verdict));
 }

package/dist/tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Knowledge of which tool inputs carry shell commands. Pi's built-ins plus context-mode's ctx_* tools, which many Pi users
+ * run instead of bash. Unknown tools return nothing and are judged from their JSON input only.
+ */
+export interface CommandView {
+    /** Shell text to pattern-match and judge. Several commands are joined with newlines. */
+    command: string;
+    /** False when the code is not shell (JavaScript, Python …); pattern rules still run, the read-only shortcut does not. */
+    shell: boolean;
+}
+/** Extract the command text a tool call would execute, or undefined for tools that run no commands. */
+export declare function commandOf(tool: string, input: Record<string, unknown>): CommandView | undefined;
+/** Tools whose calls carry commands and should be guarded by default. */
+export declare const COMMAND_TOOLS: string[];
+/** Text that signals failure in tool output when the tool itself did not flag an error (context-mode reports exit codes inline). */
+export declare function outputReportsFailure(text: string): boolean;

package/dist/tools.js

@@ -0,0 +1,37 @@
+/**
+ * Knowledge of which tool inputs carry shell commands. Pi's built-ins plus context-mode's ctx_* tools, which many Pi users
+ * run instead of bash. Unknown tools return nothing and are judged from their JSON input only.
+ */
+const SHELL_LANGUAGES = new Set(["shell", "bash", "sh", "zsh", "powershell"]);
+function commandsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(item => (item && typeof item === "object" ? item.command : undefined)).filter((command) => typeof command === "string");
+}
+/** Extract the command text a tool call would execute, or undefined for tools that run no commands. */
+export function commandOf(tool, input) {
+    switch (tool) {
+        case "bash":
+        case "powershell":
+            return typeof input.command === "string" ? { command: input.command, shell: true } : undefined;
+        case "ctx_execute":
+        case "ctx_execute_file": {
+            if (typeof input.code !== "string")
+                return undefined;
+            const language = typeof input.language === "string" ? input.language.toLowerCase() : "";
+            return { command: input.code, shell: SHELL_LANGUAGES.has(language) };
+        }
+        case "ctx_batch_execute": {
+            const commands = commandsOf(input.commands);
+            return commands.length ? { command: commands.join("\n"), shell: true } : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** Tools whose calls carry commands and should be guarded by default. */
+export const COMMAND_TOOLS = ["bash", "powershell", "ctx_execute", "ctx_batch_execute", "ctx_execute_file"];
+/** Text that signals failure in tool output when the tool itself did not flag an error (context-mode reports exit codes inline). */
+export function outputReportsFailure(text) {
+    return /(?:^|\n)\s*Command exited with code [1-9]\d*\b/.test(text) || /(?:^|\n)\s*\(timed out\)\s*$/.test(text);
+}

package/dist/trace.d.ts

@@ -0,0 +1,29 @@
+import type { DoneVerdict } from "./done.js";
+import type { Verdict } from "./guard.js";
+import type { Attempt, StuckVerdict } from "./stuck.js";
+export type GuardName = "action" | "stuck" | "done";
+export interface TraceEntry {
+    at: number;
+    guard: GuardName;
+    /** The widget line for this event. */
+    line: string;
+    /** Redacted details: what was inspected, what Jev answered, what the agent was told. */
+    details: string[];
+}
+/** Session memory of guard decisions; the widget shows the latest line per guard, the panel shows the history. */
+export declare class Trace {
+    private readonly limit;
+    private readonly items;
+    private readonly listeners;
+    constructor(limit?: number);
+    push(entry: TraceEntry): void;
+    entries(): readonly TraceEntry[];
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function actionDetails(verdict: Verdict, extra?: {
+    mode?: string;
+    told?: string;
+}): string[];
+export declare function stuckDetails(verdict: StuckVerdict, attempts: readonly Attempt[], told?: string): string[];
+export declare function doneDetails(verdict: DoneVerdict, finalMessage: string, told?: string): string[];

package/dist/trace.js

@@ -0,0 +1,81 @@
+/** Session memory of guard decisions; the widget shows the latest line per guard, the panel shows the history. */
+export class Trace {
+    limit;
+    items = [];
+    listeners = new Set();
+    constructor(limit = 100) {
+        this.limit = limit;
+    }
+    push(entry) {
+        this.items.push(entry);
+        if (this.items.length > this.limit)
+            this.items.splice(0, this.items.length - this.limit);
+        for (const listener of this.listeners)
+            listener();
+    }
+    entries() {
+        return this.items;
+    }
+    clear() {
+        this.items.length = 0;
+        for (const listener of this.listeners)
+            listener();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+}
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit)}…`);
+const percent = (value) => value.toFixed(2);
+export function actionDetails(verdict, extra = {}) {
+    const { summary, judgment } = verdict;
+    const lines = [];
+    if (summary.command !== undefined)
+        lines.push(`ran: ${clip(summary.command.replace(/\s+/g, " "), 300)}`);
+    if (summary.path !== undefined)
+        lines.push(`${summary.tool} ${summary.path}${summary.location === "outside_project" ? " (outside the project)" : ""}${summary.exists === false ? " (new file)" : ""}${summary.bytes !== undefined ? ` · ${summary.bytes} bytes` : ""}${summary.editCount !== undefined ? ` · ${summary.editCount} edit${summary.editCount === 1 ? "" : "s"}` : ""}`);
+    if (summary.input !== undefined)
+        lines.push(`input: ${clip(summary.input, 300)}`);
+    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.model} · ${judgment.elapsedMs} ms`);
+    }
+    if (verdict.slop)
+        lines.push(`slop: quality ${verdict.slop.quality.toFixed(2)}/2 · placeholder ${percent(verdict.slop.placeholder)}${verdict.slopReasons?.length ? ` → ${verdict.slopReasons.join("; ")}` : ""}`);
+    if (verdict.reasons.length)
+        lines.push(`why: ${verdict.reasons.join("; ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (extra.mode && verdict.level === "confirm")
+        lines.push(`mode: ${extra.mode}`);
+    if (extra.told)
+        lines.push(`agent told: ${clip(extra.told, 400)}`);
+    return lines;
+}
+export function stuckDetails(verdict, attempts, told) {
+    const lines = attempts.map((attempt, index) => `${index + 1}. ${attempt.failed ? "✗" : "✓"} ${clip(attempt.call.replace(/\s+/g, " "), 120)}${attempt.failed && attempt.output ? ` → ${clip(attempt.output.replace(/\s+/g, " "), 120)}` : ""}`);
+    if (verdict.judgment)
+        lines.push(`jev: same strategy ${percent(verdict.judgment.sameStrategy)} · approach change ${verdict.judgment.approachChange.toFixed(2)}/2 · progress ${percent(verdict.judgment.progress)} · ${verdict.judgment.model} · ${verdict.judgment.elapsedMs} ms`);
+    if (verdict.reasons.length)
+        lines.push(`why: ${verdict.reasons.join("; ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}
+export function doneDetails(verdict, finalMessage, told) {
+    const lines = [`final message: ${clip(finalMessage.replace(/\s+/g, " "), 300)}`];
+    lines.push(`evidence: ${verdict.evidence.mutations} code change${verdict.evidence.mutations === 1 ? "" : "s"}${verdict.evidence.checks.length ? `; checks: ${verdict.evidence.checks.map(check => `${clip(check.call, 60)} → ${check.passed ? "passed" : "failed"}`).join(", ")}` : "; no checks ran"}`);
+    if (verdict.judgment)
+        lines.push(`jev: claims done ${percent(verdict.judgment.claimsDone)} · claims verified ${percent(verdict.judgment.claimsVerified)} · checks apply ${percent(verdict.judgment.verificationApplies)} · ${verdict.judgment.outcome} · ${verdict.judgment.model} · ${verdict.judgment.elapsedMs} ms`);
+    if (verdict.reasons.length)
+        lines.push(`why: ${verdict.reasons.join("; ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}

package/dist/widget.d.ts

@@ -0,0 +1,35 @@
+import type { DoneVerdict } from "./done.js";
+import type { Verdict } from "./guard.js";
+import type { StuckVerdict } from "./stuck.js";
+export type WidgetPlacement = "aboveEditor" | "belowEditor";
+export interface WidgetConfig {
+    enabled: boolean;
+    placement: WidgetPlacement;
+    /** Keyboard shortcut that opens the trace panel; empty string disables it. */
+    shortcut: string;
+    /** Templates per guard. Segments are separated by " · "; a segment whose token has no value is dropped. */
+    action: string;
+    stuck: string;
+    done: string;
+}
+export declare const DEFAULT_TEMPLATES: {
+    readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}";
+    readonly stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}";
+    readonly done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}";
+};
+export declare function defaultWidgetConfig(): WidgetConfig;
+export type Tokens = Record<string, string | undefined>;
+/**
+ * Fill `{token}` placeholders. The template is split on " · "; a segment is dropped when any of its tokens is empty,
+ * so optional information disappears together with its label. Unknown tokens render as empty (and drop their segment).
+ */
+export declare function renderTemplate(template: string, tokens: Tokens): string;
+export declare function actionTokens(verdict: Verdict, at?: number): Tokens;
+export declare function stuckTokens(verdict: StuckVerdict, at?: number): Tokens;
+export declare function doneTokens(verdict: DoneVerdict, at?: number): Tokens;
+/** Token names users can put in templates, for /warden status and the README. */
+export declare const TOKEN_NAMES: {
+    readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
+    readonly stuck: readonly ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"];
+    readonly done: readonly ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"];
+};

package/dist/widget.js

@@ -0,0 +1,101 @@
+export const DEFAULT_TEMPLATES = {
+    action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}",
+    stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
+    done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
+};
+export function defaultWidgetConfig() {
+    return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", ...DEFAULT_TEMPLATES };
+}
+const SEPARATOR = " · ";
+const TOKEN = /\{([a-zA-Z]+)\}/g;
+/**
+ * Fill `{token}` placeholders. The template is split on " · "; a segment is dropped when any of its tokens is empty,
+ * so optional information disappears together with its label. Unknown tokens render as empty (and drop their segment).
+ */
+export function renderTemplate(template, tokens) {
+    const segments = [];
+    for (const segment of template.split(SEPARATOR)) {
+        let missing = false;
+        const rendered = segment.replace(TOKEN, (_match, name) => {
+            const value = tokens[name];
+            if (value === undefined || value === "")
+                missing = true;
+            return value ?? "";
+        });
+        if (!missing && rendered.trim())
+            segments.push(rendered.trim());
+    }
+    return segments.join(SEPARATOR);
+}
+const fixed = (value, digits = 2) => (value === undefined ? undefined : value.toFixed(digits));
+const time = (at) => new Date(at).toTimeString().slice(0, 8);
+export function actionTokens(verdict, at = Date.now()) {
+    const flags = [
+        verdict.approvedByUser ? "user approved" : undefined,
+        verdict.source === "error" ? "typesafe error" : undefined,
+        verdict.source === "read-only" ? "read-only" : undefined,
+    ].filter(Boolean).join(", ");
+    return {
+        guard: "action",
+        time: time(at),
+        tool: verdict.summary.tool,
+        level: verdict.level,
+        source: verdict.source,
+        irreversible: fixed(verdict.judgment?.irreversible),
+        offTask: fixed(verdict.judgment?.offTask),
+        scope: verdict.judgment?.scope.replace(/_/g, " "),
+        approved: fixed(verdict.judgment?.approved),
+        slopQuality: verdict.slop ? `${verdict.slop.quality.toFixed(1)}/2` : undefined,
+        slopStub: fixed(verdict.slop?.placeholder),
+        patterns: verdict.patterns.length ? verdict.patterns.map(hit => hit.id).join(", ") : undefined,
+        reasons: verdict.reasons.length ? verdict.reasons.join("; ") : undefined,
+        path: verdict.summary.path,
+        model: verdict.judgment?.model,
+        ms: verdict.judgment ? String(verdict.judgment.elapsedMs) : undefined,
+        flags: flags || undefined,
+    };
+}
+export function stuckTokens(verdict, at = Date.now()) {
+    const flags = [
+        verdict.source === "repeat" && verdict.stuck ? "exact repeat" : undefined,
+        verdict.source === "error" ? "typesafe error" : undefined,
+    ].filter(Boolean).join(", ");
+    return {
+        guard: "stuck",
+        time: time(at),
+        failures: String(verdict.failures),
+        sameStrategy: fixed(verdict.judgment?.sameStrategy),
+        approachChange: verdict.judgment ? `${verdict.judgment.approachChange.toFixed(1)}/2` : undefined,
+        progress: fixed(verdict.judgment?.progress),
+        status: verdict.stuck ? "stuck" : "ok",
+        source: verdict.source,
+        reasons: verdict.reasons.length ? verdict.reasons.join("; ") : undefined,
+        model: verdict.judgment?.model,
+        ms: verdict.judgment ? String(verdict.judgment.elapsedMs) : undefined,
+        flags: flags || undefined,
+    };
+}
+export function doneTokens(verdict, at = Date.now()) {
+    return {
+        guard: "done",
+        time: time(at),
+        changes: String(verdict.evidence.mutations),
+        checks: String(verdict.evidence.checks.length),
+        checksPassed: String(verdict.evidence.checks.filter(check => check.passed).length),
+        claimsDone: fixed(verdict.judgment?.claimsDone),
+        claimsVerified: fixed(verdict.judgment?.claimsVerified),
+        checksApply: fixed(verdict.judgment?.verificationApplies),
+        outcome: verdict.judgment?.outcome,
+        status: verdict.falseClaim ? "false claim" : verdict.unverified ? "unverified" : "ok",
+        reasons: verdict.reasons.length ? verdict.reasons.join("; ") : undefined,
+        model: verdict.judgment?.model,
+        ms: verdict.judgment ? String(verdict.judgment.elapsedMs) : undefined,
+        flags: verdict.error ? "typesafe error" : undefined,
+    };
+}
+/** Token names users can put in templates, for /warden status and the README. */
+export const TOKEN_NAMES = {
+    action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
+    stuck: ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"],
+    done: ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.2.1",
+  "version": "0.3.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, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",