pi-warden 0.5.5 → 0.7.0

package/dist/extension.js

@@ -1,12 +1,14 @@
 import { MouseRegion, Text } from "@earendil-works/pi-tui";
 import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
+import { ActionGuard } from "./action-guard.js";
 import * as configModule from "./config.js";
 import { applyUserOverrides, defaultConfig, isMode, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
 import { classifyToolResult, doneNudge, emptyEvidence, evaluateDone, finalAssistantText, formatDone, needsDoneCheck, recordOutcome } from "./done.js";
-import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason, textApproves } from "./guard.js";
+import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason } from "./guard.js";
 import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
-import { compressOutput, evaluateOutput, saveOutput, securityNotice } from "./output.js";
+import { compressOutput, duplicateNote, evaluateOutput, outputKey, saveOutput, securityNotice } from "./output.js";
+import { classifyRecall, detectSearchTool, recallInstruction } from "./recall.js";
 import { redact } from "./redact.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
 import { openTracePanel } from "./panel.js";
@@ -14,7 +16,7 @@ import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
 import { actionDetails, doneDetails, proseDetails, stuckDetails, Trace } from "./trace.js";
 import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
-export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and tail compression. Compression stores an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
 const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, errors: 0 });
@@ -69,7 +71,7 @@ export function siblingToolCalls(ctx) {
         if (!Array.isArray(content))
             return [];
         return content.flatMap(part => part.type === "toolCall" && typeof part.id === "string" && typeof part.name === "string"
-            ? [{ id: part.id, name: part.name, input: (part.arguments ?? {}) }]
+            ? [{ id: part.id, tool: part.name, input: (part.arguments ?? {}) }]
             : []);
     }
     return [];
