@gotgenes/pi-permission-system 5.15.0 → 5.17.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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)
+
+
+### Features
+
+* decision events include file path for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([eea226d](https://github.com/gotgenes/pi-permission-system/commit/eea226d990d4358983cc319d54b7544849b2b453))
+* normalizeInput returns file path for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([0b48995](https://github.com/gotgenes/pi-permission-system/commit/0b4899563ed3aaf2dd264650a98964168e7ecba1))
+* path-scoped session approvals for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([1feacc5](https://github.com/gotgenes/pi-permission-system/commit/1feacc53d4ac1653bf974886ce77e13aff014b68))
+
+
+### Documentation
+
+* document per-tool path patterns ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([81245f6](https://github.com/gotgenes/pi-permission-system/commit/81245f6ac98500e6c4d3c2191ceb2db032284f05))
+* plan per-tool path patterns for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([9458706](https://github.com/gotgenes/pi-permission-system/commit/9458706d85e4711b73677ee1abcc8f3ad7d18a2e))
+
 ## [5.15.0](https://github.com/gotgenes/pi-permission-system/compare/v5.14.1...v5.15.0) (2026-05-13)
 
 

package/README.md

@@ -34,6 +34,12 @@ pi install npm:@gotgenes/pi-permission-system
     {
       "permission": {
         "*": "allow",
+        "path": {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow"
+        },
         "bash": {
           "rm -rf *": "deny",
           "sudo *": "ask"
@@ -56,6 +62,14 @@ 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.
 
+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
 
 Config lives in one JSON file per scope:

package/config/config.example.json

@@ -9,8 +9,15 @@
 
   "permission": {
     "*": "ask",
+    "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.15.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\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,8 +63,15 @@
       "examples": [
         {
           "*": "ask",
+          "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/helpers.ts

@@ -3,14 +3,17 @@ import type { PermissionCheckResult } from "../../types";
 
 /**
  * Derive the human-readable value for a decision event from a check result.
- * Bash → extracted command; MCP → qualified target; others → tool name.
+ * Bash → extracted command; MCP → qualified target;
+ * path-bearing tools → file path; others → tool name.
  */
 export function deriveDecisionValue(
   toolName: string,
   check: Pick<PermissionCheckResult, "command" | "target">,
+  path?: string,
 ): string {
   if (toolName === "bash") return check.command ?? toolName;
   if (toolName === "mcp") return check.target ?? toolName;
+  if (path) return path;
   return toolName;
 }
 

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/gates/tool.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "../../path-utils";
+import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
 import {
   formatAskPrompt,
@@ -11,6 +11,21 @@ import type { GateDescriptor } from "./descriptor";
 import { deriveDecisionValue } from "./helpers";
 import type { ToolCallContext } from "./types";
 
+/**
+ * Derive the value used for session-approval pattern suggestions.
+ *
+ * Bash → command string; MCP → qualified target;
+ * path-bearing tools → file path; others → catch-all wildcard.
+ */
+function deriveSuggestionValue(
+  tcc: ToolCallContext,
+  check: PermissionCheckResult,
+): string {
+  if (tcc.toolName === "bash") return check.command ?? "";
+  if (tcc.toolName === "mcp") return check.target ?? "mcp";
+  return getPathBearingToolPath(tcc.toolName, tcc.input) ?? "*";
+}
+
 /**
  * Build a pure descriptor for the normal tool permission gate.
  *
@@ -28,13 +43,10 @@ export function describeToolGate(
   );
 
   // Compute session approval suggestion for the "for this session" option.
-  const suggestionValue =
-    tcc.toolName === "bash"
-      ? (check.command ?? "")
-      : tcc.toolName === "mcp"
-        ? (check.target ?? "mcp")
-        : "*";
-  const suggestion = suggestSessionPattern(tcc.toolName, suggestionValue);
+  const suggestion = suggestSessionPattern(
+    tcc.toolName,
+    deriveSuggestionValue(tcc, check),
+  );
 
   // Build the unavailable-reason message. Bash gets the command embedded.
   const inputCommand =
@@ -85,7 +97,11 @@ export function describeToolGate(
     },
     decision: {
       surface: tcc.toolName,
-      value: deriveDecisionValue(tcc.toolName, check),
+      value: deriveDecisionValue(
+        tcc.toolName,
+        check,
+        getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
+      ),
     },
   };
 }

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

@@ -1,5 +1,6 @@
 import { toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
+import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "./path-utils";
 
 /**
  * Surface-normalized representation of a tool invocation used by
@@ -21,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
@@ -85,7 +86,17 @@ export function normalizeInput(
     };
   }
 
-  // --- Tool surfaces (read, write, edit, grep, find, ls, extension tools) ---
+  // --- Path-bearing tools (read, write, edit, grep, find, ls) ---
+  if (PATH_BEARING_TOOLS.has(toolName)) {
+    const path = getPathBearingToolPath(toolName, input);
+    return {
+      surface: toolName,
+      values: [path ?? "*"],
+      resultExtras: {},
+    };
+  }
+
+  // --- Extension tools (non-path-bearing) ---
   return {
     surface: toolName,
     values: ["*"],