@pify/yolo 0.2.0 → 0.3.0

package/README.md

@@ -45,6 +45,31 @@ Always on, in both modes:
 - 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 | 3/6 | 3 |
+
+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:
@@ -65,6 +90,7 @@ Always on, in both modes:
 /yolo status     # mode, 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

@@ -24,7 +24,11 @@
  * /yolo session toggle (valdo766hi).
  */
 import {
+  DefaultResourceLoader,
+  SessionManager,
+  createAgentSession,
   getAgentDir,
+  type AgentSession,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
@@ -32,16 +36,29 @@ 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 { isRecord, type Mode, type UserRule } from "../src/types.ts";
 
 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";
+  /** Opt-in: layer 3 costs a model call on unfamiliar commands. */
+  let classifierEnabled = false;
   let userRules: UserRule[] = [];
   let dir = "";
 
@@ -134,6 +151,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,7 +234,17 @@ export default function yolo(pi: ExtensionAPI) {
       return { block: true, reason: "yolo guard: bash call without a command (fail-closed)." };
     }
 
-    const verdict = evaluateCommand(command, userRules);
+    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 };
+    }
+
     const touchesSecret = verdict.rule.startsWith("secret:");
 
     // Log risky commands, with a checkpoint of the tree as it was.
@@ -217,22 +294,30 @@ export default function yolo(pi: ExtensionAPI) {
     dir = trailDir(getAgentDir(), ctx.cwd);
     loadUserRules(ctx.cwd);
     mode = "guard";
+    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;
       }
+      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";
+    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;
       }
+      if (e.type === "custom" && e.customType === CLASSIFIER_ENTRY && isRecord(e.data)) {
+        if (typeof e.data.enabled === "boolean") classifierEnabled = e.data.enabled;
+      }
     }
     updateFooter(ctx);
   });
@@ -244,7 +329,7 @@ export default function yolo(pi: ExtensionAPI) {
   // ── Command ──────────────────────────────────────────────────────────
 
   pi.registerCommand("yolo", {
-    description: "Toggle auto-approve: /yolo [on|off|status|trail|undo [n]]",
+    description: "Toggle auto-approve: /yolo [on|off|status|trail|undo [n]|classifier on|off]",
     handler: async (args, ctx) => {
       const [route, countRaw] = (args ?? "").trim().toLowerCase().split(/\s+/);
       switch (route || "toggle") {
@@ -264,12 +349,40 @@ export default function yolo(pi: ExtensionAPI) {
             [
               `Mode: ${mode === "yolo" ? "⚡ YOLO (gate off)" : "🛡 guard"}`,
               `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 +418,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.3.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}` };
+}