@aliou/pi-guardrails 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "license": "MIT",
   "type": "module",
   "private": false,

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"];
 
@@ -691,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;
 
@@ -1067,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,
@@ -1231,10 +1400,9 @@ export function registerGuardrailsSettings(pi: ExtensionAPI): void {
               description:
                 "Paths always allowed (trailing / for directories). Supports ~/",
               currentValue: count("pathAccess.allowedPaths"),
-              submenu: patternConfigSubmenu(
+              submenu: pathListSubmenu(
                 "pathAccess.allowedPaths",
                 "Allowed Paths",
-                "file",
               ),
             },
           ],

package/src/config.ts

@@ -137,10 +137,13 @@ import { ConfigLoader, type Migration } from "@aliou/pi-utils-settings";
 import {
   backupConfig,
   CURRENT_VERSION,
+  migrateAllowedPaths,
   migrateEnvFilesToPolicies,
   migrateV0,
+  needsAllowedPathsMigration,
   needsEnvFilesToPoliciesMigration,
   needsMigration,
+  normalizeAllowedPaths,
 } from "./utils/migration";
 import { pendingWarnings } from "./utils/warnings";
 
@@ -204,6 +207,11 @@ const migrations: Migration<GuardrailsConfig>[] = [
     shouldRun: (config) => needsEnvFilesToPoliciesMigration(config),
     run: (config) => migrateEnvFilesToPolicies(config),
   },
+  {
+    name: "normalize-allowed-paths",
+    shouldRun: (config) => needsAllowedPathsMigration(config),
+    run: (config) => migrateAllowedPaths(config),
+  },
 ];
 
 const DEFAULT_CONFIG: ResolvedConfig = {
@@ -374,9 +382,7 @@ export const configLoader = new ConfigLoader<GuardrailsConfig, ResolvedConfig>(
         local?.pathAccess?.allowedPaths,
         memory?.pathAccess?.allowedPaths,
       ]) {
-        if (paths) {
-          for (const p of paths) mergedPaths.add(p);
-        }
+        for (const p of normalizeAllowedPaths(paths)) mergedPaths.add(p);
       }
       resolved.pathAccess.allowedPaths = [...mergedPaths];
 

package/src/hooks/path-access.ts

