pi-warden 0.8.0 → 0.9.0

package/dist/config.js

@@ -9,7 +9,7 @@ export function isRecallTool(value) {
 }
 export const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export const CONFIG_SCHEMA = 4;
+export const CONFIG_SCHEMA = 5;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -30,6 +30,7 @@ export function defaultConfig() {
         done: { enabled: true, claimsDone: 0.7, nudge: true },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7 },
+        rules: { enabled: true, threshold: 0.7, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
         context: { enabled: true, tailMinChars: 12000, confidence: 0.8, duplicateMinChars: 2000, recallTool: "auto", formatConfidence: 0.7 },
         runaway: { enabled: true, repeats: 4, thinkingRepeats: 10, minChars: 400, recover: true },
         notify: { enabled: true, cooldownMs: 10000, command: [] },
@@ -148,6 +149,26 @@ function applySlop(base, raw) {
     // 0.2.x used `placeholder` for the stub threshold; it still sets the shared threshold.
     return { enabled: boolean(raw.enabled, base.enabled), threshold: probability(raw.threshold ?? raw.placeholder, base.threshold), prose: applyProse(base.prose, raw.prose) };
 }
+function globList(value, fallback) {
+    return Array.isArray(value) ? value.filter((glob) => typeof glob === "string" && glob.trim().length > 0).map(glob => glob.trim()) : fallback;
+}
+function applyRules(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const notes = isObject(raw.sensitivePaths)
+        ? Object.fromEntries(Object.entries(raw.sensitivePaths).filter((entry) => entry[0].trim().length > 0 && typeof entry[1] === "string" && entry[1].trim().length > 0))
+        : base.sensitivePaths;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        threshold: probability(raw.threshold, base.threshold),
+        files: globList(raw.files, base.files),
+        fallback: boolean(raw.fallback, base.fallback),
+        maxChars: Math.max(500, positiveInteger(raw.maxChars, base.maxChars)),
+        exclude: globList(raw.exclude, base.exclude),
+        skip: globList(raw.skip, base.skip),
+        sensitivePaths: notes,
+    };
+}
 function applyWidget(base, raw) {
     if (!isObject(raw))
         return base;
@@ -165,6 +186,7 @@ function applyWidget(base, raw) {
         security: template(raw.security, base.security),
         context: template(raw.context, base.context),
         runaway: template(raw.runaway, base.runaway),
+        rules: template(raw.rules, base.rules),
     };
 }
 /** Shared request settings; `action.timeoutMs`/`action.maxRequests` from 0.1.x files are still honoured. */
