@gotgenes/pi-permission-system 10.10.1 → 12.0.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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).
 
+## [12.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v11.0.0...pi-permission-system-v12.0.0) (2026-06-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* extension and MCP tools that expose a filesystem path (input.path, or input.arguments.path for MCP) are now subject to the path and external_directory permission gates. Tools previously ungated may now prompt or be denied under existing path rules.
+
+### Features
+
+* add extensible tool input path extraction ([#352](https://github.com/gotgenes/pi-packages/issues/352)) ([3a54ea1](https://github.com/gotgenes/pi-packages/commit/3a54ea16be4d621bd7474f7a728d97ce9781a994))
+* add tool access extractor registry ([#352](https://github.com/gotgenes/pi-packages/issues/352)) ([7a34f01](https://github.com/gotgenes/pi-packages/commit/7a34f0187f6b3fbb75e056082f04d3b805a37c8a))
+* expose registerToolAccessExtractor via permissions service ([#352](https://github.com/gotgenes/pi-packages/issues/352)) ([5e02c16](https://github.com/gotgenes/pi-packages/commit/5e02c163b212adf9648a2631e4788f030539a36a))
+* gate extension and MCP path tools by default ([#352](https://github.com/gotgenes/pi-packages/issues/352)) ([1d53f4f](https://github.com/gotgenes/pi-packages/commit/1d53f4ffa1a08e953b96437e9adf0214c6ca7465))
+
+
+### Documentation
+
+* document path-aware extension/MCP gating and registerToolAccessExtractor ([#352](https://github.com/gotgenes/pi-packages/issues/352)) ([a2f825f](https://github.com/gotgenes/pi-packages/commit/a2f825f031ec26f1c47dbf13d056e724fda87021))
+
+## [11.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.10.1...pi-permission-system-v11.0.0) (2026-06-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* The permission system no longer auto-activates pi's off-by-default tools (`find`, `grep`, `ls`) in the main session. Users who want them active should enable them via pi's own `activeTools` configuration rather than relying on the permission system to expose every non-denied tool.
+
+### Features
+
+* add getActive to ToolRegistry wired to pi.getActiveTools ([#385](https://github.com/gotgenes/pi-packages/issues/385)) ([79c4594](https://github.com/gotgenes/pi-packages/commit/79c459443294c1b58643b746e3511fc17c9f8961))
+
+
+### Bug Fixes
+
+* respect pi's default active tool set in before_agent_start ([#385](https://github.com/gotgenes/pi-packages/issues/385)) ([bf5be48](https://github.com/gotgenes/pi-packages/commit/bf5be48ca8b06e8cb08f66d08eccb85af0673987))
+
+
+### Documentation
+
+* clarify before_agent_start filters pi's active tool set ([#385](https://github.com/gotgenes/pi-packages/issues/385)) ([bdb5a6a](https://github.com/gotgenes/pi-packages/commit/bdb5a6a08e3c1bb611c8b1795c4d46856104b3b0))
+
 ## [10.10.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.10.0...pi-permission-system-v10.10.1) (2026-06-11)
 
 

package/README.md

@@ -65,8 +65,8 @@ 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.
+The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.
+Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.arguments.path`, or a registered access extractor) are gated by default, so 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.

package/package.json

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

package/schemas/permissions.schema.json

@@ -53,7 +53,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`, `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.",
+      "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 built-in file 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: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware 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 '*'.",

package/src/handlers/before-agent-start.ts

@@ -38,7 +38,7 @@ export function shouldExposeTool(
  * Constructor deps:
  * - `session` — encapsulates all mutable session state and lifecycle operations
  * - `resolver` — owns permission-query surface: `getToolPermission`, `getPolicyCacheStamp`, skill check
- * - `toolRegistry` — Pi tool API subset (getAll + setActive)
+ * - `toolRegistry` — Pi tool API subset (getActive + setActive)
  */
 export class AgentPrepHandler {
   constructor(
@@ -56,10 +56,10 @@ export class AgentPrepHandler {
     this.session.refreshConfig(ctx);
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
-    const allTools = this.toolRegistry.getAll();
+    const activeTools = this.toolRegistry.getActive();
     const allowedTools: string[] = [];
 
-    for (const tool of allTools) {
+    for (const tool of activeTools) {
       const toolName = getToolNameFromValue(tool);
       if (!toolName) {
         continue;

package/src/handlers/gates/external-directory.ts

@@ -1,11 +1,12 @@
 import {
   canonicalNormalizePathForComparison,
-  getPathBearingToolPath,
+  getToolInputPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
 } from "#src/path-utils";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
@@ -21,10 +22,15 @@ import type { ToolCallContext } from "./types";
 export function describeExternalDirectoryGate(
   tcc: ToolCallContext,
   infraDirs: string[],
+  extractors?: ToolAccessExtractorLookup,
 ): GateResult {
   if (!tcc.cwd) return null;
 
-  const externalDirectoryPath = getPathBearingToolPath(tcc.toolName, tcc.input);
+  const externalDirectoryPath = getToolInputPath(
+    tcc.toolName,
+    tcc.input,
+    extractors,
+  );
   if (!externalDirectoryPath) return null;
 
   if (!isPathOutsideWorkingDirectory(externalDirectoryPath, tcc.cwd)) {

package/src/handlers/gates/path.ts

@@ -1,7 +1,8 @@
-import { getPathBearingToolPath } from "#src/path-utils";
+import { getToolInputPath } from "#src/path-utils";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateDescriptor, GateResult } from "./descriptor";
 import type { ToolCallContext } from "./types";
 
@@ -16,8 +17,9 @@ import type { ToolCallContext } from "./types";
 export function describePathGate(
   tcc: ToolCallContext,
   resolver: ScopedPermissionResolver,
+  extractors?: ToolAccessExtractorLookup,
 ): GateResult {
-  const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
+  const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
   if (!filePath) return null;
 
   const check = resolver.resolve(

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,6 +1,7 @@
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
 import {
   ToolPreviewFormatter,
@@ -53,6 +54,7 @@ export class ToolCallGatePipeline {
     private readonly resolver: ScopedPermissionResolver,
     private readonly inputs: ToolCallGateInputs,
     private readonly customFormatters?: ToolInputFormatterLookup,
+    private readonly customExtractors?: ToolAccessExtractorLookup,
   ) {}
 
   async evaluate(
@@ -77,8 +79,9 @@ export class ToolCallGatePipeline {
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
         describeSkillReadGate(tcc, () => this.inputs.getActiveSkillEntries()),
-      () => describePathGate(tcc, this.resolver),
-      () => describeExternalDirectoryGate(tcc, infraDirs),
+      () => describePathGate(tcc, this.resolver, this.customExtractors),
+      () =>
+        describeExternalDirectoryGate(tcc, infraDirs, this.customExtractors),
       () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
       () => describeBashPathGate(tcc, bashProgram, this.resolver),
       () => {

package/src/index.ts

@@ -32,6 +32,7 @@ import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./subagent-registry";
+import { ToolAccessExtractorRegistry } from "./tool-access-extractor-registry";
 import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
@@ -44,6 +45,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const subagentRegistry = getSubagentSessionRegistry();
   const formatterRegistry = new ToolInputFormatterRegistry();
   registerBuiltinToolInputFormatters(formatterRegistry);
+  const accessExtractorRegistry = new ToolAccessExtractorRegistry();
 
   // Both `configStore` and `session` are forward-declared so the logger's
   // lazy thunks can close over them without a cast or null-init holder.
@@ -129,6 +131,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     permissionManager,
     sessionRules,
     formatterRegistry,
+    accessExtractorRegistry,
   );
 
   // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
@@ -152,6 +155,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const toolRegistry = {
     getAll: () => pi.getAllTools(),
+    getActive: () => pi.getActiveTools(),
     setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
@@ -171,6 +175,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     resolver,
     session,
     formatterRegistry,
+    accessExtractorRegistry,
   );
   const skillInputGatePipeline = new SkillInputGatePipeline(resolver);
   const gates = new PermissionGateHandler(

package/src/path-utils.ts

@@ -9,6 +9,7 @@ import {
 import { canonicalizePath } from "./canonicalize-path";
 import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
+import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
 import { wildcardMatch } from "./wildcard-matcher";
 
 export function normalizePathForComparison(
@@ -123,6 +124,46 @@ export function getPathBearingToolPath(
   return getNonEmptyString(toRecord(input).path);
 }
 
+/**
+ * Extract the filesystem path a tool will access, for the cross-cutting `path`
+ * and `external_directory` gates.
+ *
+ * Unlike {@link getPathBearingToolPath} (built-in tools only), this recognizes
+ * extension and MCP tools so they are no longer exempt from path gating:
+ *
+ * - `bash` → `null` (bash has its own token-based path gates).
+ * - Built-in path-bearing tools → `input.path`.
+ * - `mcp` → `input.arguments.path`.
+ * - Any other tool → a registered {@link ToolAccessExtractor}'s path, else the
+ *   default `input.path` convention.
+ */
+export function getToolInputPath(
+  toolName: string,
+  input: unknown,
+  extractors?: ToolAccessExtractorLookup,
+): string | null {
+  if (toolName === "bash") {
+    return null;
+  }
+
+  const record = toRecord(input);
+
+  if (PATH_BEARING_TOOLS.has(toolName)) {
+    return getNonEmptyString(record.path);
+  }
+
+  if (toolName === "mcp") {
+    return getNonEmptyString(toRecord(record.arguments).path);
+  }
+
+  const custom = extractors?.get(toolName);
+  if (custom) {
+    return getNonEmptyString(custom(record));
+  }
+
+  return getNonEmptyString(record.path);
+}
+
 /**
  * Like {@link normalizePathForComparison} but also resolves symlinks via
  * `realpathSync` (best-effort). Use this for containment decisions where the

package/src/permissions-service.ts

@@ -2,6 +2,10 @@ import { buildInputForSurface } from "./input-normalizer";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PermissionsService } from "./service";
 import type { SessionRules } from "./session-rules";
+import type {
+  ToolAccessExtractor,
+  ToolAccessExtractorRegistrar,
+} from "./tool-access-extractor-registry";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistrar,
@@ -19,6 +23,7 @@ export class LocalPermissionsService implements PermissionsService {
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: Pick<SessionRules, "getRuleset">,
     private readonly formatterRegistry: ToolInputFormatterRegistrar,
+    private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar,
   ) {}
 
   checkPermission(
@@ -48,4 +53,11 @@ export class LocalPermissionsService implements PermissionsService {
   ): ReturnType<PermissionsService["registerToolInputFormatter"]> {
     return this.formatterRegistry.register(toolName, formatter);
   }
+
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): ReturnType<PermissionsService["registerToolAccessExtractor"]> {
+    return this.accessExtractorRegistry.register(toolName, extractor);
+  }
 }

package/src/service.ts

@@ -11,6 +11,7 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
+import type { ToolAccessExtractor } from "./tool-access-extractor-registry";
 import type { ToolInputFormatter } from "./tool-input-formatter-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
@@ -80,6 +81,29 @@ export interface PermissionsService {
     formatter: ToolInputFormatter,
   ): () => void;
 
+  /**
+   * Register a custom access-intent extractor for a specific tool name.
+   *
+   * The extractor declares the filesystem path a tool will access so the
+   * cross-cutting `path` and `external_directory` gates can see it. Use it for
+   * tools whose path lives under a non-standard key — built-in file tools and
+   * any tool exposing `input.path` (plus MCP via `input.arguments.path`) are
+   * already covered by convention without registration.
+   *
+   * The extractor receives the raw `input` record and returns the path string,
+   * or `undefined` to decline. Only one extractor may be registered per tool
+   * name — a second call for the same name throws. The returned disposer
+   * unregisters the extractor.
+   *
+   * @param toolName  - Exact tool name to register for (e.g. `"ffgrep"`).
+   * @param extractor - Receives the raw `input` record; return the path string,
+   *                    or `undefined` to decline.
+   */
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): () => void;
+
   /**
    * Query the tool-level permission state for pre-filtering tools before
    * creating a child session.

package/src/tool-access-extractor-registry.ts

@@ -0,0 +1,68 @@
+/**
+ * Registry for custom tool access-intent extractors.
+ *
+ * Lets sibling extensions declare the filesystem path a tool will access when
+ * the tool's input shape is not the default `input.path` convention, so the
+ * cross-cutting `path` and `external_directory` gates can see it.
+ * One extractor per tool name; duplicate registration throws.
+ */
+
+/** Returns the filesystem path this tool will access, or `undefined` to decline. */
+export type ToolAccessExtractor = (
+  input: Record<string, unknown>,
+) => string | undefined;
+
+/**
+ * Read-only lookup used by the gate pipeline (ISP — exposes only the read
+ * side, not the registration surface).
+ */
+export interface ToolAccessExtractorLookup {
+  get(toolName: string): ToolAccessExtractor | undefined;
+}
+
+/**
+ * Registration side of the extractor registry (ISP — exposes only the write
+ * surface, mirroring the read-only {@link ToolAccessExtractorLookup}).
+ */
+export interface ToolAccessExtractorRegistrar {
+  register(toolName: string, extractor: ToolAccessExtractor): () => void;
+}
+
+/**
+ * Persistent registry mapping tool names to custom access-intent extractors.
+ *
+ * Owned by the extension factory (`index.ts`) so it survives across the
+ * per-tool-call gate evaluation cycle.
+ * Exposed to sibling extensions via `PermissionsService.registerToolAccessExtractor`.
+ */
+export class ToolAccessExtractorRegistry
+  implements ToolAccessExtractorLookup, ToolAccessExtractorRegistrar
+{
+  private readonly extractors = new Map<string, ToolAccessExtractor>();
+
+  /**
+   * Register an extractor for `toolName`.
+   *
+   * Throws if an extractor is already registered for that name — keeps
+   * resolution deterministic (a pi-permission-system package priority).
+   * Returns a disposer that removes the extractor; the disposer is
+   * identity-guarded so a stale call cannot evict a later registration.
+   */
+  register(toolName: string, extractor: ToolAccessExtractor): () => void {
+    if (this.extractors.has(toolName)) {
+      throw new Error(
+        `A tool access extractor is already registered for '${toolName}'.`,
+      );
+    }
+    this.extractors.set(toolName, extractor);
+    return () => {
+      if (this.extractors.get(toolName) === extractor) {
+        this.extractors.delete(toolName);
+      }
+    };
+  }
+
+  get(toolName: string): ToolAccessExtractor | undefined {
+    return this.extractors.get(toolName);
+  }
+}

package/src/tool-registry.ts

@@ -2,7 +2,10 @@ import { getNonEmptyString, toRecord } from "./common";
 
 /** Narrow interface for the Pi tool API subset used by handler classes. */
 export interface ToolRegistry {
+  /** All registered tools (`pi.getAllTools()` — `ToolInfo[]`); kept defensively wide. */
   getAll(): unknown[];
+  /** Currently active tool names (`pi.getActiveTools()`). */
+  getActive(): string[];
   setActive(names: string[]): void;
 }
 

package/test/composition-root.test.ts

@@ -337,6 +337,42 @@ describe("service and gate share one formatter registry", () => {
   });
 });
 
+describe("service and gate share one access extractor registry", () => {
+  // An extractor registered through the published service must be consulted by
+  // the live gate handler — proving both reference the same
+  // ToolAccessExtractorRegistry instance the factory created once (#352).
+  it("path-gates a custom-shaped tool via a service-registered extractor", async () => {
+    writeGlobalConfig({
+      permission: { "*": "allow", path: { "*.env": "deny" } },
+    });
+
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-ext-cwd-"));
+    const pi = makeFakePi({ toolNames: ["ffgrep"] });
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+
+    const { ctx } = makeUiCtx(cwd, []);
+    await fireSessionStart(pi, ctx);
+
+    // ffgrep carries its path under a non-standard key; without the extractor
+    // the default input.path convention would miss it.
+    getPermissionsService()!.registerToolAccessExtractor("ffgrep", (input) =>
+      typeof input.target === "string" ? input.target : undefined,
+    );
+
+    const result = (await pi.fire(
+      "tool_call",
+      { toolName: "ffgrep", toolCallId: "ff-1", input: { target: ".env" } },
+      ctx,
+    )) as { block?: true };
+
+    // The path deny fired — so the gate extracted ffgrep's path through the
+    // same registry the service wrote to.
+    expect(result.block).toBe(true);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});
+
 describe("ready emitted after service publication", () => {
   // Ordering contracts exist only at the composition root: a consumer reacting
   // to permissions:ready must be able to resolve the service immediately. The

package/test/handlers/before-agent-start.test.ts

@@ -31,6 +31,7 @@ function makeEvent(systemPrompt = "You are an assistant.") {
 function makeToolRegistry(overrides: Partial<ToolRegistry> = {}): ToolRegistry {
   return {
     getAll: vi.fn().mockReturnValue([]),
+    getActive: vi.fn().mockReturnValue([]),
     setActive: vi.fn(),
     ...overrides,
   };
@@ -126,7 +127,7 @@ describe("AgentPrepHandler.handle", () => {
     const { handler, toolRegistry } = makeSetup({
       toolPermission: "deny",
       toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "write" }, { name: "read" }]),
+        getActive: vi.fn().mockReturnValue(["write", "read"]),
       },
     });
     await handler.handle(makeEvent(), makeCtx());
@@ -136,17 +137,44 @@ describe("AgentPrepHandler.handle", () => {
   it("includes allowed and ask tools in the active list", async () => {
     const { handler, toolRegistry } = makeSetup({
       toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "write" }]),
+        getActive: vi.fn().mockReturnValue(["read", "write"]),
       },
     });
     await handler.handle(makeEvent(), makeCtx());
     expect(toolRegistry.setActive).toHaveBeenCalledWith(["read", "write"]);
   });
 
+  it("does not activate registered tools pi left inactive (find/grep/ls)", async () => {
+    // Regression for #385: the active set is the base, not the full registry.
+    const { handler, toolRegistry } = makeSetup({
+      toolRegistry: {
+        getActive: vi.fn().mockReturnValue(["read", "bash", "edit", "write"]),
+        getAll: vi
+          .fn()
+          .mockReturnValue([
+            { name: "read" },
+            { name: "bash" },
+            { name: "edit" },
+            { name: "write" },
+            { name: "find" },
+            { name: "grep" },
+            { name: "ls" },
+          ]),
+      },
+    });
+    await handler.handle(makeEvent(), makeCtx());
+    expect(toolRegistry.setActive).toHaveBeenCalledWith([
+      "read",
+      "bash",
+      "edit",
+      "write",
+    ]);
+  });
+
   it("calls setActive once across repeated calls with the same allowed tools", async () => {
     const { handler, toolRegistry } = makeSetup({
       toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+        getActive: vi.fn().mockReturnValue(["read"]),
       },
     });
     await handler.handle(makeEvent(), makeCtx());

package/test/handlers/gates/external-directory.test.ts

@@ -168,3 +168,57 @@ describe("describeExternalDirectoryGate", () => {
     expect(result.logContext.message).toBeDefined();
   });
 });
+
+// Extension and MCP tools are now external-directory gated (#352) ───────────
+
+describe("describeExternalDirectoryGate — extension and MCP tools (#352)", () => {
+  it("gates an extension tool with an external input.path", () => {
+    const result = describeExternalDirectoryGate(
+      makeTcc({
+        toolName: "my-ext",
+        input: { path: "/outside/project/file.ts" },
+      }),
+      ["/test/agent"],
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    expect((result as GateDescriptor).surface).toBe("external_directory");
+  });
+
+  it("gates an MCP tool with an external arguments.path", () => {
+    const result = describeExternalDirectoryGate(
+      makeTcc({
+        toolName: "mcp",
+        input: { arguments: { path: "/outside/project/file.ts" } },
+      }),
+      ["/test/agent"],
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+  });
+
+  it("uses a registered extractor's external path for a custom-shaped tool", () => {
+    const extractors = {
+      get: (name: string) =>
+        name === "ffgrep"
+          ? (input: Record<string, unknown>) =>
+              typeof input.target === "string" ? input.target : undefined
+          : undefined,
+    };
+    const result = describeExternalDirectoryGate(
+      makeTcc({ toolName: "ffgrep", input: { target: "/outside/project/x" } }),
+      ["/test/agent"],
+      extractors,
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+  });
+
+  it("returns null for an extension tool whose path is inside cwd", () => {
+    const result = describeExternalDirectoryGate(
+      makeTcc({
+        toolName: "my-ext",
+        input: { path: "/test/project/src/x.ts" },
+      }),
+      ["/test/agent"],
+    );
+    expect(result).toBeNull();
+  });
+});

package/test/handlers/gates/path.test.ts

@@ -206,3 +206,75 @@ describe("describePathGate — home-relative paths", () => {
     expect(result).toBeNull();
   });
 });
+
+// Extension and MCP tools are now path-gated (#352) ──────────────────────────
+
+describe("describePathGate — extension and MCP tools (#352)", () => {
+  function extractorLookup(toolName: string, key: string) {
+    return {
+      get: (name: string) =>
+        name === toolName
+          ? (input: Record<string, unknown>) =>
+              typeof input[key] === "string" ? input[key] : undefined
+          : undefined,
+    };
+  }
+
+  it("gates an extension tool that exposes input.path", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
+    );
+    const result = describePathGate(
+      makeTcc({ toolName: "my-ext", input: { path: ".env" } }),
+      resolver,
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(resolver.resolve).toHaveBeenCalledWith(
+      "path",
+      { path: ".env" },
+      undefined,
+    );
+  });
+
+  it("gates an MCP tool via arguments.path", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "deny", matchedPattern: "*.env" }),
+    );
+    const result = describePathGate(
+      makeTcc({ toolName: "mcp", input: { arguments: { path: ".env" } } }),
+      resolver,
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(resolver.resolve).toHaveBeenCalledWith(
+      "path",
+      { path: ".env" },
+      undefined,
+    );
+  });
+
+  it("uses a registered extractor's path for a custom-shaped tool", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "deny", matchedPattern: "*" }),
+    );
+    describePathGate(
+      makeTcc({ toolName: "ffgrep", input: { target: "/etc/passwd" } }),
+      resolver,
+      extractorLookup("ffgrep", "target"),
+    );
+    expect(resolver.resolve).toHaveBeenCalledWith(
+      "path",
+      { path: "/etc/passwd" },
+      undefined,
+    );
+  });
+
+  it("returns null for an extension tool without a path", () => {
+    const resolver = makeResolver();
+    const result = describePathGate(
+      makeTcc({ toolName: "my-ext", input: { other: true } }),
+      resolver,
+    );
+    expect(result).toBeNull();
+    expect(resolver.resolve).not.toHaveBeenCalled();
+  });
+});

package/test/handlers/gates/tool-call-gate-pipeline.test.ts

@@ -186,4 +186,67 @@ describe("ToolCallGatePipeline", () => {
       expect(mockBashProgramParse).not.toHaveBeenCalled();
     });
   });
+
+  // ── customExtractors threading (#352) ────────────────────────────────────
+
+  describe("evaluate — customExtractors threading (#352)", () => {
+    // Deny only the cross-cutting `path` surface; allow everything else, so a
+    // block can only come from the path gate seeing the extracted path.
+    function pathDenyingResolver() {
+      const resolver = makeResolver();
+      resolver.resolve.mockImplementation((surface) =>
+        surface === "path"
+          ? makeCheckResult({ state: "deny", matchedPattern: "*" })
+          : makeCheckResult(),
+      );
+      return resolver;
+    }
+
+    const extractors = {
+      get: (name: string) =>
+        name === "ffgrep"
+          ? (input: Record<string, unknown>) =>
+              typeof input.target === "string" ? input.target : undefined
+          : undefined,
+    };
+
+    it("forwards extractors so a custom-shaped tool is path-gated", async () => {
+      const resolver = pathDenyingResolver();
+      const inputs = makeGateInputs();
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(
+        resolver,
+        inputs,
+        undefined,
+        extractors,
+      );
+
+      const result = await pipeline.evaluate(
+        makeTcc({
+          toolName: "ffgrep",
+          input: { target: "/test/project/secret.env" },
+        }),
+        runner,
+      );
+
+      expect(result).toMatchObject({ action: "block" });
+    });
+
+    it("without extractors the custom-shaped tool is not path-gated", async () => {
+      const resolver = pathDenyingResolver();
+      const inputs = makeGateInputs();
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
+
+      const result = await pipeline.evaluate(
+        makeTcc({
+          toolName: "ffgrep",
+          input: { target: "/test/project/secret.env" },
+        }),
+        runner,
+      );
+
+      expect(result).toEqual({ action: "allow" });
+    });
+  });
 });

package/test/helpers/handler-fixtures.ts

@@ -123,6 +123,7 @@ export function makeToolRegistry(
 ): ToolRegistry {
   return {
     getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
+    getActive: vi.fn().mockReturnValue(["read", "bash"]),
     setActive: vi.fn(),
     ...overrides,
   };

package/test/helpers/make-fake-pi.ts

@@ -42,6 +42,8 @@ export interface FakePi {
   fire(event: string, input?: unknown, ctx?: unknown): Promise<unknown>;
   /** Minimal tool registry — returns the configured tool names. */
   getAllTools(): { name: string }[];
+  /** Active tool names (`pi.getActiveTools()` shape — bare strings). */
+  getActiveTools(): string[];
   setActiveTools(names: string[]): void;
 }
 
@@ -80,6 +82,9 @@ export function makeFakePi(options: MakeFakePiOptions = {}): FakePi {
     getAllTools(): { name: string }[] {
       return toolNames.map((name) => ({ name }));
     },
+    getActiveTools(): string[] {
+      return [...toolNames];
+    },
     setActiveTools: vi.fn(),
     // ── ExtensionAPI methods the factory touches (recorded) ────────────────
     on(event: string, handler: RecordedHandler): void {

package/test/path-utils.test.ts

@@ -23,6 +23,7 @@ vi.mock("node:fs", () => ({
 import {
   canonicalNormalizePathForComparison,
   getPathBearingToolPath,
+  getToolInputPath,
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
   isPiInfrastructureRead,
@@ -32,6 +33,7 @@ import {
   READ_ONLY_PATH_BEARING_TOOLS,
   SAFE_SYSTEM_PATHS,
 } from "#src/path-utils";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 
 describe("normalizePathForComparison", () => {
   const cwd = "/projects/my-app";
@@ -244,6 +246,67 @@ describe("getPathBearingToolPath", () => {
   });
 });
 
+describe("getToolInputPath", () => {
+  function lookupOf(
+    toolName: string,
+    extractor: (input: Record<string, unknown>) => string | undefined,
+  ): ToolAccessExtractorLookup {
+    return {
+      get: (name) => (name === toolName ? extractor : undefined),
+    };
+  }
+
+  test("returns input.path for a built-in path-bearing tool", () => {
+    expect(getToolInputPath("read", { path: "/src/foo.ts" })).toBe(
+      "/src/foo.ts",
+    );
+    expect(getToolInputPath("write", { path: "/src/bar.ts" })).toBe(
+      "/src/bar.ts",
+    );
+  });
+
+  test("returns null for bash", () => {
+    expect(getToolInputPath("bash", { path: "/src/foo.ts" })).toBeNull();
+  });
+
+  test("returns the MCP arguments.path for an mcp call", () => {
+    expect(getToolInputPath("mcp", { arguments: { path: "/etc/hosts" } })).toBe(
+      "/etc/hosts",
+    );
+  });
+
+  test("returns null for an mcp call without an arguments.path", () => {
+    expect(getToolInputPath("mcp", { arguments: { query: "x" } })).toBeNull();
+    expect(getToolInputPath("mcp", {})).toBeNull();
+  });
+
+  test("defaults to input.path for an unregistered extension tool", () => {
+    expect(getToolInputPath("my-ext", { path: "/work/file.txt" })).toBe(
+      "/work/file.txt",
+    );
+  });
+
+  test("returns null for an extension tool without a path", () => {
+    expect(getToolInputPath("my-ext", { other: true })).toBeNull();
+    expect(getToolInputPath("my-ext", { path: "" })).toBeNull();
+    expect(getToolInputPath("my-ext", null)).toBeNull();
+  });
+
+  test("uses a registered extractor's path over the default convention", () => {
+    const extractors = lookupOf("ffgrep", (input) =>
+      typeof input.target === "string" ? input.target : undefined,
+    );
+    expect(
+      getToolInputPath("ffgrep", { target: "/etc/passwd" }, extractors),
+    ).toBe("/etc/passwd");
+  });
+
+  test("returns null when a registered extractor declines", () => {
+    const extractors = lookupOf("ffgrep", () => undefined);
+    expect(getToolInputPath("ffgrep", { target: "x" }, extractors)).toBeNull();
+  });
+});
+
 describe("isPathOutsideWorkingDirectory", () => {
   const cwd = "/projects/my-app";
 

package/test/permission-events.test.ts

@@ -363,6 +363,7 @@ describe("piPermissionSystemExtension ready event wiring", () => {
       ),
       registerCommand: vi.fn(),
       getAllTools: vi.fn().mockReturnValue([]),
+      getActiveTools: vi.fn().mockReturnValue([]),
       setActiveTools: vi.fn(),
       registerProvider: vi.fn(),
       events: { emit: emitSpy, on: vi.fn().mockReturnValue(() => undefined) },

package/test/permissions-service.test.ts

@@ -3,6 +3,7 @@ import type { ScopedPermissionManager } from "#src/permission-manager";
 import { LocalPermissionsService } from "#src/permissions-service";
 import type { Ruleset } from "#src/rule";
 import type { SessionRules } from "#src/session-rules";
+import type { ToolAccessExtractorRegistrar } from "#src/tool-access-extractor-registry";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistrar,
@@ -39,22 +40,40 @@ function makeFormatterRegistry(): ToolInputFormatterRegistrar {
   };
 }
 
+function makeAccessExtractorRegistry(): ToolAccessExtractorRegistrar {
+  return {
+    register: vi
+      .fn<ToolAccessExtractorRegistrar["register"]>()
+      .mockReturnValue(vi.fn()),
+  };
+}
+
 function makeService(overrides?: {
   permissionManager?: ScopedPermissionManager;
   sessionRules?: Pick<SessionRules, "getRuleset">;
   formatterRegistry?: ToolInputFormatterRegistrar;
+  accessExtractorRegistry?: ToolAccessExtractorRegistrar;
 }) {
   const permissionManager =
     overrides?.permissionManager ?? makeFakePermissionManager();
   const sessionRules = overrides?.sessionRules ?? makeSessionRules();
   const formatterRegistry =
     overrides?.formatterRegistry ?? makeFormatterRegistry();
+  const accessExtractorRegistry =
+    overrides?.accessExtractorRegistry ?? makeAccessExtractorRegistry();
   const service = new LocalPermissionsService(
     permissionManager,
     sessionRules,
     formatterRegistry,
+    accessExtractorRegistry,
   );
-  return { service, permissionManager, sessionRules, formatterRegistry };
+  return {
+    service,
+    permissionManager,
+    sessionRules,
+    formatterRegistry,
+    accessExtractorRegistry,
+  };
 }
 
 // ── tests ──────────────────────────────────────────────────────────────────
@@ -141,3 +160,18 @@ describe("registerToolInputFormatter", () => {
     expect(result).toBe(unsub);
   });
 });
+
+describe("registerToolAccessExtractor", () => {
+  it("delegates to accessExtractorRegistry.register and returns the unsubscribe function", () => {
+    const unsub = vi.fn();
+    const { service, accessExtractorRegistry } = makeService();
+    vi.mocked(accessExtractorRegistry.register).mockReturnValue(unsub);
+    const extractor = vi.fn();
+    const result = service.registerToolAccessExtractor("ffgrep", extractor);
+    expect(accessExtractorRegistry.register).toHaveBeenCalledWith(
+      "ffgrep",
+      extractor,
+    );
+    expect(result).toBe(unsub);
+  });
+});

package/test/service-lifecycle.test.ts

@@ -35,6 +35,7 @@ function makeService(): PermissionsService {
     checkPermission: vi.fn(),
     getToolPermission: vi.fn(),
     registerToolInputFormatter: vi.fn(),
+    registerToolAccessExtractor: vi.fn(),
   };
 }
 

package/test/service.test.ts

@@ -6,6 +6,7 @@ import {
   publishPermissionsService,
   unpublishPermissionsService,
 } from "#src/service";
+import { ToolAccessExtractorRegistry } from "#src/tool-access-extractor-registry";
 import { ToolInputFormatterRegistry } from "#src/tool-input-formatter-registry";
 import type { PermissionCheckResult } from "#src/types";
 
@@ -18,6 +19,7 @@ function makeService(
     checkPermission: vi.fn(),
     getToolPermission: vi.fn(),
     registerToolInputFormatter: vi.fn(),
+    registerToolAccessExtractor: vi.fn(),
     ...overrides,
   };
 }
@@ -155,6 +157,7 @@ describe("service adapter delegation", () => {
         return getToolPermissionFn(toolName, agentName);
       },
       registerToolInputFormatter: vi.fn(),
+      registerToolAccessExtractor: vi.fn(),
     };
 
     publishPermissionsService(service);
@@ -177,6 +180,7 @@ describe("service adapter delegation", () => {
         return getToolPermissionFn(toolName, agentName);
       },
       registerToolInputFormatter: vi.fn(),
+      registerToolAccessExtractor: vi.fn(),
     };
 
     publishPermissionsService(service);
@@ -253,3 +257,52 @@ describe("registerToolInputFormatter delegation", () => {
     ).toThrow("my-tool");
   });
 });
+
+// ── registerToolAccessExtractor delegation (#352) ────────────────────────
+
+describe("registerToolAccessExtractor delegation", () => {
+  afterEach(() => {
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
+  });
+
+  it("delegates to the registry and returns its disposer", () => {
+    const registry = new ToolAccessExtractorRegistry();
+    const extractor = () => "/etc/hosts";
+
+    const service = makeService({
+      registerToolAccessExtractor(toolName, ext) {
+        return registry.register(toolName, ext);
+      },
+    });
+
+    publishPermissionsService(service);
+    const dispose = getPermissionsService()!.registerToolAccessExtractor(
+      "ffgrep",
+      extractor,
+    );
+
+    expect(registry.get("ffgrep")).toBe(extractor);
+
+    dispose();
+    expect(registry.get("ffgrep")).toBeUndefined();
+  });
+
+  it("throws when an extractor is already registered for the tool name", () => {
+    const registry = new ToolAccessExtractorRegistry();
+    registry.register("ffgrep", () => undefined);
+
+    const service = makeService({
+      registerToolAccessExtractor(toolName, ext) {
+        return registry.register(toolName, ext);
+      },
+    });
+
+    publishPermissionsService(service);
+    expect(() =>
+      getPermissionsService()!.registerToolAccessExtractor("ffgrep", () => ""),
+    ).toThrow("ffgrep");
+  });
+});

package/test/session-start.test.ts

@@ -56,6 +56,7 @@ describe("session_start handler consolidation", () => {
       },
       registerCommand: (): void => {},
       getAllTools: (): Array<{ name: string }> => [],
+      getActiveTools: (): string[] => [],
       setActiveTools: (): void => {},
       registerProvider: (): void => {},
       events: {
@@ -79,6 +80,7 @@ describe("session_start handler consolidation", () => {
       },
       registerCommand: (): void => {},
       getAllTools: (): Array<{ name: string }> => [],
+      getActiveTools: (): string[] => [],
       setActiveTools: (): void => {},
       registerProvider: (): void => {},
       events: {

package/test/tool-access-extractor-registry.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  type ToolAccessExtractor,
+  ToolAccessExtractorRegistry,
+} from "#src/tool-access-extractor-registry";
+
+const noopExtractor: ToolAccessExtractor = () => "/tmp/x";
+
+describe("ToolAccessExtractorRegistry", () => {
+  describe("register", () => {
+    test("stores an extractor so get() returns it", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      registry.register("my-tool", noopExtractor);
+      expect(registry.get("my-tool")).toBe(noopExtractor);
+    });
+
+    test("returns a disposer that removes the extractor", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      const dispose = registry.register("my-tool", noopExtractor);
+      dispose();
+      expect(registry.get("my-tool")).toBeUndefined();
+    });
+
+    test("throws when an extractor is already registered for the same tool name", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      registry.register("my-tool", noopExtractor);
+      expect(() => registry.register("my-tool", () => undefined)).toThrow(
+        "my-tool",
+      );
+    });
+
+    test("allows registering different tool names independently", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      const extractorA: ToolAccessExtractor = () => "/a";
+      const extractorB: ToolAccessExtractor = () => "/b";
+      registry.register("tool-a", extractorA);
+      registry.register("tool-b", extractorB);
+      expect(registry.get("tool-a")).toBe(extractorA);
+      expect(registry.get("tool-b")).toBe(extractorB);
+    });
+  });
+
+  describe("disposer identity guard", () => {
+    test("stale disposer does not evict a later registration", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      const first: ToolAccessExtractor = () => "/first";
+      const second: ToolAccessExtractor = () => "/second";
+
+      const disposeFirst = registry.register("my-tool", first);
+      disposeFirst(); // removes first
+
+      registry.register("my-tool", second); // second registration is now valid
+      disposeFirst(); // calling stale disposer again — must not remove second
+
+      expect(registry.get("my-tool")).toBe(second);
+    });
+  });
+
+  describe("get", () => {
+    test("returns undefined for an unregistered tool name", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      expect(registry.get("unknown")).toBeUndefined();
+    });
+
+    test("the registered extractor is callable and returns its path", () => {
+      const registry = new ToolAccessExtractorRegistry();
+      const extractor: ToolAccessExtractor = (input) =>
+        typeof input.target === "string" ? input.target : undefined;
+      registry.register("ffgrep", extractor);
+      expect(registry.get("ffgrep")?.({ target: "/etc/hosts" })).toBe(
+        "/etc/hosts",
+      );
+      expect(registry.get("ffgrep")?.({ other: true })).toBeUndefined();
+    });
+  });
+});