@gotgenes/pi-permission-system 29.1.0 → 29.3.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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).
 
+## [29.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.2.0...pi-permission-system-v29.3.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** name and document the well-known permission surfaces ([#808](https://github.com/gotgenes/pi-packages/issues/808)) ([95ef9ab](https://github.com/gotgenes/pi-packages/commit/95ef9ab9c00ee09d4dda820d43abc7fe7e5ff1b2)), closes [#808](https://github.com/gotgenes/pi-packages/issues/808)
+
+### Documentation
+
+* **pi-permission-system:** document the named permission surfaces ([#808](https://github.com/gotgenes/pi-packages/issues/808)) ([03c6a52](https://github.com/gotgenes/pi-packages/commit/03c6a5228aa050ac940d851e6c219e62062acbd6))
+
+### Miscellaneous Chores
+
+* upgrade lint tooling and pin rumdl below the MD013 reflow regression ([0ee1ad8](https://github.com/gotgenes/pi-packages/commit/0ee1ad886815e6e50d99f66050fbbcf5a9f0319a)), closes [#866](https://github.com/gotgenes/pi-packages/issues/866)
+* upgrade fallow to 3.22.0 ([1b2a562](https://github.com/gotgenes/pi-packages/commit/1b2a5620bf5d7f1014676b47e58df8b43ff00496)), closes [#866](https://github.com/gotgenes/pi-packages/issues/866)
+
+## [29.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.1.0...pi-permission-system-v29.2.0) (2026-09-01)
+
+
+### Features
+
+* **pi-permission-system:** expose the registered extractor and formatter for a tool ([9d9952d](https://github.com/gotgenes/pi-packages/commit/9d9952d1ee235086e9809d6cb50e1b31ae2fc3f6))
+* **pi-permission-system:** resolve a child's missing extractor from its parent node ([91b3ef1](https://github.com/gotgenes/pi-packages/commit/91b3ef1918a827f0ee3f8c0acf13cee5ba5f72ef)), closes [#793](https://github.com/gotgenes/pi-packages/issues/793)
+
+### Documentation
+
+* **pi-permission-system:** record the fact-shaping inheritance rule (ADR 0012) ([dbdd9f1](https://github.com/gotgenes/pi-packages/commit/dbdd9f19f29a1a67d282fdc050a71b462021eb56))
+
+<!-- Entries below this point were generated by release-please, which this
+     repository used until 2026-09. Some record releases made in the
+     packages' predecessor repositories, before the monorepo existed. See
+     docs/decisions/0002-git-cliff-release-automation.md. -->
+
 ## [29.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.0.0...pi-permission-system-v29.1.0) (2026-08-31)
 
 

package/dist/public.d.ts

@@ -572,6 +572,30 @@ interface PermissionsService extends PermissionQuery {
      *                    or `undefined` to decline.
      */
     registerToolAccessExtractor(toolName: string, extractor: ToolAccessExtractor): () => void;
+    /**
+     * The access extractor registered on this node for `toolName`, or
+     * `undefined` when it has none.
+     *
+     * This is the read face of a **fact-shaping** registry, and unlike the
+     * authority surfaces it is meant to be read across a node boundary: an
+     * extractor produces a fact about a call (the path it touches) and decides
+     * nothing, so an in-process child whose own registry has no entry may
+     * resolve an ancestor node's service and use its answer to complete the
+     * child's own fact-gathering (ADR 0012 decision 1).
+     *
+     * The same does not hold for {@link registerAuthorizer}: a link produces a
+     * verdict, and live authority converges at the adjudicating node (ADR 0007
+     * §7). There is deliberately no reader for it.
+     */
+    getToolAccessExtractor(toolName: string): ToolAccessExtractor | undefined;
+    /**
+     * The preview formatter registered on this node for `toolName`, or
+     * `undefined` when it has none.
+     *
+     * Fact-shaping, and cross-node readable for the same reason as
+     * {@link getToolAccessExtractor}.
+     */
+    getToolInputFormatter(toolName: string): ToolInputFormatter | undefined;
     /**
      * Register a named live-authority chain link (ADR 0007 §4).
      *

package/docs/configuration.md

@@ -1147,6 +1147,8 @@ Additional behaviors:
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
 - Permission review logs include `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))
+- A tool whose path came from an extractor registered in an **ancestor** session rather than this one records `extractorSource: "inherited"` beside the decision; the field is absent for every path this session resolved itself.
+  This happens in a subagent child when the extractor's provider was kept out of the child but the tool's own package was not — the child borrows the declaration so its `path` and `external_directory` gates still see the path (see [Subagent Integration](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/subagent-integration.md#loading-asymmetry))
 
 ---
 
@@ -1202,4 +1204,6 @@ npx --yes ajv-cli@5 validate \
 "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json"
 ```
 
+The well-known surface keys — `*`, `path`, `external_directory`, `bash`, `mcp`, `skill`, and the four directional keys — are named properties in the schema, so an editor completes them and shows each key's own documentation on hover; any other registered tool name still validates as a surface.
+
 The schema is generated from the extension's zod source of truth (`src/config-schema.ts`); regenerate it with `pnpm run gen:schema` after changing the config shape.

package/docs/cross-extension-api.md

@@ -92,6 +92,22 @@ interface PermissionsService {
     toolName: string,
     extractor: (input: Record<string, unknown>) => string | undefined,
   ): () => void;
+
+  /**
+   * The access extractor registered on this node for `toolName`, or
+   * `undefined` when it has none.
+   */
+  getToolAccessExtractor(
+    toolName: string,
+  ): ((input: Record<string, unknown>) => string | undefined) | undefined;
+
+  /**
+   * The preview formatter registered on this node for `toolName`, or
+   * `undefined` when it has none.
+   */
+  getToolInputFormatter(
+    toolName: string,
+  ): ((input: Record<string, unknown>) => string | undefined) | undefined;
 }
 ```
 
@@ -280,6 +296,22 @@ const dispose = permissions.registerToolAccessExtractor("ffgrep", (input) =>
 Registration rules mirror `registerToolInputFormatter`: one extractor per tool name (a second `register` for the same name throws), and the returned disposer is identity-guarded.
 The extractor must not throw — guard your parsing and return `undefined` on anything unexpected.
 
+#### `getToolAccessExtractor` and `getToolInputFormatter`
+
+Read back what a node has registered for a tool.
+
+```typescript
+getToolAccessExtractor(toolName: string): ToolAccessExtractor | undefined;
+getToolInputFormatter(toolName: string): ToolInputFormatter | undefined;
+```
+
+These are the read face of the two **fact-shaping** registries, and unlike every other surface here they are meant to be read across a node boundary.
+An extractor produces a fact about a call (the path it touches) and a formatter produces display text; neither decides anything, so a node whose own registry has no entry may resolve an ancestor's service and use its answer.
+The permission system does exactly that internally: a subagent child that is missing an extractor for a tool falls back to its ancestors in the same process, so excluding an extractor's provider from child sessions cannot leave that tool's path invisible to the child's gates ([ADR 0012] decision 1, the fact-shaping clause).
+
+There is deliberately **no** equivalent reader for `registerAuthorizer`.
+A chain link returns a verdict, and live authority converges at the adjudicating node ([ADR 0007] §7) — inheriting one would run authority an operator's own extension exclusion removed.
+
 #### Subagent session registration
 
 Subagent registration is announcement-driven, and the spawner makes no service call.
@@ -514,3 +546,7 @@ pi.on("session_shutdown", () => {
 
 A registration needs no branch on `adjudicatesLocally`.
 Formatters and access extractors are read by every node's own gates, and a chain link registered on a relaying node is accepted (its disposer works) and recorded in the review log as `authorizer_link_vacant` rather than refused — so registering everywhere is the correct default.
+Registering on _every_ node also stays the best practice for a formatter or extractor provider: the ancestor fallback is a repair for a node that could not register, not a reason to register in one place on purpose.
+
+[ADR 0007]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0007-model-judge-authorizer-chain-adr.md
+[ADR 0012]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md

package/docs/subagent-integration.md

@@ -81,11 +81,22 @@ Three statements hold:
    Nothing throws and nothing warns per child start.
 2. **Excluding an extension from children is an optimization, never a correctness requirement.**
    Excluding a link-only extension saves load time; the adjudicating node's own instance still judges every descendant ask.
-3. **Excluding a provider of access extractors can weaken a child's own gates.**
-   This is the one real hazard, and it is narrower than it sounds: excluding a package also keeps that package's tools out of children, so a package that supplies both a tool and that tool's extractor takes both away and leaves no gap.
-   A gap needs the tool and its extractor to come from *different* packages, with only the extractor's package excluded.
+3. **Excluding a provider of access extractors no longer weakens an in-process child's gates.**
+   The hazard was narrower than it sounded: excluding a package also keeps that package's tools out of children, so a package supplying both a tool and that tool's extractor takes both away and leaves no gap.
+   A gap needed the tool and its extractor to come from *different* packages, with only the extractor's package excluded.
+   That case is now closed — a child whose own registry has no extractor for a tool resolves one from its ancestors in the same process, and the same holds for preview formatters.
 
-The full condition, with a worked example, is documented where the setting lives: [Excluding package extensions from children](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/configuration.md#excluding-package-extensions-from-children).
+Registration is unchanged by that: an extractor still lands only in the registry of the node whose extension registered it.
+What crosses a node boundary is the **lookup**, and only for fact-shaping registrations — an extractor produces a path and a formatter produces display text, so neither carries authority.
+Chain links are excluded by category: a link returns a verdict, and live authority converges at the adjudicating node ([ADR 0007] §7).
+
+A decision that used an inherited extractor records `extractorSource: "inherited"` in the review log, so a child's dependence on another node's registration is visible where the decision is.
+
+One residual: this repair is in-process only.
+A child in its own process shares no `globalThis`, so it reaches no ancestor's service, and an extractor is a closure that cannot be serialized to one.
+No current implementation spawns out-of-process children with an asymmetric extension set, but for one that did, the by-hand check below would still be the only cover.
+
+The condition, with a worked example, is documented where the setting lives: [Excluding package extensions from children](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/configuration.md#excluding-package-extensions-from-children).
 
 ## What this package does on both ends
 
@@ -257,5 +268,6 @@ permission:
 
 In this example the subagent extension restricts visibility to `bash` and `read`, and the permission system then gates every `bash` call with an `ask` prompt - both rules apply independently.
 
+[ADR 0007]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0007-model-judge-authorizer-chain-adr.md
 [ADR 0012]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md
 [ADR-0002]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "29.1.0",
+  "version": "29.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -67,15 +67,15 @@
     "@earendil-works/pi-tui": ">=0.79.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
+    "@biomejs/biome": "^2.5.11",
     "@earendil-works/pi-coding-agent": "0.79.1",
     "@earendil-works/pi-tui": "0.79.1",
     "@types/node": "^22.15.3",
-    "rollup": "^4.62.2",
-    "rollup-plugin-dts": "^6.4.1",
-    "rumdl": "^0.2.10",
+    "rollup": "^4.63.1",
+    "rollup-plugin-dts": "^6.5.1",
+    "rumdl": "0.2.24",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",

package/schemas/permissions.schema.json

@@ -102,6 +102,30 @@
     "permission": {
       "type": "object",
       "properties": {
+        "*": {
+          "description": "Universal fallback — the action used when no surface-specific rule matches. Omitted, it defaults to ask.",
+          "markdownDescription": "Universal fallback — the action used when **no** surface-specific rule matches.\n\n`{ \"*\": \"ask\" }` is the least-privilege posture, and is what an omitted `\"*\"` means anyway. It replaces `defaultPolicy.tools` from the legacy config format.\n\nA surface-specific rule always beats it, whatever the key order in the file.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "path": {
+          "description": "Cross-cutting gate for file access by path pattern, across every path-aware tool. Sugar for both directions.",
+          "markdownDescription": "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).\n\nA `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from every path-aware tool at once.\n\nThis bare key is **sugar**: it expands at load into `path_read` and `path_write`, its entries placed first, so an explicit directional entry always has the final say whatever the key order in the file.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
         "path_read": {
           "description": "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
           "markdownDescription": "Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `\"path_read\": { \"~/dev/*\": \"allow\" }` permits reads without permitting writes.\n\nA bare `\"path\"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.",
@@ -126,6 +150,18 @@
             }
           ]
         },
+        "external_directory": {
+          "description": "Boundary gate for access outside the session working directory. Sugar for both directions.",
+          "markdownDescription": "Boundary gate for access **outside** the session working directory.\n\nGive it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `{ \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself.\n\nBecause layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\nThis bare key is **sugar**: it expands at load into `external_directory_read` and `external_directory_write`, its entries placed first.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
         "external_directory_read": {
           "description": "Boundary gate for reading outside the working directory. The relief most asks want.",
           "markdownDescription": "Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `\"external_directory_read\": { \"~/dev/*\": \"allow\" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.",
@@ -149,6 +185,42 @@
               "$ref": "#/$defs/permissionMap"
             }
           ]
+        },
+        "bash": {
+          "description": "Shell command execution, matched per top-level command in a chain. Most restrictive wins.",
+          "markdownDescription": "Shell command execution, matched by **command pattern**.\n\nA chain (`&&`, `||`, `;`, `|`, newline) is split into its top-level commands and each is matched independently, most-restrictive-wins — so `cd /repo && npm install x` is denied when `npm *` is. A command nested in a substitution, process substitution, or subshell is matched too, since it really runs.\n\nA leading env-var assignment is stripped before matching (`AWS_PROFILE=prod aws …` matches `aws *`), and a pattern ending in ` *` (space + wildcard) also matches the bare command (`git *` matches `git`). A pattern containing a chain operator never matches — write one pattern per command.\n\nA shell wrapper (`bash -c`, `eval`, `sudo`, `xargs`) is floored from `allow` to `ask`, so an opaque payload cannot ride a permissive rule.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "mcp": {
+          "description": "Registered MCP proxy tools, matched against targets derived from the tool input.",
+          "markdownDescription": "Registered MCP proxy tools, matched against targets derived from the tool input: a baseline op (`mcp_status`, `mcp_list`, `mcp_search`, `mcp_describe`, `mcp_connect`), a server name (`myServer`), a server/tool combination (`myServer:search`, `myServer_search`), or the generic `mcp_call`.\n\nBaseline discovery targets auto-allow whenever any explicit `mcp` allow rule exists.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "skill": {
+          "description": "Skill invocation, matched by skill name. The surface is `skill`, not `skills`.",
+          "markdownDescription": "Skill invocation, matched by skill name — the surface is `skill`, not `skills`.\n\nWildcards behave as everywhere else: `{ \"*\": \"ask\", \"dangerous-*\": \"deny\", \"librarian\": \"allow\" }`.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
         }
       },
       "additionalProperties": {
@@ -162,7 +234,7 @@
         ]
       },
       "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 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\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\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\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `\"external_directory\": { \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface: the `\"*\"` fallback, a well-known surface documented below, or any registered tool name.\n\nA **string** value is shorthand for `{ \"*\": action }` (a 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\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "examples": [
         {
           "*": "ask",

package/src/access-intent/tool-input-path.ts

@@ -13,6 +13,24 @@ export function getPathBearingToolPath(
   return getNonEmptyString(toRecord(input).path);
 }
 
+/**
+ * What supplied a tool call's path.
+ *
+ * `"convention"` covers both the built-in `input.path` / `input.arguments.path`
+ * shapes and the default an unregistered extension tool falls back to — in
+ * every case, nobody declared it.
+ */
+export type ToolPathSource =
+  | "convention"
+  | "local_extractor"
+  | "inherited_extractor";
+
+/** A tool call's path together with what supplied it. */
+export interface ToolInputPathResult {
+  path: string | null;
+  source: ToolPathSource;
+}
+
 /**
  * Extract the filesystem path a tool will access, for the cross-cutting `path`
  * and `external_directory` gates.
@@ -25,28 +43,41 @@ export function getPathBearingToolPath(
  * - `mcp` → `input.arguments.path`.
  * - Any other tool → a registered {@link ToolAccessExtractor}'s path, else the
  *   default `input.path` convention.
+ *
+ * The result names what supplied the path, because an extractor resolved from
+ * an ancestor node is a fact the gates record (ADR 0012 decision 1).
  */
 export function getToolInputPath(
   toolName: string,
   input: unknown,
   extractors?: ToolAccessExtractorLookup,
-): string | null {
+): ToolInputPathResult {
   const record = toRecord(input);
 
   switch (classifyToolKind(toolName)) {
     case "bash":
-      return null;
+      return byConvention(null);
     case "path":
-      return getNonEmptyString(record.path);
+      return byConvention(getNonEmptyString(record.path));
     case "mcp":
-      return getNonEmptyString(toRecord(record.arguments).path);
+      return byConvention(getNonEmptyString(toRecord(record.arguments).path));
     case "skill":
     case "extension": {
-      const custom = extractors?.get(toolName);
+      const custom = extractors?.resolve(toolName);
       if (custom) {
-        return getNonEmptyString(custom(record));
+        return {
+          path: getNonEmptyString(custom.extractor(record)),
+          source:
+            custom.origin === "inherited"
+              ? "inherited_extractor"
+              : "local_extractor",
+        };
       }
-      return getNonEmptyString(record.path);
+      return byConvention(getNonEmptyString(record.path));
     }
   }
 }
+
+function byConvention(path: string | null): ToolInputPathResult {
+  return { path, source: "convention" };
+}

package/src/authority/inherited-registrations.ts

@@ -0,0 +1,163 @@
+/**
+ * inherited-registrations.ts — Complete a child node's fact-shaping lookups
+ * from its ancestors in the same process.
+ *
+ * Registrations are node-local (ADR 0012 decision 1): an extractor or formatter
+ * lands in the registry of the node whose extension registered it. That is
+ * unchanged here. What this module adds is the decision's fact-shaping clause —
+ * a **lookup** may cross an in-process node boundary, because an extractor
+ * produces a path and a formatter produces display text, and neither decides
+ * anything.
+ *
+ * The gap it closes is the split-provider condition (#793). Excluding a package
+ * from child sessions normally removes its tools and their extractors together,
+ * so nothing is weakened. But when package A registers a tool whose path lives
+ * under a non-standard key and package B registers the extractor for it,
+ * excluding B alone leaves the child with the tool and no way to see its path:
+ * the `path` and `external_directory` gates never run for that call, and the
+ * parent's own gating is unaffected, so the weakening is visible nowhere.
+ *
+ * Why this direction is safe, and why it stops here:
+ *
+ * - It is monotone. Without an extractor the gate does not run at all, so
+ *   resolving one can only add a check, and the four path layers compose
+ *   most-restrictive-wins — an inherited extractor can never loosen a decision.
+ * - It carries no authority. Live authority converges at the adjudicating node
+ *   (ADR 0007 §7), so there is deliberately **no** equivalent for the authorizer
+ *   registry: a link returns a verdict, and inheriting one would run authority
+ *   an operator's own `excludedExtensionPackages` removed.
+ *
+ * In-process only, by construction: an out-of-process child shares no
+ * `globalThis`, so it reaches no ancestor service, and an extractor is a
+ * closure that cannot be serialized to one.
+ */
+
+import type { PermissionsService } from "#src/service";
+import type {
+  ResolvedToolAccessExtractor,
+  ToolAccessExtractorLookup,
+} from "#src/tool-access-extractor-registry";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterLookup,
+} from "#src/tool-input-formatter-registry";
+
+/** This node's own session id, or `null` when the host exposes none. */
+export interface NodeIdentity {
+  currentSessionId(): string | null;
+}
+
+/**
+ * The read shape {@link AncestorNodes} needs from the subagent registry (ISP):
+ * which node spawned the one named by `sessionId`.
+ */
+export interface ParentChainRegistry {
+  get(sessionId: string): { parentSessionId?: string } | undefined;
+}
+
+/** Resolves a node's published service by session id. */
+export type PermissionsServiceLocator = (
+  sessionId: string,
+) => PermissionsService | undefined;
+
+/**
+ * This node's ancestors in the current process, nearest first.
+ *
+ * Binds the three collaborators the walk needs so each lookup below takes one
+ * of these rather than repeating them.
+ */
+export class AncestorNodes {
+  constructor(
+    private readonly node: NodeIdentity,
+    private readonly registry: ParentChainRegistry,
+    private readonly locate: PermissionsServiceLocator,
+  ) {}
+
+  /**
+   * The first non-`undefined` answer `pick` gives for an ancestor's service.
+   *
+   * The walk is transitive rather than one hop: an exclusion applies to every
+   * descendant equally, so in a nested spawn the grandchild's own parent is
+   * missing the same registration it is.
+   *
+   * A hop that published no service is stepped over rather than ending the
+   * walk — the registry still names that node's own parent — and each hop is
+   * resolved through the locator per call, never cached, so a torn-down node
+   * simply stops answering.
+   */
+  findFirst<T>(
+    pick: (service: PermissionsService) => T | undefined,
+  ): T | undefined {
+    let sessionId = this.node.currentSessionId();
+    // A malformed chain must not hang a tool call; a node is consulted once.
+    const visited = new Set<string>();
+
+    while (sessionId !== null && !visited.has(sessionId)) {
+      visited.add(sessionId);
+      const parentSessionId = this.registry.get(sessionId)?.parentSessionId;
+      if (parentSessionId === undefined) {
+        return undefined;
+      }
+      const service = this.locate(parentSessionId);
+      const answer = service ? pick(service) : undefined;
+      if (answer !== undefined) {
+        return answer;
+      }
+      sessionId = parentSessionId;
+    }
+    return undefined;
+  }
+}
+
+/**
+ * An extractor lookup that falls back to this node's ancestors.
+ *
+ * The local registry always wins, so a child that registers its own extractor
+ * for a tool keeps it, and the fallback is consulted only on a miss.
+ */
+export class InheritingToolAccessExtractorLookup
+  implements ToolAccessExtractorLookup
+{
+  constructor(
+    private readonly local: ToolAccessExtractorLookup,
+    private readonly ancestors: AncestorNodes,
+  ) {}
+
+  resolve(toolName: string): ResolvedToolAccessExtractor | undefined {
+    const own = this.local.resolve(toolName);
+    if (own) {
+      return own;
+    }
+    const inherited = this.ancestors.findFirst((service) =>
+      service.getToolAccessExtractor(toolName),
+    );
+    return inherited
+      ? { extractor: inherited, origin: "inherited" }
+      : undefined;
+  }
+}
+
+/**
+ * A formatter lookup that falls back to this node's ancestors.
+ *
+ * Unlike the extractor above it reports no origin, because its consumer records
+ * none: a formatter's effect is the rendered preview itself, and the child
+ * builds that preview and forwards it to whichever node renders the ask.
+ */
+export class InheritingToolInputFormatterLookup
+  implements ToolInputFormatterLookup
+{
+  constructor(
+    private readonly local: ToolInputFormatterLookup,
+    private readonly ancestors: AncestorNodes,
+  ) {}
+
+  get(toolName: string): ToolInputFormatter | undefined {
+    return (
+      this.local.get(toolName) ??
+      this.ancestors.findFirst((service) =>
+        service.getToolInputFormatter(toolName),
+      )
+    );
+  }
+}

package/src/config-schema.ts

@@ -79,57 +79,103 @@ const surfaceValueSchema = z.union([
 ]);
 
 /**
- * The `path` and `external_directory` families' directional members
- * (ADR 0013 §3), named so editors offer autocomplete and hover documentation.
+ * The legal spellings of a directional surface key (ADR 0013 §3).
  *
- * Naming them as properties rather than leaving them to the catchall is also
- * what lets the loader tell a legal directional key from a misspelled one —
- * see {@link rejectMisspelledDirectionalKeys}.
+ * This is the loader's allowlist — {@link rejectUnusableSurfaceKeys} rejects a
+ * key shaped like a directional surface that is not one of these — and the
+ * schema documents exactly these four as named properties. Nothing structural
+ * holds the two halves together, so a test in `config-schema.test.ts` does.
  */
-const DIRECTIONAL_SURFACE_DESCRIPTIONS: Record<
-  string,
-  { description: string; markdownDescription: string }
-> = {
-  path_read: {
-    description:
-      "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
-    markdownDescription:
-      'Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `"path_read": { "~/dev/*": "allow" }` permits reads without permitting writes.\n\nA bare `"path"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.',
-  },
-  path_write: {
-    description:
-      "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
-    markdownDescription:
-      'Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `"path_write": { "*": "deny" }` is a coherent read-only-agent posture. A `"path_write": "allow"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `"path"` key.',
-  },
-  external_directory_read: {
-    description:
-      "Boundary gate for reading outside the working directory. The relief most asks want.",
-    markdownDescription:
-      'Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `"external_directory_read": { "~/dev/*": "allow" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.',
-  },
-  external_directory_write: {
-    description: "Boundary gate for writing outside the working directory.",
-    markdownDescription:
-      'Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `"external_directory"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.',
-  },
-};
+const DIRECTIONAL_SURFACE_KEYS = [
+  "path_read",
+  "path_write",
+  "external_directory_read",
+  "external_directory_write",
+] as const;
+
+/**
+ * One documented, optional property for a well-known permission surface.
+ *
+ * A named property is what an editor completes and hovers; the enclosing
+ * object's `.catchall(...)` is what keeps every other tool name valid. Each
+ * surface's prose lives here rather than on the object, so a reader gets the
+ * key under their cursor and not all nine of its neighbours.
+ */
+function surfaceProperty(meta: {
+  description: string;
+  markdownDescription: string;
+}) {
+  return surfaceValueSchema.optional().meta(meta);
+}
 
 const permissionSchema = z
-  .object(
-    Object.fromEntries(
-      Object.entries(DIRECTIONAL_SURFACE_DESCRIPTIONS).map(([key, meta]) => [
-        key,
-        surfaceValueSchema.optional().meta(meta),
-      ]),
-    ),
-  )
+  .object({
+    "*": surfaceProperty({
+      description:
+        "Universal fallback — the action used when no surface-specific rule matches. Omitted, it defaults to ask.",
+      markdownDescription:
+        'Universal fallback — the action used when **no** surface-specific rule matches.\n\n`{ "*": "ask" }` is the least-privilege posture, and is what an omitted `"*"` means anyway. It replaces `defaultPolicy.tools` from the legacy config format.\n\nA surface-specific rule always beats it, whatever the key order in the file.',
+    }),
+    path: surfaceProperty({
+      description:
+        "Cross-cutting gate for file access by path pattern, across every path-aware tool. Sugar for both directions.",
+      markdownDescription:
+        "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).\n\nA `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from every path-aware tool at once.\n\nThis bare key is **sugar**: it expands at load into `path_read` and `path_write`, its entries placed first, so an explicit directional entry always has the final say whatever the key order in the file.",
+    }),
+    path_read: surfaceProperty({
+      description:
+        "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
+      markdownDescription:
+        'Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `"path_read": { "~/dev/*": "allow" }` permits reads without permitting writes.\n\nA bare `"path"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.',
+    }),
+    path_write: surfaceProperty({
+      description:
+        "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
+      markdownDescription:
+        'Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `"path_write": { "*": "deny" }` is a coherent read-only-agent posture. A `"path_write": "allow"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `"path"` key.',
+    }),
+    external_directory: surfaceProperty({
+      description:
+        "Boundary gate for access outside the session working directory. Sugar for both directions.",
+      markdownDescription:
+        'Boundary gate for access **outside** the session working directory.\n\nGive it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `{ "*": "ask", "~/.cargo/registry/*": "allow" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself.\n\nBecause layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\nThis bare key is **sugar**: it expands at load into `external_directory_read` and `external_directory_write`, its entries placed first.',
+    }),
+    external_directory_read: surfaceProperty({
+      description:
+        "Boundary gate for reading outside the working directory. The relief most asks want.",
+      markdownDescription:
+        'Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `"external_directory_read": { "~/dev/*": "allow" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.',
+    }),
+    external_directory_write: surfaceProperty({
+      description: "Boundary gate for writing outside the working directory.",
+      markdownDescription:
+        'Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `"external_directory"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.',
+    }),
+    bash: surfaceProperty({
+      description:
+        "Shell command execution, matched per top-level command in a chain. Most restrictive wins.",
+      markdownDescription:
+        "Shell command execution, matched by **command pattern**.\n\nA chain (`&&`, `||`, `;`, `|`, newline) is split into its top-level commands and each is matched independently, most-restrictive-wins — so `cd /repo && npm install x` is denied when `npm *` is. A command nested in a substitution, process substitution, or subshell is matched too, since it really runs.\n\nA leading env-var assignment is stripped before matching (`AWS_PROFILE=prod aws …` matches `aws *`), and a pattern ending in ` *` (space + wildcard) also matches the bare command (`git *` matches `git`). A pattern containing a chain operator never matches — write one pattern per command.\n\nA shell wrapper (`bash -c`, `eval`, `sudo`, `xargs`) is floored from `allow` to `ask`, so an opaque payload cannot ride a permissive rule.",
+    }),
+    mcp: surfaceProperty({
+      description:
+        "Registered MCP proxy tools, matched against targets derived from the tool input.",
+      markdownDescription:
+        "Registered MCP proxy tools, matched against targets derived from the tool input: a baseline op (`mcp_status`, `mcp_list`, `mcp_search`, `mcp_describe`, `mcp_connect`), a server name (`myServer`), a server/tool combination (`myServer:search`, `myServer_search`), or the generic `mcp_call`.\n\nBaseline discovery targets auto-allow whenever any explicit `mcp` allow rule exists.",
+    }),
+    skill: surfaceProperty({
+      description:
+        "Skill invocation, matched by skill name. The surface is `skill`, not `skills`.",
+      markdownDescription:
+        'Skill invocation, matched by skill name — the surface is `skill`, not `skills`.\n\nWildcards behave as everywhere else: `{ "*": "ask", "dangerous-*": "deny", "librarian": "allow" }`.',
+    }),
+  })
   .catchall(surfaceValueSchema)
   .meta({
     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 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\nWhen Pi\'s current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd "$DIR"` style commands remain conservative.\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\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `"external_directory": { "*": "ask", "~/.cargo/registry/*": "allow" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.',
+      'Flat permission policy.\n\nEach top-level key is a surface: the `"*"` fallback, a well-known surface documented below, or any registered tool name.\n\nA **string** value is shorthand for `{ "*": action }` (a 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\nWhen Pi\'s current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd "$DIR"` style commands remain conservative.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.',
     examples: [
       {
         "*": "ask",
@@ -176,7 +222,7 @@ function rejectUnusableSurfaceKeys(
   permission: Record<string, unknown>,
   ctx: z.core.$RefinementCtx,
 ): void {
-  const legalDirectionalKeys = Object.keys(DIRECTIONAL_SURFACE_DESCRIPTIONS);
+  const legalDirectionalKeys: readonly string[] = DIRECTIONAL_SURFACE_KEYS;
   for (const key of Object.keys(permission)) {
     if (key === "") {
       ctx.addIssue({

package/src/config-store.ts

@@ -140,8 +140,6 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    *
    * Equivalent to `saveExtensionConfig(runtime, next, ctx)`.
    */
-  // Called via the CommandConfigStore interface from config-modal.ts — fallow cannot trace through interfaces.
-  // fallow-ignore-next-line unused-class-member
   save(
     next: PermissionSystemExtensionConfig,
     ctx: ExtensionCommandContext,

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

@@ -7,7 +7,11 @@ import { SessionApproval } from "#src/session-approval";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateResult } from "./descriptor";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
-import { accessFactsFromPath } from "./helpers";
+import {
+  accessFactsFromPath,
+  buildPathGateLogContext,
+  buildPathGatePromptDetails,
+} from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -25,7 +29,7 @@ export function describeExternalDirectoryGate(
   normalizer: PathNormalizer,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
-  const externalDirectoryPath = getToolInputPath(
+  const { path: externalDirectoryPath, source: pathSource } = getToolInputPath(
     tcc.toolName,
     tcc.input,
     extractors,
@@ -49,13 +53,11 @@ export function describeExternalDirectoryGate(
       decidedBy: { kind: "infrastructure_read" },
       log: {
         event: "permission_request.infrastructure_auto_allowed",
-        details: {
-          source: "tool_call",
-          toolCallId: tcc.toolCallId,
-          toolName: tcc.toolName,
-          agentName: tcc.agentName,
-          path: externalDirectoryPath,
-        },
+        details: buildPathGateLogContext(
+          tcc,
+          externalDirectoryPath,
+          pathSource,
+        ),
       },
       decision: {
         surface: tcc.toolName,
@@ -101,21 +103,12 @@ export function describeExternalDirectoryGate(
     preCheck,
     payload,
     sessionApproval: SessionApproval.single(surface, pattern),
-    promptDetails: {
-      source: "tool_call",
-      agentName: tcc.agentName,
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      path: externalDirectoryPath,
-      accessIntent: accessFactsFromPath(surface, accessPath),
-    },
-    logContext: {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      path: externalDirectoryPath,
-    },
+    promptDetails: buildPathGatePromptDetails(
+      tcc,
+      externalDirectoryPath,
+      accessFactsFromPath(surface, accessPath),
+    ),
+    logContext: buildPathGateLogContext(tcc, externalDirectoryPath, pathSource),
     decision: {
       surface,
       value: externalDirectoryPath,

package/src/handlers/gates/helpers.ts

@@ -1,9 +1,75 @@
 import type { AccessPath } from "#src/access-intent/access-path";
+import type { ToolPathSource } from "#src/access-intent/tool-input-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type { ForwardedAccessFacts } from "#src/authority/permission-forwarding";
+import type { PromptPermissionDetails } from "#src/authority/permission-prompter";
 import type { PermissionDecisionResolution } from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
 import type { DecisionEventFacts } from "./descriptor";
+import type { ToolCallContext } from "./types";
+
+/**
+ * The identity fields every path-shaped tool gate reports about its call.
+ *
+ * Narrower than {@link ToolCallContext} (ISP): the fact builders below read
+ * who asked and which call it was, never the raw input or the cwd.
+ */
+type PathGateRequestFacts = Pick<
+  ToolCallContext,
+  "toolCallId" | "toolName" | "agentName"
+>;
+
+/**
+ * Build the review-log context for a path-shaped tool gate.
+ *
+ * The `path` and `external_directory` gates report the same five facts about a
+ * call, so they share one builder — a field added here reaches both, and the
+ * two cannot drift.
+ * The request facts and the request id are stamped by the runner, not here.
+ *
+ * `pathSource` adds `extractorSource` only when the path came from an
+ * **inherited** extractor — a decision that depended on another node's
+ * registration says so, and every other decision stays exactly as wide as it
+ * was. Stamping the ordinary case too would put a constant on effectively
+ * every record in the log.
+ */
+export function buildPathGateLogContext(
+  tcc: PathGateRequestFacts,
+  path: string,
+  pathSource?: ToolPathSource,
+): Record<string, unknown> {
+  return {
+    source: "tool_call",
+    toolCallId: tcc.toolCallId,
+    toolName: tcc.toolName,
+    agentName: tcc.agentName,
+    path,
+    ...(pathSource === "inherited_extractor"
+      ? { extractorSource: "inherited" }
+      : {}),
+  };
+}
+
+/**
+ * Build the prompt details for a path-shaped tool gate.
+ *
+ * The same five facts as {@link buildPathGateLogContext}, plus the child-fixed
+ * access facts the ask carries onto the wire.
+ */
+export function buildPathGatePromptDetails(
+  tcc: PathGateRequestFacts,
+  path: string,
+  accessIntent: ForwardedAccessFacts,
+): Omit<PromptPermissionDetails, "requestId" | "payload"> {
+  return {
+    source: "tool_call",
+    agentName: tcc.agentName,
+    toolCallId: tcc.toolCallId,
+    toolName: tcc.toolName,
+    path,
+    accessIntent,
+  };
+}
 
 /**
  * Build the child-fixed access facts for a path-shaped gate from its

package/src/handlers/gates/path.ts

@@ -6,7 +6,11 @@ import { buildPathAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateDescriptor, GateResult } from "./descriptor";
-import { accessFactsFromPath } from "./helpers";
+import {
+  accessFactsFromPath,
+  buildPathGateLogContext,
+  buildPathGatePromptDetails,
+} from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -23,7 +27,11 @@ export function describePathGate(
   normalizer: PathNormalizer,
   extractors?: ToolAccessExtractorLookup,
 ): GateResult {
-  const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
+  const { path: filePath, source: pathSource } = getToolInputPath(
+    tcc.toolName,
+    tcc.input,
+    extractors,
+  );
   if (!filePath) return null;
 
   // The narrowest `path`-family surface this tool's identity proves. A tool
@@ -66,21 +74,12 @@ export function describePathGate(
     input: { path: filePath },
     payload,
     sessionApproval: SessionApproval.single(surface, pattern),
-    promptDetails: {
-      source: "tool_call",
-      agentName: tcc.agentName,
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      path: filePath,
-      accessIntent: accessFactsFromPath(surface, accessPath),
-    },
-    logContext: {
-      source: "tool_call",
-      toolCallId: tcc.toolCallId,
-      toolName: tcc.toolName,
-      agentName: tcc.agentName,
-      path: filePath,
-    },
+    promptDetails: buildPathGatePromptDetails(
+      tcc,
+      filePath,
+      accessFactsFromPath(surface, accessPath),
+    ),
+    logContext: buildPathGateLogContext(tcc, filePath, pathSource),
     decision: {
       surface,
       value: filePath,

package/src/index.ts

@@ -17,6 +17,11 @@ import {
   ServingHeartbeatStore,
 } from "./authority/forwarding-liveness";
 import { ForwardingManager } from "./authority/forwarding-manager";
+import {
+  AncestorNodes,
+  InheritingToolAccessExtractorLookup,
+  InheritingToolInputFormatterLookup,
+} from "./authority/inherited-registrations";
 import { PERMISSION_FORWARDING_TIMEOUT_MS } from "./authority/permission-forwarding";
 import { requestPermissionDecision } from "./authority/permission-prompt-component";
 import { PermissionPrompter } from "./authority/permission-prompter";
@@ -322,11 +327,25 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     reporter,
     isYoloEnabled,
   );
+  // This node's ancestors in the current process. The gates read their
+  // fact-shaping registrations through the inheriting lookups below, so a
+  // child whose own registry is missing an extractor still sees the path its
+  // tool touches (ADR 0012 decision 1, the fact-shaping clause; #793).
+  // Registration itself is untouched: the service's registrars still write to
+  // the undecorated registries, so an entry lands in this node alone.
+  const ancestorNodes = new AncestorNodes(
+    serviceLifecycle,
+    subagentRegistry,
+    getPermissionsService,
+  );
   const toolCallGatePipeline = new ToolCallGatePipeline(
     resolver,
     session,
-    formatterRegistry,
-    accessExtractorRegistry,
+    new InheritingToolInputFormatterLookup(formatterRegistry, ancestorNodes),
+    new InheritingToolAccessExtractorLookup(
+      accessExtractorRegistry,
+      ancestorNodes,
+    ),
   );
   const skillInputGatePipeline = new SkillInputGatePipeline(resolver);
   const gates = new PermissionGateHandler(

package/src/normalize.ts

@@ -35,6 +35,11 @@ export function expandDirectionalSugar(
   const expanded: FlatPermissionConfig = {};
   for (const [surface, value] of Object.entries(permission)) {
     // A key present with an explicit `undefined` value carries no rules.
+    // `Object.entries` resolves to the catchall's non-optional value type, so
+    // the type cannot see this case even though a named optional surface
+    // admits it; dropping the guard expands `{ path: undefined }` into two
+    // empty directional surfaces. Pinned in `normalize.test.ts`.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime-reachable; see above
     if (value === undefined) continue;
     const members = surfaceFamilyMembers(surface);
     if (members === null) {

package/src/permissions-service.ts

@@ -7,10 +7,12 @@ import type { PathNormalizer } from "./path-normalizer";
 import type { PermissionsService } from "./service";
 import type {
   ToolAccessExtractor,
+  ToolAccessExtractorLookup,
   ToolAccessExtractorRegistrar,
 } from "./tool-access-extractor-registry";
 import type {
   ToolInputFormatter,
+  ToolInputFormatterLookup,
   ToolInputFormatterRegistrar,
 } from "./tool-input-formatter-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
@@ -44,8 +46,10 @@ export class LocalPermissionsService implements PermissionsService {
   constructor(
     private readonly resolver: ResolverForService,
     private readonly session: PathNormalizerProvider,
-    private readonly formatterRegistry: ToolInputFormatterRegistrar,
-    private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar,
+    private readonly formatterRegistry: ToolInputFormatterRegistrar &
+      ToolInputFormatterLookup,
+    private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar &
+      ToolAccessExtractorLookup,
     private readonly authorizerRegistry: AuthorizerRegistrar,
   ) {}
 
@@ -91,6 +95,20 @@ export class LocalPermissionsService implements PermissionsService {
     return this.accessExtractorRegistry.register(toolName, extractor);
   }
 
+  getToolAccessExtractor(
+    toolName: string,
+  ): ReturnType<PermissionsService["getToolAccessExtractor"]> {
+    // The origin is the gates' concern, not a caller's: this surface answers
+    // the capability, and where it came from rides the gate's log context.
+    return this.accessExtractorRegistry.resolve(toolName)?.extractor;
+  }
+
+  getToolInputFormatter(
+    toolName: string,
+  ): ReturnType<PermissionsService["getToolInputFormatter"]> {
+    return this.formatterRegistry.get(toolName);
+  }
+
   registerAuthorizer(
     name: string,
     authorize: Authorizer["authorize"],

package/src/service-lifecycle.ts

@@ -1,5 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AdjudicationRole } from "./authority/authorizer-selection";
+import type { NodeIdentity } from "./authority/inherited-registrations";
 import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
 import {
   type PermissionsService,
@@ -45,7 +46,7 @@ export interface ReadyAnnouncer {
  *   superseded `/reload` generation cannot evict the fresh one.
  */
 export class PermissionServiceLifecycle
-  implements ServiceLifecycle, ReadyAnnouncer
+  implements ServiceLifecycle, ReadyAnnouncer, NodeIdentity
 {
   /** The key this instance last published under; `null` until it publishes. */
   private publishedSessionId: string | null = null;
@@ -60,6 +61,17 @@ export class PermissionServiceLifecycle
     private readonly subscriptions: readonly (() => void)[],
   ) {}
 
+  /**
+   * This node's own session id, or `null` before it has published.
+   *
+   * Satisfies `NodeIdentity`: the fact-shaping lookups need to know which node
+   * they run in to find their ancestors, and this class already reads it from
+   * the context at `activate` and holds it — so identity keeps one home.
+   */
+  currentSessionId(): string | null {
+    return this.publishedSessionId;
+  }
+
   activate(ctx: ExtensionContext): void {
     // Re-arm: a new session generation gets its own post-session_start
     // announcement, so a consumer that loaded after this node still hears one.

package/src/service.ts

@@ -168,6 +168,32 @@ export interface PermissionsService extends PermissionQuery {
     extractor: ToolAccessExtractor,
   ): () => void;
 
+  /**
+   * The access extractor registered on this node for `toolName`, or
+   * `undefined` when it has none.
+   *
+   * This is the read face of a **fact-shaping** registry, and unlike the
+   * authority surfaces it is meant to be read across a node boundary: an
+   * extractor produces a fact about a call (the path it touches) and decides
+   * nothing, so an in-process child whose own registry has no entry may
+   * resolve an ancestor node's service and use its answer to complete the
+   * child's own fact-gathering (ADR 0012 decision 1).
+   *
+   * The same does not hold for {@link registerAuthorizer}: a link produces a
+   * verdict, and live authority converges at the adjudicating node (ADR 0007
+   * §7). There is deliberately no reader for it.
+   */
+  getToolAccessExtractor(toolName: string): ToolAccessExtractor | undefined;
+
+  /**
+   * The preview formatter registered on this node for `toolName`, or
+   * `undefined` when it has none.
+   *
+   * Fact-shaping, and cross-node readable for the same reason as
+   * {@link getToolAccessExtractor}.
+   */
+  getToolInputFormatter(toolName: string): ToolInputFormatter | undefined;
+
   /**
    * Register a named live-authority chain link (ADR 0007 §4).
    *

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

@@ -12,12 +12,32 @@ export type ToolAccessExtractor = (
   input: Record<string, unknown>,
 ) => string | undefined;
 
+/**
+ * Which node's registration answered a lookup.
+ *
+ * `"inherited"` means the answer came from an ancestor node in this process
+ * rather than from this node's own registry (ADR 0012 decision 1, the
+ * fact-shaping clause). A gate records it so a child's dependence on another
+ * node's registration is never invisible.
+ */
+export type RegistrationOrigin = "local" | "inherited";
+
+/** An extractor together with the node whose registry supplied it. */
+export interface ResolvedToolAccessExtractor {
+  extractor: ToolAccessExtractor;
+  origin: RegistrationOrigin;
+}
+
 /**
  * Read-only lookup used by the gate pipeline (ISP — exposes only the read
  * side, not the registration surface).
+ *
+ * It answers with the origin rather than a bare function because the gates
+ * report where a path came from; an implementation that can only answer from
+ * its own registry reports `"local"`.
  */
 export interface ToolAccessExtractorLookup {
-  get(toolName: string): ToolAccessExtractor | undefined;
+  resolve(toolName: string): ResolvedToolAccessExtractor | undefined;
 }
 
 /**
@@ -62,7 +82,8 @@ export class ToolAccessExtractorRegistry
     };
   }
 
-  get(toolName: string): ToolAccessExtractor | undefined {
-    return this.extractors.get(toolName);
+  resolve(toolName: string): ResolvedToolAccessExtractor | undefined {
+    const extractor = this.extractors.get(toolName);
+    return extractor ? { extractor, origin: "local" } : undefined;
   }
 }