@gotgenes/pi-permission-system 27.0.0 → 27.1.0

package/src/presentation/path-ask-payload.ts

@@ -19,11 +19,17 @@ interface PathAskFacts {
   pathValue: string;
   agentName: string | null;
   matchedPattern?: string;
+  /**
+   * The surface that decided — a directional member when the tool's identity
+   * proved a direction, the bare family otherwise. Distinct from the payload
+   * `kind`, which stays coarse so renderer dispatch is untouched.
+   */
+  surface: string;
 }
 
-/** A tool ask gated by an explicit `path` rule. */
+/** A tool ask gated by an explicit `path`-family rule. */
 export function buildPathAskPayload(facts: PathAskFacts): PromptPayload {
-  return pathPayload("path", "path", facts, []);
+  return pathPayload("path", facts, []);
 }
 
 /** The facts the external-directory gate adds: the boundary and the alias. */
@@ -38,7 +44,7 @@ interface ExternalDirectoryAskFacts extends PathAskFacts {
 export function buildExternalDirectoryAskPayload(
   facts: ExternalDirectoryAskFacts,
 ): PromptPayload {
-  return pathPayload("external_directory", "external_directory", facts, [
+  return pathPayload("external_directory", facts, [
     ...resolvedAliasEvidence(facts.resolvedPath),
     workingDirectoryEvidence(facts.cwd),
   ]);
@@ -53,6 +59,12 @@ interface BashExternalDirectoryAskFacts {
   agentName: string | null;
   toolName: string;
   matchedPattern?: string;
+  /**
+   * The surface that decided — a directional member when the deciding path's
+   * effect was proven, the bare family otherwise. Distinct from the payload
+   * `kind`, which stays coarse so renderer dispatch is untouched.
+   */
+  surface: string;
 }
 
 /** A bash ask whose command references paths outside the working directory. */
@@ -63,7 +75,7 @@ export function buildBashExternalDirectoryAskPayload(
     kind: "bash_external_directory",
     request: {
       requester: localRequester(facts.agentName),
-      surface: "external_directory",
+      surface: facts.surface,
       toolName: facts.toolName,
       invokedToolName: null,
       value: facts.command,
@@ -87,7 +99,6 @@ export function buildBashExternalDirectoryAskPayload(
  */
 function pathPayload(
   kind: "path" | "external_directory",
-  surface: string,
   facts: PathAskFacts,
   evidence: PromptEvidence[],
 ): PromptPayload {
@@ -95,7 +106,7 @@ function pathPayload(
     kind,
     request: {
       requester: localRequester(facts.agentName),
-      surface,
+      surface: facts.surface,
       toolName: facts.toolName,
       invokedToolName: null,
       value: facts.pathValue,

package/src/restrictiveness.ts

@@ -0,0 +1,48 @@
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+/**
+ * Select the most restrictive permission result from a possibly-empty list
+ * (deny > ask > allow).
+ *
+ * The first occurrence wins on ties, so a caller passing results in candidate
+ * order receives the earliest worst case. Returns `undefined` for an empty list.
+ *
+ * Shared by the bash gates (path, external-directory) to combine the per-candidate
+ * `checkPermission` results their tree-sitter token extraction produces.
+ */
+export function pickMostRestrictive(
+  results: readonly PermissionCheckResult[],
+): PermissionCheckResult | undefined {
+  const first = results.at(0);
+  return first === undefined
+    ? undefined
+    : mostRestrictiveOf([first, ...results.slice(1)]);
+}
+
+/**
+ * Select the most restrictive of a statically non-empty list of results
+ * (deny > ask > allow), first-wins on ties.
+ *
+ * Total by construction: the non-empty tuple parameter means the caller never
+ * handles an `undefined` branch. The winner is the losing member's **own**
+ * result, so `toolName`, `matchedPattern`, `origin`, and `source` all name the
+ * input that forced the verdict rather than a synthesized composite.
+ */
+export function mostRestrictiveOf(
+  results: readonly [PermissionCheckResult, ...PermissionCheckResult[]],
+): PermissionCheckResult {
+  let worst = results[0];
+  for (const result of results) {
+    if (RESTRICTIVENESS[result.state] > RESTRICTIVENESS[worst.state]) {
+      worst = result;
+    }
+  }
+  return worst;
+}
+
+/** Restrictiveness ordering: deny is the most restrictive, allow the least. */
+const RESTRICTIVENESS: Record<PermissionState, number> = {
+  allow: 0,
+  ask: 1,
+  deny: 2,
+};

package/src/rule.ts

@@ -139,19 +139,6 @@ function ruleMatches(
   );
 }
 
-/**
- * Evaluate a surface against an ordered list of candidate values, stopping at
- * the first candidate that matches a non-default rule (last-match-wins within
- * each candidate, first-non-default-wins across candidates).
- *
- * Used by MCP (multi-candidate target list) and, uniformly, by all other
- * surfaces (single-element candidate list).
- *
- * Returns the matched rule and the candidate value that produced it.
- * When every candidate matches only the synthesized default, falls back to
- * evaluating the first candidate so the caller always receives a concrete
- * result.
- */
 /**
  * Evaluate a surface against multiple values, returning the most restrictive
  * non-allow result (deny > ask > allow).
@@ -180,6 +167,19 @@ export function evaluateMostRestrictive(
   return worst;
 }
 
+/**
+ * Evaluate a surface against an ordered list of candidate values, stopping at
+ * the first candidate that matches a non-default rule (last-match-wins within
+ * each candidate, first-non-default-wins across candidates).
+ *
+ * Used by MCP (multi-candidate target list) and, uniformly, by all other
+ * surfaces (single-element candidate list).
+ *
+ * Returns the matched rule and the candidate value that produced it.
+ * When every candidate matches only the synthesized default, falls back to
+ * evaluating the first candidate so the caller always receives a concrete
+ * result.
+ */
 export function evaluateFirst(
   surface: string,
   values: string[],

package/src/scope-merge.ts

@@ -1,3 +1,4 @@
+import { expandDirectionalSugar } from "#src/normalize";
 import { mergeFlatPermissions } from "#src/permission-merge";
 import type { RuleOrigin } from "#src/rule";
 import type { FlatPermissionConfig, ScopeConfig } from "#src/types";
@@ -33,7 +34,12 @@ export function mergeScopesWithOrigins(
   for (const [scopeName, scope] of scopes) {
     if (!scope.permission) continue;
 
-    for (const [surface, value] of Object.entries(scope.permission)) {
+    // Sugar expands per scope, before both the origin bookkeeping and the
+    // merge (ADR 0013 §9): origins are keyed by surface name, so expanding
+    // after composition would attribute every expanded rule to `builtin`.
+    const permission = expandDirectionalSugar(scope.permission);
+
+    for (const [surface, value] of Object.entries(permission)) {
       const baseVal = mergedPermission[surface];
       /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
       const bothObjects =
@@ -65,7 +71,7 @@ export function mergeScopesWithOrigins(
       }
     }
 
-    mergedPermission = mergeFlatPermissions(mergedPermission, scope.permission);
+    mergedPermission = mergeFlatPermissions(mergedPermission, permission);
   }
 
   return { mergedPermission, origins };

package/src/session-rules.ts

@@ -1,3 +1,4 @@
+import { surfaceFamilyMembers } from "#src/access-intent/path-surfaces";
 import type { Ruleset } from "./rule";
 import type { SessionApproval } from "./session-approval";
 import type { SessionApprovalRecorder } from "./session-approval-recorder";
@@ -13,15 +14,25 @@ import type { SessionApprovalRecorder } from "./session-approval-recorder";
 export class SessionRules implements SessionApprovalRecorder {
   private rules: Ruleset = [];
 
-  /** Record a wildcard pattern as approved for the given surface. */
+  /**
+   * Record a wildcard pattern as approved for the given surface.
+   *
+   * A session approval is a policy source under ADR 0013 §9, so it expands the
+   * same way a config key does: an approval on a bare family surface becomes
+   * one rule per directional member, and one on a directional surface stays a
+   * single rule. Without the expansion an approval would sit on a surface no
+   * query names, and the next ask for the same path would prompt again.
+   */
   approve(surface: string, pattern: string): void {
-    this.rules.push({
-      surface,
-      pattern,
-      action: "allow",
-      layer: "session",
-      origin: "session",
-    });
+    for (const target of surfaceFamilyMembers(surface) ?? [surface]) {
+      this.rules.push({
+        surface: target,
+        pattern,
+        action: "allow",
+        layer: "session",
+        origin: "session",
+      });
+    }
   }
 
   /** Return a defensive copy of the current session ruleset. */

package/src/types.ts

@@ -41,6 +41,20 @@ export type BashCommandContext =
   | "process_substitution"
   | "subshell";
 
+/**
+ * Why an indirection wrapper's floor did not apply after all (#803).
+ *
+ * `"core-reader"` — the command the wrapper runs is in the built-in pure-reader
+ * core, so it is read-only for any argument feed and the floor's reason (an
+ * unknown direction behind the wrapper) does not hold.
+ *
+ * A named reason rather than a boolean, so the review log states *why* a
+ * wrapper was let through, and so a later source (a chain verdict, a user
+ * declaration) is an added member rather than a second flag. ADR 0013 §11
+ * keeps v1 at the audited core alone.
+ */
+export type FloorExemption = "core-reader";
+
 export interface PermissionCheckResult {
   toolName: string;
   state: PermissionState;
@@ -61,9 +75,16 @@ export interface PermissionCheckResult {
   /**
    * The command the winning bash unit actually runs, when it is a wrapper whose
    * inner command differs from the unit text (#713). Display-only: the gate
-   * still decides on `command`, so this never widens or narrows a decision.
+   * decides on `command`, and on `executedUnit`'s rules only when
+   * {@link floorExemption} says the inner command is a proven pure reader.
    */
   executedUnit?: string;
+  /**
+   * Set when the winning bash unit is a wrapper the floor no longer covers,
+   * naming why (#803). Recorded in the review log so an allow the floor would
+   * once have prompted for is auditable to the reason that let it through.
+   */
+  floorExemption?: FloorExemption;
 }
 
 export function isPermissionState(value: unknown): value is PermissionState {

package/src/handlers/gates/candidate-check.ts

@@ -1,32 +0,0 @@
-import type { PermissionCheckResult, PermissionState } from "#src/types";
-
-/** Restrictiveness ordering: deny is the most restrictive, allow the least. */
-const RESTRICTIVENESS: Record<PermissionState, number> = {
-  allow: 0,
-  ask: 1,
-  deny: 2,
-};
-
-/**
- * Select the most restrictive permission result from a list (deny > ask > allow).
- *
- * The first occurrence wins on ties, so a caller passing results in candidate
- * order receives the earliest worst case. Returns `undefined` for an empty list.
- *
- * Shared by the bash gates (path, external-directory) to combine the per-candidate
- * `checkPermission` results their tree-sitter token extraction produces.
- */
-export function pickMostRestrictive(
-  results: readonly PermissionCheckResult[],
-): PermissionCheckResult | undefined {
-  let worst: PermissionCheckResult | undefined;
-  for (const result of results) {
-    if (
-      worst === undefined ||
-      RESTRICTIVENESS[result.state] > RESTRICTIVENESS[worst.state]
-    ) {
-      worst = result;
-    }
-  }
-  return worst;
-}