@@ -177,6 +199,7 @@ function applyShared(base, raw) {
 }
 function applyGuards(base, raw, timeoutMs, source) {
     return {
+        rules: applyRules(base.rules, raw.rules),
         runaway: applyRunaway(base.runaway, raw.runaway),
         // A project file may switch notifications off or on, but never names a command to run.
         notify: applyNotify(base.notify, raw.notify, source === "user"),

package/dist/extension.d.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ToolCallRef } from "./action-guard.js";
 import type { SlopSymptom, Verdict } from "./guard.js";
-export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; 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.";
+export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 /**
  * Tool calls of the assistant message being preflighted. Pi runs `tool_call` hooks for sibling calls one after another,
  * so judging them one request at a time costs one round trip per call; judging them together costs one round trip.

package/dist/extension.js

@@ -10,18 +10,19 @@ import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
 import { compressOutput, duplicateNote, evaluateOutput, outputKey, saveOutput, securityNotice } from "./output.js";
 import { classifyRecall, detectSearchTool, recallInstruction } from "./recall.js";
 import { redact } from "./redact.js";
+import { formatRules, pathNoteSteer, RulesGuard, rulesSteer } from "./rules.js";
 import { detectNotifier, sendNotification } from "./notify.js";
 import { formatRunaway, RunawayMonitor, runawayNudge } from "./runaway.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
 import { openTracePanel } from "./panel.js";
 import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
-import { actionDetails, doneDetails, proseDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
+import { actionDetails, doneDetails, proseDetails, rulesDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
 import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
-export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; 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.";
+export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 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, runaway: 0, errors: 0 });
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, ruleChecks: 0, ruleViolations: 0, pathNotes: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, runaway: 0, errors: 0 });
 function latestUserPrompt(ctx) {
     const entries = ctx.sessionManager.getBranch();
     for (let index = entries.length - 1; index >= 0; index--) {
@@ -124,6 +125,7 @@ export default function wardenExtension(pi) {
     let panel;
     let lastUi;
     const actionGuard = new ActionGuard();
+    const rulesGuard = new RulesGuard();
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
@@ -230,6 +232,7 @@ export default function wardenExtension(pi) {
         trace.clear();
         panel?.close();
         actionGuard.reset();
+        rulesGuard.reset();
         attempts.reset();
         evidence = emptyEvidence();
         doneNudged = false;
@@ -254,6 +257,7 @@ export default function wardenExtension(pi) {
         runawayStops = 0;
         pendingRunaway = undefined;
         actionGuard.turnEnd();
+        rulesGuard.turnEnd();
     });
     // Each assistant message is judged on its own; Pi does not forward the stream's own "start" event, so this is the reset.
     pi.on("message_start", async (event) => {
@@ -291,6 +295,7 @@ export default function wardenExtension(pi) {
     pi.on("turn_end", async () => {
         ledger.turnEnd();
         actionGuard.turnEnd();
+        rulesGuard.turnEnd();
     });
     pi.on("tool_call", async (event, ctx) => {
         const config = configFor(ctx);
@@ -311,9 +316,18 @@ export default function wardenExtension(pi) {
         stats.inspected++;
         const task = latestUserPrompt(ctx);
         const judge = judgeFor(config);
-        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 });
+        const siblings = siblingToolCalls(ctx);
+        const call = { id: event.toolCallId, tool: event.toolName, input: event.input };
+        // The rules request carries the written content and the rule text, so it goes out beside the action request, not inside it.
+        const rulesCheck = config.rules.enabled && (event.toolName === "write" || event.toolName === "edit")
+            ? rulesGuard.inspect(call, siblings, { cwd: ctx.cwd, config: config.rules, judge, timeoutMs: config.timeoutMs, signal: ctx.signal })
+            : undefined;
+        rulesCheck?.catch(() => undefined);
+        const verdict = await actionGuard.inspect(call, { task, context: recentTaskContext(ctx), siblings }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security });
         if (verdict.source === "skipped")
             return;
+        // Notes for the agent about the content it just wrote: slop, rule violations, and sensitive paths arrive as one message.
+        const notes = [];
         if (verdict.judgment?.securityRisk !== undefined && verdict.judgment.securityRisk >= config.security.threshold) {
             steer(config, "pi-warden: the proposed write may introduce a security weakness. Check for embedded credentials, disabled TLS, unsafe command/SQL interpolation, broad permissions, or bypassed verification; use a safe implementation instead.");
         }
@@ -334,8 +348,35 @@ export default function wardenExtension(pi) {
             const where = verdict.summary.path ?? event.toolName;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · slop · ${where}: ${verdict.slopReasons.join("; ")}`, "warning");
-            steer(config, slopSteer(where, verdict.slopSymptoms, slopCounts));
+            notes.push(slopSteer(where, verdict.slopSymptoms, slopCounts));
+        }
+        if (rulesCheck) {
+            const rules = await rulesCheck;
+            if (rules.source !== "skipped") {
+                stats.ruleChecks++;
+                if (rules.error)
+                    noteError(ctx, rules.error, rules.errorCode);
+                const told = rules.findings.length ? rulesSteer(rules, rulesGuard.count(rules)) : undefined;
+                record(ctx, config, "rules", formatRules(rules, config.widget.rules), rulesDetails(rules, told));
+                if (told) {
+                    stats.ruleViolations++;
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`warden · rules · ${rules.path}: ${rules.findings.map(finding => `${finding.name} (${finding.violation.toFixed(2)})`).join("; ")}`, "warning");
+                    notes.push(told);
+                }
+            }
+            const hits = rulesGuard.notesFor(verdict.summary.location === "inside_project" ? verdict.summary.path : undefined, config.rules.sensitivePaths);
+            if (hits.length && verdict.summary.path) {
+                stats.pathNotes++;
+                const told = pathNoteSteer(verdict.summary.path, hits);
+                record(ctx, config, "rules", renderTemplate(config.widget.rules, { tool: event.toolName, path: verdict.summary.path, violations: `sensitive path ${hits.map(hit => hit.glob).join(", ")}`, status: "note" }), [`${event.toolName} ${verdict.summary.path} matches ${hits.map(hit => hit.glob).join(", ")} in rules.sensitivePaths`, `agent told: ${told}`]);
+                if (ctx.hasUI)
+                    ctx.ui.notify(`warden · sensitive path · ${verdict.summary.path} (${hits.map(hit => hit.glob).join(", ")}); the agent was given the note`, "warning");
+                notes.push(told);
+            }
         }
+        if (notes.length)
+            steer(config, notes.join("\n\n"));
         if (verdict.level === "warn") {
             stats.warned++;
             if (ctx.hasUI)
@@ -578,12 +619,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", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`, config.security.enabled && "security", config.context.enabled && "context", config.runaway.enabled && "runaway", config.notify.enabled && "desktop notifications"].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.rules.enabled && "rules", config.context.enabled && "context", config.runaway.enabled && "runaway", config.notify.enabled && "desktop notifications"].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.runaway} runaway stops, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
-                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; runaway ${config.runaway.repeats} repeats (thinking ${config.runaway.thinkingRepeats}), recover ${config.runaway.recover}; failOpen ${config.action.failOpen}.`,
+                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.ruleViolations}/${stats.ruleChecks} rule violations, ${stats.pathNotes} sensitive-path notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.runaway} runaway stops, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
+                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, rules ${config.rules.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; runaway ${config.runaway.repeats} repeats (thinking ${config.runaway.thinkingRepeats}), recover ${config.runaway.recover}; failOpen ${config.action.failOpen}.`,
                         formatLedger(ledger.snapshot()),
+                        `Rules: ${config.rules.enabled ? `${rulesGuard.describe(ctx.cwd, config.rules)}${Object.keys(config.rules.sensitivePaths).length ? `; ${Object.keys(config.rules.sensitivePaths).length} sensitive path${Object.keys(config.rules.sensitivePaths).length === 1 ? "" : "s"}` : ""}` : "off"}.`,
                         `Desktop notifications: ${config.notify.enabled ? `on (${config.notify.command.length ? `command ${config.notify.command[0]}` : (await (notifier ??= detectNotifier())) ?? "no notifier found on this machine"}; cooldown ${config.notify.cooldownMs} ms)` : "off"}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
                         widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",

package/dist/guard.d.ts

@@ -37,6 +37,8 @@ export interface ActionSummary {
         newText: string;
     }>;
     input?: string;
+    /** Present when part of the command is data (a heredoc body, a quoted message), so a destructive string inside it is payload. */
+    dataText?: string;
 }
 export type ScopeLabel = "expected_step" | "plausible_side_step" | "unrelated" | "unclear";
 export interface Judgment {
@@ -91,6 +93,17 @@ export interface EvaluateOptions {
     /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
     retryAfterHold?: boolean | undefined;
 }
+export interface ScannedCommand {
+    /** The command with data text blanked; what the pattern rules read. */
+    text: string;
+    /** True when a heredoc body or quoted data was removed. */
+    stripped: boolean;
+}
+/**
+ * Removes heredoc bodies that are not fed to a shell and quoted arguments of data commands. Interpreter heredocs
+ * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
+ */
+export declare function stripDataText(command: string): ScannedCommand;
 export declare function matchPatterns(tool: string, input: Record<string, unknown>, cwd?: string): PatternHit[];
 export declare function isReadOnlyCommand(command: string): boolean;
 export declare function describeAction(tool: string, input: Record<string, unknown>, cwd: string): ActionSummary;

package/dist/guard.js

@@ -52,12 +52,123 @@ const SENSITIVE_PATH = /(?:^|[\s/"'=:(])\.env(?:\.(?!example\b|sample\b|template
 function splitShell(command) {
     return command.split(/\n|;|&&|\|\||\||&/).map(part => part.trim()).filter(Boolean);
 }
-/** rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are risky. */
+// ---------------------------------------------------------------------------
+// Data text: a heredoc body written to a file, a quoted message, or a search pattern is not a command. Pattern rules skip
+// it so a test fixture or a commit message that mentions `git push --force` is not held. A shell sink anywhere in the
+// command (sh, eval, bash -c, command substitution) keeps every byte in scope, because the payload is executed.
+const WRAPPERS = new Set(["sudo", "nohup", "time", "env", "command", "builtin", "exec", "nice", "timeout", "doas"]);
+const SHELL_SINKS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "eval", "source", ".", "xargs", "su"]);
+/** Commands whose quoted arguments are text they print, search, or record. */
+const DATA_HEADS = new Set(["echo", "printf", "grep", "egrep", "fgrep", "rg", "ag", "ugrep", "jq", "cat", "tee", "head", "tail", "wc", "sort", "uniq", "cut", "tr", "less", "more", "test", "["]);
+const GIT_MESSAGE_SUBCOMMANDS = new Set(["commit", "tag", "notes", "merge", "stash"]);
+/** Interpreters whose stdin script can still run shell commands; their heredoc bodies stay in scope when they do. */
+const INTERPRETERS = /^(?:python[\d.]*|node|ruby|perl|php|deno|bun|tsx|Rscript|lua[\d.]*)$/;
+const EXEC_CALLS = /\b(?:os\.system|os\.popen|os\.exec\w*|subprocess|child_process|execSync|spawnSync|execFileSync|spawn\(|exec\(|system\(|popen\(|shell_exec|passthru|proc_open|Open3|IO\.popen|Deno\.run|Deno\.Command|Bun\.spawn|Bun\.\$|%x[\[{(]|`[^`\n]*\b(?:rm|git|dd|mkfs|kubectl|terraform)\b)/;
+const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|\\?(\w+))/;
+function headOf(segment) {
+    const tokens = segment.trim().split(/\s+/);
+    let index = 0;
+    while (index < tokens.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index]) || WRAPPERS.has(tokens[index])))
+        index++;
+    const head = tokens[index];
+    return head ? head.replace(/^.*\//, "") : undefined;
+}
+/** Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything. */
+function blankQuotes(segment) {
+    let out = "";
+    for (let index = 0; index < segment.length; index++) {
+        const char = segment[index];
+        if (char !== "'" && char !== "\"") {
+            out += char;
+            continue;
+        }
+        let end = index + 1;
+        while (end < segment.length && segment[end] !== char)
+            end += char === "\"" && segment[end] === "\\" ? 2 : 1;
+        if (end >= segment.length) {
+            out += segment.slice(index);
+            break;
+        }
+        out += `${char}[text]${char}`;
+        index = end;
+    }
+    return out;
+}
+function isDataSegment(segment) {
+    const head = headOf(segment);
+    if (!head)
+        return false;
+    if (head === "git") {
+        const sub = segment.trim().split(/\s+/).find(token => !token.startsWith("-") && token !== "git" && !WRAPPERS.has(token));
+        return sub !== undefined && GIT_MESSAGE_SUBCOMMANDS.has(sub) && !/\s-c\s|--config/.test(segment);
+    }
+    if (head === "gh")
+        return /\s--(?:body|title|notes)\b/.test(segment) || /\s-[bt]\s/.test(segment);
+    return DATA_HEADS.has(head);
+}
+/**
+ * Removes heredoc bodies that are not fed to a shell and quoted arguments of data commands. Interpreter heredocs
+ * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
+ */
+export function stripDataText(command) {
+    if (/\$\(|`/.test(command))
+        return { text: command, stripped: false };
+    const lines = command.split("\n");
+    const out = [];
+    let stripped = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const heredoc = HEREDOC.exec(line);
+        if (!heredoc) {
+            out.push(line);
+            continue;
+        }
+        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[3];
+        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const body = [];
+        let close = index + 1;
+        while (close < lines.length && lines[close].replace(/^\t+/, "") !== delimiter)
+            body.push(lines[close]), close++;
+        const bodyText = body.join("\n");
+        const executed = SHELL_SINKS.has(consumer) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText));
+        out.push(line);
+        if (executed)
+            out.push(...body);
+        else if (body.length) {
+            out.push(`[heredoc body: ${body.length} lines of data]`);
+            stripped = true;
+        }
+        if (close < lines.length)
+            out.push(lines[close]);
+        index = close;
+    }
+    const joined = out.join("\n");
+    const segments = splitShell(joined);
+    if (segments.some(segment => { const head = headOf(segment); return head !== undefined && SHELL_SINKS.has(head); }))
+        return { text: joined, stripped };
+    if (/\b(?:ba|z|da|k)?sh\s+-[a-zA-Z]*c\b/.test(joined))
+        return { text: joined, stripped };
+    let text = joined;
+    for (const segment of segments) {
+        if (!isDataSegment(segment) || !/["']/.test(segment))
+            continue;
+        const blanked = blankQuotes(segment);
+        if (blanked === segment)
+            continue;
+        text = text.replace(segment, blanked);
+        stripped = true;
+    }
+    return { text, stripped };
+}
+/**
+ * rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are
+ * risky. A quote before `rm` is allowed so `bash -c "rm -rf /"` is read; data quotes were blanked before this runs.
+ */
 function classifyRm(segment, cwd) {
-    const match = /(?:^|\s)rm\s+(.*)$/.exec(segment);
+    const match = /(?:^|[\s"'])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
-    const tokens = match[1].split(/\s+/).filter(Boolean);
+    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["']$/, ""));
     const flags = tokens.filter(token => token.startsWith("-"));
     const targets = tokens.filter(token => !token.startsWith("-"));
     const recursive = flags.some(flag => flag === "--recursive" || (/^-[a-zA-Z]+$/.test(flag) && /[rR]/.test(flag)));
@@ -86,8 +197,9 @@ 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 = commandOf(tool, input)?.command;
-    if (command) {
+    const raw = commandOf(tool, input)?.command;
+    if (raw) {
+        const command = stripDataText(raw).text;
         for (const rule of SHELL_RULES)
             if (rule.test.test(command))
                 add({ id: rule.id, severity: rule.severity, label: rule.label });
@@ -174,8 +286,12 @@ function displayPath(target, cwd) {
 export function describeAction(tool, input, cwd) {
     const summary = { tool };
     const view = commandOf(tool, input);
-    if (view)
+    if (view) {
         summary.command = redact(truncate(view.command, COMMAND_LIMIT));
+        // Jev sees the full text; this names the part of it that is written or printed rather than executed.
+        if (stripDataText(view.command).stripped)
+            summary.dataText = "heredoc bodies and quoted arguments of echo/printf/grep/git commit in this command are text that is written, printed, searched, or recorded, not executed";
+    }
     if (typeof input.path === "string" && input.path.trim() && tool !== "ctx_execute_file") {
         const shown = displayPath(input.path, cwd);
         summary.path = shown.path;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScannedCommand, ScopeLabel, Severity, Verdict } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.js";
@@ -25,10 +25,12 @@ export { ContextLedger, formatLedger } from "./saver.js";
 export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, RunawayConfig, NotifyConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, RulesConfig, ContextConfig, RunawayConfig, NotifyConfig, 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, runawayTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
 export type { WidgetConfig, WidgetPlacement, Tokens } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails } from "./trace.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";
+export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef } from "./rules.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, 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";
@@ -14,5 +14,6 @@ export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
-export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails } from "./trace.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
+export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";

package/dist/panel.js

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error", stopped: "error", "stopped, recovering": "error" };
+const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error", stopped: "error", "stopped, recovering": "error", violation: "warning", skipped: "muted" };
 /**
  * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
  * keeps working while it is visible. A click inside it (fullscreen mode) focuses it; then ↑/↓/j/k scroll a line,

package/dist/rules.d.ts

@@ -0,0 +1,164 @@
+import type { IntegrationErrorCode } from "pi-typesafe";
+import type { RulesConfig } from "./config.js";
+import type { Judge } from "./jev.js";
+/**
+ * Project rules: Markdown headings become rules, Jev judges each write or edit against every rule on its own request, and the
+ * agent is steered, never held, with the violated rule. Path scoping and sensitive-path notes are code only.
+ *
+ * Sources, in order: `pi-warden.md` at the project root; else the files in `rules.files`; else, with `rules.fallback`, the
+ * first of README.md, CLAUDE.md, AGENTS.md as one aggregate rule set. Files are re-read when their mtime or size changes.
+ */
+export interface Rule {
+    id: string;
+    name: string;
+    /** Rule text under the heading, fences included, `paths:` line removed. */
+    body: string;
+    /** Globs the rule applies to; empty means every file. */
+    paths: string[];
+}
+export interface RuleSet {
+    /** Project-relative file names the rules came from. */
+    sources: string[];
+    rules: Rule[];
+    /** Fallback documents have no rule headings: one question judges the content against this whole text. */
+    aggregate?: string;
+    /** Rules past the request cap, dropped in file order. */
+    dropped: number;
+}
+export declare const RULES_FILE = "pi-warden.md";
+export declare const FALLBACK_FILES: string[];
+/** TypeSafe answers at most 32 questions per request; one is kept for the edit locator. */
+export declare const MAX_RULES = 31;
+/**
+ * A fallback document cut to `limit` characters while keeping its shape: every heading stays and each section keeps its
+ * head, so a rule stated in the last section of a very long AGENTS.md is still seen. Code inside fences is treated as text.
+ */
+export declare function condense(text: string, limit: number): string;
+/**
+ * Headings at the highest level present outside code fences delimit rules (`#` in a jev-rules style file, `##` under a
+ * document title). Text before the first such heading is not a rule. A `paths:` line at the top of a body scopes the rule.
+ */
+export declare function parseRules(markdown: string): Rule[];
+export declare function globToRegExp(pattern: string): RegExp;
+/** The first pattern that matches the path, or undefined. */
+export declare function matchGlob(path: string, patterns: readonly string[]): string | undefined;
+/** Project-relative path with forward slashes, or undefined when the target lies outside the project. */
+export declare function projectPath(target: string, cwd: string): string | undefined;
+export declare class RuleStore {
+    private readonly cache;
+    private read;
+    /** The active rule set for a project, or undefined when no source exists. Never throws. */
+    load(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): RuleSet | undefined;
+}
+/** Rules that apply to a path: unscoped rules plus those whose `paths` match. */
+export declare function rulesFor(set: RuleSet, path: string): Rule[];
+export declare function describeRuleSet(set: RuleSet | undefined): string;
+export interface EditView {
+    id: string;
+    /** Current file text around the replaced text, when the file exists and the text was found. */
+    before?: string;
+    newText: string;
+}
+export interface RulesTarget {
+    tool: "write" | "edit";
+    /** Project-relative path. */
+    path: string;
+    content?: string;
+    edits?: EditView[];
+    /** Edits beyond MAX_EDITS, not shown. */
+    moreEdits?: number;
+}
+/** The redacted content of a write or edit as Jev sees it, or undefined when the call carries nothing to judge. */
+export declare function describeTarget(tool: string, input: Record<string, unknown>, cwd: string): RulesTarget | undefined;
+export type RuleOutcome = "compliant" | "violation" | "not_applicable" | "insufficient_context";
+export declare const AGGREGATE_QUESTION = "rules";
+export declare const LOCATOR_QUESTION = "which_edit";
+export declare function ruleQuestion(rule: Rule): import("pi-typesafe").ChoiceQuestion<Record<RuleOutcome, string>>;
+export declare function buildRulesRequest(target: RulesTarget, set: RuleSet): {
+    state: {
+        rules?: string;
+        moreEdits?: number;
+        edits?: {
+            newText: string;
+            before?: string;
+            id: string;
+        }[];
+        content?: string;
+        path: string;
+    };
+    questions: Record<string, import("pi-typesafe").ChoiceQuestion<import("@typesafe-ai/sdk").ChoiceCriteria>>;
+    applicable: Rule[];
+};
+export interface RuleScore {
+    id: string;
+    name: string;
+    outcome: RuleOutcome;
+    violation: number;
+}
+export interface RuleFinding extends RuleScore {
+    body: string;
+}
+export interface RulesVerdict {
+    source: "skipped" | "typesafe" | "error";
+    path: string;
+    tool: "write" | "edit";
+    sources: string[];
+    /** Rules asked about, after path scoping; 1 for an aggregate document. */
+    asked: number;
+    aggregate: boolean;
+    scores?: RuleScore[];
+    /** Violations at or above the threshold, strongest first. */
+    findings: RuleFinding[];
+    /** The edit Jev points at when several edits were judged and something was flagged. */
+    editId?: string;
+    editPreview?: string;
+    model?: string;
+    elapsedMs?: number;
+    skippedReason?: string;
+    error?: string;
+    errorCode?: IntegrationErrorCode;
+}
+export interface RulesOptions {
+    cwd: string;
+    config: RulesConfig;
+    set: RuleSet | undefined;
+    judge?: Judge | undefined;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+/** Why a write or edit is not judged against the rules: nothing to judge, no rules, or a path the config keeps out. */
+export declare function skipReason(target: RulesTarget | undefined, set: RuleSet | undefined, config: RulesConfig): string | undefined;
+export declare function evaluateRules(tool: string, input: Record<string, unknown>, options: RulesOptions): Promise<RulesVerdict>;
+/** Names each violated rule with a short quote of its text; the third hit of one rule in a session makes it a standing rule. */
+export declare function rulesSteer(verdict: RulesVerdict, counts: ReadonlyMap<string, number>): string;
+export declare function formatRules(verdict: RulesVerdict, template?: string): string;
+export interface PathNote {
+    glob: string;
+    note: string;
+}
+export declare function pathNotes(path: string | undefined, notes: Readonly<Record<string, string>>): PathNote[];
+export declare function pathNoteSteer(path: string, hits: readonly PathNote[]): string;
+export interface RulesCallRef {
+    id: string;
+    tool: string;
+    input: Record<string, unknown>;
+}
+/**
+ * The Rules guard for one session: loads and caches the rule sources, judges each write or edit on its own request (fired
+ * together with the action guard's), prejudges sibling writes so their requests overlap, and counts hits per rule so a repeat
+ * becomes a standing rule.
+ */
+export declare class RulesGuard {
+    readonly store: RuleStore;
+    private readonly prejudged;
+    private readonly counts;
+    private readonly noted;
+    inspect(call: RulesCallRef, siblings: readonly RulesCallRef[], options: Omit<RulesOptions, "set">): Promise<RulesVerdict>;
+    /** Records the findings and returns the per-rule session counts the steer text uses. */
+    count(verdict: RulesVerdict): ReadonlyMap<string, number>;
+    /** Sensitive-path notes not yet given for this path in this session. */
+    notesFor(path: string | undefined, notes: Readonly<Record<string, string>>): PathNote[];
+    describe(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): string;
+    turnEnd(): void;
+    reset(): void;
+}