@aliou/pi-guardrails 0.2.1 → 0.4.0

package/hooks/permission-gate.ts

@@ -8,142 +8,191 @@ import {
   Text,
   wrapTextWithAnsi,
 } from "@mariozechner/pi-tui";
+import type { ResolvedConfig } from "../config-schema";
+import { emitBlocked, emitDangerous } from "../events";
 
 /**
  * Permission gate that prompts user confirmation for dangerous commands.
- * Blocks patterns like rm -rf, sudo, and piped shell execution.
+ * Patterns, confirmation behavior, allow/deny lists are all configurable.
  */
 
-// Notification event channel (duplicated for decoupling)
-const NOTIFICATION_EVENT = "ad:notification";
-const ATTENTION_SOUND = "/System/Library/Sounds/Ping.aiff";
-
-interface NotificationEvent {
-  message: string;
-  sound?: string;
-}
-
-function emitNotification(pi: ExtensionAPI, message: string, sound?: string) {
-  const event: NotificationEvent = { message, sound };
-  pi.events.emit(NOTIFICATION_EVENT, event);
-}
+export function setupPermissionGateHook(
+  pi: ExtensionAPI,
+  config: ResolvedConfig,
+) {
+  if (!config.features.permissionGate) return;
+
+  // Compile patterns, skipping invalid regex
+  const dangerousPatterns = config.permissionGate.patterns
+    .map((p) => {
+      try {
+        return {
+          pattern: new RegExp(p.pattern),
+          description: p.description,
+          rawPattern: p.pattern,
+        };
+      } catch {
+        console.error(
+          `Invalid regex in guardrails permission-gate config: ${p.pattern}`,
+        );
+        return null;
+      }
+    })
+    .filter(
+      (p): p is { pattern: RegExp; description: string; rawPattern: string } =>
+        p !== null,
+    );
+
+  const allowedPatterns = config.permissionGate.allowedPatterns
+    .map((p) => {
+      try {
+        return new RegExp(p);
+      } catch {
+        console.error(
+          `Invalid regex in guardrails allowedPatterns config: ${p}`,
+        );
+        return null;
+      }
+    })
+    .filter((r): r is RegExp => r !== null);
+
+  const autoDenyPatterns = config.permissionGate.autoDenyPatterns
+    .map((p) => {
+      try {
+        return new RegExp(p);
+      } catch {
+        console.error(
+          `Invalid regex in guardrails autoDenyPatterns config: ${p}`,
+        );
+        return null;
+      }
+    })
+    .filter((r): r is RegExp => r !== null);
 
-const DANGEROUS_PATTERNS = [
-  { pattern: /rm\s+-rf/, description: "recursive force delete" },
-  { pattern: /\bsudo\b/, description: "superuser command" },
-  { pattern: /:\s*\|\s*sh/, description: "piped shell execution" },
-  { pattern: /\bdd\s+if=/, description: "disk write operation" },
-  { pattern: /mkfs\./, description: "filesystem format" },
-  {
-    pattern: /\bchmod\s+-R\s+777/,
-    description: "insecure recursive permissions",
-  },
-  { pattern: /\bchown\s+-R/, description: "recursive ownership change" },
-];
-
-export function setupPermissionGateHook(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
     if (event.toolName !== "bash") return;
 
     const command = String(event.input.command ?? "");
 
-    for (const { pattern, description } of DANGEROUS_PATTERNS) {
+    // Check allowed patterns first (bypass)
+    for (const pattern of allowedPatterns) {
+      if (pattern.test(command)) return;
+    }
+
+    // Check auto-deny patterns
+    for (const pattern of autoDenyPatterns) {
       if (pattern.test(command)) {
-        // Emit notification before showing confirm dialog
-        emitNotification(
-          pi,
-          `Dangerous command: ${description}`,
-          ATTENTION_SOUND,
-        );
+        ctx.ui.notify("Blocked dangerous command (auto-deny)", "error");
 
-        const proceed = await ctx.ui.custom<boolean>(
-          (_tui, theme, _kb, done) => {
-            const container = new Container();
-
-            // Red border styling
-            const redBorder = (s: string) => theme.fg("error", s);
-
-            // Top border
-            container.addChild(new DynamicBorder(redBorder));
-
-            // Title
-            container.addChild(
-              new Text(
-                theme.fg("error", theme.bold("Dangerous Command Detected")),
-                1,
-                0,
-              ),
-            );
-            container.addChild(new Spacer(1));
-
-            // Description
-            container.addChild(
-              new Text(
-                theme.fg("warning", `This command contains ${description}:`),
-                1,
-                0,
-              ),
-            );
-            container.addChild(new Spacer(1));
-
-            // Full command with border
-            container.addChild(
-              new DynamicBorder((s: string) => theme.fg("muted", s)),
-            );
-            const commandText = new Text("", 1, 0);
-            container.addChild(commandText);
-            container.addChild(
-              new DynamicBorder((s: string) => theme.fg("muted", s)),
-            );
-            container.addChild(new Spacer(1));
-
-            // Prompt
-            container.addChild(
-              new Text(theme.fg("text", "Allow execution?"), 1, 0),
-            );
-            container.addChild(new Spacer(1));
-
-            // Help text
-            container.addChild(
-              new Text(theme.fg("dim", "y/enter: allow • n/esc: deny"), 1, 0),
-            );
-
-            // Bottom border
-            container.addChild(new DynamicBorder(redBorder));
-
-            return {
-              render: (width: number) => {
-                // Update command text with proper wrapping for current width
-                const wrappedCommand = wrapTextWithAnsi(
-                  theme.fg("text", command),
-                  width - 4,
-                ).join("\n");
-                commandText.setText(wrappedCommand);
-                return container.render(width);
-              },
-              invalidate: () => container.invalidate(),
-              handleInput: (data: string) => {
-                if (
-                  matchesKey(data, Key.enter) ||
-                  data === "y" ||
-                  data === "Y"
-                ) {
-                  done(true);
-                } else if (
-                  matchesKey(data, Key.escape) ||
-                  data === "n" ||
-                  data === "N"
-                ) {
-                  done(false);
-                }
-              },
-            };
-          },
-        );
+        const reason =
+          "Command matched auto-deny pattern and was blocked automatically.";
+
+        emitBlocked(pi, {
+          feature: "permissionGate",
+          toolName: "bash",
+          input: event.input,
+          reason,
+        });
 
-        if (!proceed) {
-          return { block: true, reason: "User denied dangerous command" };
+        return { block: true, reason };
+      }
+    }
+
+    // Check dangerous patterns
+    for (const { pattern, description, rawPattern } of dangerousPatterns) {
+      if (pattern.test(command)) {
+        // Emit dangerous event (presenter will play sound)
+        emitDangerous(pi, { command, description, pattern: rawPattern });
+
+        if (config.permissionGate.requireConfirmation) {
+          const proceed = await ctx.ui.custom<boolean>(
+            (_tui, theme, _kb, done) => {
+              const container = new Container();
+              const redBorder = (s: string) => theme.fg("error", s);
+
+              container.addChild(new DynamicBorder(redBorder));
+              container.addChild(
+                new Text(
+                  theme.fg("error", theme.bold("Dangerous Command Detected")),
+                  1,
+                  0,
+                ),
+              );
+              container.addChild(new Spacer(1));
+              container.addChild(
+                new Text(
+                  theme.fg("warning", `This command contains ${description}:`),
+                  1,
+                  0,
+                ),
+              );
+              container.addChild(new Spacer(1));
+              container.addChild(
+                new DynamicBorder((s: string) => theme.fg("muted", s)),
+              );
+              const commandText = new Text("", 1, 0);
+              container.addChild(commandText);
+              container.addChild(
+                new DynamicBorder((s: string) => theme.fg("muted", s)),
+              );
+              container.addChild(new Spacer(1));
+              container.addChild(
+                new Text(theme.fg("text", "Allow execution?"), 1, 0),
+              );
+              container.addChild(new Spacer(1));
+              container.addChild(
+                new Text(theme.fg("dim", "y/enter: allow • n/esc: deny"), 1, 0),
+              );
+              container.addChild(new DynamicBorder(redBorder));
+
+              return {
+                render: (width: number) => {
+                  const wrappedCommand = wrapTextWithAnsi(
+                    theme.fg("text", command),
+                    width - 4,
+                  ).join("\n");
+                  commandText.setText(wrappedCommand);
+                  return container.render(width);
+                },
+                invalidate: () => container.invalidate(),
+                handleInput: (data: string) => {
+                  if (
+                    matchesKey(data, Key.enter) ||
+                    data === "y" ||
+                    data === "Y"
+                  ) {
+                    done(true);
+                  } else if (
+                    matchesKey(data, Key.escape) ||
+                    data === "n" ||
+                    data === "N"
+                  ) {
+                    done(false);
+                  }
+                },
+              };
+            },
+          );
+
+          if (!proceed) {
+            emitBlocked(pi, {
+              feature: "permissionGate",
+              toolName: "bash",
+              input: event.input,
+              reason: "User denied dangerous command",
+              userDenied: true,
+            });
+
+            return { block: true, reason: "User denied dangerous command" };
+          }
+        } else {
+          // No confirmation required - just notify and allow
+          ctx.ui.notify(
+            `Dangerous command detected: ${description}`,
+            "warning",
+          );
         }
+
         break;
       }
     }

package/hooks/prevent-brew.ts

@@ -1,36 +1,40 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config-schema";
+import { emitBlocked } from "../events";
 
 /**
- * Prevents bash tool calls that attempt to install packages using Homebrew.
- * Reminds the user that this project uses Nix for package management.
+ * Blocks all brew commands. Homebrew is not installed on this machine.
  */
 
-const BREW_INSTALL_PATTERNS = [
-  /\bbrew\s+install\b/,
-  /\bbrew\s+cask\s+install\b/,
-  /\bbrew\s+bundle\b/,
-  /\bbrew\s+upgrade\b/,
-  /\bbrew\s+reinstall\b/,
-];
+const BREW_PATTERN = /\bbrew\b/;
+
+export function setupPreventBrewHook(pi: ExtensionAPI, config: ResolvedConfig) {
+  if (!config.features.preventBrew) return;
 
-export function setupPreventBrewHook(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
     if (event.toolName !== "bash") return;
 
     const command = String(event.input.command ?? "");
 
-    for (const pattern of BREW_INSTALL_PATTERNS) {
-      if (pattern.test(command)) {
-        ctx.ui.notify(
-          "Blocked brew command. This project uses Nix for package management.",
-          "warning",
-        );
-        return {
-          block: true,
-          reason:
-            "Homebrew is not used in this project. Please use Nix for package management instead. Run packages via nix-shell or add them to the project's Nix configuration.",
-        };
-      }
+    if (BREW_PATTERN.test(command)) {
+      ctx.ui.notify(
+        "Blocked brew command. Homebrew is not installed.",
+        "warning",
+      );
+
+      const reason =
+        "Homebrew is not installed on this machine. " +
+        "Use Nix for package management instead. " +
+        "Run packages via nix-shell or add them to the project's Nix configuration.";
+
+      emitBlocked(pi, {
+        feature: "preventBrew",
+        toolName: "bash",
+        input: event.input,
+        reason,
+      });
+
+      return { block: true, reason };
     }
     return;
   });

package/hooks/prevent-python.ts

@@ -0,0 +1,45 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config-schema";
+import { emitBlocked } from "../events";
+
+/**
+ * Blocks all Python-related commands including python, python3, pip, poetry, etc.
+ * Use uv for Python package management instead.
+ */
+
+const PYTHON_PATTERN =
+  /\b(python|python3|pip|pip3|poetry|pyenv|virtualenv|venv)\b/;
+
+export function setupPreventPythonHook(
+  pi: ExtensionAPI,
+  config: ResolvedConfig,
+) {
+  if (!config.features.preventPython) return;
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "bash") return;
+
+    const command = String(event.input.command ?? "");
+
+    if (PYTHON_PATTERN.test(command)) {
+      ctx.ui.notify("Blocked Python command. Use uv instead.", "warning");
+
+      const reason =
+        "Python is not available globally on this machine. " +
+        "Use uv for Python package management instead. " +
+        "Run `uv init` to create a new Python project, " +
+        "or `uv run python` to run Python scripts. " +
+        "Use `uv add` to install packages (replaces pip/poetry).";
+
+      emitBlocked(pi, {
+        feature: "preventPython",
+        toolName: "bash",
+        input: event.input,
+        reason,
+      });
+
+      return { block: true, reason };
+    }
+    return;
+  });
+}

package/hooks/protect-env-files.ts

@@ -1,18 +1,16 @@
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config-schema";
+import { emitBlocked } from "../events";
 
 /**
- * Prevents accessing .env files unless they are suffixed with example, sample, or test.
- * This protects sensitive environment files from being accessed accidentally.
+ * Prevents accessing .env files unless they match an allowed pattern.
+ * Protects sensitive environment files from being accessed accidentally.
  *
- * Covers native tools: read, write, edit, bash, grep, find, ls
+ * Covers configurable set of tools (default: read, write, edit, bash, grep, find, ls).
  */
 
-const ENV_FILE_PATTERN = /\.env$/i;
-const ALLOWED_SUFFIXES =
-  /\.(example|sample|test)\.env$|\.env\.(example|sample|test)$/i;
-
 async function fileExists(filePath: string): Promise<boolean> {
   try {
     await stat(resolve(filePath));
@@ -22,89 +20,102 @@ async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
-async function isProtectedEnvFile(filePath: string): Promise<boolean> {
-  if (!ENV_FILE_PATTERN.test(filePath)) {
-    return false;
-  }
+function compilePatterns(patterns: string[]): RegExp[] {
+  return patterns
+    .map((p) => {
+      try {
+        return new RegExp(p, "i");
+      } catch {
+        console.error(`Invalid regex pattern in guardrails config: ${p}`);
+        return null;
+      }
+    })
+    .filter((r): r is RegExp => r !== null);
+}
 
-  if (ALLOWED_SUFFIXES.test(filePath)) {
-    return false;
+async function isProtectedEnvFile(
+  filePath: string,
+  config: ResolvedConfig,
+): Promise<boolean> {
+  const protectedRegexes = compilePatterns(config.envFiles.protectedPatterns);
+  const isProtected = protectedRegexes.some((r) => r.test(filePath));
+  if (!isProtected) return false;
+
+  const allowedRegexes = compilePatterns(config.envFiles.allowedPatterns);
+  const isAllowed = allowedRegexes.some((r) => r.test(filePath));
+  if (isAllowed) return false;
+
+  // Check protected directories (if any configured)
+  if (config.envFiles.protectedDirectories.length > 0) {
+    const dirRegexes = compilePatterns(config.envFiles.protectedDirectories);
+    const inProtectedDir = dirRegexes.some((r) => r.test(filePath));
+    if (inProtectedDir) {
+      return config.envFiles.onlyBlockIfExists
+        ? await fileExists(filePath)
+        : true;
+    }
   }
 
-  // Only block if file actually exists on disk
-  return fileExists(filePath);
+  return config.envFiles.onlyBlockIfExists ? await fileExists(filePath) : true;
 }
 
-// -------------------------------------------------------------------
-// Tool protection rule interface
-// -------------------------------------------------------------------
-
 interface ToolProtectionRule {
-  /** Tool names this rule applies to */
   tools: string[];
-  /** Extract paths/targets from tool input that need checking */
   extractTargets: (input: Record<string, unknown>) => string[];
-  /** Check if a target should be blocked */
   shouldBlock: (target: string) => Promise<boolean>;
-  /** Generate block message for a target */
   blockMessage: (target: string) => string;
 }
 
-// -------------------------------------------------------------------
-// Protection rules
-// -------------------------------------------------------------------
-
-const protectionRules: ToolProtectionRule[] = [
-  {
-    // Tools that use path/file_path input parameter
-    tools: ["read", "write", "edit", "grep", "find", "ls"],
-    extractTargets: (input) => {
-      const path = String(input.file_path ?? input.path ?? "");
-      return path ? [path] : [];
+export function setupProtectEnvFilesHook(
+  pi: ExtensionAPI,
+  config: ResolvedConfig,
+) {
+  if (!config.features.protectEnvFiles) return;
+
+  const protectionRules: ToolProtectionRule[] = [
+    {
+      tools: config.envFiles.protectedTools.filter((t) =>
+        ["read", "write", "edit", "grep", "find", "ls"].includes(t),
+      ),
+      extractTargets: (input) => {
+        const path = String(input.file_path ?? input.path ?? "");
+        return path ? [path] : [];
+      },
+      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      blockMessage: (target) =>
+        config.envFiles.blockMessage.replace("{file}", target),
     },
-    shouldBlock: isProtectedEnvFile,
-    blockMessage: (target) =>
-      `Accessing ${target} is not allowed. Environment files containing secrets are protected. Explain to the user why you want to access this .env file, and if changes are needed ask the user to make them. Only .env.example, .env.sample, or .env.test files can be accessed.`,
-  },
-  {
-    // Bash needs to parse command string for .env references
-    tools: ["bash"],
-    extractTargets: (input) => {
-      const command = String(input.command ?? "");
-      const files: string[] = [];
-
-      // Match .env file references in bash commands
-      const envFileRegex =
-        /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env)(?:\s|$|[<>|;&"'`])/gi;
-
-      for (const match of command.matchAll(envFileRegex)) {
-        const file = match[1];
-        if (file) {
-          files.push(file);
+    {
+      tools: config.envFiles.protectedTools.includes("bash") ? ["bash"] : [],
+      extractTargets: (input) => {
+        const command = String(input.command ?? "");
+        const files: string[] = [];
+
+        const envFileRegex =
+          /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
+
+        for (const match of command.matchAll(envFileRegex)) {
+          const file = match[1];
+          if (file) files.push(file);
         }
-      }
 
-      return files;
+        return files;
+      },
+      shouldBlock: (target) => isProtectedEnvFile(target, config),
+      blockMessage: (target) =>
+        `Command references protected file ${target}. ` +
+        config.envFiles.blockMessage.replace("{file}", target),
     },
-    shouldBlock: isProtectedEnvFile,
-    blockMessage: (target) =>
-      `Command references protected file ${target}. Environment files containing secrets are protected. Explain to the user why you want to access this .env file, and if changes are needed ask the user to make them. Only .env.example, .env.sample, or .env.test files can be accessed.`,
-  },
-];
-
-// Build lookup: tool name -> rule
-const rulesByTool = new Map<string, ToolProtectionRule>();
-for (const rule of protectionRules) {
-  for (const tool of rule.tools) {
-    rulesByTool.set(tool, rule);
-  }
-}
+  ];
 
-// -------------------------------------------------------------------
-// Hook
-// -------------------------------------------------------------------
+  // Build lookup: tool name -> rule
+  const rulesByTool = new Map<string, ToolProtectionRule>();
+  for (const rule of protectionRules) {
+    for (const tool of rule.tools) {
+      rulesByTool.set(tool, rule);
+    }
+  }
 
-export function setupProtectEnvFilesHook(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
     const rule = rulesByTool.get(event.toolName);
     if (!rule) return;
@@ -113,14 +124,18 @@ export function setupProtectEnvFilesHook(pi: ExtensionAPI) {
 
     for (const target of targets) {
       if (await rule.shouldBlock(target)) {
-        ctx.ui.notify(
-          `Blocked access to protected .env file: ${target}`,
-          "warning",
-        );
-        return {
-          block: true,
-          reason: rule.blockMessage(target),
-        };
+        ctx.ui.notify(`Blocked access to protected file: ${target}`, "warning");
+
+        const reason = rule.blockMessage(target);
+
+        emitBlocked(pi, {
+          feature: "protectEnvFiles",
+          toolName: event.toolName,
+          input: event.input,
+          reason,
+        });
+
+        return { block: true, reason };
       }
     }
     return;

package/index.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader } from "./config";
 import { setupGuardrailsHooks } from "./hooks";
+import { registerSettingsCommand } from "./settings-command";
 
 /**
  * Guardrails Extension
@@ -8,7 +10,18 @@ import { setupGuardrailsHooks } from "./hooks";
  * - prevent-brew: Blocks Homebrew commands (project uses Nix)
  * - protect-env-files: Prevents access to .env files (except .example/.sample/.test)
  * - permission-gate: Prompts for confirmation on dangerous commands
+ *
+ * Configuration:
+ * - Global: ~/.pi/agent/extensions/guardrails.json
+ * - Project: .pi/extensions/guardrails.json
+ * - Command: /guardrails:settings
  */
-export default function (pi: ExtensionAPI) {
-  setupGuardrailsHooks(pi);
+export default async function (pi: ExtensionAPI) {
+  await configLoader.load();
+  const config = configLoader.getConfig();
+
+  if (!config.enabled) return;
+
+  setupGuardrailsHooks(pi, config);
+  registerSettingsCommand(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "private": false,
   "keywords": [