@gotgenes/pi-permission-system 8.1.0 → 8.2.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [8.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.1.0...pi-permission-system-v8.2.0) (2026-05-31)
+
+
+### Features
+
+* add SessionApproval value object and SessionRules.record ([8f98d92](https://github.com/gotgenes/pi-packages/commit/8f98d9223a424b0993d51c2d9106e7d01c6819d7))
+* centralize decision-event construction in buildDecisionEvent ([19c2c83](https://github.com/gotgenes/pi-packages/commit/19c2c837b1907a4c302105ee86715533477247d4))
+
 ## [8.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.0.0...pi-permission-system-v8.1.0) (2026-05-31)
 
 

package/package.json

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

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

@@ -1,5 +1,6 @@
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
@@ -106,10 +107,7 @@ export async function describeBashExternalDirectoryGate(
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "external_directory",
-      patterns,
-    },
+    sessionApproval: SessionApproval.multiple("external_directory", patterns),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

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

@@ -1,5 +1,6 @@
 import { getNonEmptyString, toRecord } from "#src/common";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { extractTokensForPathRules } from "./bash-path-extractor";
@@ -117,10 +118,7 @@ export async function describeBashPathGate(
       pathValue: worstToken,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "path",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/descriptor.ts

@@ -3,6 +3,7 @@ import type { PermissionPromptDecision } from "#src/permission-dialog";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import type { PromptPermissionDetails } from "#src/permission-prompter";
 import type { Rule } from "#src/rule";
+import type { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
 
 // ── Descriptor types ───────────────────────────────────────────────────────
@@ -22,12 +23,11 @@ export interface GateDescriptor {
   /** Structured denial context — the runner formats messages from this. */
   denialContext: DenialContext;
   /**
-   * Session-approval suggestion for "for this session" option.
-   * Single pattern or multiple patterns (bash external-directory gate).
+   * Session-approval suggestion for the "for this session" option.
+   * Wraps either a single pattern or multiple patterns behind a unified
+   * interface — the runner never needs to know which case applies.
    */
-  sessionApproval?:
-    | { surface: string; pattern: string }
-    | { surface: string; patterns: string[] };
+  sessionApproval?: SessionApproval;
   /** Details passed to the interactive permission prompt (requestId is added by the runner). */
   promptDetails: Omit<PromptPermissionDetails, "requestId">;
   /** Extra context fields written to the review log alongside gate outcomes. */
@@ -87,7 +87,7 @@ export interface GateRunnerDeps {
     sessionRules?: Rule[],
   ): PermissionCheckResult;
   getSessionRuleset(): Rule[];
-  approveSessionRule(surface: string, pattern: string): void;
+  recordSessionApproval(approval: SessionApproval): void;
   writeReviewLog(event: string, details: Record<string, unknown>): void;
   emitDecision(event: PermissionDecisionEvent): void;
   canConfirm(): boolean;

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

@@ -4,6 +4,7 @@ import {
   isPiInfrastructureRead,
   normalizePathForComparison,
 } from "#src/path-utils";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
@@ -83,10 +84,7 @@ export function describeExternalDirectoryGate(
       cwd: tcc.cwd,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "external_directory",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("external_directory", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/helpers.ts

@@ -1,4 +1,7 @@
-import type { PermissionDecisionResolution } from "#src/permission-events";
+import type {
+  PermissionDecisionEvent,
+  PermissionDecisionResolution,
+} from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
 
 /**
@@ -17,6 +20,32 @@ export function deriveDecisionValue(
   return toolName;
 }
 
+/**
+ * Build a `PermissionDecisionEvent` from the gate's inputs.
+ *
+ * Centralises the `origin / agentName / matchedPattern ?? null` normalization
+ * that is otherwise duplicated across the session-hit path and the gate-result
+ * path in `runGateCheck`.
+ */
+export function buildDecisionEvent(
+  decision: { surface: string; value: string },
+  check: Pick<PermissionCheckResult, "origin" | "matchedPattern">,
+  agentName: string | null,
+  result: "allow" | "deny",
+  resolution: PermissionDecisionResolution,
+): PermissionDecisionEvent {
+  return {
+    surface: decision.surface,
+    value: decision.value,
+    result,
+    resolution,
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  };
+}
+
 /**
  * Map the gate outcome back to a PermissionDecisionResolution.
  *

package/src/handlers/gates/path.ts

@@ -1,5 +1,6 @@
 import { getPathBearingToolPath } from "#src/path-utils";
 import type { Rule } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, GateResult } from "./descriptor";
@@ -55,10 +56,7 @@ export function describePathGate(
       pathValue: filePath,
       agentName: tcc.agentName ?? undefined,
     },
-    sessionApproval: {
-      surface: "path",
-      pattern,
-    },
+    sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/gates/runner.ts

@@ -7,7 +7,7 @@ import type { PermissionPromptDecision } from "#src/permission-dialog";
 import { applyPermissionGate } from "#src/permission-gate";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, GateRunnerDeps } from "./descriptor";
-import { deriveResolution } from "./helpers";
+import { buildDecisionEvent, deriveResolution } from "./helpers";
 import type { GateOutcome } from "./types";
 
 /**
@@ -56,37 +56,21 @@ export async function runGateCheck(
       resolution: "session_approved",
       sessionApprovalPattern: check.matchedPattern,
     });
-    deps.emitDecision({
-      surface: descriptor.decision.surface,
-      value: descriptor.decision.value,
-      result: "allow",
-      resolution: "session_approved",
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
-      origin: check.origin ?? null,
-      agentName: agentName ?? null,
-      matchedPattern: check.matchedPattern ?? null,
-    });
+    deps.emitDecision(
+      buildDecisionEvent(
+        descriptor.decision,
+        check,
+        agentName,
+        "allow",
+        "session_approved",
+      ),
+    );
     return { action: "allow" };
   }
 
   // 3. Apply the deny/ask/allow gate
   const canConfirm = deps.canConfirm();
 
-  // Resolve the first pattern for applyPermissionGate's sessionApproval param
-  const singleSessionApproval = descriptor.sessionApproval
-    ? "pattern" in descriptor.sessionApproval
-      ? {
-          surface: descriptor.sessionApproval.surface,
-          pattern: descriptor.sessionApproval.pattern,
-        }
-      : descriptor.sessionApproval.patterns.length > 0
-        ? {
-            surface: descriptor.sessionApproval.surface,
-            pattern: descriptor.sessionApproval.patterns[0],
-          }
-        : undefined
-    : undefined;
-
   // Construct messages from the centralized formatter.
   const messages = {
     denyReason: formatDenyReason(descriptor.denialContext),
@@ -99,7 +83,7 @@ export async function runGateCheck(
   const gateResult = await applyPermissionGate({
     state: check.state,
     canConfirm,
-    sessionApproval: singleSessionApproval,
+    sessionApproval: descriptor.sessionApproval?.toGateApproval(),
     promptForApproval: async () => {
       const decision = await deps.promptPermission({
         requestId: toolCallId,
@@ -119,37 +103,26 @@ export async function runGateCheck(
     gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
 
   // 5. Emit decision event
-  deps.emitDecision({
-    surface: descriptor.decision.surface,
-    value: descriptor.decision.value,
-    result: gateResult.action === "allow" ? "allow" : "deny",
-    resolution: deriveResolution(
-      check.state,
-      gateResult.action,
-      hasSessionApproval,
-      canConfirm,
-      autoApproved,
+  deps.emitDecision(
+    buildDecisionEvent(
+      descriptor.decision,
+      check,
+      agentName,
+      gateResult.action === "allow" ? "allow" : "deny",
+      deriveResolution(
+        check.state,
+        gateResult.action,
+        hasSessionApproval,
+        canConfirm,
+        autoApproved,
+      ),
     ),
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the log record
-    origin: check.origin ?? null,
-    agentName: agentName ?? null,
-    matchedPattern: check.matchedPattern ?? null,
-  });
+  );
 
-  // 6. Record session approval(s)
-  if (gateResult.action === "allow" && hasSessionApproval) {
-    if (descriptor.sessionApproval) {
-      if ("patterns" in descriptor.sessionApproval) {
-        for (const pattern of descriptor.sessionApproval.patterns) {
-          deps.approveSessionRule(descriptor.sessionApproval.surface, pattern);
-        }
-      } else {
-        deps.approveSessionRule(
-          descriptor.sessionApproval.surface,
-          descriptor.sessionApproval.pattern,
-        );
-      }
-    }
+  // 6. Record session approval — tell the store; it owns the per-pattern loop
+  // hasSessionApproval already implies gateResult.action === "allow"
+  if (hasSessionApproval && descriptor.sessionApproval) {
+    deps.recordSessionApproval(descriptor.sessionApproval);
   }
 
   if (gateResult.action === "block") {

package/src/handlers/gates/tool.ts

@@ -1,6 +1,7 @@
 import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "#src/path-utils";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
+import { SessionApproval } from "#src/session-approval";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
@@ -61,10 +62,10 @@ export function describeToolGate(
       agentName: tcc.agentName ?? undefined,
       input: tcc.input,
     },
-    sessionApproval: {
-      surface: suggestion.surface,
-      pattern: suggestion.pattern,
-    },
+    sessionApproval: SessionApproval.single(
+      suggestion.surface,
+      suggestion.pattern,
+    ),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,

package/src/handlers/permission-gate-handler.ts

@@ -99,14 +99,15 @@ export class PermissionGateHandler {
       sessionRules,
     ) => this.session.checkPermission(surface, input, agent, sessionRules);
     const getSessionRuleset = () => this.session.getSessionRuleset();
-    const approveSessionRule = (surface: string, pattern: string) =>
-      this.session.approveSessionRule(surface, pattern);
+    const recordSessionApproval: GateRunnerDeps["recordSessionApproval"] = (
+      approval,
+    ) => this.session.recordSessionApproval(approval);
 
     // ── Shared runner deps (built once, reused for all gates) ────────────
     const runnerDeps: GateRunnerDeps = {
       checkPermission,
       getSessionRuleset,
-      approveSessionRule,
+      recordSessionApproval,
       writeReviewLog,
       emitDecision,
       canConfirm,

package/src/permission-manager.ts

@@ -1,7 +1,6 @@
 import { isPermissionState } from "./common";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
-import { mergeFlatPermissions } from "./permission-merge";
 import {
   FilePolicyLoader,
   type PolicyLoader,
@@ -10,6 +9,7 @@ import {
 } from "./policy-loader";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import { evaluate, evaluateFirst } from "./rule";
+import { mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
   synthesizeBaseline,
@@ -90,58 +90,15 @@ export class PermissionManager {
     const agentConfig = this.loader.loadAgentConfig(agentName);
     const projectAgentConfig = this.loader.loadProjectAgentConfig(agentName);
 
-    // Merge permission objects across scopes (lowest → highest precedence).
-    // Build a parallel origin map that tracks which scope contributed each
-    // (surface, pattern) entry, mirroring mergeFlatPermissions() semantics.
-    type OriginMap = Map<string, Map<string, RuleOrigin>>;
-    const origins: OriginMap = new Map();
-    let mergedPermission: FlatPermissionConfig = {};
-
-    for (const [scopeName, scope] of [
+    // Merge permission objects across scopes (lowest → highest precedence),
+    // building a parallel origin map that tracks which scope contributed each
+    // (surface, pattern) entry.
+    const { mergedPermission, origins } = mergeScopesWithOrigins([
       ["global", globalConfig],
       ["project", projectConfig],
       ["agent", agentConfig],
       ["project-agent", projectAgentConfig],
-    ] as const) {
-      if (!scope.permission) continue;
-
-      for (const [surface, value] of Object.entries(scope.permission)) {
-        const baseVal = mergedPermission[surface];
-        /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
-        const bothObjects =
-          typeof baseVal === "object" &&
-          baseVal !== null &&
-          typeof value === "object" &&
-          value !== null;
-        /* eslint-enable @typescript-eslint/no-unnecessary-condition */
-
-        if (bothObjects) {
-          // Shallow-merge: each incoming pattern is attributed to this scope;
-          // existing patterns from lower scopes keep their earlier origin.
-          if (!origins.has(surface)) origins.set(surface, new Map());
-          for (const pattern of Object.keys(value)) {
-            origins.get(surface)?.set(pattern, scopeName);
-          }
-        } else {
-          // Full replacement: this scope takes over the entire surface entry.
-          const surfaceOrigins = new Map<string, RuleOrigin>();
-          if (typeof value === "string") {
-            surfaceOrigins.set("*", scopeName);
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check
-          } else if (typeof value === "object" && value !== null) {
-            for (const pattern of Object.keys(value)) {
-              surfaceOrigins.set(pattern, scopeName);
-            }
-          }
-          origins.set(surface, surfaceOrigins);
-        }
-      }
-
-      mergedPermission = mergeFlatPermissions(
-        mergedPermission,
-        scope.permission,
-      );
-    }
+    ]);
 
     // Extract the universal fallback from permission["*"].
     // The "*" key feeds synthesizeDefaults() only — it is NOT included as a

package/src/permission-session.ts

@@ -12,6 +12,7 @@ import type { PermissionManager } from "./permission-manager";
 import type { PromptPermissionDetails } from "./permission-prompter";
 import type { Rule } from "./rule";
 import { createPermissionManagerForCwd } from "./runtime";
+import type { SessionApproval } from "./session-approval";
 import type { SessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
@@ -127,8 +128,8 @@ export class PermissionSession {
     return this.sessionRules.getRuleset();
   }
 
-  approveSessionRule(surface: string, pattern: string): void {
-    this.sessionRules.approve(surface, pattern);
+  recordSessionApproval(approval: SessionApproval): void {
+    this.sessionRules.record(approval);
   }
 
   // ── Session lifecycle ────────────────────────────────────────────────────

package/src/scope-merge.ts

@@ -0,0 +1,72 @@
+import { mergeFlatPermissions } from "#src/permission-merge";
+import type { RuleOrigin } from "#src/rule";
+import type { FlatPermissionConfig, ScopeConfig } from "#src/types";
+
+/** Surface → (pattern → originating scope). */
+type OriginMap = Map<string, Map<string, RuleOrigin>>;
+
+/** Result of merging permission objects across scopes with provenance tracking. */
+export interface MergedScopes {
+  /** Fully merged flat permission config (lowest → highest precedence). */
+  mergedPermission: FlatPermissionConfig;
+  /** Maps each surface to a per-pattern origin (which scope contributed it). */
+  origins: OriginMap;
+}
+
+/**
+ * Merge permission objects across scopes (lowest → highest precedence) while
+ * tracking which scope contributed each (surface, pattern) entry.
+ *
+ * Mirrors mergeFlatPermissions() semantics for origin attribution:
+ * - Both base and incoming are objects → shallow-merge: each incoming pattern
+ *   is attributed to this scope; patterns the higher scope does not redefine
+ *   keep their earlier origin.
+ * - Otherwise → full replacement: this scope takes over the entire surface
+ *   entry, discarding all lower-scope attribution.
+ */
+export function mergeScopesWithOrigins(
+  scopes: readonly (readonly [RuleOrigin, ScopeConfig])[],
+): MergedScopes {
+  const origins: OriginMap = new Map();
+  let mergedPermission: FlatPermissionConfig = {};
+
+  for (const [scopeName, scope] of scopes) {
+    if (!scope.permission) continue;
+
+    for (const [surface, value] of Object.entries(scope.permission)) {
+      const baseVal = mergedPermission[surface];
+      /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
+      const bothObjects =
+        typeof baseVal === "object" &&
+        baseVal !== null &&
+        typeof value === "object" &&
+        value !== null;
+      /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+
+      if (bothObjects) {
+        // Shallow-merge: each incoming pattern is attributed to this scope;
+        // existing patterns from lower scopes keep their earlier origin.
+        if (!origins.has(surface)) origins.set(surface, new Map());
+        for (const pattern of Object.keys(value)) {
+          origins.get(surface)?.set(pattern, scopeName);
+        }
+      } else {
+        // Full replacement: this scope takes over the entire surface entry.
+        const surfaceOrigins = new Map<string, RuleOrigin>();
+        if (typeof value === "string") {
+          surfaceOrigins.set("*", scopeName);
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive null check
+        } else if (typeof value === "object" && value !== null) {
+          for (const pattern of Object.keys(value)) {
+            surfaceOrigins.set(pattern, scopeName);
+          }
+        }
+        origins.set(surface, surfaceOrigins);
+      }
+    }
+
+    mergedPermission = mergeFlatPermissions(mergedPermission, scope.permission);
+  }
+
+  return { mergedPermission, origins };
+}

package/src/session-approval.ts

@@ -0,0 +1,43 @@
+/**
+ * Value object for a session-scoped approval: one surface, one-or-more patterns.
+ *
+ * Owned by gate descriptors and passed to the session store — the runner never
+ * needs to know whether there is one pattern or many.
+ */
+export class SessionApproval {
+  private constructor(
+    readonly surface: string,
+    readonly patterns: readonly string[],
+  ) {}
+
+  /** Create an approval for a single pattern (the common case). */
+  static single(surface: string, pattern: string): SessionApproval {
+    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).
+   */
+  static multiple(
+    surface: string,
+    patterns: readonly string[],
+  ): SessionApproval {
+    return new SessionApproval(surface, [...patterns]);
+  }
+
+  /** 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 };
+  }
+}

package/src/session-rules.ts

@@ -1,6 +1,7 @@
 import { dirname, sep } from "node:path";
 
 import type { Ruleset } from "./rule";
+import type { SessionApproval } from "./session-approval";
 
 /**
  * Ephemeral in-memory store of session-scoped permission approvals.
@@ -29,6 +30,18 @@ export class SessionRules {
     return [...this.rules];
   }
 
+  /**
+   * Record all patterns 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.
+   */
+  record(approval: SessionApproval): void {
+    for (const pattern of approval.patterns) {
+      this.approve(approval.surface, pattern);
+    }
+  }
+
   /** Remove all session approvals. */
   clear(): void {
     this.rules = [];

package/test/handlers/external-directory-integration.test.ts

@@ -113,7 +113,7 @@ function makeSession(
     checkPermission: makeCheckPermission("deny"),
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi.fn().mockReturnValue([]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),

package/test/handlers/external-directory-session-dedup.test.ts

@@ -3,7 +3,7 @@
  * external path only prompt once — the session-approval recorded by the
  * first call covers the second.
  *
- * These tests use stateful mocks: `approveSessionRule` records rules,
+ * These tests use stateful mocks: `recordSessionApproval` records rules,
  * and `checkPermission` consults them via `getSessionRuleset`, mirroring
  * the real interaction between PermissionSession, SessionRules, and
  * PermissionManager.
@@ -15,6 +15,7 @@ import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
 import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
 import type { PermissionSession } from "#src/permission-session";
 import type { Rule } from "#src/rule";
+import type { SessionApproval } from "#src/session-approval";
 import type { ToolRegistry } from "#src/tool-registry";
 import type { PermissionCheckResult } from "#src/types";
 import { wildcardMatch } from "#src/wildcard-matcher";
@@ -53,7 +54,7 @@ function makeCtx(overrides: Partial<ExtensionContext> = {}): ExtensionContext {
  * Build a PermissionSession mock with stateful session-rule tracking.
  *
  * `checkPermission` returns "ask" for `external_directory` unless a
- * matching session rule exists (via `approveSessionRule`), in which case
+ * matching session rule exists (via `recordSessionApproval`), in which case
  * it returns "allow" with `source: "session"`. All other surfaces return
  * "allow" by default.
  */
@@ -115,16 +116,18 @@ function makeStatefulSession(
       },
     );
 
-  const approveSessionRule = vi
+  const recordSessionApproval = vi
     .fn()
-    .mockImplementation((surface: string, pattern: string) => {
-      sessionRules.push({
-        surface,
-        pattern,
-        action: "allow",
-        layer: "session",
-        origin: "session",
-      });
+    .mockImplementation((approval: SessionApproval) => {
+      for (const pattern of approval.patterns) {
+        sessionRules.push({
+          surface: approval.surface,
+          pattern,
+          action: "allow",
+          layer: "session",
+          origin: "session",
+        });
+      }
     });
 
   const getSessionRuleset = vi.fn().mockImplementation(() => [...sessionRules]);
@@ -136,7 +139,7 @@ function makeStatefulSession(
     checkPermission,
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset,
-    approveSessionRule,
+    recordSessionApproval,
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi.fn().mockReturnValue([]),
     getInfrastructureReadPaths: vi.fn().mockReturnValue([]),

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

@@ -93,9 +93,8 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
     expect(desc.sessionApproval).toBeDefined();
-    expect(desc.sessionApproval).toHaveProperty("patterns");
-    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
-    expect(patterns.length).toBeGreaterThan(0);
+    if (!desc.sessionApproval) return;
+    expect(desc.sessionApproval.patterns.length).toBeGreaterThan(0);
   });
 
   it("returns GateBypass when all external paths are config-level allowed", async () => {
@@ -211,8 +210,9 @@ describe("describeBashExternalDirectoryGate", () => {
     );
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
-    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
-    expect(patterns.length).toBe(1);
+    expect(desc.sessionApproval).toBeDefined();
+    if (!desc.sessionApproval) return;
+    expect(desc.sessionApproval.patterns.length).toBe(1);
     expect(desc.preCheck?.state).toBe("ask");
   });
 
@@ -236,8 +236,9 @@ describe("describeBashExternalDirectoryGate", () => {
     const desc = result as GateDescriptor;
     expect(desc.preCheck?.state).toBe("deny");
     // Both paths are uncovered (neither is allow), so both patterns are included.
-    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
-    expect(patterns.length).toBe(2);
+    expect(desc.sessionApproval).toBeDefined();
+    if (!desc.sessionApproval) return;
+    expect(desc.sessionApproval.patterns.length).toBe(2);
   });
 
   it("only includes uncovered paths when some are session-covered", async () => {
@@ -259,7 +260,8 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(isGateDescriptor(result)).toBe(true);
     const desc = result as GateDescriptor;
     // Should have patterns only for the uncovered path
-    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
-    expect(patterns.length).toBe(1);
+    expect(desc.sessionApproval).toBeDefined();
+    if (!desc.sessionApproval) return;
+    expect(desc.sessionApproval.patterns.length).toBe(1);
   });
 });

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

@@ -126,11 +126,8 @@ describe("describeExternalDirectoryGate", () => {
       ["/test/agent"],
     ) as GateDescriptor;
     expect(result.sessionApproval).toBeDefined();
-    expect(result.sessionApproval).toHaveProperty(
-      "surface",
-      "external_directory",
-    );
-    expect(result.sessionApproval).toHaveProperty("pattern");
+    expect(result.sessionApproval?.surface).toBe("external_directory");
+    expect(result.sessionApproval?.representativePattern).toBeDefined();
   });
 
   it("denialContext contains the external path and cwd", () => {

package/test/handlers/gates/helpers.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  buildDecisionEvent,
   deriveDecisionValue,
   deriveResolution,
 } from "#src/handlers/gates/helpers";
+import type { PermissionCheckResult } from "#src/types";
 
 describe("deriveDecisionValue", () => {
   it("returns command for bash", () => {
@@ -82,3 +84,82 @@ describe("deriveResolution", () => {
     );
   });
 });
+
+describe("buildDecisionEvent", () => {
+  function makeCheck(
+    overrides: Partial<PermissionCheckResult> = {},
+  ): PermissionCheckResult {
+    return {
+      state: "allow",
+      toolName: "read",
+      source: "tool",
+      origin: "builtin",
+      matchedPattern: "*",
+      ...overrides,
+    };
+  }
+
+  it("builds a decision event with all fields populated", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck({ origin: "global", matchedPattern: "read" }),
+      "test-agent",
+      "allow",
+      "policy_allow",
+    );
+    expect(event).toEqual({
+      surface: "read",
+      value: "read",
+      result: "allow",
+      resolution: "policy_allow",
+      origin: "global",
+      agentName: "test-agent",
+      matchedPattern: "read",
+    });
+  });
+
+  it("normalises undefined origin to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "bash", value: "git status" },
+      makeCheck({ origin: undefined }),
+      null,
+      "allow",
+      "user_approved",
+    );
+    expect(event.origin).toBeNull();
+  });
+
+  it("normalises null agentName to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck(),
+      null,
+      "deny",
+      "policy_deny",
+    );
+    expect(event.agentName).toBeNull();
+  });
+
+  it("normalises undefined matchedPattern to null", () => {
+    const event = buildDecisionEvent(
+      { surface: "read", value: "read" },
+      makeCheck({ matchedPattern: undefined }),
+      null,
+      "deny",
+      "policy_deny",
+    );
+    expect(event.matchedPattern).toBeNull();
+  });
+
+  it("passes result and resolution through", () => {
+    const event = buildDecisionEvent(
+      { surface: "bash", value: "rm -rf /" },
+      makeCheck(),
+      null,
+      "deny",
+      "user_denied",
+    );
+    expect(event.result).toBe("deny");
+    expect(event.resolution).toBe("user_denied");
+  });
+});

package/test/handlers/gates/path.test.ts

@@ -160,8 +160,8 @@ describe("describePathGate", () => {
       getSessionRuleset,
     ) as GateDescriptor;
     expect(result.sessionApproval).toBeDefined();
-    expect(result.sessionApproval).toHaveProperty("surface", "path");
-    expect(result.sessionApproval).toHaveProperty("pattern");
+    expect(result.sessionApproval?.surface).toBe("path");
+    expect(result.sessionApproval?.representativePattern).toBeDefined();
   });
 
   it("descriptor denialContext references the file path and tool name", () => {

package/test/handlers/gates/runner.test.ts

@@ -7,6 +7,7 @@ import type {
   GateRunnerDeps,
 } from "#src/handlers/gates/descriptor";
 import { runGateCheck } from "#src/handlers/gates/runner";
+import { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -61,7 +62,7 @@ function makeRunnerDeps(
   return {
     checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     writeReviewLog: vi.fn(),
     emitDecision: vi.fn(),
     canConfirm: vi.fn().mockReturnValue(true),
@@ -167,7 +168,7 @@ describe("runGateCheck", () => {
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
     });
     const descriptor = makeDescriptor({
-      sessionApproval: { surface: "read", pattern: "*" },
+      sessionApproval: SessionApproval.single("read", "*"),
     });
     const result = await runGateCheck(descriptor, null, "tc-1", deps);
     expect(result).toEqual({ action: "allow" });
@@ -176,33 +177,27 @@ describe("runGateCheck", () => {
         resolution: "user_approved_for_session",
       }),
     );
-    expect(deps.approveSessionRule).toHaveBeenCalledWith("read", "*");
+    expect(deps.recordSessionApproval).toHaveBeenCalledWith(
+      SessionApproval.single("read", "*"),
+    );
   });
 
-  it("calls approveSessionRule once per pattern when sessionApproval has multiple patterns", async () => {
+  it("calls recordSessionApproval once with the full SessionApproval when sessionApproval has multiple patterns", async () => {
     const deps = makeRunnerDeps({
       checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
       promptPermission: vi
         .fn()
         .mockResolvedValue({ approved: true, state: "approved_for_session" }),
     });
-    const descriptor = makeDescriptor({
-      sessionApproval: {
-        surface: "external_directory",
-        patterns: ["/outside/a/*", "/outside/b/*"],
-      },
-    });
-    const result = await runGateCheck(descriptor, null, "tc-1", deps);
-    expect(result).toEqual({ action: "allow" });
-    expect(deps.approveSessionRule).toHaveBeenCalledTimes(2);
-    expect(deps.approveSessionRule).toHaveBeenCalledWith(
-      "external_directory",
+    const approval = SessionApproval.multiple("external_directory", [
       "/outside/a/*",
-    );
-    expect(deps.approveSessionRule).toHaveBeenCalledWith(
-      "external_directory",
       "/outside/b/*",
-    );
+    ]);
+    const descriptor = makeDescriptor({ sessionApproval: approval });
+    const result = await runGateCheck(descriptor, null, "tc-1", deps);
+    expect(result).toEqual({ action: "allow" });
+    expect(deps.recordSessionApproval).toHaveBeenCalledTimes(1);
+    expect(deps.recordSessionApproval).toHaveBeenCalledWith(approval);
   });
 
   it("returns block and emits user_denied when ask + user denies", async () => {
@@ -317,7 +312,7 @@ describe("runGateCheck", () => {
     );
   });
 
-  it("does not call approveSessionRule when user approves once (no sessionApproval)", async () => {
+  it("does not call recordSessionApproval when user approves once (no sessionApproval)", async () => {
     const deps = makeRunnerDeps({
       checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
       promptPermission: vi
@@ -325,7 +320,7 @@ describe("runGateCheck", () => {
         .mockResolvedValue({ approved: true, state: "approved" }),
     });
     await runGateCheck(makeDescriptor(), null, "tc-1", deps);
-    expect(deps.approveSessionRule).not.toHaveBeenCalled();
+    expect(deps.recordSessionApproval).not.toHaveBeenCalled();
   });
 
   it("uses preCheck result directly instead of calling checkPermission", async () => {
@@ -348,7 +343,7 @@ describe("runGateCheck", () => {
     );
   });
 
-  it("does not call approveSessionRule when user approves for session but no sessionApproval on descriptor", async () => {
+  it("does not call recordSessionApproval when user approves for session but no sessionApproval on descriptor", async () => {
     const deps = makeRunnerDeps({
       checkPermission: vi.fn().mockReturnValue(makeCheckResult("ask")),
       promptPermission: vi
@@ -357,7 +352,7 @@ describe("runGateCheck", () => {
     });
     // No sessionApproval on descriptor
     await runGateCheck(makeDescriptor(), null, "tc-1", deps);
-    expect(deps.approveSessionRule).not.toHaveBeenCalled();
+    expect(deps.recordSessionApproval).not.toHaveBeenCalled();
   });
 
   describe("denialContext formatting", () => {

package/test/handlers/gates/tool.test.ts

@@ -142,8 +142,8 @@ describe("describeToolGate", () => {
       makeFormatter(),
     );
     expect(desc.sessionApproval).toBeDefined();
-    expect(desc.sessionApproval!).toHaveProperty("surface", "bash");
-    expect(desc.sessionApproval!).toHaveProperty("pattern");
+    expect(desc.sessionApproval?.surface).toBe("bash");
+    expect(desc.sessionApproval?.representativePattern).toBeDefined();
   });
 
   it("populates promptDetails with correct fields", () => {

package/test/handlers/input-events.test.ts

@@ -55,7 +55,7 @@ function makeSession(
     }),
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),

package/test/handlers/input.test.ts

@@ -43,7 +43,7 @@ function makeSession(
     checkPermission: vi.fn().mockReturnValue({ state: "allow" }),
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     canPrompt: vi.fn().mockReturnValue(true),
     prompt: vi.fn().mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),

package/test/handlers/tool-call-events.test.ts

@@ -77,7 +77,7 @@ function makeSession(
     checkPermission: vi.fn().mockReturnValue(makeCheckResult("allow")),
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi
       .fn()

package/test/handlers/tool-call.test.ts

@@ -68,7 +68,7 @@ function makeSession(
     checkPermission: vi.fn().mockReturnValue(makePermissionResult("allow")),
     getToolPermission: vi.fn().mockReturnValue("allow"),
     getSessionRuleset: vi.fn().mockReturnValue([]),
-    approveSessionRule: vi.fn(),
+    recordSessionApproval: vi.fn(),
     getActiveSkillEntries: vi.fn().mockReturnValue([]),
     getInfrastructureDirs: vi
       .fn()

package/test/permission-session.test.ts

@@ -36,6 +36,7 @@ import {
   PermissionSession,
   type PermissionSessionRuntimeDeps,
 } from "#src/permission-session";
+import { SessionApproval } from "#src/session-approval";
 import type { SessionLogger } from "#src/session-logger";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 
@@ -219,9 +220,11 @@ describe("PermissionSession", () => {
       expect(rules).toEqual([]);
     });
 
-    it("delegates approveSessionRule to internal SessionRules", () => {
+    it("delegates recordSessionApproval to internal SessionRules", () => {
       const { session } = createSession();
-      session.approveSessionRule("bash", "/usr/bin/*");
+      session.recordSessionApproval(
+        SessionApproval.single("bash", "/usr/bin/*"),
+      );
       const rules = session.getSessionRuleset();
       expect(rules).toHaveLength(1);
       expect(rules[0]).toMatchObject({
@@ -325,7 +328,7 @@ describe("PermissionSession", () => {
   describe("shutdown", () => {
     it("clears session rules", () => {
       const { session } = createSession();
-      session.approveSessionRule("bash", "*");
+      session.recordSessionApproval(SessionApproval.single("bash", "*"));
       expect(session.getSessionRuleset()).toHaveLength(1);
 
       session.shutdown();

package/test/scope-merge.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import type { MergedScopes } from "#src/scope-merge";
+import { mergeScopesWithOrigins } from "#src/scope-merge";
+
+describe("mergeScopesWithOrigins", () => {
+  it("returns empty result for empty scopes array", () => {
+    const result: MergedScopes = mergeScopesWithOrigins([]);
+    expect(result.mergedPermission).toEqual({});
+    expect(result.origins.size).toBe(0);
+  });
+
+  it("attributes a string surface value to the contributing scope via the '*' pattern", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "allow" });
+    expect(result.origins.get("bash")?.get("*")).toBe("global");
+  });
+
+  it("attributes each pattern of an object surface value to the contributing scope", () => {
+    const result = mergeScopesWithOrigins([
+      [
+        "project",
+        { permission: { bash: { "git *": "allow", "npm *": "deny" } } },
+      ],
+    ]);
+    expect(result.mergedPermission).toEqual({
+      bash: { "git *": "allow", "npm *": "deny" },
+    });
+    expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    expect(result.origins.get("bash")?.get("npm *")).toBe("project");
+  });
+
+  it(
+    "shallow-merge: patterns not redefined by the higher scope keep their lower-scope origin;" +
+      " patterns the higher scope defines switch to the higher scope",
+    () => {
+      const result = mergeScopesWithOrigins([
+        [
+          "global",
+          { permission: { bash: { "ls *": "allow", "git *": "allow" } } },
+        ],
+        ["project", { permission: { bash: { "git *": "deny" } } }],
+      ]);
+      expect(result.mergedPermission).toEqual({
+        bash: { "ls *": "allow", "git *": "deny" },
+      });
+      // "ls *" was not touched by project — retains global attribution
+      expect(result.origins.get("bash")?.get("ls *")).toBe("global");
+      // "git *" was overridden by project — switches to project attribution
+      expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    },
+  );
+
+  it("full replacement (string over object): higher scope re-attributes the entire surface to its own origin", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: { "ls *": "allow" } } }],
+      ["project", { permission: { bash: "deny" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "deny" });
+    // The string value produces a single "*" pattern for the replacing scope
+    expect(result.origins.get("bash")?.get("*")).toBe("project");
+    // The former "ls *" pattern from global is gone — origins are replaced, not merged
+    expect(result.origins.get("bash")?.has("ls *")).toBe(false);
+  });
+
+  it("full replacement (object over string): higher scope re-attributes the entire surface to its own origin", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { bash: "ask" } }],
+      ["project", { permission: { bash: { "git *": "deny" } } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: { "git *": "deny" } });
+    // The object value attributes each pattern to the replacing scope
+    expect(result.origins.get("bash")?.get("git *")).toBe("project");
+    // The former "*" attribution from global is gone
+    expect(result.origins.get("bash")?.has("*")).toBe(false);
+  });
+
+  it("applies four-scope precedence in lowest→highest order (global → project → agent → project-agent)", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { read: "ask" } }],
+      ["project", { permission: { write: "deny" } }],
+      ["agent", { permission: { bash: "deny" } }],
+      ["project-agent", { permission: { mcp: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({
+      read: "ask",
+      write: "deny",
+      bash: "deny",
+      mcp: "allow",
+    });
+    expect(result.origins.get("read")?.get("*")).toBe("global");
+    expect(result.origins.get("write")?.get("*")).toBe("project");
+    expect(result.origins.get("bash")?.get("*")).toBe("agent");
+    expect(result.origins.get("mcp")?.get("*")).toBe("project-agent");
+  });
+
+  it("skips scopes with no permission key, contributing nothing to either map", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", {}],
+      ["project", { permission: { bash: "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ bash: "allow" });
+    expect(result.origins.get("bash")?.get("*")).toBe("project");
+  });
+
+  it("attributes the universal '*' surface like any other (downstream reads origins.get('*')?.get('*') for universalFallbackOrigin)", () => {
+    const result = mergeScopesWithOrigins([
+      ["global", { permission: { "*": "deny" } }],
+      ["project", { permission: { "*": "allow" } }],
+    ]);
+    expect(result.mergedPermission).toEqual({ "*": "allow" });
+    // Both scopes write a string — each is a full replacement; project wins last
+    expect(result.origins.get("*")?.get("*")).toBe("project");
+  });
+});

package/test/session-approval.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { SessionApproval } from "#src/session-approval";
+
+describe("SessionApproval", () => {
+  describe("single", () => {
+    it("stores surface and one pattern", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.surface).toBe("bash");
+      expect(approval.patterns).toEqual(["git *"]);
+    });
+
+    it("representativePattern returns the pattern", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.representativePattern).toBe("git *");
+    });
+
+    it("toGateApproval returns { surface, pattern }", () => {
+      const approval = SessionApproval.single("bash", "git *");
+      expect(approval.toGateApproval()).toEqual({
+        surface: "bash",
+        pattern: "git *",
+      });
+    });
+  });
+
+  describe("multiple", () => {
+    it("stores surface and all patterns", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.surface).toBe("external_directory");
+      expect(approval.patterns).toEqual(["/outside/a/*", "/outside/b/*"]);
+    });
+
+    it("representativePattern returns the first pattern", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.representativePattern).toBe("/outside/a/*");
+    });
+
+    it("toGateApproval returns { surface, pattern } using the first pattern", () => {
+      const approval = SessionApproval.multiple("external_directory", [
+        "/outside/a/*",
+        "/outside/b/*",
+      ]);
+      expect(approval.toGateApproval()).toEqual({
+        surface: "external_directory",
+        pattern: "/outside/a/*",
+      });
+    });
+
+    it("defensive copy — mutating the source array does not affect patterns", () => {
+      const source = ["/outside/a/*", "/outside/b/*"];
+      const approval = SessionApproval.multiple("external_directory", source);
+      source.push("/outside/c/*");
+      expect(approval.patterns).toEqual(["/outside/a/*", "/outside/b/*"]);
+    });
+  });
+
+  describe("empty patterns (degenerate case)", () => {
+    it("representativePattern returns undefined", () => {
+      const approval = SessionApproval.multiple("external_directory", []);
+      expect(approval.representativePattern).toBeUndefined();
+    });
+
+    it("toGateApproval returns undefined", () => {
+      const approval = SessionApproval.multiple("external_directory", []);
+      expect(approval.toGateApproval()).toBeUndefined();
+    });
+  });
+});

package/test/session-rules.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { evaluate } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern, SessionRules } from "#src/session-rules";
 
 // ── SessionRules ───────────────────────────────────────────────────────────
@@ -66,6 +67,54 @@ describe("SessionRules", () => {
     });
   });
 
+  describe("record", () => {
+    it("records a single-pattern approval as one rule", () => {
+      const rules = new SessionRules();
+      rules.record(SessionApproval.single("bash", "git *"));
+      expect(rules.getRuleset()).toEqual([
+        {
+          surface: "bash",
+          pattern: "git *",
+          action: "allow",
+          layer: "session",
+          origin: "session",
+        },
+      ]);
+    });
+
+    it("records a multi-pattern approval as one rule per pattern", () => {
+      const rules = new SessionRules();
+      rules.record(
+        SessionApproval.multiple("external_directory", [
+          "/outside/a/*",
+          "/outside/b/*",
+        ]),
+      );
+      expect(rules.getRuleset()).toHaveLength(2);
+      expect(rules.getRuleset()[0].pattern).toBe("/outside/a/*");
+      expect(rules.getRuleset()[1].pattern).toBe("/outside/b/*");
+    });
+
+    it("records each rule with the correct surface", () => {
+      const rules = new SessionRules();
+      rules.record(
+        SessionApproval.multiple("external_directory", [
+          "/outside/a/*",
+          "/outside/b/*",
+        ]),
+      );
+      for (const rule of rules.getRuleset()) {
+        expect(rule.surface).toBe("external_directory");
+      }
+    });
+
+    it("records nothing for an empty patterns list", () => {
+      const rules = new SessionRules();
+      rules.record(SessionApproval.multiple("external_directory", []));
+      expect(rules.getRuleset()).toEqual([]);
+    });
+  });
+
   describe("evaluate() integration", () => {
     it("returns allow for a path under an approved directory", () => {
       const session = new SessionRules();