pi-warden 0.1.2 → 0.2.0

package/dist/extension.js

@@ -1,11 +1,13 @@
 import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
-import { applyUserOverrides, defaultConfig, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
-import { evaluateAction, formatVerdict } from "./guard.js";
-export const disclosure = "With TypeSafe judgments enabled, pi-warden sends the latest user request plus a redacted, truncated summary of each guarded bash, write, or edit call (command text, file path, content excerpt) to api.typesafe.ai before the tool runs. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+import { 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";
+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;
-const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, confirmed: 0, blocked: 0, errors: 0 });
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, errors: 0 });
 function latestUserPrompt(ctx) {
     const entries = ctx.sessionManager.getBranch();
     for (let index = entries.length - 1; index >= 0; index--) {
@@ -19,14 +21,15 @@ function latestUserPrompt(ctx) {
     }
     return undefined;
 }
-function headlessPolicy(config) {
-    const env = process.env.PI_WARDEN_HEADLESS?.trim();
-    return env === "allow" || env === "block" ? env : config.headless;
+function activeMode(config, hasUI) {
+    const env = process.env.PI_WARDEN_MODE?.trim();
+    const mode = isMode(env) ? env : config.mode;
+    return mode === "confirm" && !hasUI ? "steer" : mode;
 }
 function clip(text) {
     return text.length <= CONFIRM_TEXT_LIMIT ? text : `${text.slice(0, CONFIRM_TEXT_LIMIT)}…`;
 }
-function confirmMessage(verdict) {
+export function confirmMessage(verdict) {
     const { summary } = verdict;
     const lines = [];
     if (summary.command !== undefined)
@@ -41,46 +44,96 @@ function confirmMessage(verdict) {
     lines.push("Judgments are model output, not authorization. Yes runs the tool; No blocks it and tells the agent.");
     return lines.join("\n");
 }
+const callKey = (tool, input) => `${tool}\0${JSON.stringify(input)}`;
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi) {
     let client;
     let budgetExhausted = false;
     let stats = freshStats();
-    let lastVerdict;
+    const widget = new Map();
+    /** 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);
+    let evidence = emptyEvidence();
+    let doneNudged = false;
     const configFor = (ctx) => loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
     const consentGiven = (config) => config.typesafe || process.env.PI_WARDEN_ENABLED === "1";
     const consentSource = (config) => config.typesafe ? "/warden enable" : process.env.PI_WARDEN_ENABLED === "1" ? "PI_WARDEN_ENABLED" : undefined;
     const judgeFor = (config) => {
         if (!consentGiven(config) || budgetExhausted || !resolveApiKey())
             return undefined;
-        return client ??= createTypeSafe({ maxRequests: config.action.maxRequests, timeoutMs: config.action.timeoutMs });
+        return client ??= createTypeSafe({ maxRequests: config.maxRequests, timeoutMs: config.timeoutMs });
     };
+    const noteError = (ctx, message, code) => {
+        stats.errors++;
+        if (code === "budget")
+            budgetExhausted = true;
+        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) => {
+        widget.set(guard, line);
+        if (ctx.hasUI)
+            ctx.ui.setWidget(WIDGET, [...widget.values()]);
+    };
+    const steer = (content) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: true }, { deliverAs: "steer" });
     pi.on("session_start", async (_event, ctx) => {
         client = undefined;
         budgetExhausted = false;
         stats = freshStats();
-        lastVerdict = undefined;
+        widget.clear();
+        held.clear();
+        attempts.reset();
+        evidence = emptyEvidence();
+        doneNudged = false;
         if (ctx.hasUI)
             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);
+        doneNudged = false;
+    });
+    // Each low-level run collects its own evidence of changes and checks.
+    pi.on("agent_start", async () => {
+        evidence = emptyEvidence();
+    });
     pi.on("tool_call", async (event, ctx) => {
         const config = configFor(ctx);
         if (!config.enabled || !config.action.enabled || !config.action.tools.includes(event.toolName))
             return;
         stats.inspected++;
-        const verdict = await evaluateAction({ tool: event.toolName, input: event.input, cwd: ctx.cwd, task: latestUserPrompt(ctx) }, { config: config.action, judge: judgeFor(config), signal: ctx.signal });
-        lastVerdict = verdict;
+        const task = latestUserPrompt(ctx);
+        const key = callKey(event.toolName, event.input);
+        const heldAt = held.get(key);
+        const retryAfterHold = held.has(key) && heldAt !== task;
+        const judge = judgeFor(config);
+        const verdict = await evaluateAction({ tool: event.toolName, input: event.input, cwd: ctx.cwd, task }, { config: config.action, judge, signal: ctx.signal, slop: config.slop, retryAfterHold });
+        if (verdict.source === "skipped")
+            return;
         if (verdict.judgment)
             stats.judged++;
-        if (verdict.source === "error") {
-            stats.errors++;
-            if (verdict.errorCode === "budget")
-                budgetExhausted = true;
+        if (verdict.source === "error")
+            noteError(ctx, verdict.error ?? "TypeSafe request failed.", verdict.errorCode);
+        // Offline stand-in for the approval question: the user has replied since the hold and the reply reads as approval.
+        if (retryAfterHold && !judge && verdict.level === "confirm" && textApproves(task)) {
+            verdict.level = "allow";
+            verdict.approvedByUser = true;
+            verdict.reasons = ["user approved in the latest message", ...verdict.reasons];
+        }
+        if (verdict.approvedByUser) {
+            stats.approved++;
+            held.delete(key);
+        }
+        if (verdict.source !== "read-only")
+            show(ctx, "action", formatVerdict(verdict));
+        if (verdict.slopReasons?.length) {
+            stats.slop++;
+            const where = verdict.summary.path ?? event.toolName;
             if (ctx.hasUI)
-                ctx.ui.notify(`warden: ${verdict.error}${budgetExhausted ? " Pattern checks continue without TypeSafe for the rest of this session." : ""}`, "warning");
+                ctx.ui.notify(`warden · slop · ${where}: ${verdict.slopReasons.join("; ")}`, "warning");
+            steer(`pi-warden: the content just written to ${where} reads as ${verdict.slopReasons.join(" and ")}. Replace stubs and placeholders with working code, remove comments that restate the code, and keep only what the request needs. If something is intentionally left unimplemented, say so in your reply instead of leaving it in the code.`);
         }
-        if (ctx.hasUI && verdict.source !== "read-only")
-            ctx.ui.setWidget(WIDGET, [formatVerdict(verdict)]);
         if (verdict.level === "warn") {
             stats.warned++;
             if (ctx.hasUI)
@@ -89,29 +142,86 @@ export default function wardenExtension(pi) {
         }
         if (verdict.level !== "confirm")
             return undefined;
-        stats.confirmed++;
+        const mode = activeMode(config, ctx.hasUI);
         const reasons = verdict.reasons.join("; ");
-        if (ctx.hasUI) {
+        if (mode === "advise") {
+            stats.warned++;
+            if (ctx.hasUI)
+                ctx.ui.notify(`warden · ${event.toolName} (advise mode, not held): ${reasons}`, "warning");
+            return undefined;
+        }
+        if (mode === "confirm") {
             const allowed = await ctx.ui.confirm(`warden: allow this ${event.toolName} call?`, confirmMessage(verdict), ctx.signal ? { signal: ctx.signal } : {});
             if (allowed)
                 return undefined;
-            stats.blocked++;
+            stats.held++;
             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.` };
         }
-        if (headlessPolicy(config) === "allow")
-            return undefined;
-        stats.blocked++;
-        return { block: true, reason: `pi-warden blocked this ${event.toolName} call because it needs user confirmation (${reasons}) and no user is present. Choose a safer approach or stop and report. Operators can set PI_WARDEN_HEADLESS=allow to permit such calls.` };
+        stats.held++;
+        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 }) };
+    });
+    pi.on("tool_result", async (event, ctx) => {
+        const config = configFor(ctx);
+        if (!config.enabled)
+            return;
+        const failed = resultFailed(event.isError, event.details);
+        if (config.done.enabled)
+            recordOutcome(evidence, classifyToolResult(event.toolName, event.input, failed), event.input);
+        if (!config.stuck.enabled)
+            return;
+        attempts.push(makeAttempt(event.toolName, event.input, event.content, failed));
+        if (!attempts.shouldJudge(config.stuck))
+            return;
+        stats.stuckChecks++;
+        const verdict = await evaluateStuck(attempts, latestUserPrompt(ctx), { config: config.stuck, judge: judgeFor(config), timeoutMs: config.timeoutMs, signal: ctx.signal });
+        if (verdict.error)
+            noteError(ctx, verdict.error, undefined);
+        if (verdict.source === "repeat" && !verdict.stuck)
+            return;
+        show(ctx, "stuck", formatStuck(verdict));
+        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));
     });
-    const actions = ["status", "enable", "disable", "config", "test"];
+    pi.on("agent_end", async (event, ctx) => {
+        const config = configFor(ctx);
+        if (!config.enabled || !config.done.enabled || doneNudged || !needsDoneCheck(evidence))
+            return;
+        const finalMessage = finalAssistantText(event.messages);
+        const judge = judgeFor(config);
+        if (!finalMessage || !judge)
+            return;
+        stats.doneChecks++;
+        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));
+        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) {
+            doneNudged = true;
+            pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: doneNudge(verdict), display: true }, { deliverAs: "followUp", triggerTurn: true });
+        }
+    });
+    const actions = ["status", "enable", "disable", "mode", "config", "test"];
     pi.registerCommand("warden", {
-        description: "pi-warden status, TypeSafe consent, config editor, and a synthetic guard test",
+        description: "pi-warden status, TypeSafe consent, steer/confirm/advise mode, config editor, 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;
         },
         async handler(args, ctx) {
-            const action = args.trim() || "status";
+            const [action = "status", argument] = args.trim().split(/\s+/);
             const report = (text, level = "info") => {
                 if (ctx.hasUI)
                     ctx.ui.notify(text, level);
@@ -124,12 +234,13 @@ export default function wardenExtension(pi) {
                     const key = resolveApiKey();
                     const source = consentSource(config);
                     const usage = client?.getUsage();
+                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop"].filter(Boolean).join(", ");
                     report([
-                        `pi-warden: ${config.enabled && config.action.enabled ? "guarding" : "off"} ${config.action.tools.join(", ")}; TypeSafe judgments ${source ? `enabled via ${source}` : "disabled (run /warden enable)"}; key ${key ? key.source === "stored" ? "stored (shared with pi-typesafe)" : "from TYPESAFE_API_KEY" : "missing (run /warden enable)"}.`,
-                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.confirmed} asked, ${stats.blocked} blocked, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.action.maxRequests} requests.`,
-                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / confirm ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / confirm ${config.action.offTask.confirm}; failOpen ${config.action.failOpen}; headless ${headlessPolicy(config)}.`,
+                        `pi-warden: ${config.enabled ? `guarding ${config.action.tools.join(", ")} (${guards})` : "off"}; mode ${activeMode(config, ctx.hasUI)}; TypeSafe judgments ${source ? `enabled via ${source}` : "disabled (run /warden enable)"}; key ${key ? key.source === "stored" ? "stored (shared with pi-typesafe)" : "from TYPESAFE_API_KEY" : "missing (run /warden enable)"}.`,
+                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests.`,
+                        `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)}` : ""}.`,
-                        lastVerdict ? `Last: ${formatVerdict(lastVerdict)}` : "No guarded tool calls yet this session.",
+                        widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",
                     ].join(" "));
                     return;
                 }
@@ -157,6 +268,15 @@ export default function wardenExtension(pi) {
                     report(`TypeSafe judgments disabled in ${path}. Offline pattern checks stay active; set enabled to false there to turn pi-warden off entirely.`);
                     return;
                 }
+                if (action === "mode") {
+                    if (!isMode(argument)) {
+                        report(`Mode is ${activeMode(config, ctx.hasUI)}${process.env.PI_WARDEN_MODE ? " (from PI_WARDEN_MODE)" : ""}. Use /warden mode steer | confirm | advise. steer holds risky calls and tells the agent why; confirm asks you with a dialog; advise only reports.`);
+                        return;
+                    }
+                    const path = setUserSetting("mode", argument);
+                    report(`Mode set to ${argument} in ${path}.`);
+                    return;
+                }
                 if (action === "config") {
                     if (!ctx.hasUI) {
                         report(`Edit ${userConfigPath()} directly. Defaults: ${JSON.stringify(defaultConfig())}`);
@@ -182,7 +302,7 @@ export default function wardenExtension(pi) {
                     const path = writeUserConfig(parsed);
                     const effective = applyUserOverrides(defaultConfig(), parsed);
                     client = undefined;
-                    report(`Saved ${path}. Effective: guard ${effective.enabled && effective.action.enabled ? "on" : "off"}, TypeSafe ${effective.typesafe ? "on" : "off"}, tools ${effective.action.tools.join(", ")}, irreversible confirm ≥ ${effective.action.irreversible.confirm}, off-task confirm ≥ ${effective.action.offTask.confirm}.`);
+                    report(`Saved ${path}. Effective: guard ${effective.enabled && effective.action.enabled ? "on" : "off"}, mode ${effective.mode}, TypeSafe ${effective.typesafe ? "on" : "off"}, tools ${effective.action.tools.join(", ")}, irreversible hold ≥ ${effective.action.irreversible.confirm}, off-task hold ≥ ${effective.action.offTask.confirm}, stuck ${effective.stuck.enabled ? "on" : "off"}, done-check ${effective.done.enabled ? "on" : "off"}, slop ${effective.slop.enabled ? "on" : "off"}.`);
                     return;
                 }
                 if (action === "test") {
@@ -190,13 +310,17 @@ 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 });
-                    if (ctx.hasUI)
-                        ctx.ui.setWidget(WIDGET, [formatVerdict(verdict)]);
+                    show(ctx, "action", formatVerdict(verdict));
                     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 (ctx.hasUI && verdict.level === "confirm") {
-                        // Show the same dialog a real call would get, so users can see what blocking looks like without touching anything.
-                        const allowed = await ctx.ui.confirm("warden: allow this bash call? (demo)", `${confirmMessage(verdict)}\n\nThis is /warden test: nothing runs either way.`);
-                        report(allowed ? "Demo: you chose Yes, so a real call would have run." : "Demo: you chose No, so a real call would have been blocked and the agent told why.");
+                    if (verdict.level === "confirm") {
+                        const mode = activeMode(config, ctx.hasUI);
+                        if (mode === "confirm" && ctx.hasUI) {
+                            const allowed = await ctx.ui.confirm("warden: allow this bash call? (demo)", `${confirmMessage(verdict)}\n\nThis is /warden test: nothing runs either way.`);
+                            report(allowed ? "Demo: you chose Yes, so a real call would have run." : "Demo: you chose No, so a real call would have been blocked and the agent told why.");
+                        }
+                        else {
+                            report(`In ${mode} mode a real call would ${mode === "advise" ? "run with this warning shown to you" : "be held and the agent would read"}: "${steerReason(verdict, { canApprove: judge !== undefined })}"`);
+                        }
                     }
                     return;
                 }

package/dist/guard.d.ts

@@ -1,5 +1,5 @@
 import type { IntegrationErrorCode, TypeSafe } from "pi-typesafe";
-import type { ActionGuardConfig } from "./config.js";
+import type { ActionGuardConfig, SlopGuardConfig } from "./config.js";
 export type Level = "allow" | "warn" | "confirm";
 export type Severity = "destructive" | "risky" | "sensitive";
 export interface PatternHit {
@@ -37,9 +37,17 @@ export interface Judgment {
     offTask: number;
     scope: ScopeLabel;
     scopeConfidence: number;
+    /** P(the latest user message approves this exact action); only asked when a previously held call is retried. */
+    approved?: number;
     model: string;
     elapsedMs: number;
 }
+export interface SlopJudgment {
+    /** 0 focused … 2 sloppy. */
+    quality: number;
+    /** P(placeholder or stub where working code is needed). */
+    placeholder: number;
+}
 export interface Verdict {
     level: Level;
     source: "skipped" | "read-only" | "pattern" | "typesafe" | "error";
@@ -48,6 +56,11 @@ export interface Verdict {
     /** Human-readable reasons without secrets or full commands. */
     reasons: string[];
     judgment?: Judgment;
+    slop?: SlopJudgment;
+    /** Set when the slop thresholds were crossed; the level itself is never raised by slop. */
+    slopReasons?: string[];
+    /** True when a previously held call was allowed because the user's latest message approves it. */
+    approvedByUser?: boolean;
     /** Safe TypeSafe error message when the judge could not answer. */
     error?: string;
     errorCode?: IntegrationErrorCode;
@@ -59,6 +72,10 @@ export interface EvaluateOptions {
     /** Omit to run offline pattern checks only (no consent, no network). */
     judge?: Judge | undefined;
     signal?: AbortSignal | undefined;
+    /** Adds quality questions for write/edit content to the same request. */
+    slop?: SlopGuardConfig | undefined;
+    /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
+    retryAfterHold?: boolean | undefined;
 }
 export declare function matchPatterns(tool: string, input: Record<string, unknown>, cwd?: string): PatternHit[];
 export declare function isReadOnlyCommand(command: string): boolean;
@@ -73,12 +90,25 @@ export declare const questions: {
         readonly unclear: "`task` or `action` gives too little information to tell";
     }>;
 };
-export declare function buildRequest(summary: ActionSummary, task: string | undefined): {
+export declare const slopQuestions: {
+    slop_quality: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
+    slop_placeholder: import("pi-typesafe").NoulQuestion;
+};
+export declare const approvalQuestion: {
+    approved: import("pi-typesafe").NoulQuestion;
+};
+export declare function buildRequest(summary: ActionSummary, task: string | undefined, extras?: {
+    slop?: boolean;
+    approval?: boolean;
+}): {
     state: {
         task: string;
         action: Record<string, string | number | boolean>;
     };
     questions: {
+        approved?: import("pi-typesafe").NoulQuestion;
+        slop_quality?: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
+        slop_placeholder?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
         off_task: import("pi-typesafe").NoulQuestion;
         scope: import("pi-typesafe").ChoiceQuestion<{
@@ -90,5 +120,14 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
     };
 };
 export declare function evaluateAction(action: ActionInput, options: EvaluateOptions): Promise<Verdict>;
+/** Offline stand-in for the approval question when TypeSafe is not available. */
+export declare function textApproves(task: string | undefined): boolean;
+/**
+ * The text the agent receives when a call is held. It explains the judgment and the two acceptable next moves,
+ * so the model re-plans instead of retrying. Contains no command text (the model already has it) and no secrets.
+ */
+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;

package/dist/guard.js

@@ -1,14 +1,14 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { choice, noul, TypeSafeIntegrationError } from "pi-typesafe";
+import { choice, noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.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;
 const COMMAND_LIMIT = 2000;
-const EXCERPT_LIMIT = 600;
-const EDIT_LIMIT = 200;
+const EXCERPT_LIMIT = 1500;
+const EDIT_LIMIT = 400;
 function truncate(text, limit) {
     return text.length <= limit ? text : `${text.slice(0, limit)}… [${text.length - limit} more chars]`;
 }
@@ -186,7 +186,7 @@ export function describeAction(tool, input, cwd) {
     return summary;
 }
 // ---------------------------------------------------------------------------
-// TypeSafe request: named state fields, three independent questions.
+// TypeSafe request: named state fields, independent questions. Slop and approval questions join the same request.
 export const questions = {
     irreversible: noul("Would executing `action` destroy, overwrite, or discard data or state that could not be recovered afterwards?", {
         true: "Yes: it force-pushes or rewrites shared history, deletes untracked or uncommitted work, drops or truncates database objects, overwrites files outside the project, publishes or deploys, or removes something no build or checkout can regenerate.",
@@ -203,13 +203,31 @@ export const questions = {
         unclear: "`task` or `action` gives too little information to tell",
     }),
 };
-export function buildRequest(summary, task) {
+export const slopQuestions = {
+    slop_quality: score("How does the new code or text that `action` writes read as a change for `task`?", [
+        "Focused: does what `task` needs, clear names, comments only where they add information",
+        "Some filler: comments that restate the code, minor dead code, hedging or repeated text",
+        "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text",
+    ]),
+    slop_placeholder: noul("Does the content `action` writes leave placeholder, stub, mock, or 'implement later' code where `task` needs a working implementation?"),
+};
+export const approvalQuestion = {
+    approved: noul("Does `task` (the user's latest message) explicitly approve running `action`, which was held earlier for the user's decision?", {
+        true: "Yes: the message says to go ahead with this action or with the deletion, push, reset, or change it performs.",
+        false: "No: the message declines, asks for something else, changes the approach, or does not address this action.",
+    }),
+};
+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);
     return {
         state: {
             task: task?.trim() ? truncate(task.trim(), TASK_LIMIT) : "(no user request recorded in this session)",
             action: summary,
         },
-        questions,
+        questions: { ...questions, ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}) },
     };
 }
 function combineSignals(timeoutMs, signal) {
@@ -217,6 +235,7 @@ function combineSignals(timeoutMs, signal) {
     return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
 const percent = (value) => value.toFixed(2);
+const APPROVAL_THRESHOLD = 0.7;
 // ---------------------------------------------------------------------------
 export async function evaluateAction(action, options) {
     const { config, judge } = options;
@@ -247,15 +266,19 @@ export async function evaluateAction(action, options) {
     if (!judge)
         return { level, source: "pattern", summary, patterns, reasons };
     try {
-        const result = await judge.evaluate(buildRequest(summary, action.task), { signal: combineSignals(config.timeoutMs, options.signal) });
+        const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false });
+        const result = await judge.evaluate(request, { signal: combineSignals(config.timeoutMs, options.signal) });
+        const answers = result.answers;
         const judgment = {
-            irreversible: result.answers.irreversible.noul,
-            offTask: result.answers.off_task.noul,
-            scope: result.answers.scope.choice,
-            scopeConfidence: result.answers.scope.confidence,
+            irreversible: answers.irreversible.noul,
+            offTask: answers.off_task.noul,
+            scope: answers.scope.choice,
+            scopeConfidence: answers.scope.confidence,
             model: result.model,
             elapsedMs: result.elapsedMs,
         };
+        if (typeof answers.approved?.noul === "number")
+            judgment.approved = answers.approved.noul;
         if (judgment.irreversible >= config.irreversible.confirm) {
             level = higher(level, "confirm");
             reasons.push(`irreversible ${percent(judgment.irreversible)}`);
@@ -272,7 +295,23 @@ export async function evaluateAction(action, options) {
             level = higher(level, "warn");
             reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
         }
-        return { level, source: "typesafe", summary, patterns, reasons, judgment };
+        const verdict = { level, source: "typesafe", summary, patterns, reasons, judgment };
+        if (options.slop?.enabled && typeof answers.slop_quality?.score === "number" && typeof answers.slop_placeholder?.noul === "number") {
+            verdict.slop = { quality: answers.slop_quality.score, placeholder: answers.slop_placeholder.noul };
+            const slopReasons = [];
+            if (verdict.slop.quality >= options.slop.quality)
+                slopReasons.push(`quality ${verdict.slop.quality.toFixed(2)}/2 (filler or sloppy)`);
+            if (verdict.slop.placeholder >= options.slop.placeholder)
+                slopReasons.push(`placeholder or stub code ${percent(verdict.slop.placeholder)}`);
+            if (slopReasons.length)
+                verdict.slopReasons = slopReasons;
+        }
+        if (level === "confirm" && judgment.approved !== undefined && judgment.approved >= APPROVAL_THRESHOLD) {
+            verdict.level = "allow";
+            verdict.approvedByUser = true;
+            verdict.reasons = [`user approved in the latest message (${percent(judgment.approved)})`, ...reasons];
+        }
+        return verdict;
     }
     catch (error) {
         const known = error instanceof TypeSafeIntegrationError ? error : undefined;
@@ -287,13 +326,37 @@ export async function evaluateAction(action, options) {
         return { level, source: "error", summary, patterns, reasons, error: message, ...(known ? { errorCode: known.code } : {}) };
     }
 }
+/** Offline stand-in for the approval question when TypeSafe is not available. */
+export function textApproves(task) {
+    return /\b(?:yes|yep|yeah|go ahead|do it|proceed|approved?|confirm(?:ed)?|ok(?:ay)?|sure|please do|run it)\b/i.test(task ?? "") && !/\b(?:no|don't|do not|stop|wait|instead|not)\b/i.test(task ?? "");
+}
+/**
+ * The text the agent receives when a call is held. It explains the judgment and the two acceptable next moves,
+ * so the model re-plans instead of retrying. Contains no command text (the model already has it) and no secrets.
+ */
+export function steerReason(verdict, options) {
+    const what = verdict.reasons.join("; ");
+    const lines = [
+        `pi-warden held this ${verdict.summary.tool} call before it ran: ${what}.`,
+        "Do not retry it unchanged. Either (1) reach the goal with a recoverable alternative that stays inside the project (a targeted path, a dry run, a move instead of a delete, a normal push), or (2) if this exact action is genuinely required, stop and tell the user in one or two sentences what it does, what cannot be undone, and why it is needed, then wait for their reply.",
+    ];
+    if (options.canApprove)
+        lines.push("If the user's reply approves it, retry the same call and pi-warden will let it through.");
+    else
+        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")

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, questions } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
+export type { Attempt, StuckJudgment, StuckVerdict, StuckOptions } from "./stuck.js";
+export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
+export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions } from "./done.js";
 export { redact } from "./redact.js";
-export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, Threshold, WardenConfig, LoadOptions } from "./config.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";

package/dist/index.js

@@ -1,3 +1,5 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, questions } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
+export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
+export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { redact } from "./redact.js";
-export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";