@aliou/pi-guardrails 0.10.0 → 0.11.0

package/src/hooks/permission-gate/index.test.ts

@@ -0,0 +1,332 @@
+import type {
+  BashToolCallEvent,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import { createEventBus } from "@mariozechner/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createEventContext } from "../../../tests/utils/pi-context";
+import type { ResolvedConfig } from "../../config";
+import { configLoader } from "../../config";
+import { setupPermissionGateHook } from "./index";
+
+// Mock configLoader so allow-session path doesn't throw.
+vi.mock("../../config", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    configLoader: {
+      getConfig: vi.fn(() => ({
+        permissionGate: { allowedPatterns: [] },
+      })),
+      save: vi.fn(async () => {}),
+    },
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Constants — must match the production code's SELECT_* constants
+// ---------------------------------------------------------------------------
+
+const SELECT_ALLOW_ONCE = "Allow once";
+const SELECT_ALLOW_SESSION = "Allow for session";
+const SELECT_DENY = "Deny";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal config enabling the permission gate with defaults.
+ * No custom patterns — relies on built-in structural matchers.
+ */
+function makeConfig(
+  overrides: Partial<ResolvedConfig["permissionGate"]> = {},
+): ResolvedConfig {
+  return {
+    version: "1",
+    enabled: true,
+    applyBuiltinDefaults: true,
+    features: { policies: false, permissionGate: true, pathAccess: false },
+    policies: { rules: [] },
+    pathAccess: { mode: "ask", allowedPaths: [] },
+    permissionGate: {
+      patterns: [],
+      useBuiltinMatchers: true,
+      requireConfirmation: true,
+      allowedPatterns: [],
+      autoDenyPatterns: [],
+      explainCommands: false,
+      explainModel: null,
+      explainTimeout: 5000,
+      ...overrides,
+    },
+  };
+}
+
+type ToolCallHandler = (
+  event: BashToolCallEvent,
+  ctx: ExtensionContext,
+) => Promise<{ block: true; reason: string } | undefined>;
+
+/**
+ * Create a mock ExtensionAPI that captures tool_call handler registrations.
+ * Returns the mock and a function to retrieve the registered handler.
+ */
+function createMockPi() {
+  const handlers: ToolCallHandler[] = [];
+  const eventBus = createEventBus();
+
+  const pi = {
+    on(event: string, handler: ToolCallHandler) {
+      if (event === "tool_call") {
+        handlers.push(handler);
+      }
+    },
+    events: eventBus,
+    // Stubs for any other ExtensionAPI methods that might be called.
+    registerCommand: vi.fn(),
+    registerTool: vi.fn(),
+    emit: vi.fn(),
+  } as unknown as ExtensionAPI;
+
+  return {
+    pi,
+    getHandler(): ToolCallHandler {
+      if (handlers.length === 0) {
+        throw new Error("No tool_call handler registered");
+      }
+      return handlers[0];
+    },
+  };
+}
+
+function bashEvent(command: string): BashToolCallEvent {
+  return {
+    type: "tool_call",
+    toolCallId: "tc_test",
+    toolName: "bash",
+    input: { command },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("permission gate", () => {
+  let handle: ReturnType<typeof createMockPi>;
+  let handler: ToolCallHandler;
+
+  beforeEach(() => {
+    handle = createMockPi();
+    setupPermissionGateHook(handle.pi, makeConfig());
+    handler = handle.getHandler();
+  });
+
+  it("allows safe commands", async () => {
+    const ctx = createEventContext({ hasUI: true });
+    const result = await handler(bashEvent("echo hello"), ctx);
+    expect(result).toBeUndefined();
+  });
+
+  it("blocks dangerous commands when user denies", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(async () => "deny") as ExtensionContext["ui"]["custom"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual({
+      block: true,
+      reason: "User denied dangerous command",
+    });
+  });
+
+  it("allows dangerous commands when user explicitly allows", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(async () => "allow") as ExtensionContext["ui"]["custom"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toBeUndefined();
+  });
+
+  it("blocks when hasUI is false (print/RPC mode)", async () => {
+    const ctx = createEventContext({ hasUI: false });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual(expect.objectContaining({ block: true }));
+  });
+
+  it("blocks when ctx.ui.custom() returns undefined (RPC stub)", async () => {
+    // This is the bug from issue #19: in RPC mode, ctx.ui.custom() returns
+    // undefined. The permission gate only checks for "deny", so undefined
+    // falls through and the command is silently allowed.
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual(expect.objectContaining({ block: true }));
+    expect(ctx.ui.select).toHaveBeenCalled();
+  });
+
+  it("blocks auto-deny patterns without prompting", async () => {
+    const { pi, getHandler } = createMockPi();
+    setupPermissionGateHook(
+      pi,
+      makeConfig({
+        autoDenyPatterns: [{ pattern: "DROP TABLE" }],
+      }),
+    );
+    const h = getHandler();
+    const ctx = createEventContext({ hasUI: true });
+    const result = await h(bashEvent("psql -c 'DROP TABLE users'"), ctx);
+    expect(result).toEqual(expect.objectContaining({ block: true }));
+    // Should not have prompted the user.
+    expect(ctx.ui.custom).not.toHaveBeenCalled();
+  });
+
+  it("skips allowed patterns", async () => {
+    const { pi, getHandler } = createMockPi();
+    setupPermissionGateHook(
+      pi,
+      makeConfig({
+        allowedPatterns: [{ pattern: "sudo echo" }],
+      }),
+    );
+    const h = getHandler();
+    const ctx = createEventContext({ hasUI: true });
+    const result = await h(bashEvent("sudo echo hello"), ctx);
+    expect(result).toBeUndefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // RPC mode: ctx.ui.select() fallback when ctx.ui.custom() returns undefined
+  // ---------------------------------------------------------------------------
+
+  it("falls back to select() when custom() returns undefined and allows on 'Allow once'", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => SELECT_ALLOW_ONCE,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toBeUndefined(); // not blocked → allowed
+    expect(ctx.ui.select).toHaveBeenCalled();
+  });
+
+  it("falls back to select() when custom() returns undefined and allows-session on 'Allow for session'", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => SELECT_ALLOW_SESSION,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toBeUndefined(); // not blocked → allowed with session grant
+    expect(ctx.ui.select).toHaveBeenCalled();
+  });
+
+  it("falls back to select() when custom() returns undefined and blocks on 'Deny'", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => SELECT_DENY,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual({
+      block: true,
+      reason: "User denied dangerous command",
+    });
+  });
+
+  it("blocks when both custom() and select() return undefined", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual(expect.objectContaining({ block: true }));
+    expect(ctx.ui.select).toHaveBeenCalled();
+  });
+
+  it("does not call select() when custom() returns a valid result", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(async () => "deny") as ExtensionContext["ui"]["custom"],
+      },
+    });
+    await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(ctx.ui.select).not.toHaveBeenCalled();
+  });
+
+  it("blocks when select() returns an unrecognized string", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(async () => "maybe") as ExtensionContext["ui"]["select"],
+      },
+    });
+    const result = await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(result).toEqual(expect.objectContaining({ block: true }));
+  });
+
+  it("saves session grant via configLoader when select() returns 'Allow for session'", async () => {
+    const ctx = createEventContext({
+      hasUI: true,
+      ui: {
+        custom: vi.fn(
+          async () => undefined,
+        ) as ExtensionContext["ui"]["custom"],
+        select: vi.fn(
+          async () => SELECT_ALLOW_SESSION,
+        ) as ExtensionContext["ui"]["select"],
+      },
+    });
+    await handler(bashEvent("sudo rm -rf /"), ctx);
+    expect(configLoader.save).toHaveBeenCalledWith("memory", {
+      permissionGate: {
+        allowedPatterns: [{ pattern: "sudo rm -rf /" }],
+      },
+    });
+  });
+});

