@aliou/pi-guardrails 0.10.0 → 0.11.1

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.1",
   "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

@@ -27,6 +27,7 @@ import type {
   ResolvedConfig,
 } from "../config";
 import { configLoader } from "../config";
+import { normalizeAllowedPaths } from "../utils/migration";
 
 type FeatureKey = keyof ResolvedConfig["features"];
 
@@ -40,6 +41,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<{
@@ -687,6 +692,157 @@ class AddRuleSubmenu implements Component {
   }
 }
 
+class PathListEditor implements Component {
+  private readonly input = new Input();
+  private items: string[];
+  private selectedIndex = 0;
+  private mode: "list" | "add" | "edit" = "list";
+  private editIndex = -1;
+
+  constructor(
+    private readonly options: {
+      label: string;
+      items: string[];
+      theme: SettingsListTheme;
+      onSave: (items: string[]) => void;
+      onDone: () => void;
+      maxVisible?: number;
+    },
+  ) {
+    this.items = [...options.items];
+    this.input.onSubmit = () => this.submit();
+    this.input.onEscape = () => this.cancel();
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const lines = [
+      this.options.theme.label(` ${this.options.label}`, true),
+      "",
+    ];
+    if (this.mode === "add" || this.mode === "edit") {
+      lines.push(
+        this.options.theme.hint(
+          this.mode === "edit" ? "  Edit path:" : "  New path:",
+        ),
+        "",
+        ...this.input.render(Math.max(1, width - 4)).map((line) => `  ${line}`),
+        "",
+        this.options.theme.hint("  Enter: save · Esc: cancel"),
+      );
+      return lines;
+    }
+
+    if (this.items.length === 0) {
+      lines.push(this.options.theme.hint("  (empty)"));
+    } else {
+      const maxVisible = this.options.maxVisible ?? 10;
+      const startIndex = Math.max(
+        0,
+        Math.min(
+          this.selectedIndex - Math.floor(maxVisible / 2),
+          this.items.length - maxVisible,
+        ),
+      );
+      const endIndex = Math.min(startIndex + maxVisible, this.items.length);
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.items[i];
+        if (!item) continue;
+        const isSelected = i === this.selectedIndex;
+        const prefix = isSelected ? this.options.theme.cursor : "  ";
+        lines.push(prefix + this.options.theme.value(item, isSelected));
+      }
+      if (startIndex > 0 || endIndex < this.items.length) {
+        lines.push(
+          this.options.theme.hint(
+            `  (${this.selectedIndex + 1}/${this.items.length})`,
+          ),
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(
+      this.options.theme.hint(
+        "  a: add · e/Enter: edit · d: delete · Esc: back",
+      ),
+    );
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (this.mode === "add" || this.mode === "edit") {
+      this.input.handleInput(data);
+      return;
+    }
+
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.items.length - 1
+          : this.selectedIndex - 1;
+    } else if (matchesKey(data, Key.down) || data === "j") {
+      if (this.items.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+    } else if (data === "a" || data === "A") {
+      this.mode = "add";
+      this.input.setValue("");
+    } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
+      this.startEdit();
+    } else if (data === "d" || data === "D") {
+      this.deleteSelected();
+    } else if (matchesKey(data, Key.escape)) {
+      this.options.onDone();
+    }
+  }
+
+  private startEdit(): void {
+    const item = this.items[this.selectedIndex];
+    if (!item) return;
+    this.mode = "edit";
+    this.editIndex = this.selectedIndex;
+    this.input.setValue(item);
+  }
+
+  private submit(): void {
+    const path = this.input.getValue().trim();
+    if (!path) {
+      this.cancel();
+      return;
+    }
+
+    if (this.mode === "edit") {
+      this.items[this.editIndex] = path;
+    } else {
+      this.items.push(path);
+      this.selectedIndex = this.items.length - 1;
+    }
+    this.items = [...new Set(this.items)];
+    this.options.onSave([...this.items]);
+    this.cancel();
+  }
+
+  private deleteSelected(): void {
+    if (this.items.length === 0) return;
+    this.items.splice(this.selectedIndex, 1);
+    if (this.selectedIndex >= this.items.length) {
+      this.selectedIndex = Math.max(0, this.items.length - 1);
+    }
+    this.options.onSave([...this.items]);
+  }
+
+  private cancel(): void {
+    this.mode = "list";
+    this.editIndex = -1;
+    this.input.setValue("");
+  }
+}
+
 class ScopePickerSubmenu implements Component {
   private selectedIndex = 0;
 
@@ -1063,6 +1219,23 @@ export function registerGuardrailsSettings(pi: ExtensionAPI): void {
         };
       }
 
+      function pathListSubmenu(id: string, label: string) {
+        return (_val: string, submenuDone: (v?: string) => void) => {
+          const items = normalizeAllowedPaths(getNestedValue(scopedConfig, id));
+          let latestCount = items.length;
+          return new PathListEditor({
+            label,
+            items,
+            theme: settingsTheme,
+            onSave: (newItems) => {
+              latestCount = newItems.length;
+              applyDraft(id, newItems);
+            },
+            onDone: () => submenuDone(`${latestCount} items`),
+          });
+        };
+      }
+
       function patternConfigSubmenu(
         id: string,
         label: string,
@@ -1210,6 +1383,30 @@ 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: pathListSubmenu(
+                "pathAccess.allowedPaths",
+                "Allowed Paths",
+              ),
+            },
+          ],
+        },
         {
           label: "Permission Gate",
           items: [