@@ -12,6 +12,7 @@ import {
 import { configLoader } from "../config";
 import { extractBashPathCandidates } from "../utils/bash-paths";
 import { emitBlocked } from "../utils/events";
+import { normalizeAllowedPaths } from "../utils/migration";
 import {
   normalizeForDisplay,
   resolveFromCwd,
@@ -246,9 +247,7 @@ async function persistGrant(
     unknown
   >;
   const pa = (raw.pathAccess ?? {}) as Record<string, unknown>;
-  const existing = Array.isArray(pa.allowedPaths)
-    ? (pa.allowedPaths as string[])
-    : [];
+  const existing = normalizeAllowedPaths(pa.allowedPaths);
 
   if (existing.includes(storagePath)) return;
 

package/src/hooks/policies.ts

@@ -10,7 +10,7 @@ import {
   compileFilePatterns,
   normalizeFilePath,
 } from "../utils/matching";
-import { expandHomePath } from "../utils/path";
+import { expandHomePath, maybePathLike } from "../utils/path";
 import { walkCommands, wordToString } from "../utils/shell-utils";
 import { pendingWarnings } from "../utils/warnings";
 
@@ -108,16 +108,6 @@ function compileRules(rules: PolicyRule[]): CompiledRule[] {
   return compiled;
 }
 
-function maybePathLike(token: string): boolean {
-  return (
-    token.includes("/") ||
-    token.includes(".") ||
-    token.startsWith("~") ||
-    token.startsWith("./") ||
-    token.startsWith("../")
-  );
-}
-
 function normalizeTargetForPolicy(filePath: string, cwd: string): string {
   if (filePath === "~" || filePath.startsWith("~/")) {
     return normalizeFilePath(filePath);

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

@@ -6,6 +6,56 @@ const CWD = "/work/project";
 const HOME = homedir();
 
 describe("extractBashPathCandidates", () => {
+  describe("when a command has regular expression arguments", () => {
+    it("ignores sed expressions and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "sed 's/abc/{2,3}/g' ./file",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/file"]);
+    });
+
+    it("ignores grep patterns and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "grep '/api/v1' ./src",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/src"]);
+    });
+
+    it("ignores ripgrep patterns and extracts search roots", async () => {
+      const result = await extractBashPathCandidates("rg '/api/v1' ./src", CWD);
+      expect(result).toEqual(["/work/project/src"]);
+    });
+
+    it("ignores jq filters and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "jq '.path | test(\"^/tmp/\")' ./data.json",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/data.json"]);
+    });
+
+    it("ignores interpreter inline code", async () => {
+      const result = await extractBashPathCandidates(
+        "python3 -c 'open(\"/etc/passwd\").read()'",
+        CWD,
+      );
+      expect(result).toEqual([]);
+    });
+  });
+
+  // Regression: github issue #32 — awk regex patterns should not be
+  // treated as file paths.
+  it("does not extract awk regex patterns as paths", async () => {
+    const result = await extractBashPathCandidates(
+      "awk '/aaa/{flag=1} flag{print}' test.txt",
+      CWD,
+    );
+    // The awk program should NOT be treated as a path
+    expect(result).toEqual([]);
+  });
+
   describe("when command has path arguments", () => {
     it("extracts a single absolute path", async () => {
       expect(await extractBashPathCandidates("cat /etc/hosts", CWD)).toEqual([

package/src/utils/bash-paths.ts

@@ -1,25 +1,10 @@
 import { resolve } from "node:path";
 import { parse } from "@aliou/sh";
+import { classifyCommandArgs } from "./command-args";
 import { expandGlob, hasGlobChars } from "./glob-expander";
-import { expandHomePath } from "./path";
+import { expandHomePath, maybePathLike } from "./path";
 import { walkCommands, wordToString } from "./shell-utils";
 
-/**
- * Heuristic: is this token likely a filesystem path?
- * Intentionally conservative — only structural signals.
- * Known false positives: "application/json", URL paths. These cause
- * spurious prompts in ask mode but are safe (better to over-prompt than miss).
- * Known false negatives: bare filenames without path separators (e.g. "README.md").
- * These are usually cwd-relative and would pass the boundary check anyway.
- */
-function maybePathLike(token: string): boolean {
-  if (token.includes("/")) return true;
-  if (token.includes("\\")) return true;
-  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
-  if (token.startsWith("~")) return true;
-  return false;
-}
-
 async function expandCandidate(
   candidate: string,
   cwd: string,
@@ -64,8 +49,11 @@ export async function extractBashPathCandidates(
 
     walkCommands(ast, (cmd) => {
       const words = (cmd.words ?? []).map(wordToString);
-      for (let i = 1; i < words.length; i++) {
-        pending.push(addCandidate(words[i] as string));
+      const commandName = words[0];
+      if (commandName) {
+        for (const arg of classifyCommandArgs(commandName, words.slice(1))) {
+          pending.push(addCandidate(arg.token, arg.forcePath));
+        }
       }
       for (const redir of cmd.redirects ?? []) {
         pending.push(addCandidate(wordToString(redir.target), true));

package/src/utils/command-args.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { classifyCommandArgs } from "./command-args";
+
+const tokens = (command: string, args: string[]) =>
+  classifyCommandArgs(command, args).map((arg) => arg.token);
+
+describe("classifyCommandArgs", () => {
+  it("keeps unknown command arguments unchanged", () => {
+    expect(tokens("cat", ["/etc/hosts", "./file"])).toEqual([
+      "/etc/hosts",
+      "./file",
+    ]);
+  });
+
+  it("ignores awk inline program and keeps file operands", () => {
+    expect(tokens("awk", ["/aaa/{print}", "./input"])).toEqual(["./input"]);
+  });
+
+  it("keeps awk -f program files", () => {
+    expect(tokens("awk", ["-f", "./prog.awk", "./input"])).toEqual([
+      "./prog.awk",
+      "./input",
+    ]);
+  });
+
+  it("ignores sed inline scripts and keeps file operands", () => {
+    expect(tokens("sed", ["s#/old#/new#g", "./file"])).toEqual(["./file"]);
+  });
+
+  it("keeps sed -f script files", () => {
+    expect(tokens("sed", ["-f", "./script.sed", "./file"])).toEqual([
+      "./script.sed",
+      "./file",
+    ]);
+  });
+
+  it("ignores grep patterns and keeps file operands", () => {
+    expect(tokens("grep", ["/api/v1", "./src"])).toEqual(["./src"]);
+  });
+
+  it("keeps grep pattern files", () => {
+    expect(tokens("grep", ["-f", "./patterns", "./src"])).toEqual([
+      "./patterns",
+      "./src",
+    ]);
+  });
+
+  it("keeps find roots and ignores expression patterns", () => {
+    expect(tokens("find", ["./src", "-regex", ".*/test/.*"])).toEqual([
+      "./src",
+    ]);
+  });
+
+  it("ignores jq filters and keeps file operands", () => {
+    expect(tokens("jq", ['.path | test("^/tmp/")', "./data.json"])).toEqual([
+      "./data.json",
+    ]);
+  });
+
+  it("keeps jq -f filter files", () => {
+    expect(tokens("jq", ["-f", "./filter.jq", "./data.json"])).toEqual([
+      "./filter.jq",
+      "./data.json",
+    ]);
+  });
+
+  it("ignores interpreter inline code", () => {
+    expect(tokens("python3", ["-c", 'open("/etc/passwd")'])).toEqual([]);
+  });
+
+  it("keeps interpreter script operands", () => {
+    expect(tokens("python3", ["./script.py", "./data.json"])).toEqual([
+      "./script.py",
+      "./data.json",
+    ]);
+  });
+
+  it("ignores delimiter args", () => {
+    expect(tokens("cut", ["-d", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("sort", ["-t", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("tr", ["/", ":"])).toEqual([]);
+  });
+});

package/src/utils/command-args.ts

@@ -0,0 +1,226 @@
+import { basename } from "node:path";
+
+export type ClassifiedArg = { token: string; forcePath?: boolean };
+
+function normalizeCommandName(command: string): string {
+  return basename(command).toLowerCase();
+}
+
+function isOption(arg: string): boolean {
+  return arg.startsWith("-") && arg !== "-" && arg !== "--";
+}
+
+export function classifyCommandArgs(
+  command: string,
+  args: string[],
+): ClassifiedArg[] {
+  const cmd = normalizeCommandName(command);
+
+  if (cmd === "awk" || cmd === "gawk" || cmd === "mawk" || cmd === "nawk") {
+    return classifyAwkArgs(args);
+  }
+  if (cmd === "sed" || cmd === "gsed") return classifySedArgs(args);
+  if (["grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack"].includes(cmd)) {
+    return classifyGrepLikeArgs(args);
+  }
+  if (cmd === "find" || cmd === "gfind") return classifyFindArgs(args);
+  if (cmd === "jq" || cmd === "yq") return classifyFilterCommandArgs(args);
+  if (
+    ["python", "python2", "python3", "node", "ruby", "perl", "php"].includes(
+      cmd,
+    )
+  ) {
+    return classifyInterpreterArgs(cmd, args);
+  }
+  if (cmd === "cut")
+    return skipOptionValues(args, new Set(["-d", "--delimiter"]));
+  if (cmd === "sort")
+    return skipOptionValues(args, new Set(["-t", "--field-separator"]));
+  if (cmd === "tr") return [];
+
+  return args.map((token) => ({ token }));
+}
+
+function classifyAwkArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let sawProgram = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "--") continue;
+    if (arg === "-f") {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      sawProgram = true;
+      continue;
+    }
+    if (arg === "-v" || arg === "-F") {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      out.push({ token: arg.slice(2) });
+      sawProgram = true;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!sawProgram) {
+      sawProgram = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifySedArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let hasExplicitScript = false;
+  let skippedImplicitScript = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-e" || arg === "--expression") {
+      hasExplicitScript = true;
+      i++;
+      continue;
+    }
+    if (arg === "-f" || arg === "--file") {
+      hasExplicitScript = true;
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+    if (arg.startsWith("-e") && arg.length > 2) {
+      hasExplicitScript = true;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      hasExplicitScript = true;
+      out.push({ token: arg.slice(2) });
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!hasExplicitScript && !skippedImplicitScript) {
+      skippedImplicitScript = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyGrepLikeArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let patternProvided = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-e" || arg === "--regexp") {
+      patternProvided = true;
+      i++;
+      continue;
+    }
+    if (arg === "-f" || arg === "--file") {
+      patternProvided = true;
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+    if (["-g", "--glob", "-t", "-T", "--type", "--type-not"].includes(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-e") && arg.length > 2) {
+      patternProvided = true;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      patternProvided = true;
+      out.push({ token: arg.slice(2) });
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!patternProvided) {
+      patternProvided = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyFindArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let inExpression = false;
+  const patternOptions = new Set([
+    "-name",
+    "-iname",
+    "-path",
+    "-ipath",
+    "-regex",
+    "-iregex",
+    "-wholename",
+    "-iwholename",
+  ]);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (!inExpression && !arg.startsWith("-") && arg !== "(" && arg !== "!") {
+      out.push({ token: arg });
+      continue;
+    }
+    inExpression = true;
+    if (patternOptions.has(arg)) i++;
+  }
+  return out;
+}
+
+function classifyFilterCommandArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let sawFilter = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-f" || arg === "--from-file") {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      sawFilter = true;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!sawFilter) {
+      sawFilter = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyInterpreterArgs(cmd: string, args: string[]): ClassifiedArg[] {
+  const codeFlags =
+    cmd === "python" || cmd.startsWith("python")
+      ? new Set(["-c"])
+      : cmd === "php"
+        ? new Set(["-r"])
+        : new Set(["-e"]);
+  const out: ClassifiedArg[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (codeFlags.has(arg)) {
+      i++;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function skipOptionValues(
+  args: string[],
+  optionsWithValues: Set<string>,
+): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (optionsWithValues.has(arg)) {
+      i++;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}

package/src/utils/migration.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import type { GuardrailsConfig } from "../config";
+import {
+  migrateAllowedPaths,
+  needsAllowedPathsMigration,
+  normalizeAllowedPaths,
+} from "./migration";
+
+describe("allowedPaths migration", () => {
+  it("normalizes strings and legacy pattern objects", () => {
+    expect(
+      normalizeAllowedPaths([
+        "/dev/null",
+        { pattern: "~/Downloads/" },
+        { pattern: " /tmp/file " },
+        { pattern: "" },
+        { regex: true },
+        42,
+        null,
+        "/dev/null",
+      ]),
+    ).toEqual(["/dev/null", "~/Downloads/", "/tmp/file"]);
+  });
+
+  it("detects legacy object-shaped allowed paths", () => {
+    const config = {
+      pathAccess: {
+        allowedPaths: [{ pattern: "/dev/null" }],
+      },
+    } as unknown as GuardrailsConfig;
+
+    expect(needsAllowedPathsMigration(config)).toBe(true);
+  });
+
+  it("does not migrate valid string allowed paths", () => {
+    const config: GuardrailsConfig = {
+      pathAccess: {
+        allowedPaths: ["/dev/null"],
+      },
+    };
+
+    expect(needsAllowedPathsMigration(config)).toBe(false);
+  });
+
+  it("converts legacy object-shaped allowed paths to strings", () => {
+    const config = {
+      pathAccess: {
+        mode: "block",
+        allowedPaths: [{ pattern: "/dev/null" }, "~/Downloads/"],
+      },
+    } as unknown as GuardrailsConfig;
+
+    expect(migrateAllowedPaths(config).pathAccess?.allowedPaths).toEqual([
+      "/dev/null",
+      "~/Downloads/",
+    ]);
+  });
+});

package/src/utils/migration.ts

@@ -151,6 +151,51 @@ export function migrateMarkOnboardingDone(
   return migrated;
 }
 
+/**
+ * Migrate allowedPaths entries accidentally written as PatternConfig objects.
+ */
+export function needsAllowedPathsMigration(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 normalizeAllowedPaths(items: unknown): string[] {
+  if (!Array.isArray(items)) return [];
+
+  const paths = new Set<string>();
+  for (const item of items) {
+    let path: string | null = null;
+    if (typeof item === "string") {
+      path = item;
+    } else if (typeof item === "object" && item !== null) {
+      const pattern = (item as Record<string, unknown>).pattern;
+      if (typeof pattern === "string") path = pattern;
+    }
+
+    const normalized = path?.trim();
+    if (normalized) paths.add(normalized);
+  }
+
+  return [...paths];
+}
+
+export function migrateAllowedPaths(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config) as Record<string, unknown>;
+  const pathAccess = migrated.pathAccess as Record<string, unknown> | undefined;
+  if (!pathAccess) return migrated as GuardrailsConfig;
+
+  pathAccess.allowedPaths = normalizeAllowedPaths(pathAccess.allowedPaths);
+  migrated.version = CURRENT_VERSION;
+  pendingWarnings.push(
+    "[guardrails] pathAccess.allowedPaths was migrated from pattern objects to path strings.",
+  );
+  return migrated as GuardrailsConfig;
+}
+
 /**
  * Migrate deprecated envFiles/protectEnvFiles fields to policies.
  */

package/src/utils/path.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   expandHomePath,
   isWithinBoundary,
+  maybePathLike,
   normalizeForDisplay,
   resolveFromCwd,
   toStorageForm,
@@ -175,3 +176,118 @@ describe("toStorageForm", () => {
     expect(toStorageForm(absPath, isDirectory)).toBe(expected);
   });
 });
+
+describe("maybePathLike", () => {
+  it.each([
+    // --- True cases: structural path signals ---
+    {
+      desc: "absolute Unix path",
+      input: "/etc/hosts",
+      expected: true,
+    },
+    {
+      desc: "relative path with /",
+      input: "src/index.ts",
+      expected: true,
+    },
+    {
+      desc: "./ prefix",
+      input: "./foo",
+      expected: true,
+    },
+    {
+      desc: "../ prefix",
+      input: "../bar",
+      expected: true,
+    },
+    {
+      desc: "backslash path (Windows)",
+      input: "foo\\bar",
+      expected: true,
+    },
+    {
+      desc: "Windows drive letter",
+      input: "C:\\tmp",
+      expected: true,
+    },
+    {
+      desc: "Windows drive with forward slash",
+      input: "C:/tmp",
+      expected: true,
+    },
+    {
+      desc: "tilde home path",
+      input: "~/code",
+      expected: true,
+    },
+    {
+      desc: "MIME type (has / — safe false positive)",
+      input: "application/json",
+      expected: true,
+    },
+    {
+      desc: "regular expression with braces (has / — safe false positive)",
+      input: "/abc/{2,3}",
+      expected: true,
+    },
+    // --- False cases: non-path tokens ---
+    {
+      desc: "empty string",
+      input: "",
+      expected: false,
+    },
+    {
+      desc: "simple command name",
+      input: "rm",
+      expected: false,
+    },
+    {
+      desc: "flag",
+      input: "--force",
+      expected: false,
+    },
+    {
+      desc: "short flag",
+      input: "-rf",
+      expected: false,
+    },
+    {
+      desc: "bare word",
+      input: "build",
+      expected: false,
+    },
+    {
+      desc: "bare tilde (no slash)",
+      input: "~",
+      expected: false,
+    },
+    {
+      desc: "version number",
+      input: "3.14",
+      expected: false,
+    },
+    {
+      desc: "domain name",
+      input: "example.com",
+      expected: false,
+    },
+    {
+      desc: "bare filename with extension",
+      input: "README.md",
+      expected: false,
+    },
+    {
+      desc: "dotfile without slash",
+      input: ".env",
+      expected: false,
+    },
+  ])("when $desc, returns $expected", ({ input, expected }) => {
+    expect(maybePathLike(input)).toBe(expected);
+  });
+
+  // maybePathLike is command-agnostic. Command-specific regex/code args are
+  // filtered by extractBashPathCandidates before this fallback heuristic runs.
+  it("treats awk-looking regex text as path-like without command context", () => {
+    expect(maybePathLike("/aaa/{flag=1} flag{print}")).toBe(true);
+  });
+});

package/src/utils/path.ts

@@ -72,3 +72,26 @@ export function toStorageForm(absPath: string, isDirectory: boolean): string {
   if (!isDirectory && stored.endsWith("/")) stored = stored.slice(0, -1);
   return stored;
 }
+
+/**
+ * Heuristic: is this token likely a filesystem path?
+ *
+ * Checks for structural path signals: separators (/ \), drive letters
+ * (C:\), home prefix (~), and relative path prefixes (./ ../).
+ *
+ * False positives (MIME types, version strings, domains) are safe —
+ * they just get checked against policies and miss.
+ *
+ * Known false negatives: bare filenames without separators or dots
+ * (Makefile, LICENSE, README). These are cwd-relative and would
+ * pass the boundary check anyway.
+ */
+export function maybePathLike(token: string): boolean {
+  if (!token) return false;
+
+  if (token.includes("/")) return true;
+  if (token.includes("\\")) return true;
+  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
+  if (/^(?:~|\.{1,2})[\\/]/.test(token)) return true;
+  return false;
+}