package/src/hooks/{permission-gate.ts → permission-gate/index.ts}

@@ -18,15 +18,19 @@ import {
   visibleWidth,
   wrapTextWithAnsi,
 } from "@mariozechner/pi-tui";
-import type { DangerousPattern, ResolvedConfig } from "../config";
-import { configLoader } from "../config";
-import { executeSubagent, resolveModel } from "../lib";
-import { emitBlocked, emitDangerous } from "../utils/events";
+import type { DangerousPattern, ResolvedConfig } from "../../config";
+import { configLoader } from "../../config";
+import { executeSubagent, resolveModel } from "../../lib";
+import { emitBlocked, emitDangerous } from "../../utils/events";
 import {
   type CompiledPattern,
   compileCommandPatterns,
-} from "../utils/matching";
-import { walkCommands, wordToString } from "../utils/shell-utils";
+} from "../../utils/matching";
+import { walkCommands, wordToString } from "../../utils/shell-utils";
+import {
+  BUILTIN_KEYWORD_PATTERNS,
+  BUILTIN_MATCHERS,
+} from "./dangerous-commands";
 
 /**
  * Permission gate that prompts user confirmation for dangerous commands.
@@ -36,53 +40,6 @@ import { walkCommands, wordToString } from "../utils/shell-utils";
  * Allowed/auto-deny patterns match against the raw command string.
  */
 
