feat(shell): pre-flight validator blocks unambiguously destructive commands

Adds src/tools/shell-validator.ts — a narrow allowlist-by-default
classifier that refuses a small set of patterns no sensible agent
issues by accident: rm -rf /, rm -rf $HOME / ~, fork bombs, raw
writes to block devices, mkfs. The shell tool consults it before
spawn and returns an error result for blocks; auto-approve does
not bypass it, so CI runs with --auto-approve can't have their
runner wiped by a bad model output.

A separate warn tier (sudo, curl|sh, chmod 777, git push --force)
flags command for the permission UI without blocking — auto-approve
still allows these because they're sometimes intentional. The line
we draw is "needs a human glance" vs "apocalyptic".

47 unit tests covering the block / warn / allow cases including
common false-positive guards (rm -rf /tmp/foo, $HOMEPAGE_DIR,
grep --grep messages containing the literal string).

Author: halfaipg

src/tools/shell-validator.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { validateShellCommand } from "./shell-validator.js";
+
+describe("validateShellCommand", () => {
+	describe("hard blocks", () => {
+		it.each([
+			"rm -rf /",
+			"rm -rf  /",
+			"rm -fr /",
+			"rm -rfv /",
+			"rm -rf $HOME",
+			"rm -rf $HOME/",
+			"rm -rf ~",
+			"rm -rf ~/",
+			"rm -rf /*",
+			":(){ :|:& };:",
+			":(){:|:&};:",
+			"dd if=/dev/zero of=/dev/sda bs=1M",
+			"dd of=/dev/sda1",
+			"dd of=/dev/nvme0n1",
+			"echo bad > /dev/sda",
+			"cat payload.iso > /dev/nvme0n1",
+			"mkfs.ext4 /dev/sda1",
+			"mkfs /dev/sda1",
+		])("blocks: %s", (cmd) => {
+			const result = validateShellCommand(cmd);
+			expect(result.verdict).toBe("block");
+			expect(result.reason).toBeTruthy();
+		});
+	});
+
+	describe("warnings (allowed but flagged)", () => {
+		it.each([
+			"sudo apt update",
+			"curl https://example.com/install.sh | sh",
+			"curl -fsSL https://example.com/install | bash",
+			"wget -O - https://example.com/install.sh | sh",
+			"chmod -R 777 ./build",
+			"chmod 0777 secret.key",
+			"git push --force origin main",
+			"git push -f origin feature",
+			"rm -rf ../../../some/path",
+		])("warns: %s", (cmd) => {
+			const result = validateShellCommand(cmd);
+			expect(result.verdict).toBe("warn");
+			expect(result.reason).toBeTruthy();
+		});
+	});
+
+	describe("allows legitimate work", () => {
+		it.each([
+			"ls -la",
+			"git status",
+			"npm test",
+			"rm src/junk.ts", // single-file delete is fine
+			"rm -rf node_modules", // common, scoped
+			"rm -rf dist/",
+			"rm -rf ./tmp",
+			"cat package.json",
+			"echo hello > /tmp/x", // /tmp redirect, not a device
+			"grep -r TODO src/",
+			"npm run build && npm test",
+			"git push origin main", // non-force push
+			"chmod +x scripts/run.sh",
+			"chmod 755 scripts/run.sh",
+			"curl -fsSL https://example.com > local-file", // not piped to shell
+			"mkdir -p src/foo && cp template.ts src/foo/", // composite, no destructive bits
+		])("allows: %s", (cmd) => {
+			const result = validateShellCommand(cmd);
+			expect(result.verdict).toBe("allow");
+		});
+
+		it("allows the empty command", () => {
+			expect(validateShellCommand("").verdict).toBe("allow");
+			expect(validateShellCommand("   ").verdict).toBe("allow");
+		});
+	});
+
+	describe("avoids common false positives", () => {
+		it("doesn't block rm of a file named like a root-edge path", () => {
+			expect(validateShellCommand("rm -rf /tmp/foo").verdict).toBe("allow");
+			expect(validateShellCommand("rm -rf /var/cache").verdict).toBe("allow");
+		});
+
+		it("doesn't block git diff containing the literal string 'rm -rf /'", () => {
+			expect(validateShellCommand("git log --grep='cleanup'").verdict).toBe("allow");
+		});
+
+		it("doesn't confuse a variable named HOMEPAGE with $HOME", () => {
+			expect(validateShellCommand("rm -rf $HOMEPAGE_DIR").verdict).toBe("allow");
+		});
+	});
+});

