@aliou/pi-guardrails 0.13.3 → 0.14.1

package/README.md

@@ -56,6 +56,8 @@ The `path-access` extension checks tool calls that target paths outside the curr
 
 It can allow, block, or ask before Pi accesses files elsewhere on your machine. In ask mode, you can allow one file or a directory once, for the session, or always.
 
+Granted paths are stored in `pathAccess.allowedPaths` as explicit `{ kind, path }` entries: `file` matches the exact path, `directory` matches the directory and its descendants. Edit them through `/guardrails:settings` (Path Access → Allowed paths, Tab toggles file/directory) or directly in the settings file. Paths support `~/` for home. Existing configs using the legacy string form (trailing `/` for directories) are migrated automatically.
+
 [![Guardrails path access prompt walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.mp4)
 
 ### permission-gate

package/extensions/guardrails/commands/onboarding/config.ts

@@ -2,6 +2,7 @@ import {
   CURRENT_VERSION,
   type GuardrailsConfig,
 } from "../../../../src/shared/config";
+import { DEFAULT_CONFIG } from "../../../../src/shared/config/defaults";
 
 export function buildOnboardedConfig(
   applyBuiltinDefaults: boolean,
@@ -18,7 +19,10 @@ export function buildOnboardedConfig(
   };
   if (pathAccessEnabled) {
     config.features = { ...config.features, pathAccess: true };
-    config.pathAccess = { mode: "ask" };
+    config.pathAccess = {
+      mode: "ask",
+      allowedPaths: [...DEFAULT_CONFIG.pathAccess.allowedPaths],
+    };
   }
   return config;
 }

package/extensions/guardrails/commands/settings/index.ts

@@ -14,6 +14,7 @@ import type {
   SettingsListTheme,
 } from "@earendil-works/pi-tui";
 import type {
+  AllowedPath,
   DangerousPattern,
   GuardrailsConfig,
   PatternConfig,
@@ -355,7 +356,13 @@ export function registerGuardrailsSettings(
         return (_val: string, submenuDone: (v?: string) => void) => {
           const value = getNestedValue(scopedConfig, id);
           const items = Array.isArray(value)
-            ? value.filter((path): path is string => typeof path === "string")
+            ? value.filter(
+                (entry): entry is AllowedPath =>
+                  typeof entry === "object" &&
+                  entry !== null &&
+                  (entry.kind === "file" || entry.kind === "directory") &&
+                  typeof entry.path === "string",
+              )
             : [];
           let latestCount = items.length;
           return new PathListEditor({
@@ -531,7 +538,7 @@ export function registerGuardrailsSettings(
               id: "pathAccess.allowedPaths",
               label: "Allowed paths",
               description:
-                "Paths always allowed (trailing / for directories). Supports ~/",
+                "Paths always allowed outside cwd. Each entry is { kind, path }: file matches exactly, directory matches the tree. Supports ~/",
               currentValue: count("pathAccess.allowedPaths"),
               submenu: pathListSubmenu(
                 "pathAccess.allowedPaths",

package/extensions/guardrails/commands/settings/path-list-editor.ts

@@ -5,25 +5,45 @@ import {
   matchesKey,
   type SettingsListTheme,
 } from "@earendil-works/pi-tui";
+import type { AllowedPath } from "../../../../src/core/paths";
+
+type PathKind = "file" | "directory";
+
+function kindLabel(kind: PathKind): string {
+  return kind === "directory" ? "dir" : "file";
+}
+
+function isAllowedPath(value: unknown): value is AllowedPath {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as { kind?: unknown; path?: unknown };
+  return (
+    (entry.kind === "file" || entry.kind === "directory") &&
+    typeof entry.path === "string"
+  );
+}
 
 export class PathListEditor implements Component {
   private readonly input = new Input();
-  private items: string[];
+  private items: AllowedPath[];
   private selectedIndex = 0;
   private mode: "list" | "add" | "edit" = "list";
   private editIndex = -1;
+  private draftKind: PathKind = "file";
 
   constructor(
     private readonly options: {
       label: string;
-      items: string[];
+      items: AllowedPath[];
       theme: SettingsListTheme;
-      onSave: (items: string[]) => void;
+      onSave: (items: AllowedPath[]) => void;
       onDone: () => void;
       maxVisible?: number;
     },
   ) {
-    this.items = [...options.items];
+    this.items = options.items.filter(isAllowedPath).map((item) => ({
+      kind: item.kind,
+      path: item.path,
+    }));
     this.input.onSubmit = () => this.submit();
     this.input.onEscape = () => this.cancel();
   }
@@ -40,6 +60,9 @@ export class PathListEditor implements Component {
         this.options.theme.hint(
           this.mode === "edit" ? "  Edit path:" : "  New path:",
         ),
+        this.options.theme.hint(
+          `  kind: ${kindLabel(this.draftKind)} (Tab to toggle file/dir)`,
+        ),
         "",
         ...this.input.render(Math.max(1, width - 4)).map((line) => `  ${line}`),
         "",
@@ -65,7 +88,9 @@ export class PathListEditor implements Component {
         if (!item) continue;
         const isSelected = i === this.selectedIndex;
         const prefix = isSelected ? this.options.theme.cursor : "  ";
-        lines.push(prefix + this.options.theme.value(item, isSelected));
+        const kind = this.options.theme.hint(`[${kindLabel(item.kind)}]`);
+        const value = this.options.theme.value(item.path, isSelected);
+        lines.push(`${prefix}${kind} ${value}`);
       }
       if (startIndex > 0 || endIndex < this.items.length) {
         lines.push(
@@ -87,6 +112,10 @@ export class PathListEditor implements Component {
 
   handleInput(data: string): void {
     if (this.mode === "add" || this.mode === "edit") {
+      if (matchesKey(data, Key.tab)) {
+        this.draftKind = this.draftKind === "file" ? "directory" : "file";
+        return;
+      }
       this.input.handleInput(data);
       return;
     }
@@ -105,6 +134,7 @@ export class PathListEditor implements Component {
           : this.selectedIndex + 1;
     } else if (data === "a" || data === "A") {
       this.mode = "add";
+      this.draftKind = "file";
       this.input.setValue("");
     } else if (data === "e" || data === "E" || matchesKey(data, Key.enter)) {
       this.startEdit();
@@ -120,7 +150,8 @@ export class PathListEditor implements Component {
     if (!item) return;
     this.mode = "edit";
     this.editIndex = this.selectedIndex;
-    this.input.setValue(item);
+    this.draftKind = item.kind;
+    this.input.setValue(item.path);
   }
 
   private submit(): void {
@@ -130,13 +161,15 @@ export class PathListEditor implements Component {
       return;
     }
 
+    const entry: AllowedPath = { kind: this.draftKind, path };
+
     if (this.mode === "edit") {
-      this.items[this.editIndex] = path;
+      this.items[this.editIndex] = entry;
     } else {
-      this.items.push(path);
+      this.items.push(entry);
       this.selectedIndex = this.items.length - 1;
     }
-    this.items = [...new Set(this.items)];
+    this.items = dedupe(this.items);
     this.options.onSave([...this.items]);
     this.cancel();
   }
@@ -153,6 +186,19 @@ export class PathListEditor implements Component {
   private cancel(): void {
     this.mode = "list";
     this.editIndex = -1;
+    this.draftKind = "file";
     this.input.setValue("");
   }
 }
+
+function dedupe(items: AllowedPath[]): AllowedPath[] {
+  const seen = new Set<string>();
+  const result: AllowedPath[] = [];
+  for (const item of items) {
+    const key = `${item.kind}:${item.path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}

package/extensions/guardrails/index.ts

@@ -9,7 +9,6 @@ import {
   type GuardrailsFeatureId,
   type GuardrailsFeatureRegisterPayload,
 } from "../../src/shared/events";
-import { drainPendingWarnings } from "../../src/shared/warnings";
 import { registerGuardrailsExamplesCommand } from "./commands/examples";
 import { registerGuardrailsOnboardingCommand } from "./commands/onboarding";
 import { isOnboardingPending } from "./commands/onboarding/config";
@@ -90,7 +89,7 @@ export default async function guardrails(pi: ExtensionAPI) {
       createFeatureRequestPayload(),
     );
 
-    const warnings = drainPendingWarnings();
+    const warnings = configLoader.drainMessages();
     if (warnings.length === 1) {
       ctx.ui.notify(warnings[0], "warning");
     } else if (warnings.length > 1) {

package/extensions/path-access/dynamic-resources.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve Pi documentation paths dynamically from the running Pi runtime.
+ *
+ * Pi bakes its docs/examples paths into the system prompt text at launch time,
+ * but those paths change between Pi versions (e.g. Nix store hashes), so we
+ * resolve them directly from Pi's package asset path helpers instead of
+ * scraping the system prompt or persisting concrete paths in config.
+ */
+import {
+  getDocsPath,
+  getExamplesPath,
+  getReadmePath,
+} from "@earendil-works/pi-coding-agent";
+import type { AllowedPath } from "../../src/core/paths";
+
+/**
+ * Resolve Pi documentation paths dynamically from the running Pi runtime.
+ *
+ * Pi bakes its docs/examples paths into the system prompt text at launch time,
+ * but those paths change between Pi versions (e.g. Nix store hashes), so we
+ * resolve them directly from Pi's package asset path helpers instead of
+ * scraping the system prompt or persisting concrete paths in config.
+ *
+ * These helpers honor `PI_PACKAGE_DIR` (Nix/Guix) and walk to the package
+ * root for npm global installs and Bun binaries, so they always match the
+ * Pi version actually running. They depend only on the process environment
+ * and are fixed for the process lifetime — resolve once, no per-turn work.
+ *
+ * The README is a single file grant; docs and examples are directory grants.
+ */
+export function piDocumentationPaths(): AllowedPath[] {
+  return [
+    { kind: "file", path: getReadmePath() },
+    { kind: "directory", path: getDocsPath() },
+    { kind: "directory", path: getExamplesPath() },
+  ];
+}

package/extensions/path-access/grants.ts

@@ -1,30 +1,33 @@
 import { homedir } from "node:os";
-import { resolveFromCwd, toStorageForm } from "../../src/core/paths";
+import {
+  type AllowedPath,
+  resolveFromCwd,
+  toStorageGrant,
+} from "../../src/core/paths";
 import { configLoader } from "../../src/shared/config";
 
 export type PendingPathGrant = {
-  storagePath: string;
+  kind: "file" | "directory";
+  storageGrant: AllowedPath;
   scope: "memory" | "local";
   absolutePath: string;
 };
 
 export function resolveAllowedPaths(
-  allowedPaths: string[],
+  allowedPaths: AllowedPath[],
   cwd: string,
-): string[] {
-  return allowedPaths.map((path) => {
-    const isDir = path.endsWith("/");
-    const resolved = resolveFromCwd(isDir ? path.slice(0, -1) : path, cwd);
-    return isDir ? `${resolved}/` : resolved;
-  });
+): AllowedPath[] {
+  return allowedPaths.map((entry) => ({
+    kind: entry.kind,
+    path: resolveFromCwd(entry.path, cwd),
+  }));
 }
 
-export function pendingAllowedPaths(grants: PendingPathGrant[]): string[] {
-  return grants.map((grant) =>
-    grant.storagePath.endsWith("/")
-      ? `${grant.absolutePath}/`
-      : grant.absolutePath,
-  );
+export function pendingAllowedPaths(grants: PendingPathGrant[]): AllowedPath[] {
+  return grants.map((grant) => ({
+    kind: grant.kind,
+    path: grant.absolutePath,
+  }));
 }
 
 export function isGrantTooBroad(absPath: string): boolean {
@@ -38,9 +41,10 @@ export function createPendingGrant(
   scope: "memory" | "local",
 ): PendingPathGrant {
   return {
+    kind: isDirectory ? "directory" : "file",
     absolutePath,
     scope,
-    storagePath: toStorageForm(absolutePath, isDirectory),
+    storageGrant: toStorageGrant(absolutePath, isDirectory),
   };
 }
 
@@ -52,17 +56,26 @@ export async function persistGrant(grant: PendingPathGrant): Promise<void> {
   const pathAccess = (raw.pathAccess ?? {}) as Record<string, unknown>;
   const existing = Array.isArray(pathAccess.allowedPaths)
     ? pathAccess.allowedPaths.filter(
-        (path): path is string => typeof path === "string",
+        (entry): entry is AllowedPath =>
+          typeof entry === "object" &&
+          entry !== null &&
+          (entry.kind === "file" || entry.kind === "directory") &&
+          typeof (entry as { path?: unknown }).path === "string",
       )
     : [];
 
-  if (existing.includes(grant.storagePath)) return;
+  const alreadyPresent = existing.some(
+    (entry) =>
+      entry.kind === grant.storageGrant.kind &&
+      entry.path === grant.storageGrant.path,
+  );
+  if (alreadyPresent) return;
 
   await configLoader.save(grant.scope, {
     ...raw,
     pathAccess: {
       ...pathAccess,
-      allowedPaths: [...existing, grant.storagePath],
+      allowedPaths: [...existing, grant.storageGrant],
     },
   });
 }

package/extensions/path-access/index.ts

@@ -2,6 +2,7 @@ import { dirname } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { checkAction } from "../../src/core";
 import {
+  type AllowedPath,
   normalizeForDisplay,
   type PathAccessState,
 } from "../../src/core/paths";
@@ -13,6 +14,7 @@ import {
   GUARDRAILS_FEATURE_REGISTER_EVENT,
   GUARDRAILS_FEATURE_REQUEST_EVENT,
 } from "../../src/shared/events";
+import { piDocumentationPaths } from "./dynamic-resources";
 import {
   createPendingGrant,
   isGrantTooBroad,
@@ -28,6 +30,23 @@ import { targetsForTool } from "./targets";
 export default async function pathAccess(pi: ExtensionAPI) {
   await configLoader.load();
 
+  // Pi docs paths depend only on `PI_PACKAGE_DIR` / the package root and are
+  // fixed for the process lifetime, so resolve once at setup.
+  const piDocsPaths = piDocumentationPaths();
+
+  let currentSkillAllowedPaths: AllowedPath[] = [];
+
+  pi.on("before_agent_start", (event) => {
+    const skills = event.systemPromptOptions.skills;
+
+    if (!skills || skills.length === 0) return;
+
+    currentSkillAllowedPaths = skills.flatMap((skill) => [
+      { kind: "file", path: skill.filePath },
+      { kind: "directory", path: skill.baseDir },
+    ]);
+  });
+
   pi.events.on(GUARDRAILS_FEATURE_REQUEST_EVENT, () => {
     pi.events.emit(
       GUARDRAILS_FEATURE_REGISTER_EVENT,
@@ -62,6 +81,8 @@ export default async function pathAccess(pi: ExtensionAPI) {
         mode: config.pathAccess.mode,
         allowedPaths: [
           ...resolveAllowedPaths(config.pathAccess.allowedPaths, ctx.cwd),
+          ...piDocsPaths,
+          ...currentSkillAllowedPaths,
           ...pendingAllowedPaths(acceptedGrants),
         ],
         hasUI: ctx.hasUI,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.13.3",
+  "version": "0.14.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -35,7 +35,7 @@
     "!extensions/**/*.test.ts"
   ],
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.15.1",
+    "@aliou/pi-utils-settings": "^0.17.0",
     "@aliou/sh": "^0.1.0"
   },
   "peerDependencies": {
@@ -46,8 +46,8 @@
     "@aliou/biome-plugins": "^0.8.1",
     "@biomejs/biome": "^2.4.15",
     "@changesets/cli": "^2.27.11",
-    "@earendil-works/pi-coding-agent": "0.74.0",
-    "@earendil-works/pi-tui": "0.74.0",
+    "@earendil-works/pi-coding-agent": "0.79.6",
+    "@earendil-works/pi-tui": "0.79.6",
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",

package/schema.json

@@ -2,6 +2,45 @@
   "$ref": "#/definitions/GuardrailsConfig",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "AllowedPath": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "file",
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "path"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "directory",
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "path"
+          ],
+          "type": "object"
+        }
+      ],
+      "description": "A path grant with an explicit kind.\n\n`file` matches the exact path only. `directory` matches the directory itself and any descendant (boundary/prefix match).\n\nThis replaces the previous trailing-slash convention on a flat `string[]`, where the kind was inferred from whether a path ended in `/`."
+    },
     "DangerousPattern": {
       "additionalProperties": false,
       "description": "Permission gate pattern. When regex is false (default), the pattern is matched as substring against the raw command string. When regex is true, uses full regex against the raw string.",
@@ -180,8 +219,9 @@
       "additionalProperties": false,
       "properties": {
         "allowedPaths": {
+          "description": "Paths always allowed, regardless of cwd. Each entry carries an explicit `kind`: `file` matches the exact path, `directory` matches the directory and its descendants.",
           "items": {
-            "type": "string"
+            "$ref": "#/definitions/AllowedPath"
           },
           "type": "array"
         },

package/src/core/paths/access.ts

@@ -1,4 +1,4 @@
-import { isWithinBoundary } from "./path";
+import { type AllowedPath, isWithinBoundary } from "./path";
 
 export type PathDecision =
   | { kind: "allow" }
@@ -8,25 +8,25 @@ export type PathDecision =
 export interface PathAccessState {
   cwd: string;
   mode: "allow" | "ask" | "block";
-  allowedPaths: string[]; // already resolved to absolute, with trailing / convention
+  allowedPaths: AllowedPath[]; // already resolved to absolute
   hasUI: boolean;
 }
 
 /**
  * Check if an absolute path is covered by the allowedPaths list.
- * - Entries ending in "/" are directory grants (boundary/prefix match).
- * - Entries without trailing "/" are exact file grants.
+ *
+ * `directory` grants match the directory itself and any descendant (boundary
+ * match). `file` grants match the exact path only.
  */
 export function isPathAllowed(
   absPath: string,
-  allowedPaths: string[],
+  allowedPaths: AllowedPath[],
 ): boolean {
   for (const entry of allowedPaths) {
-    if (entry.endsWith("/")) {
-      const dirPath = entry.slice(0, -1);
-      if (isWithinBoundary(absPath, dirPath)) return true;
+    if (entry.kind === "directory") {
+      if (isWithinBoundary(absPath, entry.path)) return true;
     } else {
-      if (absPath === entry) return true;
+      if (absPath === entry.path) return true;
     }
   }
   return false;

package/src/core/paths/index.ts

@@ -5,10 +5,11 @@ export {
   type PathDecision,
 } from "./access";
 export {
+  type AllowedPath,
   expandHomePath,
   isWithinBoundary,
   maybePathLike,
   normalizeForDisplay,
   resolveFromCwd,
-  toStorageForm,
+  toStorageGrant,
 } from "./path";

package/src/core/paths/path.ts

@@ -1,6 +1,19 @@
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
+/**
+ * A path grant with an explicit kind.
+ *
+ * `file` matches the exact path only. `directory` matches the directory itself
+ * and any descendant (boundary/prefix match).
+ *
+ * This replaces the previous trailing-slash convention on a flat `string[]`,
+ * where the kind was inferred from whether a path ended in `/`.
+ */
+export type AllowedPath =
+  | { kind: "file"; path: string }
+  | { kind: "directory"; path: string };
+
 /**
  * Expand a leading tilde to the current user's home directory.
  * Preserves all other paths unchanged.
@@ -52,9 +65,27 @@ export function normalizeForDisplay(absPath: string, cwd: string): string {
 
 /**
  * Convert an absolute path to storage form for config persistence.
- * Uses ~/ for home paths, absolute otherwise. Appends trailing / for directory grants.
+ *
+ * Uses `~/` for home paths, absolute otherwise, and normalizes separators to
+ * forward slash. The kind (file vs directory) is carried explicitly on the
+ * returned `AllowedPath` instead of via a trailing slash.
+ */
+export function toStorageGrant(
+  absPath: string,
+  isDirectory: boolean,
+): AllowedPath {
+  return {
+    kind: isDirectory ? "directory" : "file",
+    path: toStoragePath(absPath),
+  };
+}
+
+/**
+ * Normalize an absolute path for storage: expand home to `~/`, collapse
+ * backslashes to forward slashes, and strip any trailing slash (the kind now
+ * lives on `AllowedPath`, not on the path string).
  */
-export function toStorageForm(absPath: string, isDirectory: boolean): string {
+function toStoragePath(absPath: string): string {
   const home = homedir();
   let stored: string;
   if (
@@ -66,10 +97,8 @@ export function toStorageForm(absPath: string, isDirectory: boolean): string {
   } else {
     stored = absPath;
   }
-  // Normalize separators to forward slash for storage
   stored = stored.replace(/\\/g, "/");
-  if (isDirectory && !stored.endsWith("/")) stored += "/";
-  if (!isDirectory && stored.endsWith("/")) stored = stored.slice(0, -1);
+  stored = stored.replace(/\/+$/, "");
   return stored;
 }
 

package/src/shared/config/defaults.ts

@@ -12,7 +12,7 @@ export const DEFAULT_CONFIG: ResolvedConfig = {
   },
   pathAccess: {
     mode: "ask",
-    allowedPaths: [],
+    allowedPaths: [{ kind: "file", path: "/dev/null" }],
   },
   policies: {
     rules: [

package/src/shared/config/index.ts

@@ -6,6 +6,7 @@ export {
   migrations,
 } from "./migration";
 export type {
+  AllowedPath,
   DangerousPattern,
   GuardrailsConfig,
   PathAccessConfig,

package/src/shared/config/loader.ts

@@ -4,6 +4,7 @@ import {
   type Scope,
 } from "@aliou/pi-utils-settings";
 import pkg from "../../../package.json" with { type: "json" };
+import type { AllowedPath } from "../../core/paths/path";
 import { DEFAULT_CONFIG } from "./defaults";
 import { migrations } from "./migration";
 import type { GuardrailsConfig, PolicyRule, ResolvedConfig } from "./types";
@@ -63,18 +64,21 @@ export function createGuardrailsConfigLoader(): GuardrailsConfigLoader {
         resolved.permissionGate.useBuiltinMatchers = false;
       }
 
-      const mergedPaths = new Set<string>();
+      const mergedPaths = new Map<string, AllowedPath>();
       for (const paths of [
         global?.pathAccess?.allowedPaths,
         local?.pathAccess?.allowedPaths,
         memory?.pathAccess?.allowedPaths,
       ]) {
-        for (const path of paths ?? []) {
-          const trimmed = path.trim();
-          if (trimmed) mergedPaths.add(trimmed);
+        for (const entry of paths ?? []) {
+          if (!entry || typeof entry !== "object") continue;
+          const path = typeof entry.path === "string" ? entry.path.trim() : "";
+          if (!path) continue;
+          const kind = entry.kind === "directory" ? "directory" : "file";
+          mergedPaths.set(`${kind}:${path}`, { kind, path });
         }
       }
-      resolved.pathAccess.allowedPaths = [...mergedPaths];
+      resolved.pathAccess.allowedPaths = [...mergedPaths.values()];
 
       return resolved;
     },

package/src/shared/config/migration/001-v0-format-upgrade.ts

@@ -1,6 +1,5 @@
 import { copyFile, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { addPendingWarning } from "../../warnings";
 import type {
   DangerousPattern,
   GuardrailsConfig,
@@ -101,7 +100,7 @@ async function backupConfig(configPath: string): Promise<void> {
     try {
       await copyFile(configPath, backupPath);
     } catch (err) {
-      addPendingWarning(`guardrails: could not back up config: ${err}`);
+      console.error(`[guardrails] could not back up config: ${err}`);
     }
   }
 }

package/src/shared/config/migration/002-strip-toolchain-fields.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -20,12 +19,6 @@ export function shouldRun(config: GuardrailsConfig): boolean {
 }
 
 export function run(config: GuardrailsConfig): GuardrailsConfig {
-  addPendingWarning(
-    "[guardrails] preventBrew, preventPython, enforcePackageManager, and packageManager " +
-      "have been removed from guardrails and moved to @aliou/pi-toolchain. " +
-      "These fields will be stripped from your config.",
-  );
-
   const cleaned = structuredClone(config) as Record<string, unknown>;
   const features = cleaned.features as Record<string, unknown> | undefined;
   if (features) {

package/src/shared/config/migration/003-strip-command-explainer-fields.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -23,11 +22,6 @@ export function shouldRun(config: GuardrailsConfig): boolean {
 }
 
 export function run(config: GuardrailsConfig): GuardrailsConfig {
-  addPendingWarning(
-    "[guardrails] permissionGate.explainCommands, explainModel, and explainTimeout " +
-      "have been removed. These fields will be stripped from your config.",
-  );
-
   const cleaned = structuredClone(config) as Record<string, unknown>;
   const permissionGate = cleaned.permissionGate as
     | Record<string, unknown>

package/src/shared/config/migration/004-env-files-to-policies.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -15,7 +14,6 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
   const raw = migrated as Record<string, unknown>;
   const features = raw.features as Record<string, unknown> | undefined;
   const envFiles = raw.envFiles as Record<string, unknown> | undefined;
-
   if (features?.protectEnvFiles !== undefined) {
     features.policies = features.protectEnvFiles;
     delete features.protectEnvFiles;
@@ -62,10 +60,9 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
     }
 
     if (Array.isArray(envFiles.protectedTools)) {
-      addPendingWarning(
-        "[guardrails] envFiles.protectedTools is deprecated and has no direct policies equivalent. " +
-          "The migrated secret-files rule uses protection=noAccess.",
-      );
+      // protectedTools has no policies equivalent; the migrated secret-files
+      // rule uses protection=noAccess. The deprecation note is surfaced via
+      // the `message` factory exported below.
     }
 
     if (!Array.isArray(rule.patterns) || rule.patterns.length === 0) {
@@ -85,3 +82,19 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
   raw.version = CURRENT_VERSION;
   return migrated as GuardrailsConfig;
 }
+
+/**
+ * Message for the envFiles-to-policies migration. Only surface the
+ * protectedTools deprecation note when the pre-migration config actually had
+ * protectedTools set; return undefined otherwise so no message is queued.
+ */
+export function message(before: GuardrailsConfig): string | undefined {
+  const envFiles = (before as Record<string, unknown>).envFiles as
+    | Record<string, unknown>
+    | undefined;
+  if (!Array.isArray(envFiles?.protectedTools)) return undefined;
+  return (
+    "envFiles.protectedTools is deprecated and has no direct policies equivalent. " +
+    "The migrated secret-files rule uses protection=noAccess."
+  );
+}

package/src/shared/config/migration/005-normalize-allowed-paths.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -6,7 +5,12 @@ export function shouldRun(config: GuardrailsConfig): boolean {
   const raw = config as Record<string, unknown>;
   const pathAccess = raw.pathAccess as Record<string, unknown> | undefined;
   if (!Array.isArray(pathAccess?.allowedPaths)) return false;
-  return pathAccess.allowedPaths.some((item) => typeof item !== "string");
+  return pathAccess.allowedPaths.some(
+    (item) =>
+      typeof item === "object" &&
+      item !== null &&
+      typeof (item as Record<string, unknown>).pattern === "string",
+  );
 }
 
 export function run(config: GuardrailsConfig): GuardrailsConfig {
@@ -16,9 +20,6 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
 
   pathAccess.allowedPaths = normalizeAllowedPaths(pathAccess.allowedPaths);
   migrated.version = CURRENT_VERSION;
-  addPendingWarning(
-    "[guardrails] pathAccess.allowedPaths was migrated from pattern objects to path strings.",
-  );
   return migrated as GuardrailsConfig;
 }
 
@@ -31,8 +32,11 @@ function normalizeAllowedPaths(items: unknown): string[] {
     if (typeof item === "string") {
       path = item;
     } else if (typeof item === "object" && item !== null) {
-      const pattern = (item as Record<string, unknown>).pattern;
+      const obj = item as Record<string, unknown>;
+      const pattern = obj.pattern;
+      const objectPath = obj.path;
       if (typeof pattern === "string") path = pattern;
+      else if (typeof objectPath === "string") path = objectPath;
     }
 
     const normalized = path?.trim();

package/src/shared/config/migration/006-apply-builtin-defaults.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -11,9 +10,5 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
   migrated.applyBuiltinDefaults = true;
   migrated.version = CURRENT_VERSION;
 
-  addPendingWarning(
-    "Guardrails config was migrated. `applyBuiltinDefaults` was set to `true` to preserve current behavior.",
-  );
-
   return migrated;
 }

package/src/shared/config/migration/007-mark-onboarding-done.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -11,9 +10,6 @@ export function shouldRun(config: GuardrailsConfig): boolean {
 
 export function run(config: GuardrailsConfig): GuardrailsConfig {
   const migrated = structuredClone(config);
-  addPendingWarning(
-    "Guardrails config was migrated. Existing setup marked as onboarding-complete.",
-  );
   migrated.onboarding = {
     ...(migrated.onboarding ?? {}),
     completed: true,

package/src/shared/config/migration/008-normalize-string-booleans.ts

@@ -1,4 +1,3 @@
-import { addPendingWarning } from "../../warnings";
 import type { GuardrailsConfig } from "../types";
 import { CURRENT_VERSION } from "./version";
 
@@ -48,9 +47,6 @@ export function run(config: GuardrailsConfig): GuardrailsConfig {
 
   if (changed) {
     migrated.version = CURRENT_VERSION;
-    addPendingWarning(
-      "[guardrails] Config migrated: boolean settings stored as strings were converted to true/false.",
-    );
   }
 
   return migrated as GuardrailsConfig;

package/src/shared/config/migration/009-allow-dev-null.ts

@@ -0,0 +1,43 @@
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+const DEV_NULL = "/dev/null";
+
+/**
+ * Does an allowedPaths entry (legacy string or { kind, path } object) refer
+ * to /dev/null? Format-agnostic so this migration does not re-run on configs
+ * already migrated to the object form.
+ */
+function includesDevNull(allowedPaths: unknown[] | undefined): boolean {
+  return (allowedPaths ?? []).some((entry) => {
+    if (typeof entry === "string") return entry === DEV_NULL;
+    if (entry && typeof entry === "object") {
+      const obj = entry as { path?: unknown };
+      return obj.path === DEV_NULL;
+    }
+    return false;
+  });
+}
+
+export function shouldRun(config: GuardrailsConfig): boolean {
+  return (
+    config.onboarding?.completed === true &&
+    config.features?.pathAccess === true &&
+    config.pathAccess?.mode === "ask" &&
+    !includesDevNull(config.pathAccess?.allowedPaths)
+  );
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  const pathAccess = migrated.pathAccess ?? {};
+  const allowedPaths = pathAccess.allowedPaths ?? [];
+
+  migrated.pathAccess = {
+    ...pathAccess,
+    allowedPaths: [...allowedPaths, { kind: "file", path: DEV_NULL }],
+  };
+  migrated.version = CURRENT_VERSION;
+
+  return migrated;
+}

package/src/shared/config/migration/010-allowed-paths-objects.ts

@@ -0,0 +1,65 @@
+import type { GuardrailsConfig } from "../types";
+import { CURRENT_VERSION } from "./version";
+
+/**
+ * Migrate `pathAccess.allowedPaths` from the legacy flat `string[]` (where the
+ * kind was inferred from a trailing `/`) to the explicit `{ kind, path }`
+ * object form.
+ *
+ * - Strings ending in `/` become `{ kind: "directory", path }` (slash stripped).
+ * - Other strings become `{ kind: "file", path }`.
+ * - Entries already in object form are normalized (kind validated, trailing
+ *   slash stripped from directory paths).
+ *
+ * Runtime code only handles the object form; this migration is the exclusive
+ * owner of the legacy string shape.
+ */
+export function shouldRun(config: GuardrailsConfig): boolean {
+  const raw = config as Record<string, unknown>;
+  const pathAccess = raw.pathAccess as Record<string, unknown> | undefined;
+  if (!Array.isArray(pathAccess?.allowedPaths)) return false;
+  return pathAccess.allowedPaths.some((item) => typeof item === "string");
+}
+
+export function run(config: GuardrailsConfig): GuardrailsConfig {
+  const migrated = structuredClone(config) as Record<string, unknown>;
+  const pathAccess = migrated.pathAccess as Record<string, unknown> | undefined;
+  if (pathAccess && Array.isArray(pathAccess.allowedPaths)) {
+    pathAccess.allowedPaths = (pathAccess.allowedPaths as unknown[])
+      .map((item) => toAllowedPath(item))
+      .filter(
+        (item): item is { kind: "file" | "directory"; path: string } =>
+          item !== null,
+      );
+  }
+  migrated.version = CURRENT_VERSION;
+  return migrated as GuardrailsConfig;
+}
+
+function toAllowedPath(
+  item: unknown,
+): { kind: "file" | "directory"; path: string } | null {
+  if (typeof item === "string") {
+    const trimmed = item.trim();
+    if (!trimmed) return null;
+    if (trimmed.endsWith("/")) {
+      return { kind: "directory", path: trimmed.slice(0, -1) };
+    }
+    return { kind: "file", path: trimmed };
+  }
+
+  if (item && typeof item === "object") {
+    const obj = item as { kind?: unknown; path?: unknown };
+    const path = typeof obj.path === "string" ? obj.path.trim() : "";
+    if (!path) return null;
+    if (obj.kind === "file" || obj.kind === "directory") {
+      const cleanPath =
+        obj.kind === "directory" && path.endsWith("/")
+          ? path.slice(0, -1)
+          : path;
+      return { kind: obj.kind, path: cleanPath };
+    }
+  }
+
+  return null;
+}

package/src/shared/config/migration/index.ts

@@ -8,6 +8,8 @@ import * as normalizeAllowedPaths from "./005-normalize-allowed-paths";
 import * as applyBuiltinDefaults from "./006-apply-builtin-defaults";
 import * as markOnboardingDone from "./007-mark-onboarding-done";
 import * as normalizeStringBooleans from "./008-normalize-string-booleans";
+import * as allowDevNull from "./009-allow-dev-null";
+import * as allowedPathsObjects from "./010-allowed-paths-objects";
 
 export { CURRENT_VERSION } from "./version";
 
@@ -21,26 +23,52 @@ export const migrations: Migration<GuardrailsConfig>[] = [
     name: "strip-toolchain-fields",
     shouldRun: stripToolchainFields.shouldRun,
     run: stripToolchainFields.run,
+    message:
+      "preventBrew, preventPython, enforcePackageManager, and packageManager " +
+      "have been removed from guardrails and moved to @aliou/pi-toolchain. " +
+      "These fields will be stripped from your config.",
   },
   {
     name: "strip-command-explainer-fields",
     shouldRun: stripCommandExplainerFields.shouldRun,
     run: stripCommandExplainerFields.run,
+    message:
+      "permissionGate.explainCommands, explainModel, and explainTimeout " +
+      "have been removed. These fields will be stripped from your config.",
   },
   {
-    name: "envFiles-to-policies",
+    name: "env-files-to-policies",
     shouldRun: envFilesToPolicies.shouldRun,
     run: envFilesToPolicies.run,
+    message: envFilesToPolicies.message,
   },
   {
     name: "normalize-allowed-paths",
     shouldRun: normalizeAllowedPaths.shouldRun,
     run: normalizeAllowedPaths.run,
+    message:
+      "pathAccess.allowedPaths was migrated from pattern objects to path strings.",
   },
   {
     name: "normalize-string-booleans",
     shouldRun: normalizeStringBooleans.shouldRun,
     run: normalizeStringBooleans.run,
+    message:
+      "Config migrated: boolean settings stored as strings were converted to true/false.",
+  },
+  {
+    name: "allow-dev-null",
+    shouldRun: allowDevNull.shouldRun,
+    run: allowDevNull.run,
+    message:
+      "pathAccess.allowedPaths was migrated to allow /dev/null by default.",
+  },
+  {
+    name: "allowed-paths-objects",
+    shouldRun: allowedPathsObjects.shouldRun,
+    run: allowedPathsObjects.run,
+    message:
+      "pathAccess.allowedPaths was migrated from path strings to { kind, path } objects.",
   },
 ];
 

package/src/shared/config/migration/version.ts

@@ -4,4 +4,4 @@
  * Keep this independent from package.json version.
  * Bump only when config schema/default migration markers change.
  */
-export const CURRENT_VERSION = "0.9.0-20260327";
+export const CURRENT_VERSION = "0.13.0-20260619";

package/src/shared/config/types.ts

@@ -6,6 +6,14 @@
  */
 import type { GuardrailsFeatureId } from "../events";
 
+/**
+ * A path grant with an explicit kind. Re-exported from the core path module so
+ * config consumers can import it from one place.
+ */
+export type { AllowedPath } from "../../core/paths/path";
+
+import type { AllowedPath } from "../../core/paths/path";
+
 /**
  * A pattern with explicit matching mode.
  * Default: glob for files, substring for commands.
@@ -60,7 +68,12 @@ export type PathAccessMode = "allow" | "ask" | "block";
 
 export interface PathAccessConfig {
   mode?: PathAccessMode;
-  allowedPaths?: string[];
+  /**
+   * Paths always allowed, regardless of cwd. Each entry carries an explicit
+   * `kind`: `file` matches the exact path, `directory` matches the directory
+   * and its descendants.
+   */
+  allowedPaths?: AllowedPath[];
 }
 
 export interface GuardrailsConfig {
@@ -127,7 +140,7 @@ export interface ResolvedConfig {
   };
   pathAccess: {
     mode: PathAccessMode;
-    allowedPaths: string[];
+    allowedPaths: AllowedPath[];
   };
   permissionGate: {
     patterns: DangerousPattern[];

package/src/shared/index.ts

@@ -3,4 +3,3 @@ export * from "./events";
 export * from "./glob";
 export * from "./matching";
 export * from "./paths";
-export * from "./warnings";

package/src/shared/matching.ts

@@ -10,7 +10,6 @@
 
 import { matchesGlob } from "node:path";
 import type { PatternConfig } from "./config";
-import { addPendingWarning } from "./warnings";
 
 export interface CompiledPattern {
   test: (input: string) => boolean;
@@ -47,9 +46,10 @@ export function compileFilePattern(config: PatternConfig): CompiledPattern {
         source: config,
       };
     } catch {
-      addPendingWarning(
-        `Invalid regex in guardrails config: ${config.pattern}`,
-      );
+      // TODO: surface invalid regex to the user via ctx.ui.notify once pattern
+      // compilation is pre-cached at extension setup (so it has ctx access and
+      // runs once, instead of re-firing on every tool call). For now the
+      // pattern silently matches nothing.
       return { test: () => false, source: config };
     }
   }
@@ -80,9 +80,10 @@ export function compileCommandPattern(config: PatternConfig): CompiledPattern {
       const re = new RegExp(config.pattern);
       return { test: (input) => re.test(input), source: config };
     } catch {
-      addPendingWarning(
-        `Invalid regex in guardrails config: ${config.pattern}`,
-      );
+      // TODO: surface invalid regex to the user via ctx.ui.notify once pattern
+      // compilation is pre-cached at extension setup (so it has ctx access and
+      // runs once, instead of re-firing on every tool call). For now the
+      // pattern silently matches nothing.
       return { test: () => false, source: config };
     }
   }

package/src/shared/warnings.ts

@@ -1,17 +0,0 @@
-/**
- * Module-level warnings queue for messages that arise before any session
- * context is available (config loading, migration, pattern compilation).
- */
-const pendingWarnings: string[] = [];
-
-export function addPendingWarning(message: string): void {
-  pendingWarnings.push(message);
-}
-
-export function getPendingWarnings(): readonly string[] {
-  return pendingWarnings;
-}
-
-export function drainPendingWarnings(): string[] {
-  return pendingWarnings.splice(0);
-}