@gotgenes/pi-permission-system 29.3.0 → 30.0.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [30.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.3.0...pi-permission-system-v30.0.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** record a session approval's surface per pattern ([499444d](https://github.com/gotgenes/pi-packages/commit/499444df5a21e289409cbf3b360033a13d0eba56)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+* **pi-permission-system:** grant each external path only the direction its command proved ([aa38c74](https://github.com/gotgenes/pi-packages/commit/aa38c746bf9b82ed0dc96217cf4789aae9f090cd)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+
+### Documentation
+
+* **pi-permission-system:** document per-pattern approval surfaces and mark Phase 14 Step 10 ([5511450](https://github.com/gotgenes/pi-packages/commit/551145024364cc794b3c48256362d69971aa69de)), closes [#810](https://github.com/gotgenes/pi-packages/issues/810)
+
 ## [29.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.2.0...pi-permission-system-v29.3.0) (2026-09-02)
 
 

package/README.md

@@ -210,6 +210,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
 | [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
 | [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                 |
 | [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone         |
+| [docs/migration/0810-per-pattern-approval-surfaces.md](docs/migration/0810-per-pattern-approval-surfaces.md)                   | Per-pattern approval surfaces (breaking) — `ForwardedSessionApproval.grants` replaces `surface` + `patterns`         |
 
 ## Development
 

package/dist/public.d.ts

@@ -1,5 +1,19 @@
 import { z } from 'zod';
 
+/**
+ * One session-approval grant: a wildcard pattern approved on one surface.
+ *
+ * A gate proves a direction per accessed path (ADR 0013 §7), so an ask whose
+ * paths disagree records a surface per pattern rather than one for all of them
+ * (#810). This lives in its own module because both the {@link SessionApproval}
+ * value object and the forwarded wire type name it, and those two already
+ * import in one direction.
+ */
+interface ApprovalGrant {
+    readonly surface: string;
+    readonly pattern: string;
+}
+
 declare const permissionStateSchema: z.ZodUnion<readonly [z.ZodLiteral<"allow">, z.ZodLiteral<"deny">, z.ZodLiteral<"ask">]>;
 /** A permission decision. */
 type PermissionState = z.infer<typeof permissionStateSchema>;
@@ -316,16 +330,21 @@ interface PermissionDecisionEvent {
 
 /**
  * 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.
+ * human who grants "the whole session" records the same grants 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`.
+ * from it via `SessionApproval.forGrants`.
+ *
+ * Each grant carries its own surface (#810). The pre-#810 shape — one
+ * `surface` plus a `patterns` list — is rejected by the reader rather than
+ * normalized, so a version-skewed pair drops the suggestion and the serving
+ * dialog offers no whole-session scope; the requesting child still records its
+ * own grant, so the failure is narrow in both directions.
  */
 interface ForwardedSessionApproval {
-    surface: string;
-    patterns: readonly string[];
+    grants: readonly ApprovalGrant[];
 }
 /**
  * The child-fixed facts a gate emits: the surface it evaluated and the match

package/docs/migration/0810-per-pattern-approval-surfaces.md

@@ -0,0 +1,76 @@
+# Migration guide: a session approval carries a surface per pattern
+
+Starting with the release that closes #810, a session-scoped approval records each of its patterns on the surface that pattern's own access was proven on, instead of recording every pattern on one shared surface.
+
+This is a **breaking change** on one surface, with a second, milder effect during a version-skew window.
+
+| Surface                                                           | Break                                            | Who is affected                                                             |
+| ----------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
+| `ForwardedSessionApproval` (a field of `PromptPermissionDetails`) | `surface` and `patterns` removed; `grants` added | Any extension whose registered `Authorizer` reads `details.sessionApproval` |
+| `ForwardedPermissionRequest.sessionApproval` (on-disk wire)       | the old shape is rejected, not normalized        | Anyone running **out-of-process** subagents across mixed versions           |
+
+## What changed, and why it is not just a rename
+
+A permission gate proves a direction for each path it sees: reading `/outside/a.ts` proves a read, redirecting into `/elsewhere/b.ts` proves a write, and an unclassifiable access proves neither.
+The bash external-directory gate aggregates every uncovered path into **one** prompt, so it built one approval covering all of them.
+
+Because that approval held a single surface, it could only be as narrow as the whole prompt agreed.
+A command touching paths in two directions fell back to the direction-neutral family name, which grants both directions.
+So approving
+
+```bash
+cat /outside/a.ts > /elsewhere/b.ts
+```
+
+for the session also granted writes under `/outside` and reads under `/elsewhere` — wider than the prompt named.
+
+Each pattern now carries its own surface, so that approval grants a read under `/outside` and a write under `/elsewhere`, and nothing else.
+
+Two paths in the **same** directory still grant both directions there.
+The recorded pattern is the path's directory scope, so both paths produce the same pattern and the two grants land on the same directory in opposite directions — which is exactly what the prompt showed.
+
+## If you register an `Authorizer`
+
+A chain link receives `PromptPermissionDetails`, whose optional `sessionApproval` field changed shape:
+
+```typescript
+// Before
+const surface = details.sessionApproval?.surface;
+const first = details.sessionApproval?.patterns[0];
+
+// After
+const first = details.sessionApproval?.grants[0];
+const surface = first?.surface;
+const pattern = first?.pattern;
+```
+
+`grants` is a non-empty array of `{ surface, pattern }`, in the order the gate produced them.
+Read each entry's own `surface` — do not assume the first one describes the rest, which is the assumption this change exists to remove.
+
+Most links never touch this field; it exists so a serving node can offer a whole-session grant scope, and links that only rule on the request are unaffected.
+
+## If you run out-of-process subagents
+
+A subagent with no UI writes its ask to a request file that its parent session reads.
+The suggestion travels in that file, and the reader accepts only the new shape — the old one is rejected rather than converted.
+
+That matters only while a parent and a child are running **different** versions of this extension, which happens when an upgrade lands on disk while a parent session is already loaded.
+An in-process child shares its parent's loaded extension and can never skew.
+
+The effect is symmetric and bounded:
+
+- The request is still accepted, and the ask still prompts.
+  Only the suggestion is dropped.
+- With no suggestion, the prompt shows its base four options instead of asking whether the grant covers the whole serving session.
+- Choosing "for this session" then records on the **requesting subagent** — the least-privilege default the two-step dialog already pre-selected.
+
+So a skewed pair loses an affordance; it never produces a wider grant, and there is no upgrade ordering to observe.
+Restart the serving session after upgrading to restore the scope step.
+
+Carrying the old shape alongside the new was considered and declined.
+The wire file turned out to be the smaller of the two breaks: the type is reachable from this package's published type declarations, so replacing its fields breaks a consumer at compile time regardless of what any file on disk contains — and a compatibility shape would have had to be maintained forever to avoid a break that had already happened.
+
+## Related decisions
+
+- [ADR 0006 — Grant-scope selection on forwarded approvals](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0006-forwarded-grant-scope-selection.md), amended by this change.
+- [ADR 0013 — The permission policy model](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md), §3–§4 for the read/write axis and §9 for a session approval as a policy source.

package/package.json

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

package/src/approval-grant.ts

@@ -0,0 +1,13 @@
+/**
+ * One session-approval grant: a wildcard pattern approved on one surface.
+ *
+ * A gate proves a direction per accessed path (ADR 0013 §7), so an ask whose
+ * paths disagree records a surface per pattern rather than one for all of them
+ * (#810). This lives in its own module because both the {@link SessionApproval}
+ * value object and the forwarded wire type name it, and those two already
+ * import in one direction.
+ */
+export interface ApprovalGrant {
+  readonly surface: string;
+  readonly pattern: string;
+}

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

@@ -350,16 +350,11 @@ export class ForwardedRequestServer implements InboxProcessor {
       return decision;
     }
     if (request.sessionApproval) {
-      this.recorder.recordSessionApproval(
-        SessionApproval.multiple(
-          request.sessionApproval.surface,
-          request.sessionApproval.patterns,
-        ),
-      );
+      const { grants } = request.sessionApproval;
+      this.recorder.recordSessionApproval(SessionApproval.forGrants(grants));
       this.logger.review("forwarded_permission.session_recorded", {
         ...logDetails,
-        surface: request.sessionApproval.surface,
-        patterns: request.sessionApproval.patterns,
+        grants,
       });
     }
     return {

package/src/authority/forwarding-io.ts

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
+import type { ApprovalGrant } from "#src/approval-grant";
 import { asDecisionSource } from "#src/authority/decision-source";
 import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
@@ -49,12 +50,34 @@ function asNullableDisplayString(value: unknown): string | null | undefined {
   return undefined;
 }
 
+/** Narrow an unknown value to an `ApprovalGrant`, or `undefined`. */
+function asApprovalGrant(value: unknown): ApprovalGrant | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const candidate = value as Partial<ApprovalGrant>;
+  if (
+    typeof candidate.surface !== "string" ||
+    candidate.surface.length === 0 ||
+    typeof candidate.pattern !== "string"
+  ) {
+    return undefined;
+  }
+  return { surface: candidate.surface, pattern: candidate.pattern };
+}
+
 /**
  * Narrow an unknown value to a `ForwardedSessionApproval`, or `undefined`.
  *
  * Tolerant read: the child's session-approval suggestion is optional (absent
- * on an older child) and only accepted when well-formed — a non-empty surface
- * and an all-string patterns array.
+ * on an older child) and only accepted when well-formed — a non-empty `grants`
+ * array whose every entry names a non-empty surface and a pattern. The
+ * pre-#810 shape (`surface` plus `patterns`) is rejected rather than
+ * normalized, so a version-skewed request drops the suggestion and the serving
+ * dialog offers no whole-session scope.
+ *
+ * An empty `grants` array is rejected too: it would record nothing while still
+ * writing a `forwarded_permission.session_recorded` entry claiming it had.
  */
 function asForwardedSessionApproval(
   value: unknown,
@@ -63,15 +86,16 @@ function asForwardedSessionApproval(
     return undefined;
   }
   const candidate = value as Partial<ForwardedSessionApproval>;
-  if (
-    typeof candidate.surface !== "string" ||
-    candidate.surface.length === 0 ||
-    !Array.isArray(candidate.patterns) ||
-    !candidate.patterns.every((pattern) => typeof pattern === "string")
-  ) {
+  if (!Array.isArray(candidate.grants) || candidate.grants.length === 0) {
     return undefined;
   }
-  return { surface: candidate.surface, patterns: [...candidate.patterns] };
+  const grants: ApprovalGrant[] = [];
+  for (const entry of candidate.grants) {
+    const grant = asApprovalGrant(entry);
+    if (!grant) return undefined;
+    grants.push(grant);
+  }
+  return { grants };
 }
 
 /**

package/src/authority/local-user-authorizer.ts

@@ -72,13 +72,13 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
 function buildRequestOptions(
   details: PromptPermissionDetails,
 ): RequestPermissionOptions | undefined {
-  const pattern = details.sessionApproval?.patterns[0];
-  if (details.forwarding && details.sessionApproval && pattern) {
+  const grant = details.sessionApproval?.grants[0];
+  if (details.forwarding && grant) {
     return {
       sessionScope: buildForwardedScopeLabels(
         details.forwarding.requesterAgentName,
-        details.sessionApproval.surface,
-        pattern,
+        grant.surface,
+        grant.pattern,
       ),
     };
   }

package/src/authority/permission-forwarding.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import type { ApprovalGrant } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
@@ -83,16 +84,21 @@ export interface ForwardedPromptDisplay {
 
 /**
  * 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.
+ * human who grants "the whole session" records the same grants 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`.
+ * from it via `SessionApproval.forGrants`.
+ *
+ * Each grant carries its own surface (#810). The pre-#810 shape — one
+ * `surface` plus a `patterns` list — is rejected by the reader rather than
+ * normalized, so a version-skewed pair drops the suggestion and the serving
+ * dialog offers no whole-session scope; the requesting child still records its
+ * own grant, so the failure is narrow in both directions.
  */
 export interface ForwardedSessionApproval {
-  surface: string;
-  patterns: readonly string[];
+  grants: readonly ApprovalGrant[];
 }
 
 /**

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

@@ -18,11 +18,11 @@ import type { ToolCallContext } from "./types";
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  *
  * Each path is resolved on the narrowest `external_directory`-family surface
- * its own attributed effect names. The session approval holds one surface for
- * all its patterns, so it narrows only when every uncovered path agrees; a
- * mixed-direction ask falls back to the bare family, which is exactly today's
- * width. Closing that last gap needs `(surface, pattern)` pairs on the
- * approval and its forwarded wire form (#810).
+ * its own attributed effect names, and the session approval records one grant
+ * per uncovered path at that same surface (#810) — so an ask mixing a proven
+ * read with a proven write grants each path only its own direction, never both
+ * on both. Two paths sharing a directory derive the same glob and so grant
+ * both directions there, which is what the prompt showed.
  *
  * The shell command (native `bash` or an aliased shell tool) is read from the
  * injected `BashProgram`, which owns the source text it was parsed from, so
@@ -104,17 +104,15 @@ export function describeBashExternalDirectoryGate(
     surface,
   });
 
-  const patterns = uncoveredEntries.map(({ path }) =>
-    normalizer.approvalPatternFor(path),
-  );
-
   return {
     surface,
     input: {},
     payload,
-    sessionApproval: SessionApproval.multiple(
-      approvalSurfaceFor(uncoveredEntries),
-      patterns,
+    sessionApproval: SessionApproval.forGrants(
+      uncoveredEntries.map((entry) => ({
+        surface: entry.surface,
+        pattern: normalizer.approvalPatternFor(entry.path),
+      })),
     ),
     promptDetails: {
       source: "tool_call",
@@ -143,20 +141,3 @@ export function describeBashExternalDirectoryGate(
     preCheck,
   };
 }
-
-/**
- * The surface one session approval can carry for every uncovered path at once.
- *
- * A {@link SessionApproval} holds one surface for all its patterns, so it can
- * narrow only when the whole ask agrees on a direction. The bare family is the
- * fallback because it sugar-expands onto both members — exactly the width a
- * mixed-direction command is granted today, never wider.
- */
-function approvalSurfaceFor(
-  uncoveredEntries: readonly { readonly surface: string }[],
-): string {
-  const surfaces = new Set(uncoveredEntries.map(({ surface }) => surface));
-  return surfaces.size === 1
-    ? [...surfaces][0]
-    : ("external_directory" as const);
-}

package/src/handlers/gates/runner.ts

@@ -209,7 +209,7 @@ export class GateRunner {
     };
     const gateResult = await applyPermissionGate({
       state: check.state,
-      sessionApproval: descriptor.sessionApproval?.toGateApproval(),
+      canGrantForSession: descriptor.sessionApproval?.isRecordable ?? false,
       promptForApproval: async () => {
         const decision = await this.prompter.escalate({
           requestId,
@@ -230,7 +230,7 @@ export class GateRunner {
 
     // 4. Determine whether session approval was granted
     const hasSessionApproval =
-      gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
+      gateResult.action === "allow" && gateResult.forSession === true;
 
     // 5. Emit decision event
     this.emitDecision(

package/src/permission-gate.ts

@@ -13,7 +13,8 @@ export type PermissionGateResult =
   | {
       action: "allow";
       decidedBy: DecisionSource;
-      sessionApproval?: { surface: string; pattern: string };
+      /** Set when the human granted the ask for the whole session. */
+      forSession?: true;
     }
   | { action: "block"; decidedBy: DecisionSource; reason: string };
 
@@ -30,11 +31,16 @@ export interface PermissionGateParams {
   promptForApproval: () => Promise<PermissionPromptDecision>;
 
   /**
-   * Session approval suggestion to record when the user selects
-   * "for this session". When present and the decision is `approved_for_session`,
-   * the result carries the suggestion back to the caller for recording.
+   * Whether this ask has a session-approval suggestion to record when the user
+   * selects "for this session".
+   *
+   * A boolean rather than the suggestion itself: the gate decides only whether
+   * a whole-session grant happened, and the caller records the suggestion it
+   * already holds. Handing the gate the value would ask it to name a single
+   * representative `(surface, pattern)`, which a multi-pattern approval has no
+   * way to choose (#810).
    */
-  sessionApproval?: { surface: string; pattern: string };
+  canGrantForSession: boolean;
 
   /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
   writeLog: (event: string, extra: Record<string, unknown>) => void;
@@ -102,12 +108,11 @@ export async function applyPermissionGate(
         reason: messages.refusedReason(decision),
       };
     }
-    if (decision.state === "approved_for_session" && params.sessionApproval) {
-      return {
-        action: "allow",
-        decidedBy,
-        sessionApproval: params.sessionApproval,
-      };
+    if (
+      decision.state === "approved_for_session" &&
+      params.canGrantForSession
+    ) {
+      return { action: "allow", decidedBy, forSession: true };
     }
     return { action: "allow", decidedBy };
   }

package/src/session-approval.ts

@@ -1,54 +1,44 @@
+import type { ApprovalGrant } from "#src/approval-grant";
 import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 
 /**
- * Value object for a session-scoped approval: one surface, one-or-more patterns.
+ * Value object for a session-scoped approval: one or more
+ * {@link ApprovalGrant}s, each pairing a pattern with the surface it was
+ * proven on.
  *
  * Owned by gate descriptors and passed to the session store — the runner never
- * needs to know whether there is one pattern or many.
+ * needs to know how many grants an approval carries, and the store records
+ * each on the surface the grant itself names rather than one shared by all
+ * (#810).
  */
 export class SessionApproval {
-  private constructor(
-    readonly surface: string,
-    readonly patterns: readonly string[],
-  ) {}
+  private constructor(readonly grants: readonly ApprovalGrant[]) {}
 
   /** Create an approval for a single pattern (the common case). */
   static single(surface: string, pattern: string): SessionApproval {
-    return new SessionApproval(surface, [pattern]);
+    return new SessionApproval([{ surface, pattern }]);
   }
 
   /**
-   * Create an approval for multiple patterns (e.g. bash external-directory
-   * gates that cover several uncovered paths in one prompt).
+   * Create an approval from grants that may name different surfaces (e.g. a
+   * bash external-directory ask whose uncovered paths proved different
+   * directions). Returns a defensive copy.
    */
-  static multiple(
-    surface: string,
-    patterns: readonly string[],
-  ): SessionApproval {
-    return new SessionApproval(surface, [...patterns]);
+  static forGrants(grants: readonly ApprovalGrant[]): SessionApproval {
+    return new SessionApproval([...grants]);
   }
 
-  /** Representative pattern for the interactive prompt — the first, if any. */
-  get representativePattern(): string | undefined {
-    return this.patterns[0];
-  }
-
-  /**
-   * Single-pattern shape `applyPermissionGate` echoes back to the caller.
-   * Returns `undefined` when patterns is empty (degenerate case).
-   */
-  toGateApproval(): { surface: string; pattern: string } | undefined {
-    const pattern = this.representativePattern;
-    if (pattern === undefined) return undefined;
-    return { surface: this.surface, pattern };
+  /** Whether this approval carries anything for the session store to record. */
+  get isRecordable(): boolean {
+    return this.grants.length > 0;
   }
 
   /**
    * Plain data shape for relaying this approval on a forwarded request, so the
-   * serving node can record the same pattern(s) as a whole-session grant.
-   * Returns a defensive copy of the patterns.
+   * serving node can record the same grants as a whole-session grant.
+   * Returns a defensive copy.
    */
   toForwardedData(): ForwardedSessionApproval {
-    return { surface: this.surface, patterns: [...this.patterns] };
+    return { grants: [...this.grants] };
   }
 }

package/src/session-rules.ts

@@ -41,14 +41,16 @@ export class SessionRules implements SessionApprovalRecorder {
   }
 
   /**
-   * Record all patterns from a `SessionApproval` value object.
+   * Record every grant from a `SessionApproval` value object.
    *
-   * The loop lives here so callers never need to know whether an approval
-   * carries one pattern or many — they just tell the store to record it.
+   * The loop lives here so callers never need to know how many grants an
+   * approval carries — they just tell the store to record it. Each grant is
+   * recorded on the surface it names, so an ask whose paths proved different
+   * directions grants each path only its own (#810).
    */
   recordSessionApproval(approval: SessionApproval): void {
-    for (const pattern of approval.patterns) {
-      this.approve(approval.surface, pattern);
+    for (const { surface, pattern } of approval.grants) {
+      this.approve(surface, pattern);
     }
   }