-/**
- * Structural matcher for a built-in dangerous command.
- * Returns a description if matched, undefined otherwise.
- */
-type StructuralMatcher = (words: string[]) => string | undefined;
-
-/**
- * Built-in dangerous command matchers. These check the parsed command
- * structure instead of regex against the raw string.
- */
-const BUILTIN_MATCHERS: StructuralMatcher[] = [
-  // rm -rf
-  (words) => {
-    if (words[0] !== "rm") return undefined;
-    const hasRF = words.some(
-      (w) =>
-        w === "-rf" ||
-        w === "-fr" ||
-        (w.startsWith("-") && w.includes("r") && w.includes("f")),
-    );
-    return hasRF ? "recursive force delete" : undefined;
-  },
-  // sudo
-  (words) => (words[0] === "sudo" ? "superuser command" : undefined),
-  // dd if=
-  (words) => {
-    if (words[0] !== "dd") return undefined;
-    return words.some((w) => w.startsWith("if="))
-      ? "disk write operation"
-      : undefined;
-  },
-  // mkfs.*
-  (words) => (words[0]?.startsWith("mkfs.") ? "filesystem format" : undefined),
-  // chmod -R 777
-  (words) => {
-    if (words[0] !== "chmod") return undefined;
-    return words.includes("-R") && words.includes("777")
-      ? "insecure recursive permissions"
-      : undefined;
-  },
-  // chown -R
-  (words) => {
-    if (words[0] !== "chown") return undefined;
-    return words.includes("-R") ? "recursive ownership change" : undefined;
-  },
-];
-
 interface DangerMatch {
   description: string;
   pattern: string;
@@ -117,14 +74,6 @@ interface CommandViewportState {
 }
 
 const COMMAND_VIEWPORT_LINES = 12;
-const BUILTIN_KEYWORD_PATTERNS = new Set([
-  "rm -rf",
-  "sudo",
-  "dd if=",
-  "mkfs.",
-  "chmod -R 777",
-  "chown -R",
-]);
 
 function buildNumberedWrappedLines(
   command: string,
@@ -580,10 +529,34 @@ export function setupPermissionGateHook(
 
       type ConfirmResult = "allow" | "allow-session" | "deny";
 
-      const result = await ctx.ui.custom<ConfirmResult>(
+      // Fallback select options for RPC mode (ctx.ui.custom is unimplemented).
+      const SELECT_ALLOW_ONCE = "Allow once";
+      const SELECT_ALLOW_SESSION = "Allow for session";
+      const SELECT_DENY = "Deny";
+      const SELECT_OPTIONS = [
+        SELECT_ALLOW_ONCE,
+        SELECT_ALLOW_SESSION,
+        SELECT_DENY,
+      ] as const;
+
+      let result = await ctx.ui.custom<ConfirmResult>(
         createPermissionGateConfirmComponent(command, description, explanation),
       );
 
+      // Fallback: ctx.ui.custom() returns undefined in RPC/headless mode
+      // (Pi's RPC runtime stubs it as `async custom() { return undefined; }`).
+      // Fall back to ctx.ui.select() which works over the RPC protocol.
+      // If select() also returns undefined/malformed, deny by default.
+      if (result === undefined) {
+        const selection = await ctx.ui.select(
+          `Dangerous command: ${description}`,
+          [...SELECT_OPTIONS],
+        );
+        if (selection === SELECT_ALLOW_ONCE) result = "allow";
+        else if (selection === SELECT_ALLOW_SESSION) result = "allow-session";
+        else result = "deny";
+      }
+
       if (result === "allow-session") {
         // Save command as allowed in memory scope (session-only).
         // Spread the resolved allowed patterns and append the new one.

package/src/utils/bash-paths.test.ts

@@ -0,0 +1,91 @@
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { extractBashPathCandidates } from "./bash-paths";
+
+const CWD = "/work/project";
+const HOME = homedir();
+
+describe("extractBashPathCandidates", () => {
+  describe("when command has path arguments", () => {
+    it("extracts a single absolute path", async () => {
+      expect(await extractBashPathCandidates("cat /etc/hosts", CWD)).toEqual([
+        "/etc/hosts",
+      ]);
+    });
+
+    it("extracts multiple absolute paths", async () => {
+      expect(await extractBashPathCandidates("cp /a /b", CWD)).toEqual([
+        "/a",
+        "/b",
+      ]);
+    });
+
+    it("resolves a relative path with ./ against cwd", async () => {
+      expect(await extractBashPathCandidates("cat ./foo/bar", CWD)).toEqual([
+        "/work/project/foo/bar",
+      ]);
+    });
+
+    it("expands ~ to home", async () => {
+      expect(await extractBashPathCandidates("cat ~/file", CWD)).toEqual([
+        `${HOME}/file`,
+      ]);
+    });
+
+    it("detects Windows-style paths", async () => {
+      const result = await extractBashPathCandidates("type C:\\foo\\bar", CWD);
+      expect(result.length).toBeGreaterThan(0);
+      // On POSIX, resolve() treats backslash path as a single component under cwd
+      expect(result[0]).toContain("C:\\foo\\bar");
+    });
+  });
+
+  describe("when command has flags and redirects", () => {
+    it("ignores flag arguments", async () => {
+      expect(await extractBashPathCandidates("ls -la /tmp", CWD)).toEqual([
+        "/tmp",
+      ]);
+    });
+
+    it("extracts redirect targets", async () => {
+      expect(
+        await extractBashPathCandidates("echo foo > /tmp/out", CWD),
+      ).toEqual(["/tmp/out"]);
+    });
+  });
+
+  describe("when command has no path-like tokens", () => {
+    it("returns an empty array for bare filenames (no separators)", async () => {
+      expect(await extractBashPathCandidates("cat README.md", CWD)).toEqual([]);
+    });
+
+    it("returns an empty array for commands with no file arguments", async () => {
+      expect(await extractBashPathCandidates("echo hello", CWD)).toEqual([]);
+    });
+  });
+
+  describe("when command uses quoting", () => {
+    it("handles quoted paths with spaces", async () => {
+      expect(
+        await extractBashPathCandidates('cat "/tmp/hello world"', CWD),
+      ).toEqual(["/tmp/hello world"]);
+    });
+  });
+
+  describe("when command has duplicate paths", () => {
+    it("deduplicates results", async () => {
+      expect(await extractBashPathCandidates("cat /a /a", CWD)).toEqual(["/a"]);
+    });
+  });
+
+  describe("when command is malformed", () => {
+    it("falls back to regex tokenization on parse failure", async () => {
+      // Unbalanced quote triggers parse error; regex fallback still finds paths
+      const result = await extractBashPathCandidates(
+        "cat /tmp/foo 'unterminated",
+        CWD,
+      );
+      expect(result).toContain("/tmp/foo");
+    });
+  });
+});

package/src/utils/bash-paths.ts

@@ -0,0 +1,96 @@
+import { resolve } from "node:path";
+import { parse } from "@aliou/sh";
+import { expandGlob, hasGlobChars } from "./glob-expander";
+import { expandHomePath } from "./path";
+import { walkCommands, wordToString } from "./shell-utils";
+
+/**
+ * Heuristic: is this token likely a filesystem path?
+ * Intentionally conservative — only structural signals.
+ * Known false positives: "application/json", URL paths. These cause
+ * spurious prompts in ask mode but are safe (better to over-prompt than miss).
+ * Known false negatives: bare filenames without path separators (e.g. "README.md").
+ * These are usually cwd-relative and would pass the boundary check anyway.
+ */
+function maybePathLike(token: string): boolean {
+  if (token.includes("/")) return true;
+  if (token.includes("\\")) return true;
+  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
+  if (token.startsWith("~")) return true;
+  return false;
+}
+
+async function expandCandidate(
+  candidate: string,
+  cwd: string,
+): Promise<string[]> {
+  if (!hasGlobChars(candidate)) return [candidate];
+  const matches = await expandGlob(candidate, { cwd });
+  return matches.length > 0 ? matches : [candidate];
+}
+
+/**
+ * Extract path-like candidates from a bash command string.
+ * Returns absolute paths. Best-effort: uses AST parsing with regex fallback.
+ * Does NOT filter by any policy — returns all path-like arguments.
+ */
+export async function extractBashPathCandidates(
+  command: string,
+  cwd: string,
+): Promise<string[]> {
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  const addCandidate = async (
+    token: string,
+    forcePath = false,
+  ): Promise<void> => {
+    if (!token || token.startsWith("-")) return;
+    if (!forcePath && !maybePathLike(token)) return;
+
+    const expanded = await expandCandidate(token, cwd);
+    for (const file of expanded) {
+      const abs = resolve(cwd, expandHomePath(file));
+      if (!seen.has(abs)) {
+        seen.add(abs);
+        results.push(abs);
+      }
+    }
+  };
+
+  try {
+    const { ast } = parse(command);
+    const pending: Promise<void>[] = [];
+
+    walkCommands(ast, (cmd) => {
+      const words = (cmd.words ?? []).map(wordToString);
+      for (let i = 1; i < words.length; i++) {
+        pending.push(addCandidate(words[i] as string));
+      }
+      for (const redir of cmd.redirects ?? []) {
+        pending.push(addCandidate(wordToString(redir.target), true));
+      }
+      return false;
+    });
+
+    await Promise.all(pending);
+    return results;
+  } catch {
+    // Fallback: regex tokenization
+    const tokenRegex = /"([^"]+)"|'([^']+)'|`([^`]+)`|([^\s"'`<>|;&]+)/g;
+    for (const match of command.matchAll(tokenRegex)) {
+      const token = match[1] ?? match[2] ?? match[3] ?? match[4] ?? "";
+      if (token && !token.startsWith("-") && maybePathLike(token)) {
+        const expanded = await expandCandidate(token, cwd);
+        for (const file of expanded) {
+          const abs = resolve(cwd, expandHomePath(file));
+          if (!seen.has(abs)) {
+            seen.add(abs);
+            results.push(abs);
+          }
+        }
+      }
+    }
+    return results;
+  }
+}

package/src/utils/events.ts

@@ -4,7 +4,7 @@ export const GUARDRAILS_BLOCKED_EVENT = "guardrails:blocked";
 export const GUARDRAILS_DANGEROUS_EVENT = "guardrails:dangerous";
 
 export interface GuardrailsBlockedEvent {
-  feature: "policies" | "permissionGate";
+  feature: "policies" | "permissionGate" | "pathAccess";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;