@gotgenes/pi-permission-system 20.7.3 → 20.9.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.9.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.8.0...pi-permission-system-v20.9.0) (2026-07-19)
+
+
+### Features
+
+* **pi-permission-system:** add authorizerChain config field ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([6c0bb72](https://github.com/gotgenes/pi-packages/commit/6c0bb72680d864b70e8fac5bb5c480b9a96751f8))
+* **pi-permission-system:** add registerAuthorizer cross-extension seam ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([ea60900](https://github.com/gotgenes/pi-packages/commit/ea60900439d68ccc028ba75c3e432945e0ac3b72))
+* **pi-permission-system:** cap link verdicts with the delegation envelope ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([28733fc](https://github.com/gotgenes/pi-packages/commit/28733fca298f1fea1f7a810b61728f9c96bf225f))
+* **pi-permission-system:** inject a session-scoped PermissionQuery into chain links ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([29452ff](https://github.com/gotgenes/pi-packages/commit/29452ff8cbec6abc431a318b7937843ecefb724d))
+* **pi-permission-system:** resolve the configured authorizer chain ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([fb366d9](https://github.com/gotgenes/pi-packages/commit/fb366d9aed47ab439ffc033e4967a4285d37fe8a))
+
+
+### Documentation
+
+* **pi-permission-system:** document registerAuthorizer + authorizerChain and mark Phase 12 Step 5 complete ([#599](https://github.com/gotgenes/pi-packages/issues/599)) ([1d6b228](https://github.com/gotgenes/pi-packages/commit/1d6b22889296b3277a118cc8168486664c691305))
+
+## [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)
 
 

package/README.md

@@ -112,6 +112,9 @@ Within a surface map like `bash` or `mcp`, **last matching rule wins** — put b
 
 The optional `shellTools` field records which non-`bash` tools carry shell semantics (e.g. an `exec_command` tool that replaces native `bash`), so they are gated at full parity with native `bash` — see [docs/configuration.md](docs/configuration.md#shelltools--gating-aliased-shell-tools).
 
+The optional `authorizerChain` field names registered case-by-case decision links (e.g. a light model judge) to consult when a request lands on `ask`, ahead of the interactive prompt.
+A downstream extension registers a link via `getPermissionsService().registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on `external_directory`/`path` to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
+
 For the full reference — all surfaces, runtime knobs, per-agent overrides, merge semantics, and common recipes — see [docs/configuration.md](docs/configuration.md).
 
 ## Upgrading

package/config/config.example.json

@@ -11,6 +11,8 @@
 
   "piInfrastructureReadPaths": [],
 
+  "authorizerChain": [],
+
   "shellTools": {
     "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }
   },

package/dist/public.d.ts

@@ -1,65 +1,5 @@
 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. */
@@ -135,6 +75,175 @@ interface PermissionDecisionEvent {
     matchedPattern: string | null;
 }
 
+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;
+}
+
+/**
+ * The child's session-approval suggestion, relayed to the serving node so a
+ * human who grants "the whole session" records the same pattern the child
+ * would have recorded locally.
+ *
+ * A plain data shape (not the `SessionApproval` value object) so it serializes
+ * onto the forwarded request; the serving node rebuilds a `SessionApproval`
+ * from it via `SessionApproval.multiple`.
+ */
+interface ForwardedSessionApproval {
+    surface: string;
+    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`).
+ */
+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;
+}
+
+type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
+/**
+ * Provenance of a forwarded ask: who is really asking, one hop below.
+ *
+ * Present on {@link PromptPermissionDetails} only when the ask was forwarded
+ * from a subagent. Structurally identical to the event's `ForwardedPromptContext`
+ * so the details flow straight into `buildUiPrompt`, but declared here to keep
+ * the prompter layer free of an events-module import.
+ */
+interface ForwardedAskProvenance {
+    requesterAgentName: string | null;
+    requesterSessionId: string | null;
+}
+/** Details passed when prompting the user for a permission decision. */
+interface PromptPermissionDetails {
+    requestId: string;
+    source: PermissionReviewSource;
+    agentName: string | null;
+    message: string;
+    toolCallId?: string;
+    toolName?: string;
+    skillName?: string;
+    path?: string;
+    command?: string;
+    target?: string;
+    toolInputPreview?: string;
+    /** Override label for the "for this session" dialog option. */
+    sessionLabel?: string;
+    /** Explicit display-surface override (a forwarded ask carries the child's original). */
+    surface?: string | null;
+    /** Explicit display-value override (a forwarded ask carries the child's original). */
+    value?: string | null;
+    /** Present iff this ask was forwarded from a subagent; drives the non-degraded broadcast + "(Subagent)" title. */
+    forwarding?: ForwardedAskProvenance;
+    /**
+     * The session-approval suggestion for this ask. On the child's escalation it
+     * rides into the forwarded request; on the serving node it lets the dialog
+     * offer a whole-session grant scope. Absent when the gate computed no
+     * 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;
+}
+
+/**
+ * A non-terminal chain link's ruling on an `ask`: decide (`allow`/`deny`) or
+ * pass the ask on to the next link (`defer`). A `deny` carries an optional
+ * teaching `reason` the invoking model sees, so it can self-correct.
+ */
+type AuthorizerVerdict = {
+    kind: "allow";
+} | {
+    kind: "deny";
+    reason?: string;
+} | {
+    kind: "defer";
+};
+/**
+ * A non-terminal link in the live-authority chain: reviews an `ask` and may
+ * decide it or defer to the next link (ADR 0007). The chain injects a narrow,
+ * session-scoped {@link PermissionQuery} at `authorize` time (§3), so a link
+ * queries the deterministic engine at gate parity rather than reaching for the
+ * cross-extension service via `Symbol.for()`.
+ */
+interface Authorizer {
+    authorize(details: PromptPermissionDetails, query: PermissionQuery): Promise<AuthorizerVerdict>;
+}
+
+/**
+ * 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;
+
 /**
  * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
  *
@@ -149,13 +258,12 @@ interface PermissionDecisionEvent {
  */
 
 /**
- * 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.
+ * The narrow, read-only projection of {@link PermissionsService}: answer a
+ * policy query for a surface, and report a tool-level state. This is the
+ * capability an Authorizer chain link is handed (ISP) — it never sees the
+ * registration surface.
  */
-interface PermissionsService {
+interface PermissionQuery {
     /**
      * Query the permission policy for a surface and value.
      *
@@ -168,6 +276,27 @@ interface PermissionsService {
      * @returns Full check result including state, matched pattern, and origin.
      */
     checkPermission(surface: string, value?: string, agentName?: string): PermissionCheckResult;
+    /**
+     * 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;
+}
+/**
+ * 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 extends PermissionQuery {
     /**
      * Register a custom preview formatter for a specific tool name.
      *
@@ -203,17 +332,25 @@ interface PermissionsService {
      */
     registerToolAccessExtractor(toolName: string, extractor: ToolAccessExtractor): () => void;
     /**
-     * Query the tool-level permission state for pre-filtering tools before
-     * creating a child session.
+     * Register a named live-authority chain link (ADR 0007 §4).
      *
-     * 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.
+     * A link reviews an `ask` and returns `allow` / `deny` (with an optional
+     * teaching `reason`) / `defer`. It is handed a narrow, session-scoped
+     * {@link PermissionQuery} at `authorize` time so it can query the
+     * deterministic engine at gate parity. Register from a `permissions:ready`
+     * handler so registration is robust to load order and survives `/reload`.
      *
-     * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
-     * @param agentName - Optional agent name for per-agent policy resolution.
+     * Registration alone grants **no authority**: the link decides nothing until
+     * the operator names it in the `authorizerChain` config (opt-in activation),
+     * and the chain owner caps every verdict with the bounded-delegation
+     * checkpoint (an `allow` on an excluded surface downgrades to `defer`). Only
+     * one link may be registered per name — a second call for the same name
+     * throws. The returned disposer unregisters the link.
+     *
+     * @param name      - Operator-facing link name referenced from `authorizerChain`.
+     * @param authorize - The link's decision callback (`(details, query) => verdict`).
      */
-    getToolPermission(toolName: string, agentName?: string): PermissionState;
+    registerAuthorizer(name: string, authorize: Authorizer["authorize"]): () => void;
 }
 /**
  * Store a `PermissionsService` on `globalThis` so other extensions can
@@ -246,4 +383,4 @@ declare function getPermissionsService(): PermissionsService | undefined;
 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 };
+export type { Authorizer, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptPermissionDetails, ToolInputFormatter };

package/docs/configuration.md

@@ -52,6 +52,9 @@ Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConf
     "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }
   },
 
+  // Ordered names of registered live-authority chain links (empty = none)
+  "authorizerChain": [],
+
   // Flat permission policy
   "permission": {
     "*": "ask",                              // universal fallback
@@ -81,15 +84,16 @@ Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConf
 
 ## Runtime Knobs
 
-| Key                         | Default | Description                                                                                                                                          |
-| --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugLog`                  | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                        |
-| `permissionReviewLog`       | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`                                              |
-| `yoloMode`                  | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                           |
-| `doublePressToConfirm`      | `true`  | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.    |
-| `toolInputPreviewMaxLength` | `200`   | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.      |
-| `toolTextSummaryMaxLength`  | `80`    | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                |
-| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME` expansion and wildcard patterns (`*`, `?`). |
+| Key                         | Default | Description                                                                                                                                                                |
+| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugLog`                  | `false` | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                              |
+| `permissionReviewLog`       | `true`  | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`                                                                    |
+| `yoloMode`                  | `false` | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                 |
+| `doublePressToConfirm`      | `true`  | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                          |
+| `toolInputPreviewMaxLength` | `200`   | Max characters of inline JSON shown in permission prompts for tool inputs. Omit to use the default. Set to a large value to disable truncation.                            |
+| `toolTextSummaryMaxLength`  | `80`    | Max characters of inline pattern/path summaries (grep patterns, find globs, ls paths) in permission prompts. Omit to use the default.                                      |
+| `piInfrastructureReadPaths` | `[]`    | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME` expansion and wildcard patterns (`*`, `?`).                       |
+| `authorizerChain`           | `[]`    | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)). |
 
 Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
 No debug output is printed to the terminal.
@@ -159,6 +163,38 @@ To change a specific tool's mapping, set that tool's key at the project scope (t
 `shellTools` only ever *tightens* enforcement and is inert when the named tool is not registered in the current session.
 Opting a project out of a shell-aliasing extension is a package-disable concern, not a `shellTools` edit.
 
+### Authorizer chain — case-by-case decision links
+
+The deterministic policy above decides `allow` / `deny` / `ask` for every request.
+When a request lands on `ask`, the **authorizer chain** decides who answers it.
+By default that is you (an interactive prompt), the subagent-forwarding path, or a headless deny.
+A downstream extension can register a **link** — a reviewer that sees the `ask` and returns `allow`, `deny` (with an optional teaching reason), or `defer` to the next link — and the chain ends at the default terminal that always decides.
+The canonical use case is a light model judge that reviews asks case by case (e.g. auto-denying an errant typo-path with a corrective reason).
+
+`authorizerChain` is the ordered list of link names to consult, ahead of the terminal:
+
+```jsonc
+{
+  "authorizerChain": ["model-judge"]
+}
+```
+
+Three invariants govern the chain:
+
+1. **Config order wins, never registration order.**
+   The order in `authorizerChain` — not the order extensions happen to register in — fixes the security-relevant chain order.
+2. **A missing link is skipped fail-safe.**
+   A name with no registered link is skipped with a logged warning; the `ask` still reaches the terminal.
+   Absence of a judge means *more* prompting, never less.
+3. **Registration alone grants no authority.**
+   Installing a judge extension gives it nothing; a link decides nothing until you name it here (opt-in activation).
+
+The chain owner caps every link with a **bounded-delegation checkpoint**: a link's `allow` on an excluded surface (`external_directory` or the `path` surface) is downgraded to `defer`, so a buggy or over-eager judge can never approve access outside your policy.
+Deny and defer are never capped.
+
+Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService().registerAuthorizer(name, authorize)`; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
+Registration returns a disposer, and only one link may hold a given name.
+
 ---
 
 ## Policy Reference

package/package.json

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

package/schemas/permissions.schema.json

@@ -55,6 +55,16 @@
         "minLength": 1
       }
     },
+    "authorizerChain": {
+      "description": "Ordered names of registered live-authority chain links to consult before the terminal authorizer. Config order (not registration order) fixes the chain order; an unregistered name is skipped fail-safe (more prompting, never less); a link decides nothing until it is named here.",
+      "markdownDescription": "Ordered names of registered **live-authority chain links** (e.g. a model judge) to consult before the terminal authorizer (the human, or the subagent-forwarding / headless-deny fallback).\n\nA link reviews an `ask` and returns `allow` / `deny` (with an optional teaching reason) / `defer` to the next link. Three invariants govern the chain:\n\n- **Config order wins.** The order here — not the order extensions register in — fixes the security-relevant chain order.\n- **Fail-safe skip.** A name with no registered link is skipped with a warning; the `ask` still reaches the terminal (more prompting, never less).\n- **Opt-in activation.** Installing a judge extension grants it no authority; a link decides nothing until you name it here.\n\nThe chain owner caps every verdict with a bounded-delegation checkpoint: a link's `allow` on an excluded surface (`external_directory` or `path`) is downgraded to `defer`, so a link cannot exceed your policy.\n\nDefaults to an empty list (no links).",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "permission": {
       "type": "object",
       "propertyNames": {

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