@gotgenes/pi-permission-system 5.16.0 → 5.17.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.17.0](https://github.com/gotgenes/pi-permission-system/compare/v5.16.0...v5.17.0) (2026-05-14)
+
+
+### Features
+
+* bash path gate with broader token extraction ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([affe202](https://github.com/gotgenes/pi-permission-system/commit/affe20284c7b579facc46ba489a1b6b0e2acc949))
+* broader token extraction for path rules ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([6303641](https://github.com/gotgenes/pi-permission-system/commit/6303641a6efc3265e209799b93d4c8bcbc17c6a0))
+* evaluateMostRestrictive helper for cross-cutting path evaluation ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([5260f21](https://github.com/gotgenes/pi-permission-system/commit/5260f21f149f8cd9b3331c4e418bc9091db2acdb))
+* integrate path gates into permission pipeline ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([36fb30e](https://github.com/gotgenes/pi-permission-system/commit/36fb30e2564a8707b8e6eb8b798b90d536623c53))
+* path gate for tool path restrictions ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([cc53681](https://github.com/gotgenes/pi-permission-system/commit/cc5368103686eee0849644cffce463c2851dff3c))
+* register path as a special permission surface ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([356bcf7](https://github.com/gotgenes/pi-permission-system/commit/356bcf74b3028894319ea3c63b5d4b014b7bfe48))
+
+
+### Documentation
+
+* document cross-cutting path permission surface ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([3bd4478](https://github.com/gotgenes/pi-permission-system/commit/3bd4478c95197550485910c4364d35203ff53ada))
+* include edit alongside write in config examples ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([f083ccc](https://github.com/gotgenes/pi-permission-system/commit/f083ccc0316e0689390e5ecc16e14ab40baca1d9))
+* plan path-aware bash permission rules ([#148](https://github.com/gotgenes/pi-permission-system/issues/148)) ([71ff973](https://github.com/gotgenes/pi-permission-system/commit/71ff973edd57d75801b75044e238139e90a8490f))
+* **retro:** add retro notes for issue [#147](https://github.com/gotgenes/pi-permission-system/issues/147) ([e40402b](https://github.com/gotgenes/pi-permission-system/commit/e40402b018703c37c8af436dc4e15665216f59c7))
+
 ## [5.16.0](https://github.com/gotgenes/pi-permission-system/compare/v5.15.0...v5.16.0) (2026-05-13)
 
 

package/README.md

@@ -34,7 +34,7 @@ pi install npm:@gotgenes/pi-permission-system
     {
       "permission": {
         "*": "allow",
-        "read": {
+        "path": {
           "*": "allow",
           "*.env": "deny",
           "*.env.*": "deny",
@@ -62,8 +62,13 @@ All permissions use one of three states:
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 See [docs/session-approvals.md](docs/session-approvals.md) for details on session-scoped rules and pattern suggestions.
 
-For path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns in the permission map are matched against the file path from `input.path`.
-This lets you express rules like "allow reads but deny `.env` files" — see the example config above.
+The `path` surface is a cross-cutting gate that applies to **all** file access — both Pi tools and bash commands.
+A `path` deny cannot be overridden by a per-tool allow, making it the right place to protect sensitive files like `.env` or `~/.ssh/*` from every tool at once.
+
+For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`.
+This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.
+
+Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `external_directory` (CWD boundary) → per-tool patterns → `bash` command patterns.
 
 ## Configuration
 

package/config/config.example.json

@@ -9,13 +9,15 @@
 
   "permission": {
     "*": "ask",
-    "read": {
+    "path": {
       "*": "allow",
       "*.env": "deny",
       "*.env.*": "deny",
       "*.env.example": "allow"
     },
+    "read": "allow",
     "write": "deny",
+    "edit": "deny",
     "bash": {
       "*": "ask",
       "git status": "allow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.16.0",
+  "version": "5.17.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/schemas/permissions.schema.json

@@ -41,7 +41,7 @@
     },
     "permission": {
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
-      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access — both Pi tools and bash commands. A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all tools at once.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "type": "object",
       "propertyNames": {
         "description": "A surface name or the universal fallback key '*'.",
@@ -63,13 +63,15 @@
       "examples": [
         {
           "*": "ask",
-          "read": {
+          "path": {
             "*": "allow",
             "*.env": "deny",
             "*.env.*": "deny",
             "*.env.example": "allow"
           },
+          "read": "allow",
           "write": "deny",
+          "edit": "deny",
           "bash": {
             "*": "ask",
             "git status": "allow",

package/src/handlers/gates/bash-path-extractor.ts

@@ -433,6 +433,43 @@ const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
  */
 const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
 
+/**
+ * Broader token classification for cross-cutting `path` rules.
+ *
+ * Accepts the same rejections as `classifyTokenAsPathCandidate` (empty, flags,
+ * env assignments, URLs, @scope/package, bare-slash, regex metacharacters),
+ * but also accepts:
+ * - Tokens starting with `.` (dot-files: `.env`, `./src`)
+ * - Tokens containing `/` (relative paths: `src/foo.ts`)
+ *
+ * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
+ * gate that the external-directory classifier uses.
+ */
+function classifyTokenAsRuleCandidate(token: string): string | null {
+  if (!token) return null;
+  if (token.startsWith("-")) return null;
+
+  const eqIndex = token.indexOf("=");
+  const slashIndex = token.indexOf("/");
+  if (eqIndex !== -1 && (slashIndex === -1 || eqIndex < slashIndex)) {
+    return null;
+  }
+
+  if (URL_PATTERN.test(token)) return null;
+  if (token.startsWith("@") && !token.startsWith("@/")) return null;
+  if (/^\/+$/.test(token)) return null;
+  if (REGEX_METACHAR_PATTERN.test(token)) return null;
+
+  // Accept: starts with . (dot-files, ./ relative), contains / (paths),
+  // starts with / or ~/ (absolute/home), or contains .. (parent traversal).
+  if (token.startsWith(".")) return token;
+  if (token.includes("/")) return token;
+  if (token.startsWith("~/")) return token;
+  if (token.includes("..")) return token;
+
+  return null;
+}
+
 /**
  * Determines whether a token looks like a path candidate worth resolving.
  * Returns the raw token string if it's a candidate, or null to skip.
@@ -516,3 +553,41 @@ export async function extractExternalPathsFromBashCommand(
 
   return externalPaths;
 }
+
+/**
+ * Extract tokens from a bash command that may be file paths, using a broader
+ * filter suitable for cross-cutting `path` permission rules.
+ *
+ * Unlike `extractExternalPathsFromBashCommand`, this function:
+ * - Accepts relative paths (`.env`, `src/foo.ts`, `./build`)
+ * - Does NOT filter by CWD — returns raw tokens for rule evaluation
+ * - Returns deduplicated tokens
+ */
+export async function extractTokensForPathRules(
+  command: string,
+): Promise<string[]> {
+  const parser = await getParser();
+  const tree = parser.parse(command);
+  if (!tree) return [];
+
+  const tokens: string[] = [];
+  try {
+    collectPathCandidateTokens(tree.rootNode, tokens);
+  } finally {
+    tree.delete();
+  }
+
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const token of tokens) {
+    const candidate = classifyTokenAsRuleCandidate(token);
+    if (!candidate) continue;
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      result.push(candidate);
+    }
+  }
+
+  return result;
+}

package/src/handlers/gates/bash-path.ts

@@ -0,0 +1,146 @@
+import { getNonEmptyString, toRecord } from "../../common";
+import type { Rule } from "../../rule";
+import { deriveApprovalPattern } from "../../session-rules";
+import type { PermissionCheckResult } from "../../types";
+import { extractTokensForPathRules } from "./bash-path-extractor";
+import type { GateResult } from "./descriptor";
+import { formatPathAskPrompt, formatPathDenyReason } from "./path";
+import type { ToolCallContext } from "./types";
+
+/** Function type for checkPermission used by the descriptor factory. */
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+  sessionRules?: Rule[],
+) => PermissionCheckResult;
+
+/**
+ * Build a pure descriptor for the cross-cutting path permission gate (bash).
+ *
+ * Extracts path-candidate tokens from a bash command using tree-sitter with
+ * the broader filter (accepts dot-files, relative paths). Evaluates each
+ * token against the `path` permission surface and returns the most
+ * restrictive result.
+ *
+ * Returns `null` when the gate does not apply (tool is not bash, no command,
+ * no tokens extracted, or all tokens evaluate to `allow`).
+ * Returns a `GateBypass` when all tokens are session-covered.
+ * Returns a `GateDescriptor` for the most restrictive token needing a check.
+ */
+export async function describeBashPathGate(
+  tcc: ToolCallContext,
+  checkPermission: CheckPermissionFn,
+  getSessionRuleset: () => Rule[],
+): Promise<GateResult> {
+  if (tcc.toolName !== "bash") return null;
+
+  const command = getNonEmptyString(toRecord(tcc.input).command);
+  if (!command) return null;
+
+  const tokens = await extractTokensForPathRules(command);
+  if (tokens.length === 0) return null;
+
+  // Check each token against path rules with session rules appended.
+  const sessionRules = getSessionRuleset();
+
+  let worstCheck: PermissionCheckResult | null = null;
+  let worstToken: string | null = null;
+  let allSessionCovered = true;
+
+  for (const token of tokens) {
+    const check = checkPermission(
+      "path",
+      { path: token },
+      tcc.agentName ?? undefined,
+      sessionRules,
+    );
+
+    if (check.source !== "session") {
+      allSessionCovered = false;
+    }
+
+    if (check.state === "deny") {
+      worstCheck = check;
+      worstToken = token;
+      break; // Short-circuit on deny.
+    }
+    if (check.state === "ask" && (!worstCheck || worstCheck.state !== "ask")) {
+      worstCheck = check;
+      worstToken = token;
+    }
+  }
+
+  // All tokens are session-covered — bypass.
+  if (allSessionCovered) {
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.session_approved",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          command,
+          tokens,
+          resolution: "session_approved",
+        },
+      },
+    };
+  }
+
+  // All tokens evaluate to allow — no restriction.
+  if (!worstCheck || !worstToken) return null;
+
+  const pattern = deriveApprovalPattern(worstToken);
+  const askMessage = formatPathAskPrompt(
+    tcc.toolName,
+    worstToken,
+    tcc.agentName ?? undefined,
+  );
+
+  return {
+    surface: "path",
+    input: { path: worstToken },
+    messages: {
+      denyReason: formatPathDenyReason(
+        tcc.toolName,
+        worstToken,
+        tcc.agentName ?? undefined,
+      ),
+      unavailableReason: `Bash command '${command}' accesses path '${worstToken}' which requires approval, but no interactive UI is available.`,
+      userDeniedReason: (decision) => {
+        const reasonSuffix = decision.denialReason
+          ? ` Reason: ${decision.denialReason}.`
+          : "";
+        return `User denied path access for bash command '${command}' (path '${worstToken}').${reasonSuffix} Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
+      },
+    },
+    sessionApproval: {
+      surface: "path",
+      pattern,
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: askMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      command,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      command,
+      path: worstToken,
+    },
+    decision: {
+      surface: "path",
+      value: worstToken,
+    },
+    preCheck: worstCheck,
+  };
+}

package/src/handlers/gates/index.ts

@@ -1,4 +1,5 @@
 export { describeBashExternalDirectoryGate } from "./bash-external-directory";
+export { describeBashPathGate } from "./bash-path";
 export type {
   GateBypass,
   GateDescriptor,
@@ -8,6 +9,7 @@ export type {
 export { isGateBypass, isGateDescriptor } from "./descriptor";
 export { describeExternalDirectoryGate } from "./external-directory";
 export { deriveDecisionValue, deriveResolution } from "./helpers";
+export { describePathGate } from "./path";
 export { runGateCheck } from "./runner";
 export { describeSkillReadGate } from "./skill-read";
 export { describeToolGate } from "./tool";

package/src/handlers/gates/path.ts

@@ -0,0 +1,104 @@
+import { getPathBearingToolPath } from "../../path-utils";
+import { deriveApprovalPattern } from "../../session-rules";
+import type { PermissionCheckResult } from "../../types";
+import type { GateDescriptor, GateResult } from "./descriptor";
+import type { ToolCallContext } from "./types";
+
+/** Function type for checkPermission used by the descriptor factory. */
+type CheckPermissionFn = (
+  surface: string,
+  input: unknown,
+  agentName?: string,
+) => PermissionCheckResult;
+
+/**
+ * Build a pure descriptor for the cross-cutting path permission gate (tools).
+ *
+ * Returns `null` when the gate does not apply (tool is not path-bearing,
+ * no extractable path, or the `path` surface evaluates to `allow`).
+ * Returns a `GateDescriptor` when the path matches a `deny` or `ask` rule.
+ */
+export function describePathGate(
+  tcc: ToolCallContext,
+  checkPermission: CheckPermissionFn,
+): GateResult {
+  const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
+  if (!filePath) return null;
+
+  const check = checkPermission(
+    "path",
+    { path: filePath },
+    tcc.agentName ?? undefined,
+  );
+
+  if (check.state === "allow") return null;
+
+  const pattern = deriveApprovalPattern(filePath);
+
+  const descriptor: GateDescriptor = {
+    surface: "path",
+    input: { path: filePath },
+    messages: {
+      denyReason: formatPathDenyReason(
+        tcc.toolName,
+        filePath,
+        tcc.agentName ?? undefined,
+      ),
+      unavailableReason: `Accessing '${filePath}' requires approval, but no interactive UI is available.`,
+      userDeniedReason: (decision) => {
+        const reasonSuffix = decision.denialReason
+          ? ` Reason: ${decision.denialReason}.`
+          : "";
+        return `User denied access to path '${filePath}'.${reasonSuffix} Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
+      },
+    },
+    sessionApproval: {
+      surface: "path",
+      pattern,
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: formatPathAskPrompt(
+        tcc.toolName,
+        filePath,
+        tcc.agentName ?? undefined,
+      ),
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      path: filePath,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      path: filePath,
+    },
+    decision: {
+      surface: "path",
+      value: filePath,
+    },
+    preCheck: check,
+  };
+
+  return descriptor;
+}
+
+export function formatPathDenyReason(
+  toolName: string,
+  pathValue: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} is not permitted to access path '${pathValue}' via tool '${toolName}'. Hard stop: this path permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.`;
+}
+
+export function formatPathAskPrompt(
+  toolName: string,
+  pathValue: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested tool '${toolName}' for path '${pathValue}'. Allow this path access?`;
+}

package/src/handlers/permission-gate-handler.ts

@@ -22,9 +22,11 @@ import {
   type ToolRegistry,
 } from "../tool-registry";
 import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
+import { describeBashPathGate } from "./gates/bash-path";
 import type { GateRunnerDeps } from "./gates/descriptor";
 import { isGateBypass } from "./gates/descriptor";
 import { describeExternalDirectoryGate } from "./gates/external-directory";
+import { describePathGate } from "./gates/path";
 import { runGateCheck } from "./gates/runner";
 import { describeSkillReadGate } from "./gates/skill-read";
 import { describeToolGate } from "./gates/tool";
@@ -140,6 +142,26 @@ export class PermissionGateHandler {
       }
     }
 
+    // ── Path gate for tools (descriptor + runner) ────────────────────────────
+    const pathDesc = describePathGate(tcc, checkPermission);
+    if (pathDesc) {
+      if (isGateBypass(pathDesc)) {
+        if (pathDesc.log) {
+          writeReviewLog(pathDesc.log.event, pathDesc.log.details);
+        }
+      } else {
+        const pathResult = await runGateCheck(
+          pathDesc,
+          tcc.agentName,
+          tcc.toolCallId,
+          runnerDeps,
+        );
+        if (pathResult.action === "block") {
+          return { block: true, reason: pathResult.reason };
+        }
+      }
+    }
+
     // ── External-directory gate (descriptor + runner) ────────────────────────
     const infraDirs = [
       ...session.getInfrastructureDirs(),
@@ -191,6 +213,30 @@ export class PermissionGateHandler {
       }
     }
 
+    // ── Bash path gate (descriptor + runner) ────────────────────────────────
+    const bashPathDesc = await describeBashPathGate(
+      tcc,
+      checkPermission,
+      getSessionRuleset,
+    );
+    if (bashPathDesc) {
+      if (isGateBypass(bashPathDesc)) {
+        if (bashPathDesc.log) {
+          writeReviewLog(bashPathDesc.log.event, bashPathDesc.log.details);
+        }
+      } else {
+        const bashPathResult = await runGateCheck(
+          bashPathDesc,
+          tcc.agentName,
+          tcc.toolCallId,
+          runnerDeps,
+        );
+        if (bashPathResult.action === "block") {
+          return { block: true, reason: bashPathResult.reason };
+        }
+      }
+    }
+
     // ── Normal tool permission gate (descriptor + runner) ────────────────────
     const toolCheck = checkPermission(
       tcc.toolName,

package/src/input-normalizer.ts

@@ -22,7 +22,7 @@ export interface NormalizedInput {
   resultExtras: Record<string, unknown>;
 }
 
-const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
 
 /**
  * Map a raw tool invocation to the surface/values/extras triple needed by

package/src/permission-manager.ts

@@ -30,7 +30,7 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "find",
   "ls",
 ]);
-const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
 
 /** Universal fallback when permission["*"] is absent from all scopes. */
 const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";

package/src/rule.ts

@@ -79,6 +79,33 @@ export function evaluate(
  * evaluating the first candidate so the caller always receives a concrete
  * result.
  */
+/**
+ * Evaluate a surface against multiple values, returning the most restrictive
+ * non-allow result (deny > ask > allow).
+ *
+ * Used by the cross-cutting `path` surface to aggregate permission decisions
+ * across multiple file paths extracted from a single tool call or bash command.
+ *
+ * Returns `null` when all values evaluate to `allow` (no restriction).
+ * Returns the first `deny` immediately (short-circuit).
+ * Returns the first `ask` if no `deny` is found.
+ */
+export function evaluateMostRestrictive(
+  surface: string,
+  values: string[],
+  rules: Ruleset,
+): { rule: Rule; value: string } | null {
+  let worst: { rule: Rule; value: string } | null = null;
+  for (const value of values) {
+    const rule = evaluate(surface, value, rules);
+    if (rule.action === "deny") return { rule, value };
+    if (rule.action === "ask" && worst?.rule.action !== "ask") {
+      worst = { rule, value };
+    }
+  }
+  return worst;
+}
+
 export function evaluateFirst(
   surface: string,
   values: string[],

package/tests/bash-external-directory.test.ts

@@ -9,7 +9,10 @@ vi.mock("node:os", () => {
   };
 });
 
-import { extractExternalPathsFromBashCommand } from "../src/handlers/gates/bash-path-extractor";
+import {
+  extractExternalPathsFromBashCommand,
+  extractTokensForPathRules,
+} from "../src/handlers/gates/bash-path-extractor";
 import {
   formatBashExternalDirectoryAskPrompt,
   formatBashExternalDirectoryDenyReason,
@@ -887,3 +890,80 @@ describe("formatBashExternalDirectoryDenyReason", () => {
     expect(result).toContain("my-agent");
   });
 });
+
+describe("extractTokensForPathRules", () => {
+  test("extracts dot-files: cat .env", async () => {
+    const tokens = await extractTokensForPathRules("cat .env");
+    expect(tokens).toContain(".env");
+  });
+
+  test("extracts relative dot-paths: git add src/.env", async () => {
+    const tokens = await extractTokensForPathRules("git add src/.env");
+    expect(tokens).toContain("src/.env");
+  });
+
+  test("extracts nothing from plain words: echo hello", async () => {
+    const tokens = await extractTokensForPathRules("echo hello");
+    expect(tokens).toHaveLength(0);
+  });
+
+  test("extracts ./src and skips flags: rm -rf ./src", async () => {
+    const tokens = await extractTokensForPathRules("rm -rf ./src");
+    expect(tokens).toContain("./src");
+    expect(tokens).not.toContain("-rf");
+  });
+
+  test("extracts absolute paths: cat /etc/hosts", async () => {
+    const tokens = await extractTokensForPathRules("cat /etc/hosts");
+    expect(tokens).toContain("/etc/hosts");
+  });
+
+  test("skips URLs: curl https://example.com", async () => {
+    const tokens = await extractTokensForPathRules("curl https://example.com");
+    expect(tokens).not.toContain("https://example.com");
+  });
+
+  test("extracts slash-containing tokens: cat src/foo.ts", async () => {
+    const tokens = await extractTokensForPathRules("cat src/foo.ts");
+    expect(tokens).toContain("src/foo.ts");
+  });
+
+  test("skips heredoc content", async () => {
+    const tokens = await extractTokensForPathRules("cat <<EOF\n.env\nEOF");
+    expect(tokens).not.toContain(".env");
+  });
+
+  test("skips @scope/package patterns", async () => {
+    const tokens = await extractTokensForPathRules(
+      "npm install @scope/package",
+    );
+    expect(tokens).not.toContain("@scope/package");
+  });
+
+  test("skips env assignments", async () => {
+    const tokens = await extractTokensForPathRules("FOO=/bar command");
+    expect(tokens).not.toContain("FOO=/bar");
+  });
+
+  test("skips bare-slash tokens", async () => {
+    const tokens = await extractTokensForPathRules("ls /");
+    expect(tokens).not.toContain("/");
+  });
+
+  test("extracts redirect targets: echo test > .env", async () => {
+    const tokens = await extractTokensForPathRules("echo test > .env");
+    expect(tokens).toContain(".env");
+  });
+
+  test("extracts multiple path tokens: cp .env .env.backup", async () => {
+    const tokens = await extractTokensForPathRules("cp .env .env.backup");
+    expect(tokens).toContain(".env");
+    expect(tokens).toContain(".env.backup");
+  });
+
+  test("deduplicates repeated tokens", async () => {
+    const tokens = await extractTokensForPathRules("cat .env && rm .env");
+    const envCount = tokens.filter((t) => t === ".env").length;
+    expect(envCount).toBe(1);
+  });
+});