@pify/yolo 0.2.0 → 0.4.0

package/README.md

@@ -1,26 +1,35 @@
 # @pify/yolo
 
-One toggle to auto-approve everything in [pi](https://github.com/earendil-works/pi) — with an undo trail so YOLO never means unrecoverable.
+A safety gradient for [pi](https://github.com/earendil-works/pi), from auto-approve-everything to ask-about-anything — with an undo trail so YOLO never means unrecoverable.
 
 Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install yolo`](https://github.com/pifydev/cli) or `pi install npm:@pify/yolo`.
 
-## Two modes, one toggle
+## Four modes, one command (v0.4)
 
-**🛡 guard** (default) — every bash call runs through a three-tier gate:
+`/yolo <mode>` moves along a gradient. Two things hold in **every** mode, which is what makes the gradient safe to move along: catastrophic commands block, and secret material asks.
+
+| Mode | Catastrophic | Built-in destructive | Your `.pi/yolo.json` ask-rules | Everything else |
+|---|---|---|---|---|
+| `⚡ yolo` | blocked | runs | runs | runs |
+| `⚙ auto` | blocked | runs | asks | runs |
+| `🛡 approve` *(default)* | blocked | asks | asks | runs |
+| `🔒 strict` | blocked | asks | asks | asks unless plainly read-only |
+
+Bare `/yolo` still flips between `yolo` and `approve` — the two ends people actually toggle between. Sessions saved before v0.4 carried `guard`; that is what `approve` is now called, and they reopen there.
+
+**Behaviour change in v0.4**: `yolo` used to stand the *whole* gate down, catastrophic patterns included, which contradicted the rules' own claim that the floor is never overridable. The floor now holds in yolo mode too. If you were relying on `rm -rf /` auto-approving, you were relying on a bug.
 
 | Tier | Examples | Behavior |
 |---|---|---|
-| **BLOCK** | `rm -rf /`, `rm -rf ~`, `rm -rf .git`, `mkfs`, `dd of=/dev/…`, fork bomb, `> /dev/sda` | Refused outright. Never overridable — not even by user rules. |
+| **BLOCK** | `rm -rf /`, `rm -rf ~`, `rm -rf .git`, `mkfs`, `dd of=/dev/…`, fork bomb, `> /dev/sda` | Refused outright, in every mode. Never overridable — not by user rules, not by a mode. |
 | **ASK** | `rm -rf <path>`, `git push --force`, `git reset --hard`, `git clean -f`, `curl \| sh`, `find -delete`, `chmod 777`, history rewrites | Confirmation dialog with the command shown. Denials can carry your reason back to the agent. |
-| ALLOW | everything else | Runs untouched. |
-
-**⚡ yolo** (`/yolo`) — the gate stands down and everything auto-approves. The trail keeps recording.
+| ALLOW | everything else | Runs untouched (unless you are in `strict`). |
 
 Fail-closed everywhere: rule-evaluation errors block; ASK without a UI (headless/CI) denies.
 
 ## Secret files (v0.2)
 
-Credentials are the one thing yolo mode does **not** wave through — auto-approving speed is worth it, auto-approving your AWS keys into a prompt is not. Any `read`/`edit`/`write` on secret material, and any bash command that names it, asks first in both modes:
+Credentials are the one thing no mode waves through — auto-approving speed is worth it, auto-approving your AWS keys into a prompt is not. Any `read`/`edit`/`write` on secret material, and any bash command that names it, asks first in every mode:
 
 `.env` (and `.env.*`, but not `.env.example`/`.sample`/`.template`) · `~/.ssh/*` and `id_rsa`/`id_ed25519`-style keys (`.pub` halves are fine) · `.aws/credentials` · `.pi/agent/auth.json`, `.claude/.credentials.json` · `.npmrc`, `.pypirc`, `.netrc`, `.git-credentials` · `~/.config/gh/hosts.yml` · `*.pem`, `*.key`, `*.p12`, `*.pfx` · `secrets.json`/`credentials.yaml`
 
@@ -39,12 +48,37 @@ That covers what `/yolo undo` can't: damage done by a command rather than by an
 
 ## The undo trail
 
-Always on, in both modes:
+Always on, in every mode:
 
 - Every `edit`/`write` saves the file's **pre-image** first (per-project trail under the agent dir — survives restarts).
 - Risky bash commands are logged with cwd, timestamp, and git HEAD.
 - `/yolo trail` shows history; `/yolo undo [n]` restores the newest n file changes (with a confirmation listing exactly what will be touched). Files that didn't exist before are deleted; bash effects are logged but not undoable.
 
+## AI classifier (v0.3, opt-in)
+
+`/yolo classifier on` adds a third tier behind the regexes. Regexes only know the destructive shapes someone thought to write down — `find . -name '*.ts' -exec sed -i … {} +` is not one of them. When no rule matches, a model reads the command and can raise it to a confirmation.
+
+Two rules keep it honest:
+
+- **Escalation only.** It can turn `allow` into `ask`. It can never turn an `ask` or a `block` into an `allow`, so a classifier that gets talked into approving something cannot open the gate.
+- **A broken classifier changes nothing.** Timeout (20s), unreadable answer, no model available → the deterministic verdict stands. Safety comes from the rules; this is a second pair of eyes, not the gate.
+
+Obviously-safe commands (`git status`, `ls`, `cat`, `bun test`, …) skip the call entirely, so the cost lands only on unfamiliar ones.
+
+Measured over OpenRouter on six commands (three genuinely destructive, three read-only):
+
+| Model | Correct | Unreadable → no opinion |
+|---|---|---|
+| GPT-5.6 luna | 6/6 | 0 |
+| GPT-5.5 | 6/6 | 0 |
+| Claude Opus 4.8 | 6/6 | 0 |
+| GPT-5.6 terra / sol | 5/6 | 1 |
+| Claude Opus 5 | 4/6 | 1 |
+| Gemini 3.1 Pro | 2/6 | 4 |
+| Qwen3 235B | 2/6 | 4 |
+
+Every miss fell back to *allow* — no run ever downgraded a command the rules had already flagged. Weaker models simply give you less extra protection.
+
 ## Custom rules
 
 `.pi/yolo.json` — wildcard patterns, last-match-wins, may retune ASK/ALLOW but never the BLOCK floor:
@@ -61,10 +95,12 @@ Always on, in both modes:
 ## Commands
 
 ```
-/yolo            # toggle guard ↔ yolo
-/yolo status     # mode, rule count, trail size
+/yolo            # flip between yolo and approve
+/yolo strict     # or: yolo | auto | approve | strict (v0.4)
+/yolo status     # mode, the other modes, rule count, trail size
 /yolo trail      # recent trail entries
 /yolo undo 3     # restore the newest 3 file pre-images
+/yolo classifier on   # let a model flag unfamiliar commands (v0.3)
 ```
 
 ## License

package/extensions/yolo.ts

@@ -1,11 +1,12 @@
 /**
  * @pify/yolo — one toggle to auto-approve everything, with an undo trail.
  *
- * Two modes. guard (default): bash runs through a three-tier safety gate —
- * catastrophic patterns BLOCK outright (never overridable), destructive
- * ones ASK with the command shown (denial reasons flow back to the agent),
- * everything else runs. yolo: the gate stands down and everything
- * auto-approves — but the trail keeps recording. In BOTH modes every
+ * A four-mode gradient (v0.4): yolo · auto · approve (default) · strict.
+ * Bash runs through a three-tier rule set — catastrophic patterns BLOCK,
+ * destructive ones ASK with the command shown (denial reasons flow back to
+ * the agent), everything else runs — and the mode decides how much of that
+ * to relax or tighten. Two invariants hold in every mode: the catastrophic
+ * floor blocks, and secret material asks. In EVERY mode
  * edit/write saves a pre-image first and risky bash commands are logged,
  * so /yolo undo can walk file changes back even after a restart.
  *
@@ -13,7 +14,7 @@
  * headless ASK becomes deny. User rules in .pi/yolo.json (wildcard,
  * last-match-wins) can retune ASK/ALLOW but never the catastrophic floor.
  *
- * v0.2 adds two things yolo mode deliberately does not stand down for:
+ * v0.2 adds two things no mode stands down for:
  * secret material (.env, ssh keys, cloud/registry credentials) asks before
  * any read/edit/write or naming command, and every risky bash command gets a
  * `git stash create` checkpoint recorded on the trail so command damage —
@@ -24,7 +25,11 @@
  * /yolo session toggle (valdo766hi).
  */
 import {
+  DefaultResourceLoader,
+  SessionManager,
+  createAgentSession,
   getAgentDir,
+  type AgentSession,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
@@ -32,22 +37,46 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import {
+  CLASSIFY_SYSTEM_PROMPT,
+  applyClassification,
+  buildClassifyPrompt,
+  needsClassification,
+  parseClassification,
+  type Classification,
+} from "../src/classify.ts";
 import { evaluateCommand, evaluatePath, parseUserRules } from "../src/rules.ts";
 import { formatTrail, readManifest, recordBash, recordPreImage, trailDir, undo } from "../src/trail.ts";
+import {
+  MODES,
+  MODE_BADGES,
+  MODE_LABELS,
+  askTitle,
+  normalizeMode,
+  resolveAction,
+} from "../src/modes.ts";
 import { isRecord, type Mode, type UserRule } from "../src/types.ts";
 
+/** Today's guard, under its new name. */
+const DEFAULT_MODE: Mode = "approve";
+
 const MODE_ENTRY = "yolo-mode";
+const CLASSIFIER_ENTRY = "yolo-classifier";
+/** In front of every bash call: a slow answer costs seconds, not minutes. */
+const CLASSIFY_TIMEOUT_MS = 20_000;
 
 type UiContext = ExtensionContext;
 
 export default function yolo(pi: ExtensionAPI) {
-  let mode: Mode = "guard";
+  let mode: Mode = DEFAULT_MODE;
+  /** Opt-in: layer 3 costs a model call on unfamiliar commands. */
+  let classifierEnabled = false;
   let userRules: UserRule[] = [];
   let dir = "";
 
   function updateFooter(ctx: UiContext): void {
     if (!ctx.hasUI) return;
-    ctx.ui.setStatus("yolo", mode === "yolo" ? "⚡ YOLO" : undefined);
+    ctx.ui.setStatus("yolo", MODE_BADGES[mode]);
   }
 
   function setMode(ctx: UiContext, next: Mode): void {
@@ -56,9 +85,10 @@ export default function yolo(pi: ExtensionAPI) {
     updateFooter(ctx);
     if (ctx.hasUI) {
       ctx.ui.notify(
-        next === "yolo"
-          ? "⚡ YOLO on — everything auto-approves. The undo trail keeps recording; /yolo to turn the guard back on."
-          : "🛡 Guard on — catastrophic commands block, destructive ones ask.",
+        [
+          MODE_LABELS[next],
+          "Catastrophic commands block and secrets ask in every mode. The undo trail keeps recording.",
+        ].join("\n"),
         next === "yolo" ? "warning" : "info",
       );
     }
@@ -134,6 +164,56 @@ export default function yolo(pi: ExtensionAPI) {
     };
   }
 
+  /**
+   * Ask a model whether an unmatched command is risky. Short timeout: this
+   * sits in front of every bash call, so a slow answer must cost the session
+   * seconds, not minutes — and a timeout is simply "no opinion".
+   */
+  async function classifyCommand(ctx: UiContext, command: string): Promise<Classification> {
+    let session: AgentSession | null = null;
+    try {
+      const created = await createAgentSession({
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model: ctx.model as never,
+        tools: [],
+        resourceLoader: new DefaultResourceLoader({
+          cwd: ctx.cwd,
+          agentDir: getAgentDir(),
+          noExtensions: true,
+          noPromptTemplates: true,
+          noThemes: true,
+          // Replace the coding-agent prompt rather than append to it: with
+          // the default prompt in place, models answer a classification
+          // request with a markdown explanation instead of the JSON line.
+          systemPrompt: CLASSIFY_SYSTEM_PROMPT.join(" "),
+        } as never),
+      });
+      session = created.session;
+      await session.prompt(buildClassifyPrompt(command, ctx.cwd), {
+        signal: AbortSignal.timeout(CLASSIFY_TIMEOUT_MS),
+      } as never);
+      const messages = session.messages as Array<{ role?: string; content?: Array<{ type?: string; text?: string }> }>;
+      const last = [...messages].reverse().find((m) => m.role === "assistant");
+      const text = (last?.content ?? [])
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("");
+      return parseClassification(text);
+    } catch (err) {
+      return {
+        risk: "safe",
+        reason: `classifier unavailable (${err instanceof Error ? err.message : String(err)})`,
+        fallback: true,
+      };
+    } finally {
+      try {
+        session?.dispose();
+      } catch {
+        // best-effort
+      }
+    }
+  }
+
   function loadUserRules(cwd: string): void {
     try {
       userRules = parseUserRules(JSON.parse(readFileSync(join(cwd, ".pi", "yolo.json"), "utf8")));
@@ -167,8 +247,25 @@ export default function yolo(pi: ExtensionAPI) {
       return { block: true, reason: "yolo guard: bash call without a command (fail-closed)." };
     }
 
-    const verdict = evaluateCommand(command, userRules);
-    const touchesSecret = verdict.rule.startsWith("secret:");
+    let verdict = evaluateCommand(command, userRules);
+
+    // Layer 3: a model looks at what the regexes had no opinion about. It can
+    // only escalate allow → ask, so a talked-into-it classifier cannot open
+    // the gate, and a broken one leaves the deterministic verdict standing.
+    if (classifierEnabled && verdict.action === "allow" && needsClassification(command)) {
+      const classification = await classifyCommand(ctx, command);
+      const escalated = applyClassification(verdict.action, classification);
+      if (escalated.rule) verdict = { action: "ask", rule: escalated.rule };
+    }
+
+    // The mode decides what the verdict means: it may relax the destructive
+    // tier (auto/yolo) or tighten the allow tier (strict), but never touches
+    // the catastrophic floor or the secret gate.
+    const action = resolveAction({
+      mode,
+      verdict,
+      obviouslySafe: !needsClassification(command),
+    });
 
     // Log risky commands, with a checkpoint of the tree as it was.
     if (dir && verdict.action !== "allow") {
@@ -176,12 +273,9 @@ export default function yolo(pi: ExtensionAPI) {
       recordBash(dir, command, ctx.cwd, gitHead(ctx.cwd), now, gitCheckpoint(ctx.cwd, now));
     }
 
-    // The gate stands down in yolo mode — except for secrets.
-    if (mode === "yolo" && !touchesSecret) return undefined;
-
-    if (verdict.action === "allow") return undefined;
+    if (action === "allow") return undefined;
 
-    if (verdict.action === "block") {
+    if (action === "block") {
       return {
         block: true,
         reason: `yolo guard blocked this command (${verdict.rule}) — catastrophic patterns are never auto-approved. Do not retry it; choose a safer approach.`,
@@ -196,7 +290,7 @@ export default function yolo(pi: ExtensionAPI) {
       };
     }
     const approved = await ctx.ui.confirm(
-      touchesSecret ? "Command touches secret material" : "Destructive command",
+      askTitle(mode, verdict),
       `${command}\n\nRule: ${verdict.rule}. Run it?`,
     );
     if (approved) return undefined;
@@ -216,22 +310,32 @@ export default function yolo(pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     dir = trailDir(getAgentDir(), ctx.cwd);
     loadUserRules(ctx.cwd);
-    mode = "guard";
+    mode = DEFAULT_MODE;
+    classifierEnabled = false;
     for (const entry of ctx.sessionManager.getBranch()) {
       const e = entry as { type?: string; customType?: string; data?: unknown };
       if (e.type === "custom" && e.customType === MODE_ENTRY && isRecord(e.data)) {
-        if (e.data.mode === "yolo" || e.data.mode === "guard") mode = e.data.mode;
+        const restored = normalizeMode(e.data.mode);
+        if (restored) mode = restored;
+      }
+      if (e.type === "custom" && e.customType === CLASSIFIER_ENTRY && isRecord(e.data)) {
+        if (typeof e.data.enabled === "boolean") classifierEnabled = e.data.enabled;
       }
     }
     updateFooter(ctx);
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    mode = "guard";
+    mode = DEFAULT_MODE;
+    classifierEnabled = false;
     for (const entry of ctx.sessionManager.getBranch()) {
       const e = entry as { type?: string; customType?: string; data?: unknown };
       if (e.type === "custom" && e.customType === MODE_ENTRY && isRecord(e.data)) {
-        if (e.data.mode === "yolo" || e.data.mode === "guard") mode = e.data.mode;
+        const restored = normalizeMode(e.data.mode);
+        if (restored) mode = restored;
+      }
+      if (e.type === "custom" && e.customType === CLASSIFIER_ENTRY && isRecord(e.data)) {
+        if (typeof e.data.enabled === "boolean") classifierEnabled = e.data.enabled;
       }
     }
     updateFooter(ctx);
@@ -244,32 +348,69 @@ export default function yolo(pi: ExtensionAPI) {
   // ── Command ──────────────────────────────────────────────────────────
 
   pi.registerCommand("yolo", {
-    description: "Toggle auto-approve: /yolo [on|off|status|trail|undo [n]]",
+    description: "Safety gradient: /yolo [yolo|auto|approve|strict|status|trail|undo [n]|classifier on|off]",
     handler: async (args, ctx) => {
       const [route, countRaw] = (args ?? "").trim().toLowerCase().split(/\s+/);
       switch (route || "toggle") {
         case "toggle":
-          setMode(ctx, mode === "yolo" ? "guard" : "yolo");
+          // The bare command still flips between the two ends people use.
+          setMode(ctx, mode === "yolo" ? DEFAULT_MODE : "yolo");
           return;
         case "on":
           setMode(ctx, "yolo");
           return;
         case "off":
-          setMode(ctx, "guard");
+        case "guard":
+          setMode(ctx, DEFAULT_MODE);
+          return;
+        case "yolo":
+        case "auto":
+        case "approve":
+        case "strict":
+          setMode(ctx, route as Mode);
           return;
         case "status": {
           if (!ctx.hasUI) return;
           const entries = readManifest(dir);
           ctx.ui.notify(
             [
-              `Mode: ${mode === "yolo" ? "⚡ YOLO (gate off)" : "🛡 guard"}`,
+              `Mode: ${MODE_LABELS[mode]}`,
+              `Other modes: ${MODES.filter((m) => m !== mode).join(" · ")} (/yolo <mode>)`,
               `User rules: ${userRules.length} (.pi/yolo.json)`,
+              `AI classifier: ${classifierEnabled ? "on" : "off"} (/yolo classifier on)`,
               `Trail: ${entries.length} entries — /yolo trail to view, /yolo undo [n] to restore`,
             ].join("\n"),
             "info",
           );
           return;
         }
+        case "classifier": {
+          const value = (countRaw ?? "").toLowerCase();
+          if (value !== "on" && value !== "off") {
+            if (ctx.hasUI) {
+              ctx.ui.notify(
+                [
+                  `AI classifier: ${classifierEnabled ? "on" : "off"}.`,
+                  "When on, commands no rule matched are read by a model, which can escalate them to a confirmation — never to an approval.",
+                  "Usage: /yolo classifier <on|off>",
+                ].join("\n"),
+                "info",
+              );
+            }
+            return;
+          }
+          classifierEnabled = value === "on";
+          pi.appendEntry(CLASSIFIER_ENTRY, { enabled: classifierEnabled });
+          if (ctx.hasUI) {
+            ctx.ui.notify(
+              classifierEnabled
+                ? "AI classifier ON — unmatched commands get a second opinion before they run."
+                : "AI classifier OFF.",
+              "info",
+            );
+          }
+          return;
+        }
         case "trail": {
           if (!ctx.hasUI) return;
           ctx.ui.notify(formatTrail(readManifest(dir), 20), "info");
@@ -305,7 +446,7 @@ export default function yolo(pi: ExtensionAPI) {
           return;
         }
         default:
-          if (ctx.hasUI) ctx.ui.notify("Usage: /yolo [on|off|status|trail|undo [n]]", "warning");
+          if (ctx.hasUI) ctx.ui.notify("Usage: /yolo [on|off|status|trail|undo [n]|classifier on|off]", "warning");
       }
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/yolo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "One toggle to auto-approve everything, with an undo trail: three-tier bash guard, file pre-images, fail-closed everywhere",
   "keywords": [
     "pi-package",

package/src/classify.ts

@@ -0,0 +1,157 @@
+/**
+ * Layer 3 of the guard (zhushanwen's model): a model reads the commands the
+ * regex tiers had no opinion about. Regexes only know the destructive shapes
+ * someone thought to write down; `find . -name '*.ts' -exec sed -i ... {} +`
+ * is not one of them.
+ *
+ * Two rules keep this honest. The classifier can only ESCALATE — it may turn
+ * an allow into an ask, never an ask or a block into an allow, so a model
+ * that is talked into approving something cannot open the gate. And when it
+ * is slow, broken, or unreadable, the deterministic verdict stands: safety
+ * here comes from the rules, and the model is an extra pair of eyes.
+ */
+
+export type Risk = "safe" | "risky";
+
+export interface Classification {
+  risk: Risk;
+  reason: string;
+  /** True when the model was not consulted or could not be read. */
+  fallback: boolean;
+}
+
+export const CLASSIFY_SYSTEM_PROMPT = [
+  "You classify shell commands for a coding agent's safety guard.",
+  "A command is RISKY if running it could destroy work or state that is hard to get back:",
+  "deleting or overwriting files, rewriting git history, force-pushing, resetting or cleaning a",
+  "working tree, mass in-place edits, dropping databases, killing processes, changing permissions",
+  "or ownership broadly, downloading and executing code, or writing outside the project.",
+  "A command is SAFE if it only reads, inspects, queries, builds, or tests.",
+  "Judge what the command actually does, not what it is named. When you are unsure, answer risky.",
+  'Answer with ONE line of JSON and nothing else: {"risk":"safe","reason":"…"} or',
+  '{"risk":"risky","reason":"…"}. Keep the reason under 140 characters.',
+  "Do not explain. Do not use markdown. Your entire reply must start with { and end with }.",
+];
+
+/** Commands so common that asking a model about them is pure latency. */
+const OBVIOUSLY_SAFE =
+  /^(git (status|log|diff|show|branch|remote|fetch)|ls|pwd|cat|head|tail|wc|grep|rg|find|which|echo|node -v|npm (ls|view|test)|bun (test|--version)|python -V|cd|whoami|date|env)\b/i;
+
+/** Flags that turn a read-only-looking command into an executor. */
+const EXECUTOR_FLAGS = /\s-(exec|execdir|delete|ok|okdir)\b/i;
+
+/** Should the classifier be consulted for this command at all? */
+export function needsClassification(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed) return false;
+  // A pipeline or chain hides its real work; always look at those.
+  if (/[|;&]|&&|\$\(|`/.test(trimmed)) return true;
+  // `find` is on the safe list, but `find … -exec` is a way to run anything.
+  if (EXECUTOR_FLAGS.test(trimmed)) return true;
+  return !OBVIOUSLY_SAFE.test(trimmed);
+}
+
+export function buildClassifyPrompt(command: string, cwd: string): string {
+  return [
+    `Working directory: ${cwd}`,
+    "Command:",
+    "```sh",
+    command.trim(),
+    "```",
+    "Classify it.",
+  ].join("\n");
+}
+
+const MAX_REASON = 140;
+
+const RISKY_WORDS = new Set(["risky", "unsafe", "dangerous", "destructive", "irreversible"]);
+const SAFE_WORDS = new Set(["safe", "harmless", "benign"]);
+
+/** First meaningful sentence of a prose answer, trimmed to reason length. */
+function summarize(text: string): string {
+  const flat = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/[*_`#]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return flat.slice(0, MAX_REASON);
+}
+
+/**
+ * Read the classifier's answer. Anything unreadable falls back to safe with
+ * `fallback: true` — the caller then keeps the deterministic verdict rather
+ * than inventing an escalation from noise.
+ */
+export function parseClassification(text: string): Classification {
+  const trimmed = (text ?? "").trim();
+  if (!trimmed) return { risk: "safe", reason: "the classifier returned nothing", fallback: true };
+
+  const objects = [...trimmed.matchAll(/\{[^{}]*\}/g)].map((m) => m[0]).reverse();
+  for (const raw of objects) {
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    const reason = typeof parsed.reason === "string" ? parsed.reason.trim().slice(0, MAX_REASON) : "";
+    for (const key of ["risk", "verdict", "classification", "result"]) {
+      const value = String(parsed[key] ?? "").toLowerCase();
+      if (value === "risky" || value === "unsafe" || value === "dangerous" || value === "destructive") {
+        return { risk: "risky", reason: reason || "the classifier flagged it", fallback: false };
+      }
+      if (value === "safe" || value === "harmless") {
+        return { risk: "safe", reason: reason || "the classifier saw no risk", fallback: false };
+      }
+    }
+    if (typeof parsed.risky === "boolean") {
+      return {
+        risk: parsed.risky ? "risky" : "safe",
+        reason: reason || (parsed.risky ? "the classifier flagged it" : "the classifier saw no risk"),
+        fallback: false,
+      };
+    }
+  }
+
+  // Models routinely ignore the format and write an explanation instead. Read
+  // the verdict out of the prose rather than throwing the answer away: a
+  // labelled verdict first, then a standalone RISKY/SAFE token (the last one
+  // wins — the conclusion comes at the end), then a single unambiguous signal.
+  const labelled = [...trimmed.matchAll(/\b(?:classification|verdict|risk|answer)\b\s*[:=]?\s*\**\s*(\w+)/gi)];
+  for (const match of labelled.reverse()) {
+    const word = match[1]!.toLowerCase();
+    if (RISKY_WORDS.has(word)) return { risk: "risky", reason: summarize(trimmed), fallback: false };
+    if (SAFE_WORDS.has(word)) return { risk: "safe", reason: summarize(trimmed), fallback: false };
+  }
+
+  const tokens = [...trimmed.matchAll(/\b(RISKY|SAFE|UNSAFE|DANGEROUS|DESTRUCTIVE)\b/g)];
+  const lastToken = tokens.length > 0 ? tokens[tokens.length - 1]![1]! : null;
+  if (lastToken) {
+    return {
+      risk: lastToken === "SAFE" ? "safe" : "risky",
+      reason: summarize(trimmed),
+      fallback: false,
+    };
+  }
+
+  const risky = /\b(risky|unsafe|dangerous|destructive|irreversible)\b/i.test(trimmed);
+  const safe = /\b(safe|harmless|read-only|benign)\b/i.test(trimmed);
+  if (risky && !safe) return { risk: "risky", reason: summarize(trimmed), fallback: false };
+  if (safe && !risky) return { risk: "safe", reason: summarize(trimmed), fallback: false };
+  return { risk: "safe", reason: `unreadable classifier answer: ${trimmed.slice(0, 80)}`, fallback: true };
+}
+
+export type GuardAction = "allow" | "ask" | "block";
+
+/**
+ * Fold a classification into the deterministic verdict. Escalation only:
+ * allow can become ask, nothing can become allow.
+ */
+export function applyClassification(
+  action: GuardAction,
+  classification: Classification,
+): { action: GuardAction; rule: string | null } {
+  if (action !== "allow") return { action, rule: null };
+  if (classification.fallback || classification.risk === "safe") return { action, rule: null };
+  return { action: "ask", rule: `classifier:${classification.reason}` };
+}

package/src/modes.ts

@@ -0,0 +1,78 @@
+/**
+ * The four-mode gradient (zhushanwen). One toggle was too blunt: "guard"
+ * asked about every `rm -rf build`, and "yolo" stood the whole gate down,
+ * including the catastrophic floor the rules call non-negotiable. These are
+ * the four positions people actually want between those extremes.
+ *
+ * Two invariants hold in every mode, which is what makes the gradient safe
+ * to move along: the catastrophic tier always blocks, and secret material
+ * always asks.
+ */
+import type { GuardAction } from "./classify.ts";
+import type { Mode, RuleHit } from "./types.ts";
+
+export const MODES: readonly Mode[] = ["yolo", "auto", "approve", "strict"];
+
+export const MODE_LABELS: Record<Mode, string> = {
+  yolo: "⚡ YOLO — only catastrophic commands and secrets stop you",
+  auto: "⚙ auto — built-in destructive commands run; your own ask-rules still ask",
+  approve: "🛡 approve — catastrophic blocks, destructive asks (default)",
+  strict: "🔒 strict — anything not plainly read-only asks first",
+};
+
+export const MODE_BADGES: Record<Mode, string | undefined> = {
+  yolo: "⚡ YOLO",
+  auto: "⚙ auto",
+  // The default needs no badge; a permanent one just becomes furniture.
+  approve: undefined,
+  strict: "🔒 strict",
+};
+
+export function isMode(value: unknown): value is Mode {
+  return typeof value === "string" && (MODES as readonly string[]).includes(value);
+}
+
+/** Pre-v0.4 sessions stored "guard"; it is what "approve" is now called. */
+export function normalizeMode(value: unknown): Mode | null {
+  if (value === "guard") return "approve";
+  return isMode(value) ? value : null;
+}
+
+export interface ResolveInput {
+  mode: Mode;
+  verdict: RuleHit;
+  /** The command is on the read-only list (see classify.ts). */
+  obviouslySafe: boolean;
+}
+
+/**
+ * The effective action for a command, given the deterministic verdict and the
+ * current mode. Modes may relax the destructive tier and tighten the allow
+ * tier; they can never touch the two invariants.
+ */
+export function resolveAction({ mode, verdict, obviouslySafe }: ResolveInput): GuardAction {
+  // Invariant 1: catastrophic patterns block everywhere, yolo included. The
+  // rules call this floor non-negotiable, so a mode must not be a way under it.
+  if (verdict.action === "block") return "block";
+  // Invariant 2: credentials are never auto-approved (cc-safety-net pillar 2).
+  if (verdict.rule.startsWith("secret:")) return "ask";
+
+  switch (mode) {
+    case "yolo":
+      return "allow";
+    case "auto":
+      // A rule the user wrote by hand is an instruction, not a default.
+      return verdict.action === "ask" && verdict.rule.startsWith("user:") ? "ask" : "allow";
+    case "approve":
+      return verdict.action;
+    case "strict":
+      return verdict.action === "allow" && obviouslySafe ? "allow" : "ask";
+  }
+}
+
+/** Explains a mode-driven decision in the confirmation dialog. */
+export function askTitle(mode: Mode, verdict: RuleHit): string {
+  if (verdict.rule.startsWith("secret:")) return "Command touches secret material";
+  if (mode === "strict" && verdict.action === "allow") return "Strict mode — unrecognised command";
+  return "Destructive command";
+}

package/src/types.ts

@@ -3,7 +3,8 @@
  * No imports from pi packages: src/ typechecks and runs standalone.
  */
 
-export type Mode = "guard" | "yolo";
+/** Four positions on the safety gradient; see src/modes.ts (v0.4). */
+export type Mode = "yolo" | "auto" | "approve" | "strict";
 
 export type RuleAction = "allow" | "ask" | "block";