@gotgenes/pi-permission-system 20.7.2 → 20.8.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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).
 
+## [20.8.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.7.3...pi-permission-system-v20.8.0) (2026-07-18)
+
+
+### Features
+
+* **pi-permission-system:** accept pre-fixed path-values intents for forwarded serving ([ab60874](https://github.com/gotgenes/pi-packages/commit/ab6087464c7719c01bd7f2a15fd4c56a1a7e9f93))
+* **pi-permission-system:** declare ForwardedAccessIntent wire schema with tolerant read ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([66ddbef](https://github.com/gotgenes/pi-packages/commit/66ddbef74e3fa6cd41d17358a0b817ae91d49ed1))
+* **pi-permission-system:** emit access-intent facts from the bash path gates ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([1a0e6de](https://github.com/gotgenes/pi-packages/commit/1a0e6de3fdf411ab576d0c9aa5571ff23cb5f179))
+* **pi-permission-system:** emit access-intent facts from the per-tool gate ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([2e17256](https://github.com/gotgenes/pi-packages/commit/2e1725695442b10073ea627ce9699ef363e4c77c))
+* **pi-permission-system:** emit access-intent facts from the skill gates ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([5a20033](https://github.com/gotgenes/pi-packages/commit/5a20033fca9f33dee576c5d39c0c04e468d2d031))
+* **pi-permission-system:** emit access-intent facts from the tool path gates ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([93a3398](https://github.com/gotgenes/pi-packages/commit/93a3398245b06fe6cb80f841d2a2ca5dc8172de5))
+* **pi-permission-system:** serialize the child-fixed access intent onto the forwarded request ([#596](https://github.com/gotgenes/pi-packages/issues/596)) ([5234614](https://github.com/gotgenes/pi-packages/commit/52346148c41a097719558175582b57d12e7832d0))
+* **pi-permission-system:** serving resolves the forwarded access intent at gate parity ([#597](https://github.com/gotgenes/pi-packages/issues/597)) ([a8fe815](https://github.com/gotgenes/pi-packages/commit/a8fe815bd70e3243553b7cac6841ec270e20bf23))
+
+
+### Documentation
+
+* **pi-permission-system:** fix stale ServingPolicy doc comment ([#597](https://github.com/gotgenes/pi-packages/issues/597)) ([64b1b8e](https://github.com/gotgenes/pi-packages/commit/64b1b8e13a8d22ee4f088bef7d54024a81d9a437))
+
+## [20.7.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.7.2...pi-permission-system-v20.7.3) (2026-07-15)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** ship consumable public type declarations ([#592](https://github.com/gotgenes/pi-packages/issues/592)) ([542e094](https://github.com/gotgenes/pi-packages/commit/542e094b9650e8f13bd9dad3864007f3ce2c0cc2))
+
+
+### Documentation
+
+* **pi-permission-system:** document the bundled public type declaration ([070875d](https://github.com/gotgenes/pi-packages/commit/070875d654efde50e8867f8fd4aeba857a26c4fb))
+
 ## [20.7.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.7.1...pi-permission-system-v20.7.2) (2026-07-14)
 
 

package/dist/public.d.ts

@@ -0,0 +1,249 @@
+import { z } from 'zod';
+
+/**
+ * Registry for custom tool access-intent extractors.
+ *
+ * Lets sibling extensions declare the filesystem path a tool will access when
+ * the tool's input shape is not the default `input.path` convention, so the
+ * cross-cutting `path` and `external_directory` gates can see it.
+ * One extractor per tool name; duplicate registration throws.
+ */
+/** Returns the filesystem path this tool will access, or `undefined` to decline. */
+type ToolAccessExtractor = (input: Record<string, unknown>) => string | undefined;
+
+/**
+ * Registry for custom tool-input preview formatters.
+ *
+ * Allows extensions to register a formatter for a specific tool name so
+ * permission prompts can show a human-readable summary instead of raw JSON.
+ * One formatter per tool name; duplicate registration throws.
+ */
+/** A custom preview formatter for one tool's input. Returns `undefined` to decline. */
+type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined;
+
+declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
+/** A permission decision. */
+type PermissionState = z.infer<typeof permissionStateSchema>;
+
+/**
+ * Provenance of a rule — which source contributed it.
+ *
+ * Config scopes: "global", "project", "agent", "project-agent".
+ * Synthesized:   "builtin" (universal default / evaluate() fallback),
+ *                "baseline" (conditional MCP metadata auto-allow).
+ * Runtime:       "session" (session approvals).
+ * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode).
+ */
+type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo";
+
+/**
+ * Execution context of a bash command nested inside a substitution or subshell.
+ * Absent for current-shell (top-level) commands.
+ */
+type BashCommandContext = "command_substitution" | "process_substitution" | "subshell";
+interface PermissionCheckResult {
+    toolName: string;
+    state: PermissionState;
+    /** Custom denial reason from a deny-with-reason pattern, when present. */
+    reason?: string;
+    matchedPattern?: string;
+    command?: string;
+    target?: string;
+    source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
+    /** Which source contributed the winning rule. */
+    origin: RuleOrigin;
+    /**
+     * Execution context of the offending nested command, when the winning bash
+     * unit came from a substitution or subshell. Absent for current-shell
+     * (top-level) commands.
+     */
+    commandContext?: BashCommandContext;
+}
+
+/** Emitted at `session_start`, after the service is published. */
+declare const PERMISSIONS_READY_CHANNEL = "permissions:ready";
+/** Emitted when a permission request is committed to the active UI prompt path. */
+declare const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
+/** Emitted after every permission gate resolution. */
+declare const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
+/**
+ * Payload emitted on `permissions:ready`.
+ *
+ * Intentionally empty: the channel is a readiness signal. There is no
+ * `protocolVersion` — the published types plus package semver define the
+ * broadcast contract.
+ */
+type PermissionsReadyEvent = Record<string, never>;
+/**
+ * Origin of a UI prompt.
+ *
+ * Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its
+ * original source and is identified by a non-null `forwarding` field, not by a
+ * dedicated source value.
+ */
+type PermissionUiPromptSource = "tool_call" | "skill_input" | "skill_read";
+/** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
+interface ForwardedPromptContext {
+    /** Requesting subagent's display name, when known. */
+    requesterAgentName: string | null;
+    /** Requesting subagent's session id, when known. */
+    requesterSessionId: string | null;
+}
+/**
+ * Payload emitted on `permissions:ui_prompt`, immediately before the active
+ * user-facing permission UI is shown.
+ *
+ * Lean by design: `surface`/`value` are the normalized display projection a
+ * notification consumer reads; `source` is the origin; `forwarding` is non-null
+ * only for forwarded subagent prompts. There is no `protocolVersion` — the
+ * published types plus package semver define the broadcast contract, and
+ * consumers should read defensively.
+ */
+interface PermissionUiPromptEvent {
+    /** Unique ID for the permission request being prompted. */
+    requestId: string;
+    /** Prompt origin. */
+    source: PermissionUiPromptSource;
+    /** Normalized display surface (e.g. "bash", "skill"), when known. */
+    surface: string | null;
+    /** Normalized display value (command, path, skill name, etc.), when known. */
+    value: string | null;
+    /** Agent name (when known). */
+    agentName: string | null;
+    /** Message displayed to the user. */
+    message: string;
+    /** Forwarding context, or null for a direct prompt. */
+    forwarding: ForwardedPromptContext | null;
+}
+/** How a permission decision was reached. */
+type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable";
+/** Payload emitted on `permissions:decision`. */
+interface PermissionDecisionEvent {
+    /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
+    surface: string;
+    /** The value that was evaluated (command, tool name, skill name, path). */
+    value: string;
+    /** Final decision. */
+    result: "allow" | "deny";
+    /** How the decision was reached. */
+    resolution: PermissionDecisionResolution;
+    /** Which config scope contributed the winning rule (when available). */
+    origin: string | null;
+    /** Agent name (when known). */
+    agentName: string | null;
+    /** Matched pattern from the winning rule (when available). */
+    matchedPattern: string | null;
+}
+
+/**
+ * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ *
+ * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
+ * module isolation (`moduleCache: false`). A consumer doing
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
+ * `getPermissionsService()` reads from the same `globalThis` slot the provider
+ * wrote to — enabling direct, synchronous, type-safe function calls.
+ *
+ * Best practice: call `getPermissionsService()` per use rather than caching the
+ * reference — this ensures resilience across `/reload` and load-order edge cases.
+ */
+
+/**
+ * Public interface exposed to other extensions via `getPermissionsService()`.
+ *
+ * `checkPermission` takes a surface + optional value + optional agent name,
+ * and delegates to `PermissionManager.checkPermission()` with current session
+ * rules internally.
+ */
+interface PermissionsService {
+    /**
+     * Query the permission policy for a surface and value.
+     *
+     * @param surface   - Permission surface: "bash", "read", "mcp", "skill",
+     *                    "external_directory", etc.
+     * @param value     - The value to evaluate: command string, tool name, skill
+     *                    name, or path. Omit or pass `undefined` for a
+     *                    surface-level query.
+     * @param agentName - Optional agent name for per-agent policy resolution.
+     * @returns Full check result including state, matched pattern, and origin.
+     */
+    checkPermission(surface: string, value?: string, agentName?: string): PermissionCheckResult;
+    /**
+     * Register a custom preview formatter for a specific tool name.
+     *
+     * The formatter is consulted first inside `ToolPreviewFormatter.formatToolInputForPrompt`;
+     * returning `undefined` falls through to the built-in switch (and ultimately
+     * the JSON default).
+     *
+     * Only one formatter may be registered per tool name — a second call for the
+     * same name throws.  The returned disposer unregisters the formatter.
+     *
+     * @param toolName  - Exact tool name to register for (e.g. `"mcp"`, `"my-server:run"`).
+     * @param formatter - Receives the raw `input` record; return a string to use
+     *                    as the prompt preview, or `undefined` to decline.
+     */
+    registerToolInputFormatter(toolName: string, formatter: ToolInputFormatter): () => void;
+    /**
+     * Register a custom access-intent extractor for a specific tool name.
+     *
+     * The extractor declares the filesystem path a tool will access so the
+     * cross-cutting `path` and `external_directory` gates can see it. Use it for
+     * tools whose path lives under a non-standard key — built-in file tools and
+     * any tool exposing `input.path` (plus MCP via `input.arguments.path`) are
+     * already covered by convention without registration.
+     *
+     * The extractor receives the raw `input` record and returns the path string,
+     * or `undefined` to decline. Only one extractor may be registered per tool
+     * name — a second call for the same name throws. The returned disposer
+     * unregisters the extractor.
+     *
+     * @param toolName  - Exact tool name to register for (e.g. `"ffgrep"`).
+     * @param extractor - Receives the raw `input` record; return the path string,
+     *                    or `undefined` to decline.
+     */
+    registerToolAccessExtractor(toolName: string, extractor: ToolAccessExtractor): () => void;
+    /**
+     * Query the tool-level permission state for pre-filtering tools before
+     * creating a child session.
+     *
+     * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
+     * Does not consider command-level rules (e.g. per-bash-command patterns) —
+     * use `checkPermission` for runtime invocation gates.
+     *
+     * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+     * @param agentName - Optional agent name for per-agent policy resolution.
+     */
+    getToolPermission(toolName: string, agentName?: string): PermissionState;
+}
+/**
+ * Store a `PermissionsService` on `globalThis` so other extensions can
+ * retrieve it via `getPermissionsService()`.
+ *
+ * Called at `session_start` by the top-level (parent) instance only — an
+ * in-process subagent child skips publishing so it cannot clobber the parent's
+ * service. Overwrites any previously published service, which keeps `/reload`
+ * working: a reloaded parent re-publishes its fresh service.
+ */
+declare function publishPermissionsService(service: PermissionsService): void;
+/**
+ * Retrieve the published `PermissionsService`, or `undefined` if the
+ * permission-system extension has not loaded (or has been unloaded).
+ */
+declare function getPermissionsService(): PermissionsService | undefined;
+/**
+ * Remove `service` from `globalThis`, but only when the current slot still
+ * holds it (identity compare-and-delete).
+ *
+ * Called during `session_shutdown` to avoid stale references after the
+ * extension is torn down. Scoping the delete to the publishing instance keeps
+ * two cases correct:
+ *
+ * - An in-process subagent child never published the parent's service, so its
+ *   shutdown is a no-op and the parent's slot survives.
+ * - A superseded `/reload` generation no longer owns the slot, so its late
+ *   shutdown cannot wipe the new generation's freshly published service.
+ */
+declare function unpublishPermissionsService(service: PermissionsService): void;
+
+export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
+export type { ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, ToolInputFormatter };

package/docs/cross-extension-api.md

@@ -39,6 +39,9 @@ Consumers call `getPermissionsService()` to retrieve it — even though their `i
 An in-process subagent child does not publish its own service; inside a child, `getPermissionsService()` resolves the parent's service.
 A consumer reacting to the `permissions:ready` broadcast (also emitted at `session_start`, after the publish) can resolve the service immediately.
 
+All types below are directly importable and type-check with `tsc` out of the box.
+`@gotgenes/pi-permission-system`'s published `exports` resolve `import type { … }` to a self-contained, bundled declaration file with no internal module references, so a downstream `tsconfig.json` needs no special path configuration.
+
 ### API
 
 The `PermissionsService` interface:

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "20.7.2",
+  "version": "20.8.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
-    ".": "./src/service.ts"
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service.ts"
+    }
   },
   "imports": {
     "#src/*": "./src/*",
@@ -12,6 +15,7 @@
   },
   "files": [
     "src",
+    "dist",
     "config/config.example.json",
     "schemas/permissions.schema.json",
     "docs/*.md",
@@ -67,6 +71,8 @@
     "@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",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
@@ -78,9 +84,11 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
     "gen:schema": "node --experimental-strip-types scripts/generate-permissions-schema.ts && biome format --write schemas/permissions.schema.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"
   }

package/src/access-intent/input-normalizer.ts

@@ -1,7 +1,7 @@
 import { stripBashCommentLines } from "#src/bash-arity";
 import type { PathNormalizer } from "#src/path-normalizer";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
-import type { AccessIntent } from "./access-intent";
+import type { AccessIntent, ResolvedAccessIntent } from "./access-intent";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { PATH_SURFACES } from "./path-surfaces";
 import { classifyToolKind } from "./tool-kind";
@@ -41,6 +41,39 @@ export function buildAccessIntentForSurface(
   };
 }
 
+/**
+ * Build a {@link ResolvedAccessIntent} directly from a forwarded request's
+ * child-fixed match values (ADR 0008 §2), for the forwarded-serving wire
+ * (#597).
+ *
+ * Unlike {@link buildAccessIntentForSurface}, this never touches a
+ * `PathNormalizer` and never rebuilds an `AccessPath` — a path-shaped surface
+ * gets a `path-values` intent carrying `matchValues` as-is (the values the
+ * child already fixed), and every other surface gets a `tool` intent built
+ * from its single portable value. `agentName` is always the requester's
+ * `principal.agentName` (ADR 0008 §3, agent-scoped serving).
+ */
+export function buildResolvedIntentFromMatchValues(
+  surface: string,
+  matchValues: readonly string[],
+  agentName: string,
+): ResolvedAccessIntent {
+  if (PATH_SURFACES.has(surface)) {
+    return {
+      kind: "path-values",
+      surface,
+      values: [...matchValues],
+      agentName,
+    };
+  }
+  return {
+    kind: "tool",
+    surface,
+    input: buildInputForSurface(surface, matchValues[0]),
+    agentName,
+  };
+}
+
 /**
  * Construct a surface-appropriate input object from a raw value string for the
  * `tool`-intent branch of {@link buildAccessIntentForSurface} (the non-path

package/src/authority/approval-escalator.ts

@@ -6,6 +6,7 @@ import {
 } from "#src/active-agent";
 import {
   type ForwarderContext,
+  getCwd,
   getSessionId,
 } from "#src/authority/forwarder-context";
 import {
@@ -20,6 +21,7 @@ import {
 } from "#src/authority/forwarding-io";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
+  type ForwardedAccessFacts,
   type ForwardedPermissionRequest,
   type ForwardedPromptDisplay,
   type ForwardedSessionApproval,
@@ -61,6 +63,23 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
 
 // ── ParentAuthorizer ────────────────────────────────────────────────────
 
+/**
+ * The facts a forwarded request relays unchanged from the child's ask: the
+ * prompt message, the optional display projection, and the optional
+ * session-approval suggestion.
+ *
+ * Bundled into one object so the two-hop private chain
+ * (`waitForForwardedApproval` → `buildForwardedRequest`) threads a single
+ * relayed value instead of three positional optionals.
+ */
+interface ForwardedRequestFacts {
+  message: string;
+  display?: ForwardedPromptDisplay;
+  sessionApproval?: ForwardedSessionApproval;
+  /** The child-fixed access facts; the edge completes them into a `ForwardedAccessIntent`. */
+  accessIntent?: ForwardedAccessFacts;
+}
+
 /** Constructor config for {@link ParentAuthorizer}. */
 export interface ParentAuthorizerDeps {
   forwardingDir: string;
@@ -99,25 +118,23 @@ export class ParentAuthorizer implements Authorizer {
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
     const uiPrompt = buildUiPrompt(details);
-    return this.waitForForwardedApproval(
-      this.ctx,
-      details.message,
-      {
+    return this.waitForForwardedApproval(this.ctx, {
+      message: details.message,
+      display: {
         source: uiPrompt.source,
         surface: uiPrompt.surface,
         value: uiPrompt.value,
       },
-      details.sessionApproval,
-    );
+      sessionApproval: details.sessionApproval,
+      accessIntent: details.accessIntent,
+    });
   }
 
   // ── Private methods ────────────────────────────────────────────────────
 
   private async waitForForwardedApproval(
     ctx: ForwarderContext,
-    message: string,
-    forwarded?: ForwardedPromptDisplay,
-    sessionApproval?: ForwardedSessionApproval,
+    facts: ForwardedRequestFacts,
   ): Promise<PermissionPromptDecision> {
     const requesterSessionId = getSessionId(ctx);
     const targetSessionId = resolvePermissionForwardingTargetSessionId({
@@ -159,11 +176,9 @@ export class ParentAuthorizer implements Authorizer {
 
     const request = this.buildForwardedRequest(
       ctx,
-      message,
+      facts,
       requesterSessionId,
       targetSessionId,
-      forwarded,
-      sessionApproval,
     );
     const requestPath = join(location.requestsDir, `${request.id}.json`);
     const responsePath = join(location.responsesDir, `${request.id}.json`);
@@ -198,32 +213,47 @@ export class ParentAuthorizer implements Authorizer {
 
   private buildForwardedRequest(
     ctx: ForwarderContext,
-    message: string,
+    facts: ForwardedRequestFacts,
     requesterSessionId: string,
     targetSessionId: string,
-    forwarded?: ForwardedPromptDisplay,
-    sessionApproval?: ForwardedSessionApproval,
   ): ForwardedPermissionRequest {
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
     const requesterAgentName =
       getActiveAgentName(ctx) ??
       getActiveAgentNameFromSystemPrompt(getContextSystemPrompt(ctx)) ??
       "unknown";
+    // Complete the child-fixed facts into a full ForwardedAccessIntent: the
+    // gate fixed the access facts; the edge stamps the requester identity it
+    // alone knows (cwd + principal). The parent resolves against this intent
+    // and never re-derives the match set (ADR 0008).
+    const accessIntent = facts.accessIntent
+      ? {
+          ...facts.accessIntent,
+          requesterCwd: getCwd(ctx),
+          principal: {
+            sessionId: requesterSessionId,
+            agentName: requesterAgentName,
+          },
+        }
+      : undefined;
     return {
       id: requestId,
       createdAt: Date.now(),
       requesterSessionId,
       targetSessionId,
       requesterAgentName,
-      message,
-      ...(forwarded
+      message: facts.message,
+      ...(facts.display
         ? {
-            source: forwarded.source,
-            surface: forwarded.surface,
-            value: forwarded.value,
+            source: facts.display.source,
+            surface: facts.display.surface,
+            value: facts.display.value,
           }
         : {}),
-      ...(sessionApproval ? { sessionApproval } : {}),
+      ...(facts.sessionApproval
+        ? { sessionApproval: facts.sessionApproval }
+        : {}),
+      ...(accessIntent ? { accessIntent } : {}),
     };
   }
 

package/src/authority/forwarded-request-server.ts

@@ -5,6 +5,7 @@ import {
 } from "#src/authority/forwarder-context";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
+  type ForwardedAccessIntent,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   isForwardedPermissionRequestForSession,
@@ -43,23 +44,25 @@ export interface InboxProcessor {
 
 /**
  * Recorded-authority view the serving node resolves a forwarded request
- * against: answer one `(surface, value)` query on the serving session's
- * composed base ruleset (agent-neutral — the child already applied its own
- * per-agent overrides before forwarding).
+ * against: answer one {@link ForwardedAccessIntent} query on the serving
+ * session's composed ruleset, agent-scoped to the requester
+ * (`principal.agentName`, ADR 0008 §3) — the child-fixed `matchValues` are
+ * used as-is, never re-derived through this session's `PathNormalizer`/cwd.
  *
  * Narrow by design (ISP): the server needs one decision, not the whole
- * resolver. The composition root satisfies it with an access-intent build plus
- * `resolver.resolve`, the same primitives `LocalPermissionsService` composes.
+ * resolver. The composition root satisfies it with
+ * `buildResolvedIntentFromMatchValues` plus `resolver.resolve`, the same
+ * `resolve` entry point `LocalPermissionsService` composes.
  */
 export interface ServingPolicy {
-  check(surface: string, value: string | null): PermissionCheckResult;
+  resolve(intent: ForwardedAccessIntent): PermissionCheckResult;
 }
 
 /** Constructor config for `ForwardedRequestServer`. */
 export interface ForwardedRequestServerDeps {
   forwardingDir: string;
   logger: DebugReviewLogger;
-  /** Recorded-authority resolution for `(surface, value)` requests. */
+  /** Recorded-authority resolution for a forwarded `ForwardedAccessIntent`. */
   policy: ServingPolicy;
   /** Escalation seam to the serving session's selected `Authorizer` on `ask`. */
   escalator: AskEscalator;
@@ -87,22 +90,6 @@ function formatForwardedPermissionPrompt(
   ].join("\n");
 }
 
-/**
- * A request is resolvable against the ruleset only when it carries a concrete
- * `(surface, value)` display projection. A legacy/version-skew request without
- * them floors to `ask` (escalate), never a silent grant.
- */
-function hasDisplayFields(
-  request: ForwardedPermissionRequest,
-): request is ForwardedPermissionRequest & { surface: string; value: string } {
-  return (
-    typeof request.surface === "string" &&
-    request.surface.length > 0 &&
-    typeof request.value === "string" &&
-    request.value.length > 0
-  );
-}
-
 /**
  * Map a forwarded request onto the escalated ask's details, carrying the
  * forwarded provenance (requester agent/session + the child's original display
@@ -135,9 +122,10 @@ function buildForwardedAskDetails(
 /**
  * Owner of the serving-down role of the forwarded-permission behavior:
  * draining this session's forwarded-permission inbox and answering each
- * request the same way the session resolves a local action — `evaluate()`
- * against its recorded authority (`ServingPolicy`), then escalation to its
- * selected `Authorizer` (`AskEscalator`) on `ask`.
+ * request the same way the session resolves a local action — resolving its
+ * `ForwardedAccessIntent` against recorded authority (`ServingPolicy`), then
+ * escalation to its selected `Authorizer` (`AskEscalator`) on `ask` (ADR
+ * 0008).
  */
 export class ForwardedRequestServer implements InboxProcessor {
   private readonly forwardingDir: string;
@@ -343,17 +331,19 @@ export class ForwardedRequestServer implements InboxProcessor {
 
   /**
    * Resolve the request the same way the session resolves a local action:
-   * recorded authority first (a request carrying `(surface, value)` resolves
-   * against the serving node's composed ruleset — `allow`, including
-   * yolo-rewritten, auto-approves; `deny` auto-denies), then escalate `ask`
-   * (or a request without display fields) to the selected `Authorizer`.
+   * recorded authority first (a request carrying an `accessIntent` — the
+   * child-fixed facts, ADR 0008 §2 — resolves against the serving node's
+   * composed ruleset — `allow`, including yolo-rewritten, auto-approves;
+   * `deny` auto-denies), then escalate `ask` (or a request missing
+   * `accessIntent`, the version-skew floor, ADR 0008 §4) to the selected
+   * `Authorizer`.
    */
   private async resolveDecision(
     request: ForwardedPermissionRequest,
     logDetails: Record<string, unknown>,
   ): Promise<PermissionPromptDecision> {
-    const state = hasDisplayFields(request)
-      ? this.policy.check(request.surface, request.value).state
+    const state = request.accessIntent
+      ? this.policy.resolve(request.accessIntent).state
       : "ask";
 
     if (state === "allow") {

package/src/authority/forwarder-context.ts

@@ -12,6 +12,8 @@ import type { PermissionDecisionUi } from "#src/authority/permission-dialog";
 export interface ForwarderContext {
   hasUI: boolean;
   ui: PermissionDecisionUi;
+  /** The session's working directory, stamped onto a forwarded request as the requester cwd. */
+  cwd: string;
   sessionManager: {
     getSessionId(): string;
     getSessionDir(): string;
@@ -19,6 +21,11 @@ export interface ForwarderContext {
   };
 }
 
+/** Reads the current session cwd off `ctx`. */
+export function getCwd(ctx: ForwarderContext): string {
+  return ctx.cwd;
+}
+
 /** Reads the current session id off `ctx`, falling back to `"unknown"`. */
 export function getSessionId(ctx: ForwarderContext): string {
   try {

package/src/authority/forwarding-io.ts

@@ -12,6 +12,7 @@ import {
 import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
   createPermissionForwardingLocation,
+  type ForwardedAccessIntent,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   type ForwardedSessionApproval,
@@ -67,6 +68,65 @@ function asForwardedSessionApproval(
   return { surface: candidate.surface, patterns: [...candidate.patterns] };
 }
 
+/**
+ * Narrow an unknown value to a `ForwardedAccessIntent`, or `undefined`.
+ *
+ * Tolerant read: the child-fixed access intent is optional (absent on an older
+ * child) and only accepted when fully well-formed — a string `surface`, an
+ * all-string `matchValues` array, a `string | null` `boundaryValue`, a string
+ * `requesterCwd`, and a `principal` with string `sessionId`/`agentName`. Any
+ * malformed shape → `undefined`, so the serving node floors to `ask` (Step 3)
+ * rather than resolving against corrupt facts.
+ */
+function asForwardedAccessIntent(
+  value: unknown,
+): ForwardedAccessIntent | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const candidate = value as {
+    surface?: unknown;
+    matchValues?: unknown;
+    boundaryValue?: unknown;
+    requesterCwd?: unknown;
+    principal?: unknown;
+  };
+  if (
+    typeof candidate.surface !== "string" ||
+    !Array.isArray(candidate.matchValues) ||
+    !candidate.matchValues.every((entry) => typeof entry === "string") ||
+    !(
+      candidate.boundaryValue === null ||
+      typeof candidate.boundaryValue === "string"
+    ) ||
+    typeof candidate.requesterCwd !== "string" ||
+    typeof candidate.principal !== "object" ||
+    candidate.principal === null
+  ) {
+    return undefined;
+  }
+  const principal = candidate.principal as {
+    sessionId?: unknown;
+    agentName?: unknown;
+  };
+  if (
+    typeof principal.sessionId !== "string" ||
+    typeof principal.agentName !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    surface: candidate.surface,
+    matchValues: [...candidate.matchValues],
+    boundaryValue: candidate.boundaryValue,
+    requesterCwd: candidate.requesterCwd,
+    principal: {
+      sessionId: principal.sessionId,
+      agentName: principal.agentName,
+    },
+  };
+}
+
 export function formatUnknownErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message) {
     return error.message;
@@ -350,6 +410,7 @@ export function readForwardedPermissionRequest(
       surface: asNullableDisplayString(parsed.surface),
       value: asNullableDisplayString(parsed.value),
       sessionApproval: asForwardedSessionApproval(parsed.sessionApproval),
+      accessIntent: asForwardedAccessIntent(parsed.accessIntent),
     };
   } catch (error) {
     logPermissionForwardingWarning(

package/src/authority/permission-forwarding.ts

@@ -66,6 +66,46 @@ export interface ForwardedSessionApproval {
   patterns: readonly string[];
 }
 
+/**
+ * The child-fixed facts a gate emits: the surface it evaluated and the match
+ * set it computed. `requesterCwd` and `principal` are stamped at the escalation
+ * edge (`ParentAuthorizer`), so a gate carries only what it alone can produce.
+ *
+ * Strings only — an `AccessPath` never crosses onto the wire
+ * (`docs/decisions/0002-path-values-string-boundary.md`).
+ */
+export interface ForwardedAccessFacts {
+  /** Gate surface: `"path"`, `"external_directory"`, `"bash"`, a tool name, or a skill name. */
+  surface: string;
+  /**
+   * The child-fixed match set. Path surface: `AccessPath.matchValues()`
+   * (absolute ∪ cwd-relative ∪ canonical), computed at the child. Non-path
+   * surface: the already-portable single value as a one-element array.
+   */
+  matchValues: string[];
+  /** `AccessPath.boundaryValue()` (canonical) for a path surface; `null` for a non-path surface. */
+  boundaryValue: string | null;
+}
+
+/**
+ * The forwarded-wire access intent (ADR 0008 §2): the child-fixed access facts
+ * plus the requester identity the escalation edge stamps.
+ *
+ * The serving node resolves against this intent directly (Step 3, [#597]),
+ * using `matchValues` as-is — it never re-derives a path through its own
+ * `PathNormalizer`/cwd. See
+ * `docs/decisions/0008-cross-session-access-intent.md`.
+ */
+export interface ForwardedAccessIntent extends ForwardedAccessFacts {
+  /** The requester's cwd, for provenance/disclosure — never for parent re-derivation. */
+  requesterCwd: string;
+  /** Who is requesting. */
+  principal: {
+    sessionId: string;
+    agentName: string;
+  };
+}
+
 export type ForwardedPermissionRequest = {
   id: string;
   createdAt: number;
@@ -89,6 +129,12 @@ export type ForwardedPermissionRequest = {
    * omits it, and the serving dialog then offers no scope choice).
    */
   sessionApproval?: ForwardedSessionApproval;
+  /**
+   * The child-fixed access intent (ADR 0008 §2). Optional for version-skew
+   * tolerance: an older child omits it, and the serving node floors to `ask`
+   * (Step 3). Present on a current child's request for every gate surface.
+   */
+  accessIntent?: ForwardedAccessIntent;
 };
 
 export type ForwardedPermissionResponse = {

package/src/authority/permission-prompter.ts

@@ -1,5 +1,8 @@
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
-import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
+import type {
+  ForwardedAccessFacts,
+  ForwardedSessionApproval,
+} from "#src/authority/permission-forwarding";
 import type { ReviewLogger } from "#src/session-logger";
 import type { Authorizer } from "./authorizer";
 
@@ -46,6 +49,14 @@ export interface PromptPermissionDetails {
    * suggestion.
    */
   sessionApproval?: ForwardedSessionApproval;
+  /**
+   * The child-fixed access facts the raising gate computed (surface + match
+   * set). Rides through the runner to the escalation edge, which completes
+   * them into a `ForwardedAccessIntent` by stamping `requesterCwd` and
+   * `principal`. Absent for a serving-node local prompt reconstructed from a
+   * forwarded request.
+   */
+  accessIntent?: ForwardedAccessFacts;
 }
 
 /**

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

@@ -5,6 +5,7 @@ import { deriveApprovalPattern } from "#src/session-rules";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";
+import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -65,6 +66,10 @@ export function describeBashExternalDirectoryGate(
   // defined; the fallback keeps TypeScript happy across the early return. A
   // config-level "deny" is preserved (not downgraded to the catch-all "ask").
   const preCheck = worstCheck ?? uncoveredEntries[0].check;
+  // The AccessPath the decision was made against — its facts ride the wire.
+  const worstEntry =
+    uncoveredEntries.find(({ check }) => check === preCheck) ??
+    uncoveredEntries[0];
 
   const disclosures = uncoveredEntries.map(({ path }) => ({
     path: path.value(),
@@ -98,6 +103,7 @@ export function describeBashExternalDirectoryGate(
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,
+      accessIntent: accessFactsFromPath("external_directory", worstEntry.path),
     },
     logContext: {
       source: "tool_call",

package/src/handlers/gates/bash-path.ts

@@ -6,6 +6,7 @@ import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
+import { accessFactsFromPath } from "./helpers";
 import { formatPathAskPrompt } from "./path";
 import type { ToolCallContext } from "./types";
 
@@ -135,6 +136,7 @@ export function describeBashPathGate(
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,
+      accessIntent: accessFactsFromPath("path", worstEntry.path),
     },
     logContext: {
       source: "tool_call",

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

@@ -7,6 +7,7 @@ import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-regis
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
+import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -104,6 +105,7 @@ export function describeExternalDirectoryGate(
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: externalDirectoryPath,
+      accessIntent: accessFactsFromPath("external_directory", accessPath),
     },
     logContext: {
       source: "tool_call",

package/src/handlers/gates/helpers.ts

@@ -1,10 +1,43 @@
+import type { AccessPath } from "#src/access-intent/access-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
+import type { ForwardedAccessFacts } from "#src/authority/permission-forwarding";
 import type {
   PermissionDecisionEvent,
   PermissionDecisionResolution,
 } from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
 
+/**
+ * Build the child-fixed access facts for a path-shaped gate from its
+ * `AccessPath`.
+ *
+ * Converts the `AccessPath` to strings at the point of emission (ADR-0002: an
+ * `AccessPath` never crosses onto the wire), carrying the lexical ∪ canonical
+ * match set. An empty `boundaryValue()` (a literal-only path) becomes `null`,
+ * so the wire distinguishes "no canonical form" cleanly.
+ */
+export function accessFactsFromPath(
+  surface: string,
+  path: AccessPath,
+): ForwardedAccessFacts {
+  return {
+    surface,
+    matchValues: path.matchValues(),
+    boundaryValue: path.boundaryValue() || null,
+  };
+}
+
+/**
+ * Build the child-fixed access facts for a non-path gate (bash command, MCP
+ * target, skill name, plain tool) from its already-portable single value.
+ */
+export function accessFactsFromValue(
+  surface: string,
+  value: string,
+): ForwardedAccessFacts {
+  return { surface, matchValues: [value], boundaryValue: null };
+}
+
 /**
  * Derive the human-readable value for a decision event from a check result.
  * Bash → extracted command; MCP → qualified target;

package/src/handlers/gates/path.ts

@@ -5,6 +5,7 @@ import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateDescriptor, GateResult } from "./descriptor";
+import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -67,6 +68,7 @@ export function describePathGate(
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: filePath,
+      accessIntent: accessFactsFromPath("path", accessPath),
     },
     logContext: {
       source: "tool_call",

package/src/handlers/gates/skill-input.ts

@@ -1,6 +1,7 @@
 import { formatSkillAskPrompt } from "#src/permission-prompts";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
+import { accessFactsFromValue } from "./helpers";
 
 /**
  * Build a pure descriptor for the skill-input permission gate.
@@ -29,6 +30,7 @@ export function describeSkillInputGate(
       agentName,
       message,
       skillName,
+      accessIntent: accessFactsFromValue("skill", skillName),
     },
     logContext: {
       source: "skill_input",

package/src/handlers/gates/skill-read.ts

@@ -4,6 +4,7 @@ import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
 import { toRecord } from "#src/value-guards";
 import type { GateDescriptor } from "./descriptor";
+import { accessFactsFromValue } from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -64,6 +65,7 @@ export function describeSkillReadGate(
       toolName: tcc.toolName,
       skillName: matchedSkill.name,
       path,
+      accessIntent: accessFactsFromValue("skill", matchedSkill.name),
     },
     logContext: {
       source: "skill_read",

package/src/handlers/gates/tool.ts

@@ -11,7 +11,11 @@ import { SessionApproval } from "#src/session-approval";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
-import { deriveDecisionValue } from "./helpers";
+import {
+  accessFactsFromPath,
+  accessFactsFromValue,
+  deriveDecisionValue,
+} from "./helpers";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -75,6 +79,18 @@ export function describeToolGate(
     formatter,
   );
 
+  const decisionValue = deriveDecisionValue(
+    gateSurface,
+    check,
+    getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
+  );
+
+  // A path-bearing tool carries the AccessPath's alias set; every other surface
+  // (bash command, MCP target, plain tool) carries its already-portable value.
+  const accessIntent = accessPath
+    ? accessFactsFromPath(gateSurface, accessPath)
+    : accessFactsFromValue(gateSurface, decisionValue);
+
   return {
     surface: gateSurface,
     input: tcc.input,
@@ -95,6 +111,7 @@ export function describeToolGate(
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       sessionLabel: suggestion.label,
+      accessIntent,
       ...permissionLogContext,
     },
     logContext: {
@@ -106,11 +123,7 @@ export function describeToolGate(
     },
     decision: {
       surface: gateSurface,
-      value: deriveDecisionValue(
-        gateSurface,
-        check,
-        getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
-      ),
+      value: decisionValue,
     },
   };
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "./access-intent/bash/parser";
-import { buildAccessIntentForSurface } from "./access-intent/input-normalizer";
+import { buildResolvedIntentFromMatchValues } from "./access-intent/input-normalizer";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
 import {
   ForwardedRequestServer,
@@ -116,20 +116,18 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // service and gates below share this one instance.
   const resolver = new PermissionResolver(permissionManager, sessionRules);
 
-  // Serving a forwarded request is resolution: evaluate (surface, value)
-  // against the serving node's composed base ruleset (agentName undefined —
-  // the child already applied its own per-agent overrides before forwarding).
-  // The session.getPathNormalizer() read is deferred behind the closure: inbox
-  // polling starts at session_start, after `session` is assigned — the same
-  // deferred-binding precedent as the logger notify sink below.
+  // Serving a forwarded request is resolution: resolve the child-fixed
+  // ForwardedAccessIntent (ADR 0008) directly against the serving node's
+  // composed ruleset, agent-scoped to the requester (§3) — the match values
+  // are used as fixed by the child, never re-derived through this session's
+  // PathNormalizer/cwd (#597).
   const servingPolicy: ServingPolicy = {
-    check: (surface, value) =>
+    resolve: (intent) =>
       resolver.resolve(
-        buildAccessIntentForSurface(
-          surface,
-          value ?? undefined,
-          session.getPathNormalizer(),
-          undefined,
+        buildResolvedIntentFromMatchValues(
+          intent.surface,
+          intent.matchValues,
+          intent.principal.agentName,
         ),
       ),
   };

package/src/permission-resolver.ts

@@ -1,5 +1,6 @@
 import type {
   AccessIntent,
+  PathValuesAccessIntent,
   ResolvedAccessIntent,
 } from "./access-intent/access-intent";
 import type { ScopedPermissionManager } from "./permission-manager";
@@ -31,8 +32,14 @@ export interface ScopedPermissionResolver {
  * canonical alias set (#418) is derived. Keeping it here (not in the manager)
  * is the deliberate boundary formalized in ADR-0002
  * (`docs/decisions/0002-path-values-string-boundary.md`).
+ *
+ * Also accepts an already-resolved {@link PathValuesAccessIntent} (the
+ * forwarded-serving wire's producer, #597) as a pure passthrough — it is
+ * already a `ResolvedAccessIntent`, so there is nothing to unwrap.
  */
-function toResolvedIntent(intent: AccessIntent): ResolvedAccessIntent {
+function toResolvedIntent(
+  intent: AccessIntent | PathValuesAccessIntent,
+): ResolvedAccessIntent {
   if (intent.kind === "access-path") {
     return {
       kind: "path-values",
@@ -66,8 +73,16 @@ export class PermissionResolver
    * Answer a gate-emitted access intent, composing the current session ruleset
    * so callers never thread it by hand. Unwraps the `access-path` variant via
    * `matchValues()` before handing a string-based intent to the manager.
+   *
+   * Also accepts a pre-fixed `path-values` intent (the forwarded-serving wire,
+   * #597) — a passthrough, since it is already a `ResolvedAccessIntent`. The
+   * gate-facing {@link ScopedPermissionResolver} interface stays narrow
+   * (`AccessIntent` only); this wider acceptance is available only through the
+   * concrete `PermissionResolver` instance the composition root holds.
    */
-  resolve(intent: AccessIntent): PermissionCheckResult {
+  resolve(
+    intent: AccessIntent | PathValuesAccessIntent,
+  ): PermissionCheckResult {
     return this.permissionManager.check(
       toResolvedIntent(intent),
       this.sessionRules.getRuleset(),