pi-warden 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gapac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# pi-warden
+
+Harness guardrails for [Pi](https://pi.dev), built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe). Before the agent runs a `bash`, `write`, or `edit` call, pi-warden checks it twice: a fast offline pattern pass for the obvious hazards, then one TypeSafe (Jev) request that scores how **irreversible** and how **off-task** the action is relative to your latest request. High scores open a confirm dialog; you decide, and a declined call is blocked with a short reason the agent can act on.
+
+Independent project. Not affiliated with TypeSafe AI or the Pi authors.
+
+![Pi asking for confirmation before a destructive command, with pi-warden's irreversible and off-task scores in the dialog](https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png)
+
+## Install
+
+```bash
+pi install npm:pi-warden
+```
+
+Requires Pi 0.85 or newer and Node.js 22.19 or newer. Pattern checks work with no account. Jev judgments need a TypeSafe API key and are billed to your TypeSafe account (a judgment is roughly 600 input tokens; output is free).
+
+## Setup
+
+1. Get a key at [console.typesafe.ai](https://console.typesafe.ai) (API Keys).
+2. Run `/warden enable`. Read the data notice and confirm; if no key is configured yet, paste it at the hidden prompt. The key is verified against the API and saved to `~/.pi/agent/pi-typesafe/auth.json` with owner-only permissions, shared with [pi-typesafe](https://github.com/DevMortimer/pi-typesafe) and anything else built on it. Consent is saved to `~/.pi/agent/pi-warden/config.json`, so judgments stay on in every new session until you run `/warden disable`.
+3. Optionally run `/warden test` to see one synthetic verdict.
+
+A `TYPESAFE_API_KEY` environment variable takes precedence over the stored key. Without step 2, pi-warden still guards with offline pattern checks only.
+
+## What it does on each guarded call
+
+1. **Skip** read-only tools, and read-only shell lines such as `git status && ls` (no network, no widget).
+2. **Pattern pass** (offline): force pushes, `git reset --hard`, `git clean -f`, recursive `rm` on absolute/home/variable/parent paths, SQL `DROP`/`TRUNCATE`/`DELETE FROM`, block-device writes, `chmod -R 777`, fork bombs, `curl | sh`, `kill -1`, shutdown, package publishing, infrastructure destroys → **confirm**. `rm -rf` on a project path, `git checkout -- .`, `git branch -D`, `git stash drop`, `find -delete`, `sudo` → **warn**. Reads or writes of `.env`, SSH, AWS, npm, kube, and other credential files → **warn**. A `write` that overwrites an existing file outside the project → **confirm**; creating or editing outside the project → **warn**.
+3. **Jev judgment** (with consent): one request with the state `{ task, action }` and three questions — `irreversible` (Noul), `off_task` (Noul), `scope` (Choice: expected step, plausible side step, unrelated, unclear). Defaults: irreversible ≥ 0.5 warns, ≥ 0.7 confirms; off-task ≥ 0.6 warns, ≥ 0.85 with `unrelated` confirms. Pattern results set the floor; Jev can only raise it.
+4. **Act**: allow silently, warn with a notification, or ask with `ctx.ui.confirm`. The widget above the editor shows the last verdict, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`.
+
+Headless runs (`pi -p`, JSON mode) cannot ask, so a confirm-level call is **blocked** unless `PI_WARDEN_HEADLESS=allow` or `"headless": "allow"` is set. Consent in headless runs comes from `PI_WARDEN_ENABLED=1`.
+
+If TypeSafe cannot answer (timeout after 5 s, outage, budget), the call is allowed with a warning (`failOpen: true`). Set `failOpen` to `false` to ask instead. When the per-session request budget is spent, pi-warden says so once and continues with pattern checks.
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/warden status` | Guard state, consent source, key source, session counts, thresholds, config paths, last verdict |
+| `/warden enable` | Show the data notice, prompt for a key if none is stored, and save consent for Jev judgments |
+| `/warden disable` | Stop Jev judgments; pattern checks continue |
+| `/warden config` | Edit the user config JSON in Pi's editor and save it |
+| `/warden test` | Evaluate one synthetic destructive action and show the verdict |
+
+## Configuration
+
+User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use these defaults:
+
+```json
+{
+  "enabled": true,
+  "typesafe": false,
+  "headless": "block",
+  "action": {
+    "enabled": true,
+    "tools": ["bash", "write", "edit"],
+    "failOpen": true,
+    "timeoutMs": 5000,
+    "maxRequests": 500,
+    "irreversible": { "warn": 0.5, "confirm": 0.7 },
+    "offTask": { "warn": 0.6, "confirm": 0.85 }
+  }
+}
+```
+
+A project may add `.pi/pi-warden.json` with `enabled` and `action` overrides (for example stricter thresholds or extra guarded tools). Project files are read only when Pi trusts the project, and they can never grant `typesafe` consent or change `headless`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_HEADLESS=allow|block`.
+
+## Data handling
+
+- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 600-character content excerpt for `write`, and the first three edit pairs (200 characters each) for `edit`. No other files, history, or telemetry.
+- Obvious credentials in the action (`Authorization` headers, `TOKEN=`/`SECRET=` assignments, `sk-`, `ghp_`, `AKIA`, JWTs, URL passwords, PEM blocks) are replaced with `[redacted]` before sending. This is best-effort; do not rely on it for prompts that contain secrets.
+- The block reason returned to the agent names the tool and the reasons, not the command text. UI errors never include upstream response bodies or keys.
+- Judgments are model output. Thresholds are yours to tune; the dialog is the decision.
+
+## For extension authors
+
+The guard is a plain function you can call from your own extension or tests, with any object that has pi-typesafe's `evaluate` method as the judge:
+
+```ts
+import { evaluateAction, defaultConfig } from "pi-warden";
+import { createTypeSafe } from "pi-typesafe";
+
+const verdict = await evaluateAction(
+  { tool: "bash", input: { command: "git push --force" }, cwd: process.cwd(), task: "push my branch" },
+  { config: defaultConfig().action, judge: createTypeSafe() },   // omit judge for pattern checks only
+);
+verdict.level;      // "allow" | "warn" | "confirm"
+verdict.reasons;    // ["destructive: git force push", "irreversible 0.91"]
+verdict.judgment;   // { irreversible, offTask, scope, scopeConfidence, model, elapsedMs }
+```
+
+Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`, `formatVerdict`, `questions`, and the config helpers.
+
+## Development
+
+```bash
+npm install
+npm run check        # typecheck, offline tests (mocked transport), build
+npm run test:live    # nine billable synthetic judgments against api.typesafe.ai (key from .env or the stored login)
+npm run dev:pi       # start Pi with this working tree plus an installed pi-typesafe
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+export interface Threshold {
+    /** P(yes) at or above this shows a warning and continues. */
+    warn: number;
+    /** P(yes) at or above this asks the user before the tool runs. */
+    confirm: number;
+}
+export interface ActionGuardConfig {
+    enabled: boolean;
+    /** Tool names inspected before execution. Read-only tools are skipped to keep latency low. */
+    tools: string[];
+    /** When TypeSafe cannot answer (timeout, outage, budget), allow the call with a warning instead of asking. */
+    failOpen: boolean;
+    /** Per-request TypeSafe timeout. The call is judged as an error after this. */
+    timeoutMs: number;
+    /** Maximum TypeSafe requests per session for this guard. */
+    maxRequests: number;
+    irreversible: Threshold;
+    offTask: Threshold;
+}
+export interface WardenConfig {
+    /** Master switch. false disables every guard, including offline pattern checks. */
+    enabled: boolean;
+    /** Consent to send task and action summaries to api.typesafe.ai. Set by /warden enable; never by a project file. */
+    typesafe: boolean;
+    /** Decision when confirmation is required and no UI can ask. PI_WARDEN_HEADLESS overrides it. */
+    headless: "block" | "allow";
+    action: ActionGuardConfig;
+}
+export declare const PACKAGE_NAME = "pi-warden";
+export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
+export declare function defaultConfig(): WardenConfig;
+/** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
+export declare function userConfigPath(): string;
+export declare function projectConfigPath(cwd: string): string;
+type Json = Record<string, unknown>;
+/** Unknown keys and invalid values fall back to the base; nothing throws on a malformed file. */
+export declare function applyUserOverrides(base: WardenConfig, raw: unknown): WardenConfig;
+/** Project files may tune the guard but cannot grant TypeSafe consent or change headless policy. */
+export declare function applyProjectOverrides(base: WardenConfig, raw: unknown): WardenConfig;
+export interface LoadOptions {
+    cwd?: string;
+    /** Project overrides are applied only when the caller vouches for the project (Pi's trust decision). */
+    projectTrusted?: boolean;
+}
+export declare function loadConfig(options?: LoadOptions): WardenConfig;
+/** Reads only the user file, for editing and persisting consent. */
+export declare function readUserConfig(): Json;
+export declare function writeUserConfig(raw: Json): string;
+/** Persists one top-level user setting without disturbing the rest of the file. */
+export declare function setUserSetting(key: "typesafe" | "enabled" | "headless", value: boolean | "block" | "allow"): string;
+export {};

package/dist/config.js

@@ -0,0 +1,114 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const PACKAGE_NAME = "pi-warden";
+export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
+export function defaultConfig() {
+    return {
+        enabled: true,
+        typesafe: false,
+        headless: "block",
+        action: {
+            enabled: true,
+            tools: ["bash", "write", "edit"],
+            failOpen: true,
+            timeoutMs: 5000,
+            maxRequests: 500,
+            irreversible: { warn: 0.5, confirm: 0.7 },
+            offTask: { warn: 0.6, confirm: 0.85 },
+        },
+    };
+}
+/** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
+export function userConfigPath() {
+    const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+    const agentDir = configured
+        ? (configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured)
+        : join(homedir(), ".pi", "agent");
+    return join(agentDir, PACKAGE_NAME, "config.json");
+}
+export function projectConfigPath(cwd) {
+    return join(cwd, ".pi", PROJECT_CONFIG_FILE);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function probability(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : fallback;
+}
+function threshold(value, fallback) {
+    if (!isObject(value))
+        return fallback;
+    const warn = probability(value.warn, fallback.warn);
+    const confirm = probability(value.confirm, fallback.confirm);
+    return { warn: Math.min(warn, confirm), confirm };
+}
+function boolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+function applyAction(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const tools = Array.isArray(raw.tools) ? raw.tools.filter((tool) => typeof tool === "string" && tool.trim().length > 0) : base.tools;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        tools,
+        failOpen: boolean(raw.failOpen, base.failOpen),
+        timeoutMs: positiveInteger(raw.timeoutMs, base.timeoutMs),
+        maxRequests: positiveInteger(raw.maxRequests, base.maxRequests),
+        irreversible: threshold(raw.irreversible, base.irreversible),
+        offTask: threshold(raw.offTask, base.offTask),
+    };
+}
+/** Unknown keys and invalid values fall back to the base; nothing throws on a malformed file. */
+export function applyUserOverrides(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        typesafe: boolean(raw.typesafe, base.typesafe),
+        headless: raw.headless === "allow" || raw.headless === "block" ? raw.headless : base.headless,
+        action: applyAction(base.action, raw.action),
+    };
+}
+/** Project files may tune the guard but cannot grant TypeSafe consent or change headless policy. */
+export function applyProjectOverrides(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return { ...base, enabled: boolean(raw.enabled, base.enabled), action: applyAction(base.action, raw.action) };
+}
+export function loadConfig(options = {}) {
+    let config = applyUserOverrides(defaultConfig(), readJson(userConfigPath()));
+    if (options.cwd && options.projectTrusted)
+        config = applyProjectOverrides(config, readJson(projectConfigPath(options.cwd)));
+    return config;
+}
+/** Reads only the user file, for editing and persisting consent. */
+export function readUserConfig() {
+    return readJson(userConfigPath()) ?? {};
+}
+export function writeUserConfig(raw) {
+    const path = userConfigPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(raw, null, 2)}\n`, { mode: 0o600, flag: "w" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+    return path;
+}
+/** Persists one top-level user setting without disturbing the rest of the file. */
+export function setUserSetting(key, value) {
+    return writeUserConfig({ ...readUserConfig(), [key]: value });
+}

package/dist/extension.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare 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.";
+/** Native Pi registration; importing the root library does not load this module. */
+export default function wardenExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -0,0 +1,205 @@
+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.";
+const WIDGET = PACKAGE_NAME;
+const CONFIRM_TEXT_LIMIT = 500;
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, confirmed: 0, blocked: 0, errors: 0 });
+function latestUserPrompt(ctx) {
+    const entries = ctx.sessionManager.getBranch();
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry?.type !== "message" || entry.message.role !== "user")
+            continue;
+        const content = entry.message.content;
+        if (typeof content === "string")
+            return content;
+        return content.filter((part) => part.type === "text").map(part => part.text).join("\n");
+    }
+    return undefined;
+}
+function headlessPolicy(config) {
+    const env = process.env.PI_WARDEN_HEADLESS?.trim();
+    return env === "allow" || env === "block" ? env : config.headless;
+}
+function clip(text) {
+    return text.length <= CONFIRM_TEXT_LIMIT ? text : `${text.slice(0, CONFIRM_TEXT_LIMIT)}…`;
+}
+function confirmMessage(verdict) {
+    const { summary } = verdict;
+    const lines = [];
+    if (summary.command !== undefined)
+        lines.push(clip(summary.command));
+    if (summary.path !== undefined)
+        lines.push(`${summary.tool} ${summary.path}${summary.location === "outside_project" ? " (outside the project)" : ""}${summary.exists === false ? " (new file)" : ""}`);
+    if (summary.input !== undefined)
+        lines.push(clip(summary.input));
+    lines.push("", `Why: ${verdict.reasons.join("; ")}`);
+    if (verdict.judgment)
+        lines.push(`Jev: irreversible ${verdict.judgment.irreversible.toFixed(2)}, off-task ${verdict.judgment.offTask.toFixed(2)}, ${verdict.judgment.scope.replace(/_/g, " ")} (${verdict.judgment.model}, ${verdict.judgment.elapsedMs} ms)`);
+    lines.push("Judgments are model output, not authorization. Yes runs the tool; No blocks it and tells the agent.");
+    return lines.join("\n");
+}
+/** 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 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 });
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        client = undefined;
+        budgetExhausted = false;
+        stats = freshStats();
+        lastVerdict = undefined;
+        if (ctx.hasUI)
+            ctx.ui.setWidget(WIDGET, undefined);
+    });
+    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;
+        if (verdict.judgment)
+            stats.judged++;
+        if (verdict.source === "error") {
+            stats.errors++;
+            if (verdict.errorCode === "budget")
+                budgetExhausted = true;
+            if (ctx.hasUI)
+                ctx.ui.notify(`warden: ${verdict.error}${budgetExhausted ? " Pattern checks continue without TypeSafe for the rest of this session." : ""}`, "warning");
+        }
+        if (ctx.hasUI && verdict.source !== "read-only")
+            ctx.ui.setWidget(WIDGET, [formatVerdict(verdict)]);
+        if (verdict.level === "warn") {
+            stats.warned++;
+            if (ctx.hasUI)
+                ctx.ui.notify(`warden · ${event.toolName}: ${verdict.reasons.join("; ")}`, "warning");
+            return undefined;
+        }
+        if (verdict.level !== "confirm")
+            return undefined;
+        stats.confirmed++;
+        const reasons = verdict.reasons.join("; ");
+        if (ctx.hasUI) {
+            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++;
+            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.` };
+    });
+    const actions = ["status", "enable", "disable", "config", "test"];
+    pi.registerCommand("warden", {
+        description: "pi-warden status, TypeSafe consent, 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 report = (text, level = "info") => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(text, level);
+                else
+                    pi.sendMessage({ customType: `${PACKAGE_NAME}-status`, content: text, display: true });
+            };
+            try {
+                const config = configFor(ctx);
+                if (action === "status") {
+                    const key = resolveApiKey();
+                    const source = consentSource(config);
+                    const usage = client?.getUsage();
+                    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)}.`,
+                        `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
+                        lastVerdict ? `Last: ${formatVerdict(lastVerdict)}` : "No guarded tool calls yet this session.",
+                    ].join(" "));
+                    return;
+                }
+                if (action === "enable") {
+                    if (!ctx.hasUI) {
+                        report("Consent needs an interactive session. For headless runs set PI_WARDEN_ENABLED=1 and TYPESAFE_API_KEY explicitly.", "warning");
+                        return;
+                    }
+                    if (!await ctx.ui.confirm("Enable TypeSafe judgments for pi-warden?", disclosure))
+                        return;
+                    // One flow: consent, then a key if none is configured yet (hidden input, verified, stored for every pi-typesafe consumer).
+                    const key = await ensureApiKey(ctx);
+                    if (!key) {
+                        report("No key entered; pi-warden stays on pattern checks only. Run /warden enable again when you have a key from console.typesafe.ai.", "warning");
+                        return;
+                    }
+                    const path = setUserSetting("typesafe", true);
+                    client = undefined;
+                    budgetExhausted = false;
+                    report(`TypeSafe judgments enabled and saved to ${path}${key.login ? `; key verified (${key.login.models} model${key.login.models === 1 ? "" : "s"}) and stored at ${key.login.path}` : ` using the ${key.source === "stored" ? "stored key" : "key from TYPESAFE_API_KEY"}`}. This stays on in new sessions until /warden disable.`);
+                    return;
+                }
+                if (action === "disable") {
+                    const path = setUserSetting("typesafe", false);
+                    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 === "config") {
+                    if (!ctx.hasUI) {
+                        report(`Edit ${userConfigPath()} directly. Defaults: ${JSON.stringify(defaultConfig())}`);
+                        return;
+                    }
+                    const current = readUserConfig();
+                    const seed = Object.keys(current).length ? current : { ...defaultConfig(), typesafe: config.typesafe };
+                    const text = await ctx.ui.editor(`pi-warden config · ${userConfigPath()}`, JSON.stringify(seed, null, 2));
+                    if (text === undefined)
+                        return;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(text);
+                    }
+                    catch {
+                        report("Invalid JSON; nothing was saved.", "error");
+                        return;
+                    }
+                    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                        report("The config must be a JSON object; nothing was saved.", "error");
+                        return;
+                    }
+                    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}.`);
+                    return;
+                }
+                if (action === "test") {
+                    const judge = judgeFor(config);
+                    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)]);
+                    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}` : ""}`);
+                    return;
+                }
+                report(`Unknown action "${action}". Use: ${actions.join(", ")}.`, "warning");
+            }
+            catch (error) {
+                report(error instanceof Error ? error.message : "pi-warden command failed.", "error");
+            }
+        },
+    });
+}

package/dist/guard.d.ts

@@ -0,0 +1,94 @@
+import type { IntegrationErrorCode, TypeSafe } from "pi-typesafe";
+import type { ActionGuardConfig } from "./config.js";
+export type Level = "allow" | "warn" | "confirm";
+export type Severity = "destructive" | "risky" | "sensitive";
+export interface PatternHit {
+    id: string;
+    severity: Severity;
+    /** Short human label; never contains the matched text. */
+    label: string;
+}
+export interface ActionInput {
+    tool: string;
+    input: Record<string, unknown>;
+    cwd: string;
+    /** Latest user request, used to judge whether the action is on task. */
+    task?: string | undefined;
+}
+/** Redacted, truncated view of a tool call. This object is what leaves the machine. */
+export interface ActionSummary {
+    tool: string;
+    command?: string;
+    path?: string;
+    location?: "inside_project" | "outside_project";
+    exists?: boolean;
+    bytes?: number;
+    excerpt?: string;
+    editCount?: number;
+    edits?: Array<{
+        oldText: string;
+        newText: string;
+    }>;
+    input?: string;
+}
+export type ScopeLabel = "expected_step" | "plausible_side_step" | "unrelated" | "unclear";
+export interface Judgment {
+    irreversible: number;
+    offTask: number;
+    scope: ScopeLabel;
+    scopeConfidence: number;
+    model: string;
+    elapsedMs: number;
+}
+export interface Verdict {
+    level: Level;
+    source: "skipped" | "read-only" | "pattern" | "typesafe" | "error";
+    summary: ActionSummary;
+    patterns: PatternHit[];
+    /** Human-readable reasons without secrets or full commands. */
+    reasons: string[];
+    judgment?: Judgment;
+    /** Safe TypeSafe error message when the judge could not answer. */
+    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 interface EvaluateOptions {
+    config: ActionGuardConfig;
+    /** Omit to run offline pattern checks only (no consent, no network). */
+    judge?: Judge | undefined;
+    signal?: AbortSignal | undefined;
+}
+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;
+export declare const questions: {
+    irreversible: import("pi-typesafe").NoulQuestion;
+    off_task: import("pi-typesafe").NoulQuestion;
+    scope: import("pi-typesafe").ChoiceQuestion<{
+        readonly expected_step: "A step that `task` directly requires";
+        readonly plausible_side_step: "Reasonable preparation, inspection, verification, or cleanup while doing `task`";
+        readonly unrelated: "Not connected to `task`";
+        readonly unclear: "`task` or `action` gives too little information to tell";
+    }>;
+};
+export declare function buildRequest(summary: ActionSummary, task: string | undefined): {
+    state: {
+        task: string;
+        action: Record<string, string | number | boolean>;
+    };
+    questions: {
+        irreversible: import("pi-typesafe").NoulQuestion;
+        off_task: import("pi-typesafe").NoulQuestion;
+        scope: import("pi-typesafe").ChoiceQuestion<{
+            readonly expected_step: "A step that `task` directly requires";
+            readonly plausible_side_step: "Reasonable preparation, inspection, verification, or cleanup while doing `task`";
+            readonly unrelated: "Not connected to `task`";
+            readonly unclear: "`task` or `action` gives too little information to tell";
+        }>;
+    };
+};
+export declare function evaluateAction(action: ActionInput, options: EvaluateOptions): Promise<Verdict>;
+/** One-line rendering for widgets and logs. Includes no command text. */
+export declare function formatVerdict(verdict: Verdict): string;

package/dist/guard.js

@@ -0,0 +1,303 @@
+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 { 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;
+function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit)}… [${text.length - limit} more chars]`;
+}
+const SHELL_RULES = [
+    { id: "git-force-push", severity: "destructive", label: "git force push", test: /\bgit\s+push\b[^\n;&|]*\s(?:-f|--force)(?![-\w])/ },
+    { id: "git-force-with-lease", severity: "risky", label: "git push --force-with-lease", test: /\bgit\s+push\b[^\n;&|]*--force-with-lease/ },
+    { id: "git-reset-hard", severity: "destructive", label: "git reset --hard", test: /\bgit\s+reset\b[^\n;&|]*--hard/ },
+    { id: "git-clean", severity: "destructive", label: "git clean (removes untracked files)", test: /\bgit\s+clean\b[^\n;&|]*\s-[a-zA-Z]*[fFxX]/ },
+    { id: "git-checkout-discard", severity: "risky", label: "git checkout/restore discards working changes", test: /\bgit\s+checkout\s+(?:--\s+\S|(?:\.|\*)(?=\s|$))|\bgit\s+restore\b(?:(?![^\n;&|]*--staged)|(?=[^\n;&|]*(?:--worktree|\s-\w*W)))/ },
+    { id: "git-branch-force-delete", severity: "risky", label: "git branch -D", test: /\bgit\s+branch\b[^\n;&|]*\s-D\b/ },
+    { id: "git-stash-drop", severity: "risky", label: "git stash drop/clear", test: /\bgit\s+stash\s+(?:drop|clear)\b/ },
+    { id: "sql-drop", severity: "destructive", label: "SQL DROP", test: /\bdrop\s+(?:table|database|schema|index|view|user|role)\b/i },
+    { id: "sql-truncate", severity: "destructive", label: "SQL TRUNCATE", test: /\btruncate\s+(?:table\s+)?\w/i },
+    { id: "sql-delete", severity: "destructive", label: "SQL DELETE FROM", test: /\bdelete\s+from\s+\w/i },
+    { id: "block-device-write", severity: "destructive", label: "write to a block device", test: /(?:\bdd\b[^\n;&|]*\bof=\/dev\/|>\s*\/dev\/(?:sd|hd|nvme|disk|mmcblk|vd)|\bmkfs(?:\.\w+)?\b|\bwipefs\b|\bfdisk\b|\bparted\b)/ },
+    { id: "chmod-777", severity: "destructive", label: "chmod -R 777", test: /\bchmod\b[^\n;&|]*\s-[a-zA-Z]*R[a-zA-Z]*\s+[0-7]*777\b|\bchmod\b[^\n;&|]*\s777\s+[^\n;&|]*\s-[a-zA-Z]*R/ },
+    { id: "fork-bomb", severity: "destructive", label: "fork bomb", test: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/ },
+    { id: "remote-script-exec", severity: "destructive", label: "pipe remote script into a shell", test: /\b(?:curl|wget)\b[^\n;&]*\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b/ },
+    { id: "kill-all", severity: "destructive", label: "kill every process", test: /\bkill\s+(?:-\w+\s+)*-1\b|\bkillall5\b/ },
+    { id: "power", severity: "destructive", label: "shutdown/reboot", test: /(?:^|[;&|(]\s*|\bsudo\s+)(?:shutdown|reboot|halt|poweroff)\b/m },
+    { id: "npm-publish", severity: "destructive", label: "publish a package", test: /\b(?:npm|pnpm|yarn)\s+publish\b|\bcargo\s+publish\b|\btwine\s+upload\b/ },
+    { id: "infra-destroy", severity: "destructive", label: "destroy infrastructure", test: /\b(?:terraform|tofu|pulumi)\s+destroy\b|\bkubectl\s+delete\b|\bhelm\s+(?:uninstall|delete)\b|\bdocker\s+(?:system\s+prune|volume\s+rm|rm\s+-[a-z]*f)/ },
+    { id: "find-delete", severity: "risky", label: "find -delete / -exec rm", test: /\bfind\b[^\n;&|]*(?:-delete\b|-exec\w*\s+rm\b)/ },
+    { id: "sudo", severity: "risky", label: "sudo", test: /(?:^|[\s;&|(])sudo\s/ },
+];
+const SENSITIVE_PATH = /(?:^|[\s/"'=:(])\.env(?:\.(?!example\b|sample\b|template\b|dist\b)[\w.-]+)?(?=$|[\s"';|&)])|(?:^|[\s"'=:/~])\.?(?:ssh\/(?:id_\w+|authorized_keys|known_hosts)|aws\/credentials|gnupg\/|netrc\b|npmrc\b|pypirc\b|docker\/config\.json|kube\/config\b|pi\/agent\/auth\.json|pi\/agent\/pi-typesafe\/auth\.json)|\b\w+\.(?:pem|p12|pfx|keystore|jks)\b|\bid_(?:rsa|ed25519|ecdsa|dsa)\b/i;
+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. */
+function classifyRm(segment, cwd) {
+    const match = /(?:^|\s)rm\s+(.*)$/.exec(segment);
+    if (!match)
+        return undefined;
+    const tokens = match[1].split(/\s+/).filter(Boolean);
+    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)));
+    const force = flags.some(flag => flag === "--force" || (/^-[a-zA-Z]+$/.test(flag) && flag.includes("f")));
+    if (!recursive)
+        return undefined;
+    const dangerousTarget = targets.some(target => {
+        const clean = target.replace(/^["']|["']$/g, "");
+        if (clean === "/" || clean === "~" || clean === "*" || clean === "." || clean === ".." || clean.startsWith("~/") || clean.startsWith("$") || clean.startsWith("/*") || clean === "./" || clean === "../")
+            return true;
+        if (isAbsolute(clean))
+            return cwd ? !isInside(clean, cwd) : true;
+        return clean.split(/[\\/]/).includes("..");
+    });
+    if (dangerousTarget)
+        return { id: "rm-recursive-dangerous-target", severity: "destructive", label: "recursive rm on an absolute, home, variable, or parent path" };
+    if (force)
+        return { id: "rm-rf", severity: "risky", label: "rm -rf on a project path" };
+    return { id: "rm-recursive", severity: "risky", label: "recursive rm" };
+}
+function isInside(target, cwd) {
+    const rel = relative(resolve(cwd), resolve(target));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function matchPatterns(tool, input, cwd) {
+    const hits = new Map();
+    const add = (hit) => { if (hit && !hits.has(hit.id))
+        hits.set(hit.id, hit); };
+    const command = typeof input.command === "string" ? input.command : undefined;
+    if (command) {
+        for (const rule of SHELL_RULES)
+            if (rule.test.test(command))
+                add({ id: rule.id, severity: rule.severity, label: rule.label });
+        for (const segment of splitShell(command))
+            add(classifyRm(segment, cwd));
+        if (SENSITIVE_PATH.test(command))
+            add({ id: "sensitive-path", severity: "sensitive", label: "touches a secrets or credentials file" });
+    }
+    const path = typeof input.path === "string" ? input.path : undefined;
+    if (path && SENSITIVE_PATH.test(path))
+        add({ id: "sensitive-path", severity: "sensitive", label: "touches a secrets or credentials file" });
+    return [...hits.values()];
+}
+// ---------------------------------------------------------------------------
+// Read-only shell detection: a latency optimisation, not a security boundary. Runs only when no pattern matched.
+const READ_ONLY_COMMANDS = new Set([
+    "ls", "cat", "head", "tail", "less", "more", "wc", "grep", "rg", "egrep", "fgrep", "ag", "find", "fd", "pwd", "echo", "printf", "which", "whereis", "type",
+    "file", "stat", "du", "df", "tree", "diff", "sort", "uniq", "cut", "tr", "cd", "true", "false", "test", "[", "date", "basename", "dirname", "realpath",
+    "readlink", "jq", "column", "nl", "strings", "md5", "md5sum", "shasum", "sha1sum", "sha256sum", "hexdump", "xxd", "od", "uname", "hostname", "whoami", "id", "uptime",
+]);
+const READ_ONLY_GIT = new Set(["status", "log", "diff", "show", "blame", "ls-files", "ls-tree", "rev-parse", "describe", "shortlog", "grep", "cat-file", "rev-list", "name-rev"]);
+export function isReadOnlyCommand(command) {
+    if (!command.trim() || /\$\(|`/.test(command))
+        return false;
+    const stripped = command.replace(/\d?>\s*&\s*\d/g, "").replace(/&?\d?>\s*\/dev\/null/g, "");
+    if (stripped.includes(">"))
+        return false;
+    for (const segment of splitShell(stripped)) {
+        const tokens = segment.split(/\s+/);
+        let index = 0;
+        while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index]))
+            index++;
+        const head = tokens[index];
+        if (!head)
+            return false;
+        if (head === "git") {
+            const rest = tokens.slice(index + 1).join(" ");
+            const sub = tokens[index + 1];
+            if (!sub)
+                return false;
+            if (sub === "branch") {
+                if (/\s-[a-zA-Z]*[dDmMcCu]|--(?:delete|move|copy|set-upstream|unset-upstream|edit-description)/.test(` ${rest}`))
+                    return false;
+                continue;
+            }
+            if (sub === "remote") {
+                if (tokens.slice(index + 2).some(token => !token.startsWith("-")))
+                    return false;
+                continue;
+            }
+            if (sub === "tag") {
+                if (!tokens.slice(index + 2).every(token => token === "-l" || token === "--list" || token.startsWith("-n")))
+                    return false;
+                continue;
+            }
+            if (sub === "config") {
+                if (!/--get|--list|-l\b/.test(rest))
+                    return false;
+                continue;
+            }
+            if (!READ_ONLY_GIT.has(sub))
+                return false;
+            continue;
+        }
+        if (head === "find" && /-(?:delete|exec\w*|ok\w*|fprint\w*|fls)\b/.test(segment))
+            return false;
+        if (!READ_ONLY_COMMANDS.has(head))
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Action summary: what is shown to the user and what is sent to TypeSafe.
+function displayPath(target, cwd) {
+    const absolute = resolve(cwd, target);
+    if (isInside(absolute, cwd)) {
+        const rel = relative(resolve(cwd), absolute);
+        return { path: rel === "" ? "." : rel.split(sep).join("/"), location: "inside_project" };
+    }
+    const home = homedir();
+    const shown = absolute === home || absolute.startsWith(home + sep) ? `~${absolute.slice(home.length)}` : absolute;
+    return { path: shown, location: "outside_project" };
+}
+export function describeAction(tool, input, cwd) {
+    const summary = { tool };
+    if (typeof input.command === "string")
+        summary.command = redact(truncate(input.command, COMMAND_LIMIT));
+    if (typeof input.path === "string" && input.path.trim()) {
+        const shown = displayPath(input.path, cwd);
+        summary.path = shown.path;
+        summary.location = shown.location;
+        summary.exists = existsSync(resolve(cwd, input.path));
+    }
+    if (tool === "write" && typeof input.content === "string") {
+        summary.bytes = Buffer.byteLength(input.content, "utf8");
+        summary.excerpt = redact(truncate(input.content, EXCERPT_LIMIT));
+    }
+    if (tool === "edit" && Array.isArray(input.edits)) {
+        summary.editCount = input.edits.length;
+        summary.edits = input.edits.slice(0, 3).map(edit => {
+            const item = (edit ?? {});
+            return {
+                oldText: redact(truncate(typeof item.oldText === "string" ? item.oldText : "", EDIT_LIMIT)),
+                newText: redact(truncate(typeof item.newText === "string" ? item.newText : "", EDIT_LIMIT)),
+            };
+        });
+    }
+    if (summary.command === undefined && summary.path === undefined)
+        summary.input = redact(truncate(JSON.stringify(input), COMMAND_LIMIT));
+    return summary;
+}
+// ---------------------------------------------------------------------------
+// TypeSafe request: named state fields, three independent questions.
+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.",
+        false: "No: it only reads, builds, tests, or creates new files, or it deletes generated output, caches, or temporary files that a build or checkout can recreate, or it is a change `task` explicitly asked for.",
+    }),
+    off_task: noul("Is `action` outside the scope of what `task` asks for?", {
+        true: "Yes: `task` does not call for this action, and it is not a normal preparatory, verification, or cleanup step for `task`.",
+        false: "No: `action` is a direct or reasonable step toward completing `task`.",
+    }),
+    scope: choice("How does `action` relate to `task`?", {
+        expected_step: "A step that `task` directly requires",
+        plausible_side_step: "Reasonable preparation, inspection, verification, or cleanup while doing `task`",
+        unrelated: "Not connected to `task`",
+        unclear: "`task` or `action` gives too little information to tell",
+    }),
+};
+export function buildRequest(summary, task) {
+    return {
+        state: {
+            task: task?.trim() ? truncate(task.trim(), TASK_LIMIT) : "(no user request recorded in this session)",
+            action: summary,
+        },
+        questions,
+    };
+}
+function combineSignals(timeoutMs, signal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+const percent = (value) => value.toFixed(2);
+// ---------------------------------------------------------------------------
+export async function evaluateAction(action, options) {
+    const { config, judge } = options;
+    const summary = describeAction(action.tool, action.input, action.cwd);
+    if (!config.enabled || !config.tools.includes(action.tool)) {
+        return { level: "allow", source: "skipped", summary, patterns: [], reasons: [] };
+    }
+    const patterns = matchPatterns(action.tool, action.input, action.cwd);
+    const reasons = [];
+    let level = "allow";
+    for (const hit of patterns) {
+        level = higher(level, hit.severity === "destructive" ? "confirm" : "warn");
+        reasons.push(`${hit.severity}: ${hit.label}`);
+    }
+    if (summary.location === "outside_project") {
+        if (action.tool === "write" && summary.exists) {
+            level = higher(level, "confirm");
+            reasons.push("overwrites an existing file outside the project");
+        }
+        else {
+            level = higher(level, "warn");
+            reasons.push(`${action.tool === "write" ? "creates" : "changes"} a file outside the project`);
+        }
+    }
+    if (action.tool === "bash" && patterns.length === 0 && typeof action.input.command === "string" && isReadOnlyCommand(action.input.command)) {
+        return { level, source: "read-only", summary, patterns, reasons };
+    }
+    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 judgment = {
+            irreversible: result.answers.irreversible.noul,
+            offTask: result.answers.off_task.noul,
+            scope: result.answers.scope.choice,
+            scopeConfidence: result.answers.scope.confidence,
+            model: result.model,
+            elapsedMs: result.elapsedMs,
+        };
+        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") {
+            level = higher(level, "confirm");
+            reasons.push(`off-task ${percent(judgment.offTask)} (unrelated to the request)`);
+        }
+        else if (judgment.offTask >= config.offTask.warn) {
+            level = higher(level, "warn");
+            reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
+        }
+        return { level, source: "typesafe", summary, patterns, reasons, judgment };
+    }
+    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");
+        }
+        else {
+            reasons.push("TypeSafe unavailable; allowed by failOpen");
+        }
+        return { level, source: "error", summary, patterns, reasons, error: message, ...(known ? { errorCode: known.code } : {}) };
+    }
+}
+/** 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.patterns.length)
+        parts.push(`patterns: ${verdict.patterns.map(hit => hit.id).join(", ")}`);
+    if (verdict.source === "error")
+        parts.push("typesafe error");
+    if (verdict.source === "read-only")
+        parts.push("read-only");
+    parts.push(verdict.level);
+    return parts.join(" · ");
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+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 { 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";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, questions } from "./guard.js";
+export { redact } from "./redact.js";
+export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";

package/dist/redact.d.ts

@@ -0,0 +1 @@
+export declare function redact(text: string): string;

package/dist/redact.js

@@ -0,0 +1,22 @@
+const REPLACEMENT = "[redacted]";
+/** Best-effort credential scrubbing for text that leaves the machine. Ordered: multi-token shapes before bare tokens. */
+const RULES = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, REPLACEMENT],
+    [/(authorization\s*[:=]\s*)(?:basic|bearer|token)?\s*\S+/gi, `$1${REPLACEMENT}`],
+    [/\b(bearer\s+)\S+/gi, `$1${REPLACEMENT}`],
+    [/((?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|private[_-]?key|passw(?:or)?d|passphrase|token|secret|credentials?)[a-z0-9_-]*\s*[=:]\s*["']?)([^\s"'&;]+)/gi, `$1${REPLACEMENT}`],
+    [/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REPLACEMENT}@`],
+    [/\bsk-[A-Za-z0-9_-]{8,}/g, REPLACEMENT],
+    [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, REPLACEMENT],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, REPLACEMENT],
+    [/\bAKIA[0-9A-Z]{16}\b/g, REPLACEMENT],
+    [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, REPLACEMENT],
+    [/\bAIza[0-9A-Za-z_-]{30,}/g, REPLACEMENT],
+    [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, REPLACEMENT],
+];
+export function redact(text) {
+    let out = text;
+    for (const [pattern, replacement] of RULES)
+        out = out.replace(pattern, replacement);
+    return out;
+}

package/extensions/index.js

@@ -0,0 +1,2 @@
+// Pi entry point. Kept at extensions/index.js so Pi lists the extension as "pi-warden".
+export { default } from "../dist/extension.js";

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "pi-warden",
+  "version": "0.1.0",
+  "description": "Harness guardrails for Pi built on pi-typesafe: pattern checks plus Jev judgments flag irreversible or off-task bash, write, and edit calls before they run.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ryan Gapac",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevMortimer/pi-warden.git"
+  },
+  "homepage": "https://github.com/DevMortimer/pi-warden#readme",
+  "bugs": "https://github.com/DevMortimer/pi-warden/issues",
+  "funding": "https://github.com/sponsors/DevMortimer",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "typesafe",
+    "jev",
+    "guardrails",
+    "harness-engineering"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:live": "node --env-file-if-exists=.env scripts/live-smoke.mjs",
+    "dev:pi": "node scripts/dev-pi.mjs",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.1 <1",
+    "@earendil-works/pi-tui": ">=0.85.1 <1"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^6.0.0"
+  },
+  "dependencies": {
+    "pi-typesafe": "^0.3.0"
+  }
+}