@gotgenes/pi-permission-system 26.0.0 → 26.2.0

package/src/authority/permission-prompt-decision.ts

@@ -1,8 +1,8 @@
 import {
   createDeniedPermissionDecision,
   normalizePermissionDenialReason,
-  type PermissionPromptDecision,
   type RequestPermissionOptions,
+  type UnattributedDecision,
 } from "#src/authority/permission-dialog";
 
 /**
@@ -70,7 +70,7 @@ export type PromptEvent =
 /** Either a re-render or a terminal decision. */
 export type PromptOutcome =
   | { kind: "render"; state: PromptViewState }
-  | { kind: "decision"; decision: PermissionPromptDecision };
+  | { kind: "decision"; decision: UnattributedDecision };
 
 export function initialPromptState(
   _config: PromptModelConfig,
@@ -88,7 +88,11 @@ export function initialPromptState(
 
 /**
  * Advance the dialog by one input event, returning either the next view state
- * to render or the committed {@link PermissionPromptDecision}.
+ * to render or the committed {@link UnattributedDecision}.
+ *
+ * The model states the outcome and not the decider: which human surface this
+ * is gets attributed by the dispatcher that chose to render this dialog, so
+ * the two cannot disagree about the surface.
  */
 export function reducePrompt(
   config: PromptModelConfig,

package/src/authority/permission-prompter.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
   ForwardedAccessFacts,
@@ -131,6 +132,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
           ? "confirmation_unavailable"
           : decision.state,
         denialReason: decision.denialReason,
+        decidedBy: decision.decidedBy,
       },
     );
 
@@ -139,14 +141,20 @@ export class PermissionPrompter implements PermissionPrompterApi {
 
   // ── Private helpers ──────────────────────────────────────────────────────
 
+  /**
+   * The `waiting` entry carries no `decidedBy` — nothing has decided yet, and
+   * a `null` there would read as "decided by nobody" rather than "not yet".
+   */
   private writeReviewEntry(
     event: string,
     details: PromptPermissionDetails & {
       resolution?: string;
       denialReason?: string;
+      decidedBy?: DecisionSource;
     },
   ): void {
     this.deps.logger.review(event, {
+      ...(details.decidedBy ? { decidedBy: details.decidedBy } : {}),
       requestId: details.requestId,
       source: details.source,
       agentName: details.agentName,

package/src/authority/serving-registry.ts

@@ -35,10 +35,43 @@ export const SERVING_SESSION_REGISTRY_KEY = Symbol.for(
  * neither reads the store nor gains a query it has no business making (ISP).
  */
 export interface ServingAnnouncer {
+  /**
+   * Record that `sessionId` is polling its inbox.
+   *
+   * Idempotent, and called on every poll tick rather than once per session: an
+   * announcement that can decay (the filesystem heartbeat) has to be kept
+   * current, and one that cannot (this registry) costs a set insertion to say
+   * so again.
+   */
   markServing(sessionId: string): void;
   clearServing(sessionId: string): void;
 }
 
+/**
+ * Fan an announcement out to every channel a serving session publishes on.
+ *
+ * A session announces to the process-global registry (for its in-process
+ * children) and to the filesystem (for children in other processes). Composing
+ * them keeps `ForwardingManager` holding one collaborator, so adding or
+ * removing a channel never reaches the poll loop.
+ */
+export function composeServingAnnouncers(
+  ...announcers: readonly ServingAnnouncer[]
+): ServingAnnouncer {
+  return {
+    markServing(sessionId: string): void {
+      for (const announcer of announcers) {
+        announcer.markServing(sessionId);
+      }
+    },
+    clearServing(sessionId: string): void {
+      for (const announcer of announcers) {
+        announcer.clearServing(sessionId);
+      }
+    },
+  };
+}
+
 /**
  * Query-side seam: a forwarding child asks whether its target is draining.
  *

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

@@ -47,6 +47,15 @@ export function describeBashExternalDirectoryGate(
   if (uncoveredPaths.length === 0) {
     return {
       action: "allow",
+      // A whole-command bypass covers every external path at once, and each
+      // may have matched a different session pattern -- so the surface is one
+      // value and the pattern is not. The entry's `externalPaths` lists what
+      // was covered.
+      decidedBy: {
+        kind: "session_approval",
+        surface: "external_directory",
+        pattern: null,
+      },
       log: {
         event: "permission_request.session_approved",
         details: {

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

@@ -84,6 +84,14 @@ export function describeBashPathGate(
   if (allSessionCovered) {
     return {
       action: "allow",
+      // Every token was covered, each possibly by a different session pattern
+      // -- the surface is one value and the pattern is not. The entry's
+      // `tokens` lists what was covered.
+      decidedBy: {
+        kind: "session_approval",
+        surface: "path",
+        pattern: null,
+      },
       log: {
         event: "permission_request.session_approved",
         details: {

package/src/handlers/gates/descriptor.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PromptPermissionDetails } from "#src/authority/permission-prompter";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
@@ -79,6 +80,14 @@ export type DecisionEventFacts = Omit<PermissionDecisionEvent, "requestId">;
  */
 export interface GateBypass {
   action: "allow";
+  /**
+   * What decided this short-circuit.
+   *
+   * The gate that bypasses *is* the decider, so it states its own provenance
+   * and the runner relays it onto the log entry rather than inferring one from
+   * the event name (#726). Required, so a bypass added later cannot omit it.
+   */
+  decidedBy: DecisionSource;
   /** Optional review log entry to emit. */
   log?: { event: string; details: Record<string, unknown> };
   /** Optional decision event to emit. */

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

@@ -45,6 +45,8 @@ export function describeExternalDirectoryGate(
   if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {
       action: "allow",
+      // Containment allowed this, not a rule the operator wrote.
+      decidedBy: { kind: "infrastructure_read" },
       log: {
         event: "permission_request.infrastructure_auto_allowed",
         details: {

package/src/handlers/gates/runner.ts

@@ -66,6 +66,7 @@ export class GateRunner {
         this.reporter.writeReviewLog(gate.log.event, {
           ...gate.log.details,
           requestId,
+          decidedBy: gate.decidedBy,
         });
       }
       if (gate.decision) {
@@ -123,12 +124,22 @@ export class GateRunner {
       requestId,
     };
 
+    // Each resolution below states its own decider. The provenance is built
+    // at the branch that decides rather than merged into `logContext`: that
+    // context holds what every resolution of this gate shares, and who decided
+    // is by definition not shared (#726).
+
     // 2. Session-hit fast path
     if (check.source === "session") {
       this.reporter.writeReviewLog("permission_request.session_approved", {
         ...logContext,
         resolution: "session_approved",
         sessionApprovalPattern: check.matchedPattern,
+        decidedBy: {
+          kind: "session_approval",
+          surface: descriptor.surface,
+          pattern: check.matchedPattern ?? null,
+        },
       });
       this.emitDecision(
         requestId,
@@ -152,6 +163,9 @@ export class GateRunner {
       this.reporter.writeReviewLog("permission_request.auto_approved", {
         ...logContext,
         resolution: "auto_approved",
+        // The pattern that raised the ask, sentinel included: "yolo allowed
+        // it" alone does not say why it was asked in the first place.
+        decidedBy: { kind: "yolo", pattern: check.matchedPattern ?? null },
       });
       this.emitDecision(
         requestId,
@@ -202,6 +216,12 @@ export class GateRunner {
       writeLog: (event, details) =>
         this.reporter.writeReviewLog(event, details),
       logContext,
+      decidedByRule: {
+        kind: "rule",
+        surface: descriptor.surface,
+        pattern: check.matchedPattern ?? null,
+        origin: check.origin,
+      },
       messages,
     });
 

package/src/handlers/tool-call-boundary.ts

@@ -76,12 +76,15 @@ function recordGateError(
 ): void {
   try {
     audit.recordError();
+    const reason = errorMessage(error);
     reporter.writeReviewLog("permission_request.blocked", {
       requestId: createPermissionRequestId(),
       toolName: bestEffortToolName(event),
       command: bestEffortCommand(event),
       resolution: "gate_error",
-      error: errorMessage(error),
+      error: reason,
+      // The boundary decided, by failing closed -- no rule and no human did.
+      decidedBy: { kind: "gate_error", reason },
     });
   } catch {
     // The block is the guarantee; its bookkeeping is not.

package/src/index.ts

@@ -8,11 +8,18 @@ import {
   ForwardedRequestServer,
   type ServingPolicy,
 } from "./authority/forwarded-request-server";
+import {
+  ForwardingLivenessJudge,
+  ServingHeartbeatStore,
+} from "./authority/forwarding-liveness";
 import { ForwardingManager } from "./authority/forwarding-manager";
 import { PERMISSION_FORWARDING_TIMEOUT_MS } from "./authority/permission-forwarding";
 import { requestPermissionDecision } from "./authority/permission-prompt-component";
 import { PermissionPrompter } from "./authority/permission-prompter";
-import { getServingSessionRegistry } from "./authority/serving-registry";
+import {
+  composeServingAnnouncers,
+  getServingSessionRegistry,
+} from "./authority/serving-registry";
 import { SubagentDetection } from "./authority/subagent-detection";
 import { subscribeSubagentLifecycle } from "./authority/subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./authority/subagent-registry";
@@ -111,6 +118,20 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const prompter = new PermissionPrompter({ logger });
 
+  // The filesystem half of the serving announcement. `servingRegistry` reaches
+  // an in-process child through `globalThis`; a child in its own process shares
+  // nothing but this directory, so the served session publishes a heartbeat
+  // there too (#721).
+  const servingHeartbeats = new ServingHeartbeatStore({
+    forwardingDir: paths.forwardingDir,
+    logger,
+  });
+  // The read side of both channels, routed by how the target was resolved.
+  const servingLiveness = new ForwardingLivenessJudge({
+    registry: servingRegistry,
+    heartbeats: servingHeartbeats,
+  });
+
   const authorizerSelection = new AuthorizerSelection({
     detection: subagentDetection,
     events: pi.events,
@@ -121,7 +142,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,
     registry: subagentRegistry,
-    servingRegistry,
+    serving: servingLiveness,
     getForwardingTimeoutMs: () =>
       configStore.current().forwardingTimeoutMs ??
       PERMISSION_FORWARDING_TIMEOUT_MS,
@@ -177,7 +198,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     new ForwardingManager({
       detection: subagentDetection,
       forwarder: requestServer,
-      serving: servingRegistry,
+      serving: composeServingAnnouncers(servingRegistry, servingHeartbeats),
       logger,
     }),
     permissionManager,

package/src/permission-gate.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
 /** Result of applying the permission gate. */
@@ -30,6 +31,15 @@ export interface PermissionGateParams {
   /** Log context fields shared across all log calls for this gate. */
   logContext: Record<string, unknown>;
 
+  /**
+   * The rule that resolved this gate, for the deny arm's review entry.
+   *
+   * A sibling of `logContext` rather than a member of it: the context holds
+   * what every resolution of this gate shares, and the decider is by
+   * definition not shared (#726).
+   */
+  decidedByRule: DecisionSource;
+
   /** Message strings/factories for each outcome. */
   messages: {
     denyReason: string;
@@ -52,6 +62,7 @@ export async function applyPermissionGate(
     writeLog("permission_request.blocked", {
       ...logContext,
       resolution: "policy_denied",
+      decidedBy: params.decidedByRule,
     });
     return { action: "block", reason: messages.denyReason };
   }