@gotgenes/pi-permission-system 5.16.0 → 5.18.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.18.0](https://github.com/gotgenes/pi-permission-system/compare/v5.17.0...v5.18.0) (2026-05-14)
+
+
+### Features
+
+* add package.json exports field for cross-extension import ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([1091de5](https://github.com/gotgenes/pi-permission-system/commit/1091de5eb673050c3b83448ee69cffb876c407d9))
+* add Symbol.for()-backed service accessor module ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([6a7ddab](https://github.com/gotgenes/pi-permission-system/commit/6a7ddab6e3e58ca0f93807255e9e48716d96ca24))
+* publish permissions service on startup, clear on shutdown ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([97bea7b](https://github.com/gotgenes/pi-permission-system/commit/97bea7bec043de4f6abb823846cef5c04a069517))
+
+
+### Documentation
+
+* deprecate permissions:rpc:check types in favor of service accessor ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([a64b1b9](https://github.com/gotgenes/pi-permission-system/commit/a64b1b91f141e1a98b576433280ad09d95ec3011))
+* document service accessor and deprecate RPC check ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([931a14e](https://github.com/gotgenes/pi-permission-system/commit/931a14efec1ef9bc53075f8974bfd1eeff7e0749))
+* plan Symbol.for()-backed service accessor ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([d9448bc](https://github.com/gotgenes/pi-permission-system/commit/d9448bc8c9ee71714599a18f03cf516a5ffca2cb))
+* **retro:** add retro notes for issue [#148](https://github.com/gotgenes/pi-permission-system/issues/148) ([84e0262](https://github.com/gotgenes/pi-permission-system/commit/84e026264e292357c18c0333b1d1bd561f70149b))
+
+## [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
 
@@ -86,7 +91,7 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 |---|---|
 |[docs/configuration.md](docs/configuration.md)|Full policy reference, runtime knobs, per-agent overrides, recipes|
 |[docs/session-approvals.md](docs/session-approvals.md)|Session-scoped rules, pattern suggestions, bash arity table|
-|[docs/event-api.md](docs/event-api.md)|Event bus integration, decision broadcasts, RPC check/prompt|
+|[docs/cross-extension-api.md](docs/cross-extension-api.md)|Cross-extension service accessor, event bus integration, decision broadcasts|
 |[docs/subagent-integration.md](docs/subagent-integration.md)|Permission forwarding, coexistence with subagent extensions|
 |[docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md)|Convention guide for subagent extension authors|
 |[docs/opencode-compatibility.md](docs/opencode-compatibility.md)|OpenCode compatibility — shared concepts, divergences, porting guide|

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,8 +1,11 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.16.0",
+  "version": "5.18.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
+  "exports": {
+    ".": "./src/service.ts"
+  },
   "files": [
     "src",
     "tests",

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/index.ts

@@ -8,6 +8,7 @@ import {
   PermissionGateHandler,
   SessionLifecycleHandler,
 } from "./handlers";
+import { buildInputForSurface } from "./input-normalizer";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { emitReadyEvent } from "./permission-events";
@@ -19,6 +20,11 @@ import {
   refreshExtensionConfig,
   saveExtensionConfig,
 } from "./runtime";
+import type { PermissionsService } from "./service";
+import {
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "./service";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import {
@@ -91,6 +97,20 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     writeReviewLog: runtime.writeReviewLog.bind(runtime),
   });
 
+  const permissionsService: PermissionsService = {
+    checkPermission(surface, value, agentName) {
+      const input = buildInputForSurface(surface, value);
+      const sessionRules = runtime.sessionRules.getRuleset();
+      return runtime.permissionManager.checkPermission(
+        surface,
+        input,
+        agentName,
+        sessionRules,
+      );
+    },
+  };
+  publishPermissionsService(permissionsService);
+
   emitReadyEvent(pi.events);
 
   const toolRegistry = {
@@ -101,6 +121,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const lifecycle = new SessionLifecycleHandler(session, () => {
     rpcHandles.unsubCheck();
     rpcHandles.unsubPrompt();
+    unpublishPermissionsService();
   });
   const agentPrep = new AgentPrepHandler(session, toolRegistry);
   const gates = new PermissionGateHandler(session, pi.events, toolRegistry);

package/src/input-normalizer.ts

@@ -2,6 +2,34 @@ import { toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "./path-utils";
 
+/**
+ * Construct a surface-appropriate input object from a raw value string.
+ *
+ * This is the inverse of `normalizeInput()` — it builds the minimal input
+ * object that `PermissionManager.checkPermission()` expects for a given
+ * surface, from a single string value.
+ *
+ * Used by the event-bus RPC handler and the `Symbol.for()` service accessor
+ * so external callers can query policy with `(surface, value)` instead of
+ * constructing a full tool-call input payload.
+ *
+ * Note: MCP inputs are complex (server name + tool name derivation). Callers
+ * providing an MCP surface receive a best-effort policy evaluation using the
+ * value as a pre-qualified target string. Pass the fully-qualified target
+ * (e.g. "exa:search" or "exa") directly.
+ */
+export function buildInputForSurface(
+  surface: string,
+  value: string | undefined,
+): unknown {
+  const v = value ?? "";
+  if (surface === "bash") return { command: v };
+  if (surface === "skill") return { name: v };
+  if (surface === "external_directory") return { path: v };
+  // MCP and tool surfaces: normalizeInput handles them from the surface alone.
+  return {};
+}
+
 /**
  * Surface-normalized representation of a tool invocation used by
  * `checkPermission()` to feed a single `evaluateFirst()` call.
@@ -22,7 +50,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