src/tools/shell-validator.ts

@@ -0,0 +1,113 @@
+/**
+ * Pre-flight check for shell commands the model wants to run. Returns
+ * a verdict the shell tool consults BEFORE spawning. The point isn't
+ * to enforce policy — the permission store does that — it's to refuse
+ * a small set of unambiguously destructive patterns that no sensible
+ * agent has any reason to issue, even by accident.
+ *
+ * Examples of what we block:
+ *   rm -rf /                  (delete root)
+ *   rm -rf ~ / $HOME          (delete the user's home dir)
+ *   dd of=/dev/sda            (overwrite a block device)
+ *   mkfs.ext4 /dev/sda1       (format a filesystem)
+ *   :(){ :|:& };:             (classic fork bomb)
+ *   curl ... | sh             (run a downloaded script unverified)
+ *
+ * The classifier is intentionally narrow. We err toward false-negatives
+ * (let through borderline-but-defensible commands) over false-positives
+ * (block legitimate work and frustrate the user). Granular policy belongs
+ * in the user's hooks.json or in the permission allow/deny patterns.
+ *
+ * Auto-approve bypasses the permission prompt but NOT this validator —
+ * `block` here is final regardless of permission policy. That's the
+ * point: a CI run with --auto-approve shouldn't be one bad model output
+ * away from wiping the runner.
+ */
+
+export type ShellVerdict = "allow" | "warn" | "block";
+
+export interface ShellValidationResult {
+	verdict: ShellVerdict;
+	/** Human-readable reason. Always set for warn / block. */
+	reason?: string;
+}
+
+interface PatternRule {
+	regex: RegExp;
+	reason: string;
+}
+
+/**
+ * Hard-block patterns. These return a verdict that auto-approve cannot
+ * override. The list is intentionally short — only patterns we'd be
+ * embarrassed to ship without catching. Anything that's only sometimes
+ * destructive (e.g. `git push -f`) goes in WARN_PATTERNS instead.
+ */
+const BLOCK_PATTERNS: readonly PatternRule[] = [
+	// `rm -rf /` and friends. The (?!\S) negative-lookahead lets us match
+	// the literal "/" as the target without matching "/something" paths.
+	{ regex: /\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+\/(?!\S)/, reason: "recursive delete targeting the filesystem root" },
+	{ regex: /\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+\$HOME(?![A-Za-z0-9_])/, reason: "recursive delete targeting $HOME" },
+	{
+		regex: /\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+~(\s|$|\/(\s|$|[^/]))/,
+		reason: "recursive delete targeting the home directory (~)",
+	},
+	{
+		regex: /\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+\/\*(?!\S)/,
+		reason: "recursive delete targeting every top-level directory (/*)",
+	},
+
+	// Fork bomb. The classic glyph soup.
+	{ regex: /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, reason: "fork bomb" },
+
+	// Writing raw bytes to a block device — almost always a mistake or
+	// malicious. Covers `dd of=/dev/sda`, `> /dev/nvme0n1`, etc.
+	{ regex: /\bdd\b[^\n;]*\bof=\/dev\/(sd|hd|nvme|vd|mmcblk)/, reason: "raw write to a block device" },
+	{ regex: />\s*\/dev\/(sd|hd|nvme|vd|mmcblk)/, reason: "shell redirect to a block device" },
+
+	// Format-the-disk commands. `mkfs.ext4`, `mkfs.xfs`, ...
+	{ regex: /\bmkfs(\.[a-z0-9]+)?\b/, reason: "formats a filesystem" },
+];
+
+/**
+ * Soft-warn patterns. These don't get blocked outright — sometimes you
+ * really do want to `sudo` something — but the verdict bubbles up so the
+ * permission UI can render the warning and demand a deliberate click,
+ * and downstream telemetry / hook layers can react.
+ *
+ * Auto-approve still allows these (it's already auto-approve), so the
+ * line we draw is "needs a human to glance at, but isn't apocalyptic."
+ */
+const WARN_PATTERNS: readonly PatternRule[] = [
+	{ regex: /\bsudo\b/, reason: "uses sudo (privilege escalation)" },
+	{
+		regex: /\bcurl\b[^\n;|]*\|\s*(sh|bash|zsh|sh\b)/,
+		reason: "pipes a downloaded script straight into a shell — verify the source",
+	},
+	{
+		regex: /\bwget\b[^\n;|]*\|\s*(sh|bash|zsh|sh\b)/,
+		reason: "pipes a downloaded script straight into a shell — verify the source",
+	},
+	{
+		regex: /\bchmod\s+(-[a-zA-Z]*R[a-zA-Z]*\s+)?(0?777|a\+w)\b/,
+		reason: "world-writable permissions",
+	},
+	{ regex: /\bgit\s+push\b[^\n]*--force\b/, reason: "force-pushes — rewrites remote history" },
+	{ regex: /\bgit\s+push\b[^\n]*-f\b/, reason: "force-pushes — rewrites remote history" },
+	{
+		regex: /\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+(\.\.\/){2,}/,
+		reason: "recursive delete escaping multiple parent directories",
+	},
+];
+
+export function validateShellCommand(command: string): ShellValidationResult {
+	const normalized = command.trim();
+	if (!normalized) return { verdict: "allow" };
+	for (const rule of BLOCK_PATTERNS) {
+		if (rule.regex.test(normalized)) return { verdict: "block", reason: rule.reason };
+	}
+	for (const rule of WARN_PATTERNS) {
+		if (rule.regex.test(normalized)) return { verdict: "warn", reason: rule.reason };
+	}
+	return { verdict: "allow" };
+}

