@gotgenes/pi-permission-system 20.2.0 → 20.3.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.2.0...pi-permission-system-v20.3.0) (2026-07-09)
+
+
+### Features
+
+* **pi-permission-system:** forward the child's session-approval suggestion ([fa04d8c](https://github.com/gotgenes/pi-packages/commit/fa04d8ca3485ca3f6e29bbe8d53146f5eeb6672c))
+* **pi-permission-system:** offer whole-session scope on forwarded approvals ([bd2be07](https://github.com/gotgenes/pi-packages/commit/bd2be0799923ed809cd0939047486fdc1b2a477f))
+
+
+### Documentation
+
+* **pi-permission-system:** record forwarded grant-scope selection (Phase 9 Step 4) ([a3d1fca](https://github.com/gotgenes/pi-packages/commit/a3d1fca183dc5e4d6fb15ec6ec78199f5d092bc3))
+
 ## [20.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.1.0...pi-permission-system-v20.2.0) (2026-07-09)
 
 

package/docs/subagent-integration.md

@@ -17,6 +17,7 @@ The integration enables:
 2. **Per-agent policy enforcement** - the permission system's `before_agent_start` handler resolves the agent name from the `<active_agent>` system-prompt tag and applies per-agent `permission:` frontmatter overrides.
 3. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
    The parent approves or denies, and the child resumes.
+   When the parent approves "for this session," it chooses a scope: **this subagent only** (the least-privilege default) records the grant on the requesting child, while **the whole session** records it on the serving parent so the parent and all its subagents resolve it without re-prompting.
 
 No configuration is required - the integration is automatic when both extensions are installed.
 When `@gotgenes/pi-permission-system` is not installed, `@gotgenes/pi-subagents` emits its lifecycle events with no subscriber - a harmless no-op.
@@ -25,6 +26,7 @@ When `@gotgenes/pi-permission-system` is not installed, `@gotgenes/pi-subagents`
 
 When a delegated or routed subagent runs without direct UI access, `ask` permissions can still be enforced by forwarding the confirmation request through Pi session directories.
 The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
+A parent `allow`/`deny` rule governs a child's escalation directly (the serving node resolves it as recorded authority before prompting), and a "whole session" grant recorded on the parent auto-approves later forwards of the same pattern.
 
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 

package/package.json

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

package/src/authority/approval-escalator.ts

@@ -22,6 +22,7 @@ import type { PermissionPromptDecision } from "#src/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPromptDisplay,
+  type ForwardedSessionApproval,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
   PERMISSION_FORWARDING_TIMEOUT_MS,
   type PermissionForwardingLocation,
@@ -98,11 +99,16 @@ export class ParentAuthorizer implements Authorizer {
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
     const uiPrompt = buildUiPrompt(details);
-    return this.waitForForwardedApproval(this.ctx, details.message, {
-      source: uiPrompt.source,
-      surface: uiPrompt.surface,
-      value: uiPrompt.value,
-    });
+    return this.waitForForwardedApproval(
+      this.ctx,
+      details.message,
+      {
+        source: uiPrompt.source,
+        surface: uiPrompt.surface,
+        value: uiPrompt.value,
+      },
+      details.sessionApproval,
+    );
   }
 
   // ── Private methods ────────────────────────────────────────────────────
@@ -111,6 +117,7 @@ export class ParentAuthorizer implements Authorizer {
     ctx: ForwarderContext,
     message: string,
     forwarded?: ForwardedPromptDisplay,
+    sessionApproval?: ForwardedSessionApproval,
   ): Promise<PermissionPromptDecision> {
     const requesterSessionId = getSessionId(ctx);
     const targetSessionId = resolvePermissionForwardingTargetSessionId({
@@ -156,6 +163,7 @@ export class ParentAuthorizer implements Authorizer {
       requesterSessionId,
       targetSessionId,
       forwarded,
+      sessionApproval,
     );
     const requestPath = join(location.requestsDir, `${request.id}.json`);
     const responsePath = join(location.responsesDir, `${request.id}.json`);
@@ -194,6 +202,7 @@ export class ParentAuthorizer implements Authorizer {
     requesterSessionId: string,
     targetSessionId: string,
     forwarded?: ForwardedPromptDisplay,
+    sessionApproval?: ForwardedSessionApproval,
   ): ForwardedPermissionRequest {
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
     const requesterAgentName =
@@ -214,6 +223,7 @@ export class ParentAuthorizer implements Authorizer {
             value: forwarded.value,
           }
         : {}),
+      ...(sessionApproval ? { sessionApproval } : {}),
     };
   }
 

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

@@ -10,6 +10,8 @@ import {
   isForwardedPermissionRequestForSession,
   type PermissionForwardingLocation,
 } from "#src/permission-forwarding";
+import { SessionApproval } from "#src/session-approval";
+import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import type { PermissionCheckResult } from "#src/types";
@@ -61,6 +63,11 @@ export interface ForwardedRequestServerDeps {
   policy: ServingPolicy;
   /** Escalation seam to the serving session's selected `Authorizer` on `ask`. */
   escalator: AskEscalator;
+  /**
+   * The serving session's `SessionRules`. Records a whole-session grant when a
+   * human approves a forwarded request for the entire serving session.
+   */
+  recorder: SessionApprovalRecorder;
   /** In-process subagent registry, read only by the one-hop canary. */
   registry?: SubagentSessionRegistry;
 }
@@ -115,6 +122,11 @@ function buildForwardedAskDetails(
       requesterAgentName: request.requesterAgentName || null,
       requesterSessionId: request.requesterSessionId || null,
     },
+    // Carries the child's suggestion so LocalUserAuthorizer can offer the
+    // whole-session grant scope; absent for a legacy/version-skew request.
+    ...(request.sessionApproval
+      ? { sessionApproval: request.sessionApproval }
+      : {}),
   };
 }
 
@@ -132,6 +144,7 @@ export class ForwardedRequestServer implements InboxProcessor {
   private readonly logger: DebugReviewLogger;
   private readonly policy: ServingPolicy;
   private readonly escalator: AskEscalator;
+  private readonly recorder: SessionApprovalRecorder;
   private readonly registry: SubagentSessionRegistry | undefined;
 
   constructor(deps: ForwardedRequestServerDeps) {
@@ -139,6 +152,7 @@ export class ForwardedRequestServer implements InboxProcessor {
     this.logger = deps.logger;
     this.policy = deps.policy;
     this.escalator = deps.escalator;
+    this.recorder = deps.recorder;
     this.registry = deps.registry;
   }
 
@@ -237,10 +251,44 @@ export class ForwardedRequestServer implements InboxProcessor {
       location,
       requestPath,
       currentSessionId,
-      decision,
+      this.applyGrantScope(request, decision, forwardedPermissionLogDetails),
     );
   }
 
+  /**
+   * Apply the human's grant-scope choice on a forwarded approval.
+   *
+   * A whole-session grant (`approved_for_serving_session`) records the child's
+   * suggested pattern into this serving node's `SessionRules` — the single
+   * source of truth for the scope — and is then translated to a plain
+   * `approved` so the child records nothing (its next identical action
+   * re-forwards and resolves as recorded authority). Every other decision
+   * passes through unchanged (`approved_for_session` → the child records).
+   */
+  private applyGrantScope(
+    request: ForwardedPermissionRequest,
+    decision: PermissionPromptDecision,
+    logDetails: Record<string, unknown>,
+  ): PermissionPromptDecision {
+    if (decision.state !== "approved_for_serving_session") {
+      return decision;
+    }
+    if (request.sessionApproval) {
+      this.recorder.recordSessionApproval(
+        SessionApproval.multiple(
+          request.sessionApproval.surface,
+          request.sessionApproval.patterns,
+        ),
+      );
+      this.logger.review("forwarded_permission.session_recorded", {
+        ...logDetails,
+        surface: request.sessionApproval.surface,
+        patterns: request.sessionApproval.patterns,
+      });
+    }
+    return { approved: true, state: "approved" };
+  }
+
   /**
    * Persist the served decision: write the response file the child polls for,
    * log the outcome, and delete the drained request. The symmetric "respond"

package/src/authority/forwarding-io.ts

@@ -15,6 +15,7 @@ import {
   createPermissionForwardingLocation,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
+  type ForwardedSessionApproval,
   type PermissionForwardingLocation,
 } from "#src/permission-forwarding";
 import type { DebugReviewLogger } from "#src/session-logger";
@@ -41,6 +42,31 @@ function asNullableDisplayString(value: unknown): string | null | undefined {
   return undefined;
 }
 
+/**
+ * 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.
+ */
+function asForwardedSessionApproval(
+  value: unknown,
+): ForwardedSessionApproval | undefined {
+  if (typeof value !== "object" || value === null) {
+    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")
+  ) {
+    return undefined;
+  }
+  return { surface: candidate.surface, patterns: [...candidate.patterns] };
+}
+
 export function formatUnknownErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message) {
     return error.message;
@@ -323,6 +349,7 @@ export function readForwardedPermissionRequest(
       source: asUiPromptSource(parsed.source),
       surface: asNullableDisplayString(parsed.surface),
       value: asNullableDisplayString(parsed.value),
+      sessionApproval: asForwardedSessionApproval(parsed.sessionApproval),
     };
   } catch (error) {
     logPermissionForwardingWarning(

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

@@ -1,6 +1,8 @@
+import { buildForwardedScopeLabels } from "#src/pattern-suggest";
 import type {
   PermissionDecisionUi,
   PermissionPromptDecision,
+  RequestPermissionOptions,
   requestPermissionDecisionFromUi,
 } from "#src/permission-dialog";
 import {
@@ -45,7 +47,30 @@ export class LocalUserAuthorizer implements Authorizer {
         ? "Permission Required (Subagent)"
         : "Permission Required",
       details.message,
-      details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+      buildRequestOptions(details),
     );
   }
 }
+
+/**
+ * A forwarded ask carrying a session-approval suggestion offers the scope
+ * choice (subagent vs whole session); any other ask keeps its single
+ * "for this session" option (custom label when the gate supplied one).
+ */
+function buildRequestOptions(
+  details: PromptPermissionDetails,
+): RequestPermissionOptions | undefined {
+  const pattern = details.sessionApproval?.patterns[0];
+  if (details.forwarding && details.sessionApproval && pattern) {
+    return {
+      sessionScope: buildForwardedScopeLabels(
+        details.forwarding.requesterAgentName,
+        details.sessionApproval.surface,
+        pattern,
+      ),
+    };
+  }
+  return details.sessionLabel
+    ? { sessionLabel: details.sessionLabel }
+    : undefined;
+}

package/src/authority/permission-prompter.ts

@@ -1,4 +1,5 @@
 import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { ForwardedSessionApproval } from "#src/permission-forwarding";
 import type { ReviewLogger } from "#src/session-logger";
 import type { Authorizer } from "./authorizer";
 
@@ -38,6 +39,13 @@ export interface PromptPermissionDetails {
   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;
 }
 
 /**

package/src/handlers/gates/runner.ts

@@ -147,6 +147,9 @@ export class GateRunner {
         const decision = await this.prompter.escalate({
           requestId: toolCallId,
           ...descriptor.promptDetails,
+          ...(descriptor.sessionApproval
+            ? { sessionApproval: descriptor.sessionApproval.toForwardedData() }
+            : {}),
         });
         autoApproved = decision.autoApproved === true;
         confirmationUnavailable = decision.confirmationUnavailable === true;

package/src/index.ts

@@ -132,6 +132,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
     policy: servingPolicy,
     escalator: authorizerSelection,
+    // Records a whole-session grant into the same SessionRules the resolver and
+    // gate runner read, so a serving-scope grant governs the parent and future
+    // forwarded resolutions.
+    recorder: sessionRules,
     registry: subagentRegistry,
   });
 

package/src/pattern-suggest.ts

@@ -62,6 +62,35 @@ export function suggestMcpPattern(target: string): string {
   return "*";
 }
 
+/** Scope labels for the forwarded-approval two-step scope select. */
+export interface ForwardedScopeLabels {
+  /** Least-privilege default: record on the requesting subagent only. */
+  subagentLabel: string;
+  /** Record on the serving node — covers the parent and all subagents. */
+  servingSessionLabel: string;
+}
+
+/**
+ * Build the two scope labels shown when a human grants a forwarded request
+ * "for this session."
+ *
+ * The subagent option names the requester (least privilege); the whole-session
+ * option restates the surface + pattern being granted session-wide.
+ */
+export function buildForwardedScopeLabels(
+  agentName: string | null,
+  surface: string,
+  pattern: string,
+): ForwardedScopeLabels {
+  const subagentLabel = agentName
+    ? `This subagent ('${agentName}') only`
+    : "This subagent only";
+  return {
+    subagentLabel,
+    servingSessionLabel: `The whole session — allow ${surface} "${pattern}" for parent and all subagents`,
+  };
+}
+
 /** Surface-aware human-readable labels for the session-approval option. */
 function buildLabel(pattern: string, surface: string): string {
   switch (surface) {

package/src/permission-dialog.ts

@@ -1,6 +1,7 @@
 export type PermissionDecisionState =
   | "approved"
   | "approved_for_session"
+  | "approved_for_serving_session"
   | "denied"
   | "denied_with_reason";
 
@@ -67,6 +68,7 @@ export function isPermissionDecisionState(
   return (
     value === "approved" ||
     value === "approved_for_session" ||
+    value === "approved_for_serving_session" ||
     value === "denied" ||
     value === "denied_with_reason"
   );
@@ -75,6 +77,15 @@ export function isPermissionDecisionState(
 export interface RequestPermissionOptions {
   /** Override the "for this session" option label (e.g. to show the suggested pattern). */
   sessionLabel?: string;
+  /**
+   * Forwarded asks only: when set, choosing the "for this session" option opens
+   * a second select asking whether the grant applies to the requesting subagent
+   * only (the least-privilege default) or the whole serving session.
+   */
+  sessionScope?: {
+    subagentLabel: string;
+    servingSessionLabel: string;
+  };
 }
 
 export async function requestPermissionDecisionFromUi(
@@ -103,6 +114,21 @@ export async function requestPermissionDecisionFromUi(
   }
 
   if (selected === sessionOption) {
+    if (options?.sessionScope) {
+      const scope = await ui.select(`${title}\nApply this session grant to:`, [
+        options.sessionScope.subagentLabel,
+        options.sessionScope.servingSessionLabel,
+      ]);
+      return {
+        approved: true,
+        // A cancelled scope select (undefined) falls back to the
+        // least-privilege subagent scope.
+        state:
+          scope === options.sessionScope.servingSessionLabel
+            ? "approved_for_serving_session"
+            : "approved_for_session",
+      };
+    }
     return {
       approved: true,
       state: "approved_for_session",

package/src/permission-forwarding.ts

@@ -53,6 +53,20 @@ export interface ForwardedPromptDisplay {
   value: string | null;
 }
 
+/**
+ * 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`.
+ */
+export interface ForwardedSessionApproval {
+  surface: string;
+  patterns: readonly string[];
+}
+
 export type ForwardedPermissionRequest = {
   id: string;
   createdAt: number;
@@ -69,6 +83,13 @@ export type ForwardedPermissionRequest = {
   source?: PermissionUiPromptSource;
   surface?: string | null;
   value?: string | null;
+  /**
+   * The child's session-approval suggestion. Present when the child computed a
+   * "for this session" pattern for the ask; lets the serving node record a
+   * whole-session grant. Optional for version-skew tolerance (an older child
+   * omits it, and the serving dialog then offers no scope choice).
+   */
+  sessionApproval?: ForwardedSessionApproval;
 };
 
 export type ForwardedPermissionResponse = {

package/src/session-approval.ts

@@ -1,3 +1,5 @@
+import type { ForwardedSessionApproval } from "./permission-forwarding";
+
 /**
  * Value object for a session-scoped approval: one surface, one-or-more patterns.
  *
@@ -40,4 +42,13 @@ export class SessionApproval {
     if (pattern === undefined) return undefined;
     return { surface: this.surface, pattern };
   }
+
+  /**
+   * 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.
+   */
+  toForwardedData(): ForwardedSessionApproval {
+    return { surface: this.surface, patterns: [...this.patterns] };
+  }
 }