@gotgenes/pi-permission-system 29.1.0 → 29.2.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.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))
 
 ---
 

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.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

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/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/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;
   }
 }