@@ -119,21 +121,15 @@ export default function wardenExtension(pi) {
     const trace = new Trace();
     let panel;
     let lastUi;
-    /** Judgments for tool calls of the current assistant message, keyed by tool call id; `used` marks preflighted ones. */
-    const prejudged = new Map();
-    /**
-     * Steer-mode hold state. After a hold, the next guarded call that runs under a *new* user prompt asks Jev whether that
-     * prompt approves it. The retry rarely repeats the held string byte for byte (a `command -v` dropped, a different
-     * timeout), so approval is judged against the action itself, not matched against the earlier command text.
-     */
-    let lastHoldPrompt;
-    let holdPending = false;
+    const actionGuard = new ActionGuard();
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
     const prose = new ProseTrend();
     const slopCounts = { stub: 0, comments: 0, dead: 0, hedging: 0 };
     const ledger = new ContextLedger();
+    // Probed once per session, outside any tool_result handler; the footer under excerpts names this command.
+    let searchTool;
     // A partially updated module graph can hand this build a config without the sections it expects; see shape.ts.
     let shapeReported = false;
     const configFor = (ctx) => {
@@ -206,13 +202,13 @@ export default function wardenExtension(pi) {
         widget.clear();
         trace.clear();
         panel?.close();
-        lastHoldPrompt = undefined;
-        holdPending = false;
+        actionGuard.reset();
         attempts.reset();
         evidence = emptyEvidence();
         doneNudged = false;
         prose.reset();
         ledger.reset();
+        searchTool = undefined;
         for (const symptom of Object.keys(slopCounts))
             slopCounts[symptom] = 0;
         if (ctx.hasUI)
@@ -222,7 +218,7 @@ export default function wardenExtension(pi) {
     pi.on("before_agent_start", async (_event, ctx) => {
         attempts = new AttemptWindow(configFor(ctx).stuck.window);
         doneNudged = false;
-        prejudged.clear();
+        actionGuard.turnEnd();
     });
     // Each low-level run collects its own evidence of changes and checks.
     pi.on("agent_start", async () => {
@@ -231,44 +227,28 @@ export default function wardenExtension(pi) {
     // Every turn that runs after a compression is a turn that did not carry the removed text.
     pi.on("turn_end", async () => {
         ledger.turnEnd();
-        // Siblings that were never preflighted (an earlier one terminated the batch, or Esc) do not outlive their turn.
-        prejudged.clear();
+        actionGuard.turnEnd();
     });
     pi.on("tool_call", async (event, ctx) => {
         const config = configFor(ctx);
         if (!config.enabled)
             return;
         // A read of a stored full output means the excerpt was not enough; that is the number that tunes context.confidence.
-        const recalled = ledger.noteAccess(JSON.stringify(event.input));
-        if (recalled)
-            record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: "full output recalled" }), [`the agent went back to ${recalled}`, formatLedger(ledger.snapshot())]);
+        // A whole-file read also undoes the saving, so the kind of access is kept apart.
+        const serializedInput = JSON.stringify(event.input);
+        const storedPath = ledger.storedPathIn(serializedInput);
+        if (storedPath) {
+            const kind = classifyRecall(event.toolName, event.input, storedPath);
+            const recalled = ledger.noteAccess(serializedInput, kind);
+            if (recalled)
+                record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: `full output recalled (${kind})` }), [`the agent went back to ${recalled} (${kind === "full" ? "whole-file read" : "scoped access"})`, formatLedger(ledger.snapshot())]);
+        }
         if (!config.action.enabled || !config.action.tools.includes(event.toolName))
             return;
         stats.inspected++;
         const task = latestUserPrompt(ctx);
-        // A hold happened under an earlier prompt and the user has since replied: ask whether the reply approves this action.
-        const retryAfterHold = holdPending && lastHoldPrompt !== task;
         const judge = judgeFor(config);
-        const context = recentTaskContext(ctx);
-        const options = { config: config.action, judge, signal: ctx.signal, slop: config.slop, security: config.security, retryAfterHold };
-        const judgeCall = (tool, input) => evaluateAction({ tool, input, cwd: ctx.cwd, task, context }, options);
-        // Sibling calls in the same assistant message are preflighted one after another; their requests go out together.
-        // A retry after a hold stays sequential because an approval consumed by one sibling changes the question for the next.
-        if (judge && !retryAfterHold) {
-            for (const sibling of siblingToolCalls(ctx)) {
-                if (sibling.id === event.toolCallId || prejudged.has(sibling.id) || !config.action.tools.includes(sibling.name))
-                    continue;
-                const verdict = judgeCall(sibling.name, sibling.input);
-                verdict.catch(() => undefined);
-                prejudged.set(sibling.id, { key: JSON.stringify(sibling.input), verdict, used: false });
-            }
-        }
-        // An earlier hook may have changed this call's input; a stale judgment is discarded, not reused.
-        const key = JSON.stringify(event.input);
-        const ready = prejudged.get(event.toolCallId);
-        const pending = ready && !ready.used && ready.key === key && !retryAfterHold ? ready.verdict : judgeCall(event.toolName, event.input);
-        prejudged.set(event.toolCallId, { key, verdict: pending, used: true });
-        const verdict = await pending;
+        const verdict = await actionGuard.inspect({ id: event.toolCallId, tool: event.toolName, input: event.input }, { task, context: recentTaskContext(ctx), siblings: siblingToolCalls(ctx) }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security });
         if (verdict.source === "skipped")
             return;
         if (verdict.judgment?.securityRisk !== undefined && verdict.judgment.securityRisk >= config.security.threshold) {
@@ -278,16 +258,8 @@ export default function wardenExtension(pi) {
             stats.judged++;
         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) {
+        if (verdict.approvedByUser)
             stats.approved++;
-            holdPending = false;
-        }
         const mode = activeMode(config, ctx.hasUI);
         const told = verdict.level === "confirm" && mode === "steer" ? steerReason(verdict, { canApprove: judge !== undefined }) : undefined;
         if (verdict.source !== "read-only")
@@ -324,10 +296,7 @@ export default function wardenExtension(pi) {
             return { block: true, reason: `pi-warden: the user declined this ${event.toolName} call (${reasons}). Do not retry it unchanged; ask the user how to proceed.` };
         }
         stats.held++;
-        // A re-hold under the user's reply keeps the original reference prompt; otherwise the reply could never approve anything.
-        if (!holdPending)
-            lastHoldPrompt = task;
-        holdPending = true;
+        actionGuard.hold(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: told ?? steerReason(verdict, { canApprove: judge !== undefined }) };
@@ -349,7 +318,12 @@ export default function wardenExtension(pi) {
             stats.stuckChecks++;
             return evaluateStuck(attempts, latestUserPrompt(ctx), { config: config.stuck, judge: judgeFor(config), timeoutMs: config.timeoutMs, signal: ctx.signal });
         })();
-        const output = await evaluateOutput(event.toolName, text, latestUserPrompt(ctx), {
+        // A recall brings stored text back on purpose: it is not judged, compressed, or dropped again.
+        const recallRead = ledger.storedPathIn(JSON.stringify(event.input)) !== undefined;
+        // Duplicate detection is code only: an identical result adds nothing, whatever Jev would say about it.
+        const key = config.context.enabled && !recallRead && textBlocks.length === 1 && text.length >= config.context.duplicateMinChars ? outputKey(text) : undefined;
+        const earlier = key ? ledger.duplicateOf(key) : undefined;
+        const output = earlier || recallRead ? { secret: false, suspicious: false, retention: "all" } : await evaluateOutput(event.toolName, text, latestUserPrompt(ctx), {
             security: config.security, context: config.context, judge: judgeFor(config), timeoutMs: config.timeoutMs,
             signal: ctx.signal, compressible: textBlocks.length === 1, taskContext: recentTaskContext(ctx),
         });
@@ -359,19 +333,41 @@ export default function wardenExtension(pi) {
             noteError(ctx, output.error, output.errorCode);
         let content = event.content;
         const notice = securityNotice(output);
-        if (config.context.enabled && textBlocks.length === 1 && text.length >= config.context.tailMinChars)
+        const recallTool = await (searchTool ??= detectSearchTool(config.context.recallTool));
+        let storedPath;
+        if (earlier && key) {
+            try {
+                storedPath = earlier.path ?? await saveOutput(text);
+                const replacement = `${duplicateNote(text, earlier.tool)}\n\n${recallInstruction(recallTool, storedPath)}`;
+                const bytesSaved = Buffer.byteLength(text) - Buffer.byteLength(replacement);
+                if (bytesSaved > 0) {
+                    content = content.map(part => part.type === "text" ? { ...part, text: replacement } : part);
+                    ledger.duplicate(bytesSaved);
+                    ledger.remember(key, earlier.tool, storedPath);
+                    record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: "duplicate", bytesSaved: String(bytesSaved) }), [
+                        `identical to an earlier ${earlier.tool} result; saved ${bytesSaved} bytes; full output: ${storedPath}`,
+                        formatLedger(ledger.snapshot()),
+                    ]);
+                }
+            }
+            catch {
+                noteError(ctx, "Could not store full output; keeping it unchanged.", undefined);
+            }
+        }
+        if (config.context.enabled && !earlier && !recallRead && textBlocks.length === 1 && text.length >= config.context.tailMinChars)
             ledger.candidate();
-        const excerpt = compressOutput(text, output.retention);
+        const excerpt = earlier ? undefined : compressOutput(text, output.retention, output.format);
         if (excerpt && !ctx.signal?.aborted) {
             try {
                 const path = await saveOutput(text);
-                const replacement = `${excerpt}\n\nFull output: ${path}`;
+                const replacement = `${excerpt}\n\n${recallInstruction(recallTool, path)}`;
                 const bytesSaved = Buffer.byteLength(text) - Buffer.byteLength(replacement) - (notice ? Buffer.byteLength(notice) * 2 + 4 : 0);
                 if (bytesSaved > 0) {
                     content = content.map(part => part.type === "text" ? { ...part, text: replacement } : part);
                     ledger.record(path, bytesSaved);
+                    storedPath = path;
                     record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: output.retention, bytesSaved: String(bytesSaved) }), [
-                        `retention: ${output.retention}; confidence ${output.confidence?.toFixed(2)}; ${output.model}; ${output.elapsedMs} ms`,
+                        `retention: ${output.retention}; confidence ${output.confidence?.toFixed(2)}; format ${output.format ?? "generic"}${output.formatConfidence === undefined ? "" : ` (${output.formatConfidence.toFixed(2)})`}; ${output.model}; ${output.elapsedMs} ms`,
                         `saved ${bytesSaved} bytes; full output: ${path}`,
                         formatLedger(ledger.snapshot()),
                     ]);
@@ -381,6 +377,8 @@ export default function wardenExtension(pi) {
                 noteError(ctx, "Could not store full output; keeping it unchanged.", undefined);
             }
         }
+        if (key && !earlier)
+            ledger.remember(key, event.toolName, storedPath);
         if (notice && textBlocks.length) {
             let index = 0;
             content = content.map(part => {
@@ -406,7 +404,7 @@ export default function wardenExtension(pi) {
         if (!verdict)
             return patch;
         if (verdict.error)
-            noteError(ctx, verdict.error, undefined);
+            noteError(ctx, verdict.error, verdict.errorCode);
         if (verdict.source === "repeat" && !verdict.stuck)
             return patch;
         const nudge = verdict.stuck && config.stuck.nudge ? stuckNudge(verdict) : undefined;
@@ -440,7 +438,7 @@ export default function wardenExtension(pi) {
             stats.proseChecks++;
             const verdict = await proseCheck;
             if (verdict.error)
-                noteError(ctx, verdict.error, undefined);
+                noteError(ctx, verdict.error, verdict.errorCode);
             else
                 prose.record(verdict.flagged);
             const due = verdict.error ? [] : prose.due(config.slop.prose.trend);
@@ -462,7 +460,7 @@ export default function wardenExtension(pi) {
         stats.doneChecks++;
         const verdict = await doneCheck;
         if (verdict.error)
-            noteError(ctx, verdict.error, undefined);
+            noteError(ctx, verdict.error, verdict.errorCode);
         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)
@@ -505,7 +503,7 @@ 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", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`, config.security.enabled && "security", config.context.enabled && "context (tail-only)"].filter(Boolean).join(", ");
+                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`, config.security.enabled && "security", config.context.enabled && "context"].filter(Boolean).join(", ");
                     report([
                         `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.proseNudges}/${stats.proseChecks} prose nudges, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,

package/dist/guard.d.ts

@@ -1,5 +1,6 @@
-import type { IntegrationErrorCode, TypeSafe } from "pi-typesafe";
+import type { IntegrationErrorCode } from "pi-typesafe";
 import type { ActionGuardConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { Judge } from "./jev.js";
 export type Level = "allow" | "warn" | "confirm";
 export type Severity = "destructive" | "risky" | "sensitive";
 export interface PatternHit {
@@ -78,8 +79,7 @@ export interface Verdict {
     error?: string;
     errorCode?: IntegrationErrorCode;
 }
-/** The subset of pi-typesafe's client the guard needs; tests supply a fake. */
-export type Judge = Pick<TypeSafe, "evaluate">;
+export type { Judge } from "./jev.js";
 export interface EvaluateOptions {
     config: ActionGuardConfig;
     /** Omit to run offline pattern checks only (no consent, no network). */

package/dist/guard.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { choice, noul, score, TypeSafeIntegrationError } from "pi-typesafe";
+import { choice, noul, score } from "pi-typesafe";
+import { askJev } from "./jev.js";
 import { redact } from "./redact.js";
 import { commandOf } from "./tools.js";
 import { actionTokens, DEFAULT_TEMPLATES, renderTemplate } from "./widget.js";
@@ -271,10 +272,6 @@ export function buildRequest(summary, task, extras = {}) {
         questions: { ...questions, ...(wantSlop ? slopQuestions : {}), ...(extras.approval ? approvalQuestion : {}), ...(extras.security && (summary.tool === "write" || summary.tool === "edit") && hasContent(summary) ? securityQuestion : {}) },
     };
 }
-function combineSignals(timeoutMs, signal) {
-    const timeout = AbortSignal.timeout(timeoutMs);
-    return signal ? AbortSignal.any([signal, timeout]) : timeout;
-}
 const percent = (value) => value.toFixed(2);
 const APPROVAL_THRESHOLD = 0.7;
 // ---------------------------------------------------------------------------
@@ -312,91 +309,87 @@ export async function evaluateAction(action, options) {
     }
     if (!judge)
         return { level, source: "pattern", summary, patterns, reasons };
-    try {
-        const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context });
-        const result = await judge.evaluate(request, { signal: combineSignals(config.timeoutMs, options.signal) });
-        const answers = result.answers;
-        const judgment = {
-            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 (typeof answers.mutates?.noul === "number")
-            judgment.mutates = answers.mutates.noul;
-        if (deferSensitive) {
-            for (const hit of patterns) {
-                if (hit.severity !== "sensitive")
-                    continue;
-                if ((judgment.mutates ?? 1) >= 0.5) {
-                    level = higher(level, "warn");
-                    reasons.push(`${hit.severity}: ${hit.label}`);
-                }
-                else
-                    reasons.push(`${hit.label} (read-only, not warned)`);
-            }
-        }
-        // write/edit always change something; a command that Jev judges read-only is warned about, never held, for scope alone.
-        const canChange = summary.tool === "write" || summary.tool === "edit" || (judgment.mutates ?? 1) >= 0.5;
-        if (judgment.irreversible >= config.irreversible.confirm) {
-            level = higher(level, "confirm");
-            reasons.push(`irreversible ${percent(judgment.irreversible)}`);
-        }
-        else if (judgment.irreversible >= config.irreversible.warn) {
-            level = higher(level, "warn");
-            reasons.push(`possibly irreversible ${percent(judgment.irreversible)}`);
-        }
-        if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated" && canChange) {
+    const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context });
+    const result = await askJev(judge, request, { timeoutMs: config.timeoutMs, signal: options.signal });
+    if (!result.ok) {
+        if (!config.failOpen) {
             level = higher(level, "confirm");
-            reasons.push(`off-task ${percent(judgment.offTask)} (unrelated to the request)`);
-        }
-        else if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated") {
-            level = higher(level, "warn");
-            reasons.push(`off-task ${percent(judgment.offTask)} (unrelated, but read-only: not held)`);
+            reasons.push("TypeSafe unavailable and failOpen is false");
         }
-        else if (judgment.offTask >= config.offTask.warn && judgment.scope !== "unclear") {
-            level = higher(level, "warn");
-            reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
+        else {
+            reasons.push("TypeSafe unavailable; allowed by failOpen");
         }
-        if (options.security?.enabled && typeof answers.security_risk?.noul === "number") {
-            judgment.securityRisk = answers.security_risk.noul;
-            if (judgment.securityRisk >= options.security.threshold) {
+        return { level, source: "error", summary, patterns, reasons, error: result.error, ...(result.errorCode ? { errorCode: result.errorCode } : {}) };
+    }
+    const answers = result.answers;
+    const judgment = {
+        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 (typeof answers.mutates?.noul === "number")
+        judgment.mutates = answers.mutates.noul;
+    if (deferSensitive) {
+        for (const hit of patterns) {
+            if (hit.severity !== "sensitive")
+                continue;
+            if ((judgment.mutates ?? 1) >= 0.5) {
                 level = higher(level, "warn");
-                reasons.push(`possible security weakness ${percent(judgment.securityRisk)} in written content`);
+                reasons.push(`${hit.severity}: ${hit.label}`);
             }
+            else
+                reasons.push(`${hit.label} (read-only, not warned)`);
         }
-        const verdict = { level, source: "typesafe", summary, patterns, reasons, judgment };
-        if (options.slop?.enabled && SLOP_SYMPTOMS.every(symptom => typeof answers[`slop_${symptom}`]?.noul === "number")) {
-            verdict.slop = { stub: answers.slop_stub.noul, comments: answers.slop_comments.noul, dead: answers.slop_dead.noul, hedging: answers.slop_hedging.noul };
-            const flagged = SLOP_SYMPTOMS.filter(symptom => verdict.slop[symptom] >= options.slop.threshold).sort((a, b) => verdict.slop[b] - verdict.slop[a]);
-            if (flagged.length) {
-                verdict.slopSymptoms = flagged;
-                verdict.slopReasons = flagged.map(symptom => `${SLOP_LABELS[symptom]} (${percent(verdict.slop[symptom])})`);
-            }
-        }
-        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;
-        const message = known?.message ?? "TypeSafe request failed.";
-        if (!config.failOpen) {
-            level = higher(level, "confirm");
-            reasons.push("TypeSafe unavailable and failOpen is false");
+    // write/edit always change something; a command that Jev judges read-only is warned about, never held, for scope alone.
+    const canChange = summary.tool === "write" || summary.tool === "edit" || (judgment.mutates ?? 1) >= 0.5;
+    if (judgment.irreversible >= config.irreversible.confirm) {
+        level = higher(level, "confirm");
+        reasons.push(`irreversible ${percent(judgment.irreversible)}`);
+    }
+    else if (judgment.irreversible >= config.irreversible.warn) {
+        level = higher(level, "warn");
+        reasons.push(`possibly irreversible ${percent(judgment.irreversible)}`);
+    }
+    if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated" && canChange) {
+        level = higher(level, "confirm");
+        reasons.push(`off-task ${percent(judgment.offTask)} (unrelated to the request)`);
+    }
+    else if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated") {
+        level = higher(level, "warn");
+        reasons.push(`off-task ${percent(judgment.offTask)} (unrelated, but read-only: not held)`);
+    }
+    else if (judgment.offTask >= config.offTask.warn && judgment.scope !== "unclear") {
+        level = higher(level, "warn");
+        reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
+    }
+    if (options.security?.enabled && typeof answers.security_risk?.noul === "number") {
+        judgment.securityRisk = answers.security_risk.noul;
+        if (judgment.securityRisk >= options.security.threshold) {
+            level = higher(level, "warn");
+            reasons.push(`possible security weakness ${percent(judgment.securityRisk)} in written content`);
         }
-        else {
-            reasons.push("TypeSafe unavailable; allowed by failOpen");
+    }
+    const verdict = { level, source: "typesafe", summary, patterns, reasons, judgment };
+    if (options.slop?.enabled && SLOP_SYMPTOMS.every(symptom => typeof answers[`slop_${symptom}`]?.noul === "number")) {
+        verdict.slop = { stub: answers.slop_stub.noul, comments: answers.slop_comments.noul, dead: answers.slop_dead.noul, hedging: answers.slop_hedging.noul };
+        const flagged = SLOP_SYMPTOMS.filter(symptom => verdict.slop[symptom] >= options.slop.threshold).sort((a, b) => verdict.slop[b] - verdict.slop[a]);
+        if (flagged.length) {
+            verdict.slopSymptoms = flagged;
+            verdict.slopReasons = flagged.map(symptom => `${SLOP_LABELS[symptom]} (${percent(verdict.slop[symptom])})`);
         }
-        return { level, source: "error", summary, patterns, reasons, error: message, ...(known ? { errorCode: known.code } : {}) };
     }
+    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;
 }
 /** Offline stand-in for the approval question when TypeSafe is not available. */
 export function textApproves(task) {

package/dist/index.d.ts

@@ -1,21 +1,27 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
 export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { ActionGuard } from "./action-guard.js";
+export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
 export type { ProseSymptom, ProseVerdict, ProseOptions } from "./prose.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 { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice } from "./output.js";
+export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice, outputKey, duplicateNote } from "./output.js";
 export type { Retention, OutputVerdict, OutputOptions } from "./output.js";
+export { formatExcerpt, formatQuestion } from "./excerpt.js";
+export type { OutputFormat } from "./excerpt.js";
+export { detectSearchTool, recallInstruction, classifyRecall } from "./recall.js";
+export type { SearchTool } from "./recall.js";
 export { redact } from "./redact.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
-export type { ContextLedgerSnapshot } from "./saver.js";
+export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
-export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, RecallTool, 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, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";

package/dist/index.js

@@ -1,13 +1,16 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { ActionGuard } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
 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 { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice } from "./output.js";
+export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice, outputKey, duplicateNote } from "./output.js";
+export { formatExcerpt, formatQuestion } from "./excerpt.js";
+export { detectSearchTool, recallInstruction, classifyRecall } from "./recall.js";
 export { redact } from "./redact.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
-export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";

package/dist/jev.d.ts

@@ -0,0 +1,23 @@
+import type { Evaluation, IntegrationErrorCode, Questions, SystemOneRequest, TypeSafe } from "pi-typesafe";
+/** Anything with pi-typesafe's `evaluate`: the real client in a session, a stub in tests. */
+export type Judge = Pick<TypeSafe, "evaluate">;
+export interface AskOptions {
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export type JevAnswer<Q extends Questions> = {
+    ok: true;
+    answers: Evaluation<Q>["answers"];
+    model: string;
+    elapsedMs: number;
+} | {
+    ok: false;
+    error: string;
+    errorCode?: IntegrationErrorCode;
+};
+/**
+ * One Jev request with the per-guard timeout merged into the caller's abort signal. Never throws: a failure comes back as
+ * `{ ok: false }` with pi-typesafe's own message (which carries no upstream body) and its code, so the caller can stop
+ * asking after a `budget` error. Unknown errors get a fixed message so nothing from the transport reaches the user.
+ */
+export declare function askJev<Q extends Questions>(judge: Judge, request: SystemOneRequest<Q>, options: AskOptions): Promise<JevAnswer<Q>>;

package/dist/jev.js

@@ -0,0 +1,19 @@
+import { TypeSafeIntegrationError } from "pi-typesafe";
+const FALLBACK_MESSAGE = "TypeSafe request failed.";
+/**
+ * One Jev request with the per-guard timeout merged into the caller's abort signal. Never throws: a failure comes back as
+ * `{ ok: false }` with pi-typesafe's own message (which carries no upstream body) and its code, so the caller can stop
+ * asking after a `budget` error. Unknown errors get a fixed message so nothing from the transport reaches the user.
+ */
+export async function askJev(judge, request, options) {
+    const timeout = AbortSignal.timeout(options.timeoutMs);
+    try {
+        const result = await judge.evaluate(request, { signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout });
+        return { ok: true, answers: result.answers, model: result.model, elapsedMs: result.elapsedMs };
+    }
+    catch (error) {
+        if (error instanceof TypeSafeIntegrationError)
+            return { ok: false, error: error.message, errorCode: error.code };
+        return { ok: false, error: FALLBACK_MESSAGE };
+    }
+}