@aliou/pi-guardrails 0.10.0 → 0.11.0

package/README.md

@@ -1,3 +1,5 @@
+![banner](https://assets.aliou.me/pi-extensions/banners/pi-guardrails.png)
+
 # Guardrails
 
 Security hooks for Pi to reduce accidental destructive actions and secret-file access.
@@ -27,6 +29,7 @@ pi install git:github.com/aliou/pi-guardrails
 
 - **policies**: named file-protection rules with per-rule protection levels.
 - **permission-gate**: detects dangerous bash commands and asks for confirmation.
+- **path-access**: restricts tool access to the current working directory with allow/ask/block modes.
 - **optional command explainer**: can call a small LLM to explain a dangerous command inline in the confirmation dialog.
 
 ## Config locations
@@ -48,7 +51,12 @@ Use `/guardrails:settings` to edit config interactively.
   "enabled": true,
   "features": {
     "policies": true,
-    "permissionGate": true
+    "permissionGate": true,
+    "pathAccess": false
+  },
+  "pathAccess": {
+    "mode": "ask",
+    "allowedPaths": []
   },
   "policies": {
     "rules": [
@@ -121,6 +129,31 @@ Use:
 
 This starts a subagent that helps build and save one policy rule.
 
+## Path access
+
+Restrict tool access to the current working directory. When enabled, any tool call targeting a path outside `cwd` is checked against the configured mode:
+
+- **allow**: no restrictions
+- **ask**: prompt with options to grant access (file or directory, for session or always)
+- **block**: deny all outside access
+
+```jsonc
+{
+  "features": { "pathAccess": true },
+  "pathAccess": {
+    "mode": "ask",
+    "allowedPaths": ["~/code/shared-libs/", "~/.config/myapp"]
+  }
+}
+```
+
+Grants are stored in project config (always) or session memory (session). The `allowedPaths` array is merged across all config scopes.
+
+Limitations:
+- Symlinks are not resolved (lexical path comparison only).
+- Bash path extraction is best-effort (AST-based heuristics).
+- In non-interactive mode, `ask` mode degrades to `block`.
+
 ## Permission gate
 
 Detects dangerous bash commands and prompts user confirmation.
@@ -161,6 +194,16 @@ Also note:
 
 - `preventBrew`, `preventPython`, `enforcePackageManager`, `packageManager` were removed from guardrails and moved to `@aliou/pi-toolchain`.
 
+## Development
+
+```bash
+pnpm test         # Run tests
+pnpm test:watch   # Run tests in watch mode
+pnpm typecheck    # Type check
+pnpm lint         # Lint
+pnpm format       # Format
+```
+
 ## Events
 
 Guardrails emits events for other extensions:
@@ -169,7 +212,7 @@ Guardrails emits events for other extensions:
 
 ```ts
 interface GuardrailsBlockedEvent {
-  feature: "policies" | "permissionGate";
+  feature: "policies" | "permissionGate" | "pathAccess";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;
@@ -185,4 +228,4 @@ interface GuardrailsDangerousEvent {
   description: string;
   pattern: string;
 }
-```
+```

package/docs/defaults.md

@@ -101,6 +101,31 @@ Blocks access to GPG/GnuPG private keys, keyrings, and configuration. Disabled b
 
 ---
 
+## Path Access
+
+| Setting | Default |
+|---|---|
+| `features.pathAccess` | `false` |
+| `pathAccess.mode` | `"ask"` |
+| `pathAccess.allowedPaths` | `[]` |
+
+Modes:
+- `allow` — no path restrictions
+- `ask` — prompt when accessing paths outside working directory
+- `block` — deny all access outside working directory
+
+Allowed paths use trailing-slash convention:
+- `/path/to/file` — exact file match
+- `/path/to/dir/` — directory and all descendants
+- Supports `~/` for home directory
+
+Limitations:
+- Bash path extraction is best-effort (AST-based heuristics). Tokens like `application/json` may trigger false-positive prompts.
+- Symlinks are not resolved. Lexical path comparison only.
+- In non-interactive mode (--print), `ask` mode degrades to `block`.
+
+---
+
 ## Default Permission Gate Patterns
 
 These commands are detected using AST-based structural matching for accuracy.
@@ -109,7 +134,7 @@ These commands are detected using AST-based structural matching for accuracy.
 |-----------------|--------------------------------|
 | `rm -rf`        | Recursive force delete         |
 | `sudo`          | Superuser command              |
-| `dd if=`        | Disk write operation           |
+| `dd of=`        | Disk write operation           |
 | `mkfs.`         | Filesystem format              |
 | `chmod -R 777`  | Insecure recursive permissions |
 | `chown -R`      | Recursive ownership change     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -49,7 +49,8 @@
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-agent-core": {
@@ -67,6 +68,8 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "biome check",
     "format": "biome check --write",
     "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",

package/src/commands/onboarding-command.ts

@@ -10,12 +10,25 @@ import {
 function mergeOnboarding(
   base: GuardrailsConfig | null,
   applyBuiltinDefaults: boolean,
+  pathAccessEnabled?: boolean | null,
 ): GuardrailsConfig {
   const next = structuredClone(base ?? {});
-  const onboarded = buildOnboardedConfig(applyBuiltinDefaults);
+  const onboarded = buildOnboardedConfig(
+    applyBuiltinDefaults,
+    pathAccessEnabled,
+  );
   next.applyBuiltinDefaults = onboarded.applyBuiltinDefaults;
   next.version = onboarded.version;
   next.onboarding = onboarded.onboarding;
+  if (onboarded.features?.pathAccess !== undefined) {
+    next.features = {
+      ...next.features,
+      pathAccess: onboarded.features.pathAccess,
+    };
+  }
+  if (onboarded.pathAccess) {
+    next.pathAccess = onboarded.pathAccess;
+  }
   return next;
 }
 
@@ -48,7 +61,11 @@ export function registerGuardrailsOnboardingCommand(
         return;
       }
 
-      const merged = mergeOnboarding(globalConfig, result.applyBuiltinDefaults);
+      const merged = mergeOnboarding(
+        globalConfig,
+        result.applyBuiltinDefaults,
+        result.pathAccessEnabled,
+      );
       await configLoader.save("global", merged);
       await configLoader.load();
 

package/src/commands/onboarding.ts

@@ -11,11 +11,13 @@ import { CURRENT_VERSION } from "../utils/migration";
 
 interface OnboardingState {
   applyBuiltinDefaults: boolean | null;
+  pathAccessEnabled: boolean | null;
 }
 
 export interface OnboardingResult {
   completed: boolean;
   applyBuiltinDefaults: boolean | null;
+  pathAccessEnabled: boolean | null;
 }
 
 class IntroStep implements Component {
@@ -68,7 +70,7 @@ class DefaultsChoiceStep implements Component {
         "",
         "- Protect secret files like `.env`, `.env.local`, `.env.production`, and `.dev.vars`",
         "- Keep safe exceptions like `.env.example` and `*.sample.env`",
-        "- Require confirmation before running dangerous commands like `rm -rf`, `sudo`, and `dd if=`",
+        "- Require confirmation before running dangerous commands like `rm -rf`, `sudo`, and `dd of=`",
       ].join("\n"),
       [
         "Start with no built-in file policy defaults.",
@@ -129,6 +131,88 @@ class DefaultsChoiceStep implements Component {
   }
 }
 
+class PathAccessStep implements Component {
+  private selectedIndex = 0;
+  private readonly settingsTheme: SettingsTheme;
+
+  constructor(
+    private readonly theme: Theme,
+    private readonly state: OnboardingState,
+    private readonly onSelect: () => void,
+  ) {
+    this.settingsTheme = getSettingsTheme(theme);
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const options = ["Ask before accessing outside files", "No restrictions"];
+    const explanations = [
+      [
+        "When enabled, guardrails will prompt you before the agent accesses files outside the current working directory.",
+        "",
+        "- You can grant access per-file or per-directory",
+        "- Grants can be session-only or permanent",
+        "- In non-interactive mode, outside access is blocked",
+      ].join("\n"),
+      [
+        "The agent can access any path on your system without prompting.",
+        "",
+        "- You can enable path access later in `/guardrails:settings`",
+      ].join("\n"),
+    ];
+
+    const lines: string[] = [
+      "  Restrict access to your project directory?",
+      "",
+    ];
+
+    for (let i = 0; i < options.length; i++) {
+      const option = options[i];
+      if (!option) continue;
+      const selected = i === this.selectedIndex;
+      const prefix = selected ? this.settingsTheme.cursor : "  ";
+      const label = this.settingsTheme.value(` ${option}`, selected);
+      lines.push(`${prefix}${label}`);
+    }
+
+    lines.push("");
+
+    const explanationBox = new Box(1, 0, (s: string) => s);
+    explanationBox.addChild(
+      new Markdown(
+        explanations[this.selectedIndex] ?? "",
+        0,
+        0,
+        getMarkdownTheme(),
+        {
+          color: (s: string) => this.theme.fg("text", s),
+        },
+      ),
+    );
+
+    lines.push(...explanationBox.render(Math.max(1, width)));
+
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex = this.selectedIndex === 0 ? 1 : 0;
+      return;
+    }
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex = this.selectedIndex === 1 ? 0 : 1;
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      this.state.pathAccessEnabled = this.selectedIndex === 0;
+      this.onSelect();
+    }
+  }
+}
+
 class FinishStep implements Component {
   private readonly recapMarkdown = new Markdown("", 2, 0, getMarkdownTheme());
 
@@ -142,7 +226,7 @@ class FinishStep implements Component {
   }
 
   render(width: number): string[] {
-    const content =
+    const defaultsPart =
       this.state.applyBuiltinDefaults === true
         ? [
             "You selected **Recommended defaults**.",
@@ -150,7 +234,7 @@ class FinishStep implements Component {
             "Guardrails will start with built-in protection, including:",
             "- secret files like `.env`, `.env.local`, `.env.production`, `.dev.vars`",
             "- safe exceptions like `.env.example` and `*.sample.env`",
-            "- confirmation before running dangerous commands like `rm -rf`, `sudo`, `dd if=`",
+            "- confirmation before running dangerous commands like `rm -rf`, `sudo`, `dd of=`",
           ].join("\n")
         : [
             "You selected **Minimal setup**.",
@@ -160,6 +244,12 @@ class FinishStep implements Component {
             "You can configure policies later with `/guardrails:settings`.",
           ].join("\n");
 
+    const pathAccessPart = this.state.pathAccessEnabled
+      ? "\n\n**Path access**: enabled (ask mode). The agent will prompt before accessing files outside the working directory."
+      : "\n\n**Path access**: disabled. No path restrictions.";
+
+    const content = defaultsPart + pathAccessPart;
+
     this.recapMarkdown.setText(content);
     return [...this.recapMarkdown.render(Math.max(1, width)), ""];
   }
@@ -177,6 +267,7 @@ export function createOnboardingWizard(
 ): Component {
   const state: OnboardingState = {
     applyBuiltinDefaults: null,
+    pathAccessEnabled: null,
   };
 
   let markWelcomeComplete: (() => void) | null = null;
@@ -210,6 +301,14 @@ export function createOnboardingWizard(
             ctx.goNext();
           }),
       },
+      {
+        label: "Path access",
+        build: (ctx) =>
+          new PathAccessStep(theme, state, () => {
+            ctx.markComplete();
+            ctx.goNext();
+          }),
+      },
       {
         label: "Recap",
         build: (ctx) =>
@@ -219,21 +318,32 @@ export function createOnboardingWizard(
             finalize({
               completed: true,
               applyBuiltinDefaults: state.applyBuiltinDefaults,
+              pathAccessEnabled: state.pathAccessEnabled,
             });
           }),
       },
     ],
     onComplete: () => {
       if (state.applyBuiltinDefaults === null) {
-        finalize({ completed: false, applyBuiltinDefaults: null });
+        finalize({
+          completed: false,
+          applyBuiltinDefaults: null,
+          pathAccessEnabled: null,
+        });
         return;
       }
       finalize({
         completed: true,
         applyBuiltinDefaults: state.applyBuiltinDefaults,
+        pathAccessEnabled: state.pathAccessEnabled,
       });
     },
-    onCancel: () => finalize({ completed: false, applyBuiltinDefaults: null }),
+    onCancel: () =>
+      finalize({
+        completed: false,
+        applyBuiltinDefaults: null,
+        pathAccessEnabled: null,
+      }),
     hintSuffix: "Enter select/continue",
     minContentHeight: 12,
   });
@@ -256,8 +366,9 @@ export function createOnboardingWizard(
 
 export function buildOnboardedConfig(
   applyBuiltinDefaults: boolean,
+  pathAccessEnabled?: boolean | null,
 ): GuardrailsConfig {
-  return {
+  const config: GuardrailsConfig = {
     version: CURRENT_VERSION,
     applyBuiltinDefaults,
     onboarding: {
@@ -266,6 +377,11 @@ export function buildOnboardedConfig(
       version: CURRENT_VERSION,
     },
   };
+  if (pathAccessEnabled) {
+    config.features = { ...config.features, pathAccess: true };
+    config.pathAccess = { mode: "ask" };
+  }
+  return config;
 }
 
 export function isOnboardingPending(config: GuardrailsConfig | null): boolean {

package/src/commands/settings-command.ts

@@ -40,6 +40,10 @@ const FEATURE_UI: Record<FeatureKey, { label: string; description: string }> = {
     description:
       "Prompt for confirmation on dangerous commands (rm -rf, sudo, etc.)",
   },
+  pathAccess: {
+    label: "Path access",
+    description: "Restrict tool access to the current working directory",
+  },
 };
 
 const POLICY_EXAMPLES: Array<{
@@ -1210,6 +1214,31 @@ export function registerGuardrailsSettings(pi: ExtensionAPI): void {
           label: `Policies (${policyRules.length})`,
           items: policyItems,
         },
+        {
+          label: "Path Access",
+          items: [
+            {
+              id: "pathAccess.mode",
+              label: "Mode",
+              description:
+                "allow: no restrictions, ask: prompt for outside paths, block: deny all outside paths",
+              currentValue: scopedConfig.pathAccess?.mode ?? "(inherited)",
+              values: ["allow", "ask", "block"],
+            },
+            {
+              id: "pathAccess.allowedPaths",
+              label: "Allowed paths",
+              description:
+                "Paths always allowed (trailing / for directories). Supports ~/",
+              currentValue: count("pathAccess.allowedPaths"),
+              submenu: patternConfigSubmenu(
+                "pathAccess.allowedPaths",
+                "Allowed Paths",
+                "file",
+              ),
+            },
+          ],
+        },
         {
           label: "Permission Gate",
           items: [

package/src/config.ts

@@ -53,6 +53,13 @@ export interface PolicyRule {
   enabled?: boolean;
 }
 
+export type PathAccessMode = "allow" | "ask" | "block";
+
+export interface PathAccessConfig {
+  mode?: PathAccessMode;
+  allowedPaths?: string[];
+}
+
 export interface GuardrailsConfig {
   version?: string;
   enabled?: boolean;
@@ -66,12 +73,14 @@ export interface GuardrailsConfig {
   features?: {
     policies?: boolean;
     permissionGate?: boolean;
+    pathAccess?: boolean;
     // Deprecated. Kept only for migration.
     protectEnvFiles?: boolean;
   };
   policies?: {
     rules?: PolicyRule[];
   };
+  pathAccess?: PathAccessConfig;
   // Deprecated. Kept only for migration.
   envFiles?: {
     protectedPatterns?: PatternConfig[];
@@ -101,10 +110,15 @@ export interface ResolvedConfig {
   features: {
     policies: boolean;
     permissionGate: boolean;
+    pathAccess: boolean;
   };
   policies: {
     rules: PolicyRule[];
   };
+  pathAccess: {
+    mode: PathAccessMode;
+    allowedPaths: string[];
+  };
   permissionGate: {
     patterns: DangerousPattern[];
     /** When true, use hardcoded structural matchers for built-in patterns.
@@ -199,6 +213,11 @@ const DEFAULT_CONFIG: ResolvedConfig = {
   features: {
     policies: true,
     permissionGate: true,
+    pathAccess: false,
+  },
+  pathAccess: {
+    mode: "ask",
+    allowedPaths: [],
   },
   policies: {
     rules: [
@@ -277,13 +296,24 @@ const DEFAULT_CONFIG: ResolvedConfig = {
     patterns: [
       { pattern: "rm -rf", description: "recursive force delete" },
       { pattern: "sudo", description: "superuser command" },
-      { pattern: "dd if=", description: "disk write operation" },
+      { pattern: "dd of=", description: "disk write operation" },
       { pattern: "mkfs.", description: "filesystem format" },
       {
         pattern: "chmod -R 777",
         description: "insecure recursive permissions",
       },
       { pattern: "chown -R", description: "recursive ownership change" },
+      { pattern: "doas", description: "privileged command execution" },
+      { pattern: "pkexec", description: "privileged command execution" },
+      { pattern: "shred", description: "secure file overwrite" },
+      { pattern: "wipefs", description: "filesystem signature wipe" },
+      { pattern: "blkdiscard", description: "block device discard" },
+      { pattern: "fdisk", description: "disk partitioning" },
+      { pattern: "parted", description: "disk partitioning" },
+      {
+        pattern: "docker run --privileged",
+        description: "container with privileged mode",
+      },
     ],
     useBuiltinMatchers: true,
     requireConfirmation: true,
@@ -337,6 +367,19 @@ export const configLoader = new ConfigLoader<GuardrailsConfig, ResolvedConfig>(
         resolved.permissionGate.patterns = customPatterns;
         resolved.permissionGate.useBuiltinMatchers = false;
       }
+      // Merge allowedPaths across scopes (additive)
+      const mergedPaths = new Set<string>();
+      for (const paths of [
+        global?.pathAccess?.allowedPaths,
+        local?.pathAccess?.allowedPaths,
+        memory?.pathAccess?.allowedPaths,
+      ]) {
+        if (paths) {
+          for (const p of paths) mergedPaths.add(p);
+        }
+      }
+      resolved.pathAccess.allowedPaths = [...mergedPaths];
+
       return resolved;
     },
   },

package/src/hooks/index.ts

@@ -1,9 +1,11 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { ResolvedConfig } from "../config";
+import { setupPathAccessHook } from "./path-access";
 import { setupPermissionGateHook } from "./permission-gate";
 import { setupPoliciesHook } from "./policies";
 
 export function setupGuardrailsHooks(pi: ExtensionAPI, config: ResolvedConfig) {
-  setupPoliciesHook(pi, config);
-  setupPermissionGateHook(pi, config);
+  setupPathAccessHook(pi); // boundary check — runs first
+  setupPoliciesHook(pi, config); // policy rules — runs second
+  setupPermissionGateHook(pi, config); // dangerous commands — runs third
 }