src/tools/shell.ts

@@ -6,6 +6,7 @@ import { join, resolve } from "node:path";
 import type { AgentTool, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
 import { type Static, Type } from "typebox";
 import { TimeoutError } from "./errors.js";
+import { validateShellCommand } from "./shell-validator.js";
 import type { ToolContext } from "./types.js";
 
 const Params = Type.Object({
@@ -72,6 +73,38 @@ export function createShell(ctx: ToolContext): AgentTool<typeof Params, ShellDet
 		execute: async (toolCallId, params, signal, onUpdate) => {
 			const cwd = resolveSubCwd(ctx.cwd, params.cwd);
 
+			// Pre-flight validator: refuse a small set of unambiguously
+			// destructive patterns BEFORE spawn, regardless of permission
+			// policy. Auto-approve doesn't bypass this — CI runners
+			// shouldn't be one bad model output away from `rm -rf $HOME`.
+			const verdict = validateShellCommand(params.command);
+			if (verdict.verdict === "block") {
+				return {
+					details: {
+						command: params.command,
+						exitCode: null,
+						signal: null,
+						durationMs: 0,
+						bytesTotal: 0,
+						truncated: false,
+						spillPath: null,
+						timedOut: false,
+						aborted: false,
+					},
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text:
+								`Command refused by the shell validator: ${verdict.reason}.\n\n` +
+								"This is a hard block — the command was not executed. If this " +
+								"is a false positive, restructure the command (e.g. target the " +
+								"specific subdirectory explicitly) and try again.",
+						},
+					],
+				};
+			}
+
 			// Background mode: spawn detached, return immediately with a
 			// task_id. The agent can read output via shell_output and
 			// terminate via shell_kill. The store fires its own listeners