@gotgenes/pi-permission-system 10.4.0 → 10.5.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.5.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.4.0...pi-permission-system-v10.5.0) (2026-06-07)
+
+
+### Features
+
+* add PermissionResolver class and route gate runner through it ([#340](https://github.com/gotgenes/pi-packages/issues/340)) ([4133601](https://github.com/gotgenes/pi-packages/commit/41336018d495f85b30b7b77fadb5912870f0dedd))
+
+
+### Bug Fixes
+
+* suppress fallow unused-class-member for pre-Step-8 resolver methods ([#340](https://github.com/gotgenes/pi-packages/issues/340)) ([fd65626](https://github.com/gotgenes/pi-packages/commit/fd65626ae867457edeb829ea28d0ab94fe51dea6))
+
 ## [10.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.3.1...pi-permission-system-v10.4.0) (2026-06-07)
 
 

package/package.json

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

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

@@ -1,6 +1,6 @@
 import type { BashCommand } from "#src/handlers/gates/bash-program";
 import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
 
 /**
@@ -30,7 +30,7 @@ export function resolveBashCommandCheck(
   command: string,
   commands: BashCommand[],
   agentName: string | undefined,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
   const results = commands.map((cmd) => {
     const result = resolver.resolve("bash", { command: cmd.text }, agentName);

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

@@ -1,5 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
@@ -21,7 +21,7 @@ import type { ToolCallContext } from "./types";
 export function describeBashExternalDirectoryGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): GateResult {
   if (tcc.toolName !== "bash" || !tcc.cwd) return null;
 

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

@@ -1,5 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
@@ -25,7 +25,7 @@ import type { ToolCallContext } from "./types";
 export function describeBashPathGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): GateResult {
   if (tcc.toolName !== "bash") return null;
 

package/src/handlers/gates/path.ts

@@ -1,5 +1,5 @@
 import { getPathBearingToolPath } from "#src/path-utils";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { GateDescriptor, GateResult } from "./descriptor";
@@ -15,7 +15,7 @@ import type { ToolCallContext } from "./types";
  */
 export function describePathGate(
   tcc: ToolCallContext,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): GateResult {
   const filePath = getPathBearingToolPath(tcc.toolName, tcc.input);
   if (!filePath) return null;

package/src/handlers/gates/runner.ts

@@ -7,7 +7,7 @@ import {
 import type { GatePrompter } from "#src/gate-prompter";
 import type { PermissionPromptDecision } from "#src/permission-dialog";
 import { applyPermissionGate } from "#src/permission-gate";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor, GateResult } from "./descriptor";
@@ -28,7 +28,7 @@ import type { GateOutcome } from "./types";
  */
 export class GateRunner {
   constructor(
-    private readonly resolver: PermissionResolver,
+    private readonly resolver: ScopedPermissionResolver,
     private readonly recorder: SessionApprovalRecorder,
     private readonly prompter: GatePrompter,
     private readonly reporter: DecisionReporter,

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,5 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/common";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
 import {
@@ -21,14 +21,14 @@ import type { GateOutcome, ToolCallContext } from "./types";
 /**
  * Narrow interface the pipeline needs from its session-side dependency.
  *
- * Extends `PermissionResolver` (the `resolve` method gate factories use)
- * with the three query methods needed to assemble gate inputs.
+ * The three query methods needed to assemble gate inputs.
+ * The resolver is injected separately as a constructor parameter.
  *
  * `PermissionSession` satisfies this structurally at the construction call
  * site; no `implements` clause is needed and would create a layer-inversion
  * import from the domain module into the handler layer.
  */
-export interface ToolCallGateInputs extends PermissionResolver {
+export interface ToolCallGateInputs {
   /** Active skill prompt entries for the skill-read gate. */
   getActiveSkillEntries(): SkillPromptEntry[];
   /** Combined infrastructure read directories (static + config-derived). */
@@ -50,6 +50,7 @@ export interface ToolCallGateInputs extends PermissionResolver {
  */
 export class ToolCallGatePipeline {
   constructor(
+    private readonly resolver: ScopedPermissionResolver,
     private readonly inputs: ToolCallGateInputs,
     private readonly customFormatters?: ToolInputFormatterLookup,
   ) {}
@@ -76,10 +77,10 @@ export class ToolCallGatePipeline {
     const gateProducers: Array<() => GateResult | Promise<GateResult>> = [
       () =>
         describeSkillReadGate(tcc, () => this.inputs.getActiveSkillEntries()),
-      () => describePathGate(tcc, this.inputs),
+      () => describePathGate(tcc, this.resolver),
       () => describeExternalDirectoryGate(tcc, infraDirs),
-      () => describeBashExternalDirectoryGate(tcc, bashProgram, this.inputs),
-      () => describeBashPathGate(tcc, bashProgram, this.inputs),
+      () => describeBashExternalDirectoryGate(tcc, bashProgram, this.resolver),
+      () => describeBashPathGate(tcc, bashProgram, this.resolver),
       () => {
         // Bash commands may chain several sub-commands (`a && b`, `a | b`, …);
         // evaluate each unit from the shared parse on the bash surface and
@@ -91,9 +92,9 @@ export class ToolCallGatePipeline {
                 command ?? "",
                 bashProgram.commands(),
                 tcc.agentName ?? undefined,
-                this.inputs,
+                this.resolver,
               )
-            : this.inputs.resolve(
+            : this.resolver.resolve(
                 tcc.toolName,
                 tcc.input,
                 tcc.agentName ?? undefined,

package/src/index.ts

@@ -23,6 +23,7 @@ import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { PermissionManager } from "./permission-manager";
 import { PermissionPrompter } from "./permission-prompter";
+import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
 import { PromptingGateway } from "./prompting-gateway";
@@ -158,13 +159,16 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const lifecycle = new SessionLifecycleHandler(session, serviceLifecycle);
   const agentPrep = new AgentPrepHandler(session, toolRegistry);
+  const resolver = new PermissionResolver(permissionManager, sessionRules);
+
   const reporter = new GateDecisionReporter(session.logger, pi.events);
-  const gateRunner = new GateRunner(session, session, gateway, reporter);
+  const gateRunner = new GateRunner(resolver, session, gateway, reporter);
   const toolCallGatePipeline = new ToolCallGatePipeline(
+    resolver,
     session,
     formatterRegistry,
   );
-  const skillInputGatePipeline = new SkillInputGatePipeline(session);
+  const skillInputGatePipeline = new SkillInputGatePipeline(resolver);
   const gates = new PermissionGateHandler(
     session,
     toolRegistry,

package/src/permission-resolver.ts

@@ -1,4 +1,7 @@
-import type { PermissionCheckResult } from "./types";
+import type { ScopedPermissionManager } from "./permission-manager";
+import type { Rule } from "./rule";
+import type { SessionRules } from "./session-rules";
+import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
  * Resolves the effective permission for a surface/input, applying the current
@@ -8,10 +11,74 @@ import type { PermissionCheckResult } from "./types";
  * previously threaded by hand: the ruleset was only ever fetched to be passed
  * straight back into `checkPermission`, so the two are one operation.
  */
-export interface PermissionResolver {
+export interface ScopedPermissionResolver {
   resolve(
     surface: string,
     input: unknown,
     agentName?: string,
   ): PermissionCheckResult;
 }
+
+/**
+ * Concrete collaborator that owns the resolution surface.
+ *
+ * Holds a `ScopedPermissionManager` and a `SessionRules` store, composing
+ * them so callers never thread the session ruleset by hand.
+ *
+ * Constructor deps:
+ * - `permissionManager` — the narrow session-scoped permission-checking interface
+ * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
+ */
+export class PermissionResolver implements ScopedPermissionResolver {
+  constructor(
+    private readonly permissionManager: ScopedPermissionManager,
+    private readonly sessionRules: Pick<SessionRules, "getRuleset">,
+  ) {}
+
+  /**
+   * Resolve the effective permission for a surface/input, applying the current
+   * session rules. Composes `checkPermission` with `getRuleset()` so callers
+   * never thread the ruleset by hand.
+   */
+  resolve(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult {
+    return this.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
+  checkPermission(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+    sessionRules?: Rule[],
+  ): PermissionCheckResult {
+    return this.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName,
+      sessionRules,
+    );
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  getToolPermission(toolName: string, agentName?: string): PermissionState {
+    return this.permissionManager.getToolPermission(toolName, agentName);
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  getConfigIssues(agentName?: string): string[] {
+    return this.permissionManager.getConfigIssues(agentName);
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  getPolicyCacheStamp(agentName?: string): string {
+    return this.permissionManager.getPolicyCacheStamp(agentName);
+  }
+}

package/src/permission-session.ts

@@ -11,7 +11,6 @@ import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
 import type { GateHandlerSession } from "./gate-handler-session";
 import type { ScopedPermissionManager } from "./permission-manager";
-import type { PermissionResolver } from "./permission-resolver";
 import type { PromptingGatewayLifecycle } from "./prompting-gateway";
 import type { Rule } from "./rule";
 import type { SessionApproval } from "./session-approval";
@@ -43,7 +42,6 @@ import type { PermissionCheckResult, PermissionState } from "./types";
  */
 export class PermissionSession
   implements
-    PermissionResolver,
     SessionApprovalRecorder,
     GateHandlerSession,
     AgentPrepSession,
@@ -102,24 +100,6 @@ export class PermissionSession
     );
   }
 
-  /**
-   * Resolve the effective permission for a surface/input, applying the current
-   * session rules. Composes `checkPermission` with `getSessionRuleset` so
-   * callers never thread the ruleset by hand.
-   */
-  resolve(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-  ): PermissionCheckResult {
-    return this.checkPermission(
-      surface,
-      input,
-      agentName,
-      this.getSessionRuleset(),
-    );
-  }
-
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     return this.permissionManager.getToolPermission(toolName, agentName);
   }

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

@@ -153,17 +153,6 @@ function makeStatefulSession(
       vi
         .fn<MockGateHandlerSession["getToolPreviewLimits"]>()
         .mockReturnValue(resolveToolPreviewLimits(DEFAULT_EXTENSION_CONFIG)),
-    // Resolve delegation — closure reads `session` at call time so overrides win.
-    resolve:
-      overrides.resolve ??
-      vi.fn<MockGateHandlerSession["resolve"]>((surface, input, agentName) =>
-        session.checkPermission(
-          surface,
-          input,
-          agentName,
-          session.getSessionRuleset(),
-        ),
-      ),
   };
   return session;
 }
@@ -180,11 +169,22 @@ function makeHandlerForSession(
       .fn<GatePrompter["prompt"]>()
       .mockResolvedValue({ approved: true, state: "approved_for_session" }),
   };
-  const runner = new GateRunner(session, session, resolvedPrompter, reporter);
+  // Resolver delegates to session's checkPermission + getSessionRuleset so
+  // stateful approval tracking steers resolve automatically.
+  const resolver = {
+    resolve: (surface: string, input: unknown, agentName?: string) =>
+      session.checkPermission(
+        surface,
+        input,
+        agentName,
+        session.getSessionRuleset(),
+      ),
+  };
+  const runner = new GateRunner(resolver, session, resolvedPrompter, reporter);
   const handler = new PermissionGateHandler(
     session,
     makeToolRegistry(),
-    new ToolCallGatePipeline(session),
+    new ToolCallGatePipeline(resolver, session),
     new SkillInputGatePipeline(session),
     runner,
   );

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

@@ -9,7 +9,7 @@ import type {
 } from "#src/handlers/gates/descriptor";
 import { isGateBypass, isGateDescriptor } from "#src/handlers/gates/descriptor";
 import type { ToolCallContext } from "#src/handlers/gates/types";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { PermissionCheckResult } from "#src/types";
 
 import { makeResolver } from "#test/helpers/gate-fixtures";
@@ -47,7 +47,7 @@ function makeCheckResult(
  */
 async function describeGate(
   tcc: ToolCallContext,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): Promise<GateResult> {
   const command = getNonEmptyString(toRecord(tcc.input).command);
   const bashProgram =

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

@@ -19,7 +19,7 @@ import type {
 } from "#src/handlers/gates/descriptor";
 import { isGateBypass, isGateDescriptor } from "#src/handlers/gates/descriptor";
 import type { ToolCallContext } from "#src/handlers/gates/types";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 
 import {
   makeGateCheckResult as makeCheckResult,
@@ -39,7 +39,7 @@ afterEach(() => {
  */
 async function describeGate(
   tcc: ToolCallContext,
-  resolver: PermissionResolver,
+  resolver: ScopedPermissionResolver,
 ): Promise<GateResult> {
   const command = getNonEmptyString(toRecord(tcc.input).command);
   const bashProgram =

package/test/handlers/gates/tool-call-gate-pipeline.test.ts

@@ -40,9 +40,10 @@ describe("ToolCallGatePipeline", () => {
 
   describe("evaluate — non-bash tool", () => {
     it("returns allow when all gates pass", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       const result = await pipeline.evaluate(
         makeTcc({ toolName: "read", input: {} }),
@@ -53,12 +54,12 @@ describe("ToolCallGatePipeline", () => {
     });
 
     it("returns block when the tool gate denies", async () => {
-      const { resolve } = makeResolver(
+      const resolver = makeResolver(
         makeCheckResult({ state: "deny", matchedPattern: "*" }),
       );
-      const inputs = makeGateInputs({ resolve });
-      const { runner } = makeGateRunner({ resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const inputs = makeGateInputs();
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       const result = await pipeline.evaluate(
         makeTcc({ toolName: "read", input: {} }),
@@ -69,13 +70,14 @@ describe("ToolCallGatePipeline", () => {
     });
 
     it("short-circuits after the first blocking gate without evaluating later ones", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
       const { runner } = makeGateRunner();
       const runSpy = vi
         .spyOn(runner, "run")
         .mockResolvedValue({ action: "block", reason: "first gate blocked" });
 
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
       const result = await pipeline.evaluate(
         makeTcc({ toolName: "read", input: {} }),
         runner,
@@ -92,9 +94,10 @@ describe("ToolCallGatePipeline", () => {
         toolTextSummaryMaxLength: 100,
         toolInputLogPreviewMaxLength: 200,
       }));
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs({ getToolPreviewLimits });
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(makeTcc({ toolName: "read", input: {} }), runner);
 
@@ -103,9 +106,10 @@ describe("ToolCallGatePipeline", () => {
 
     it("calls getInfrastructureReadDirs() during evaluate", async () => {
       const getInfrastructureReadDirs = vi.fn<() => string[]>(() => []);
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs({ getInfrastructureReadDirs });
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(makeTcc({ toolName: "read", input: {} }), runner);
 
@@ -114,9 +118,10 @@ describe("ToolCallGatePipeline", () => {
 
     it("calls getActiveSkillEntries() during evaluate", async () => {
       const getActiveSkillEntries = vi.fn<() => []>(() => []);
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs({ getActiveSkillEntries });
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(makeTcc({ toolName: "read", input: {} }), runner);
 
@@ -124,9 +129,10 @@ describe("ToolCallGatePipeline", () => {
     });
 
     it("does not call BashProgram.parse for non-bash tools", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(makeTcc({ toolName: "read", input: {} }), runner);
 
@@ -138,9 +144,10 @@ describe("ToolCallGatePipeline", () => {
 
   describe("evaluate — bash tool", () => {
     it("returns allow when the bash command is permitted", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       const result = await pipeline.evaluate(
         makeTcc({ toolName: "bash", input: { command: "echo hello" } }),
@@ -151,9 +158,10 @@ describe("ToolCallGatePipeline", () => {
     });
 
     it("parses BashProgram exactly once per evaluate for bash tools with a command", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(
         makeTcc({ toolName: "bash", input: { command: "echo hello" } }),
@@ -165,9 +173,10 @@ describe("ToolCallGatePipeline", () => {
     });
 
     it("does not parse BashProgram when the bash command is empty", async () => {
+      const resolver = makeResolver(makeCheckResult());
       const inputs = makeGateInputs();
-      const { runner } = makeGateRunner({ resolve: inputs.resolve });
-      const pipeline = new ToolCallGatePipeline(inputs);
+      const { runner } = makeGateRunner();
+      const pipeline = new ToolCallGatePipeline(resolver, inputs);
 
       await pipeline.evaluate(
         makeTcc({ toolName: "bash", input: { command: "" } }),

package/test/helpers/gate-fixtures.ts

@@ -10,7 +10,7 @@ import { GateRunner } from "#src/handlers/gates/runner";
 import type { SkillInputGateInputs } from "#src/handlers/gates/skill-input-gate-pipeline";
 import type { ToolCallGateInputs } from "#src/handlers/gates/tool-call-gate-pipeline";
 import type { ToolCallContext } from "#src/handlers/gates/types";
-import type { PermissionResolver } from "#src/permission-resolver";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolPreviewFormatterOptions } from "#src/tool-preview-formatter";
@@ -25,7 +25,7 @@ import { makeCheckResult } from "#test/helpers/handler-fixtures";
  * mock access (`mockReturnValue`, `mockImplementation`, `mock.calls`).
  */
 export function makeResolver(defaultCheck?: PermissionCheckResult) {
-  const resolve = vi.fn<PermissionResolver["resolve"]>();
+  const resolve = vi.fn<ScopedPermissionResolver["resolve"]>();
   if (defaultCheck) {
     resolve.mockReturnValue(defaultCheck);
   }
@@ -91,7 +91,7 @@ export function makeReporter(
 export function makeGateRunner(
   overrides: {
     resolveResult?: PermissionCheckResult;
-    resolve?: PermissionResolver["resolve"];
+    resolve?: ScopedPermissionResolver["resolve"];
     recordSessionApproval?: SessionApprovalRecorder["recordSessionApproval"];
     canConfirm?: GatePrompter["canConfirm"];
     prompt?: GatePrompter["prompt"];
@@ -102,7 +102,7 @@ export function makeGateRunner(
   const resolve =
     overrides.resolve ??
     vi
-      .fn<PermissionResolver["resolve"]>()
+      .fn<ScopedPermissionResolver["resolve"]>()
       .mockReturnValue(
         overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
       );
@@ -204,7 +204,7 @@ export function makePathDispatchResolver(
   byPath: Record<string, PermissionCheckResult>,
   defaultResult: PermissionCheckResult,
 ) {
-  const resolve = vi.fn<PermissionResolver["resolve"]>();
+  const resolve = vi.fn<ScopedPermissionResolver["resolve"]>();
   resolve.mockImplementation((_surface, input) => {
     const path = (input as Record<string, unknown>).path;
     if (typeof path === "string" && path in byPath) {
@@ -243,16 +243,12 @@ export function makeGateCheckResult(
  */
 export function makeGateInputs(
   overrides: {
-    resolve?: PermissionResolver["resolve"];
     getActiveSkillEntries?: () => SkillPromptEntry[];
     getInfrastructureReadDirs?: () => string[];
     getToolPreviewLimits?: () => ToolPreviewFormatterOptions;
   } = {},
 ): ToolCallGateInputs {
   return {
-    resolve:
-      overrides.resolve ??
-      vi.fn<PermissionResolver["resolve"]>().mockReturnValue(makeCheckResult()),
     getActiveSkillEntries:
       overrides.getActiveSkillEntries ??
       vi.fn<() => SkillPromptEntry[]>(() => []),

package/test/helpers/handler-fixtures.ts

@@ -124,10 +124,6 @@ export function makeCheckResult(
  * field against `MockGateHandlerSession` individually — a missing field fails
  * `pnpm run check` instead of failing silently at runtime.
  *
- * The `resolve` delegation is inlined as a closure that reads `session` at
- * call time, so overriding `checkPermission` or `getSessionRuleset`
- * automatically steers it without extra guards.
- *
  * Prompting is not part of this mock — pass `prompter` to `makeHandler`.
  */
 export function makeSession(
@@ -169,17 +165,6 @@ export function makeSession(
       vi
         .fn<MockGateHandlerSession["getToolPreviewLimits"]>()
         .mockReturnValue(resolveToolPreviewLimits(DEFAULT_EXTENSION_CONFIG)),
-    // Resolve delegation — closure reads `session` at call time so overrides win.
-    resolve:
-      overrides.resolve ??
-      vi.fn<MockGateHandlerSession["resolve"]>((surface, input, agentName) =>
-        session.checkPermission(
-          surface,
-          input,
-          agentName,
-          session.getSessionRuleset(),
-        ),
-      ),
   };
   return session;
 }
@@ -293,7 +278,18 @@ export function makeHandler(overrides?: {
             .mockReturnValue(overrides.tools.map((name) => ({ name }))),
         })
       : makeToolRegistry(overrides?.toolRegistry);
-  const pipeline = new ToolCallGatePipeline(session);
+  // Resolver delegates to session's checkPermission + getSessionRuleset —
+  // overriding session.checkPermission steers resolve automatically.
+  const resolver = {
+    resolve: (surface: string, input: unknown, agentName?: string) =>
+      session.checkPermission(
+        surface,
+        input,
+        agentName,
+        session.getSessionRuleset(),
+      ),
+  };
+  const pipeline = new ToolCallGatePipeline(resolver, session);
   const skillInputPipeline = new SkillInputGatePipeline(session);
   const reporter = new GateDecisionReporter(session.logger, events);
   const prompter: GatePrompter = overrides?.prompter ?? {
@@ -302,7 +298,7 @@ export function makeHandler(overrides?: {
       .fn<GatePrompter["prompt"]>()
       .mockResolvedValue({ approved: true, state: "approved" }),
   };
-  const runner = new GateRunner(session, session, prompter, reporter);
+  const runner = new GateRunner(resolver, session, prompter, reporter);
   const handler = new PermissionGateHandler(
     session,
     toolRegistry,

package/test/permission-resolver.test.ts

@@ -0,0 +1,194 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ScopedPermissionManager } from "#src/permission-manager";
+import { PermissionResolver } from "#src/permission-resolver";
+import type { Ruleset } from "#src/rule";
+import { SessionApproval } from "#src/session-approval";
+import { SessionRules } from "#src/session-rules";
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+function makePermissionManager() {
+  return {
+    configureForCwd: vi.fn<(cwd: string | undefined | null) => void>(),
+    checkPermission: vi
+      .fn<
+        (
+          toolName: string,
+          input: unknown,
+          agentName?: string,
+          sessionRules?: Ruleset,
+        ) => PermissionCheckResult
+      >()
+      .mockReturnValue({
+        state: "allow",
+        toolName: "read",
+        source: "tool",
+        origin: "builtin",
+      }),
+    getToolPermission: vi
+      .fn<(toolName: string, agentName?: string) => PermissionState>()
+      .mockReturnValue("allow"),
+    getConfigIssues: vi.fn((): string[] => []),
+    getPolicyCacheStamp: vi.fn((): string => "stamp-1"),
+  };
+}
+
+function makeResolver(
+  pm?: ScopedPermissionManager,
+  sessionRules?: Pick<SessionRules, "getRuleset">,
+) {
+  const permissionManager = pm ?? makePermissionManager();
+  const rules = sessionRules ?? new SessionRules();
+  return {
+    resolver: new PermissionResolver(permissionManager, rules),
+    permissionManager,
+  };
+}
+
+beforeEach(() => {
+  // no module-level vi.fn() stubs to reset
+});
+
+describe("PermissionResolver", () => {
+  describe("resolve", () => {
+    it("forwards surface, input, and agentName, applying the empty session ruleset", () => {
+      const { resolver, permissionManager } = makeResolver();
+
+      resolver.resolve("bash", { command: "ls" }, "agent-x");
+
+      expect(permissionManager.checkPermission).toHaveBeenCalledWith(
+        "bash",
+        { command: "ls" },
+        "agent-x",
+        [],
+      );
+    });
+
+    it("defaults agentName to undefined when omitted", () => {
+      const { resolver, permissionManager } = makeResolver();
+
+      resolver.resolve("read", { path: ".env" });
+
+      expect(permissionManager.checkPermission).toHaveBeenCalledWith(
+        "read",
+        { path: ".env" },
+        undefined,
+        [],
+      );
+    });
+
+    it("applies a recorded session approval on the next resolve", () => {
+      const pm = makePermissionManager();
+      const sessionRules = new SessionRules();
+      const { resolver } = makeResolver(pm, sessionRules);
+
+      // Record an approval directly into the shared SessionRules instance.
+      sessionRules.record(SessionApproval.single("bash", "git *"));
+      resolver.resolve("bash", { command: "git status" });
+
+      const passedRules = vi.mocked(pm.checkPermission).mock.calls[0][3];
+      expect(passedRules).toHaveLength(1);
+      expect(passedRules?.[0]).toMatchObject({
+        surface: "bash",
+        pattern: "git *",
+        action: "allow",
+      });
+    });
+
+    it("returns the PermissionManager's check result", () => {
+      const pm = makePermissionManager();
+      vi.mocked(pm.checkPermission).mockReturnValue({
+        state: "deny",
+        toolName: "bash",
+        source: "bash",
+        origin: "global",
+        matchedPattern: "rm *",
+      });
+      const { resolver } = makeResolver(pm);
+
+      const result = resolver.resolve("bash", { command: "rm -rf /" });
+
+      expect(result).toEqual({
+        state: "deny",
+        toolName: "bash",
+        source: "bash",
+        origin: "global",
+        matchedPattern: "rm *",
+      });
+    });
+  });
+
+  describe("checkPermission", () => {
+    it("delegates to permissionManager.checkPermission with the given args", () => {
+      const { resolver, permissionManager } = makeResolver();
+
+      resolver.checkPermission("bash", { command: "ls" }, "agent-1");
+
+      expect(permissionManager.checkPermission).toHaveBeenCalledWith(
+        "bash",
+        { command: "ls" },
+        "agent-1",
+        undefined,
+      );
+    });
+
+    it("passes optional sessionRules through when supplied", () => {
+      const { resolver, permissionManager } = makeResolver();
+      const extraRules: Ruleset = [
+        { surface: "bash", pattern: "*", action: "allow", origin: "session" },
+      ];
+
+      resolver.checkPermission(
+        "bash",
+        { command: "ls" },
+        undefined,
+        extraRules,
+      );
+
+      expect(permissionManager.checkPermission).toHaveBeenCalledWith(
+        "bash",
+        { command: "ls" },
+        undefined,
+        extraRules,
+      );
+    });
+  });
+
+  describe("getToolPermission", () => {
+    it("delegates to permissionManager.getToolPermission", () => {
+      const pm = makePermissionManager();
+      vi.mocked(pm.getToolPermission).mockReturnValue("deny");
+      const { resolver } = makeResolver(pm);
+
+      const result = resolver.getToolPermission("write", "my-agent");
+
+      expect(pm.getToolPermission).toHaveBeenCalledWith("write", "my-agent");
+      expect(result).toBe("deny");
+    });
+  });
+
+  describe("getConfigIssues", () => {
+    it("delegates to permissionManager.getConfigIssues", () => {
+      const pm = makePermissionManager();
+      vi.mocked(pm.getConfigIssues).mockReturnValue(["issue-1"]);
+      const { resolver } = makeResolver(pm);
+
+      const result = resolver.getConfigIssues("agent-1");
+
+      expect(pm.getConfigIssues).toHaveBeenCalledWith("agent-1");
+      expect(result).toEqual(["issue-1"]);
+    });
+  });
+
+  describe("getPolicyCacheStamp", () => {
+    it("delegates to permissionManager.getPolicyCacheStamp", () => {
+      const pm = makePermissionManager();
+      vi.mocked(pm.getPolicyCacheStamp).mockReturnValue("stamp-abc");
+      const { resolver } = makeResolver(pm);
+
+      const result = resolver.getPolicyCacheStamp("agent-1");
+
+      expect(pm.getPolicyCacheStamp).toHaveBeenCalledWith("agent-1");
+      expect(result).toBe("stamp-abc");
+    });
+  });
+});

package/test/permission-session.test.ts

@@ -240,74 +240,6 @@ describe("PermissionSession", () => {
     });
   });
 
-  describe("resolve", () => {
-    it("forwards surface, input, and agentName, applying the empty session ruleset", () => {
-      const pm = makePermissionManager();
-      const { session } = createSession({ permissionManager: pm });
-
-      session.resolve("bash", { command: "ls" }, "agent-x");
-
-      expect(pm.checkPermission).toHaveBeenCalledWith(
-        "bash",
-        { command: "ls" },
-        "agent-x",
-        [],
-      );
-    });
-
-    it("defaults agentName to undefined when omitted", () => {
-      const pm = makePermissionManager();
-      const { session } = createSession({ permissionManager: pm });
-
-      session.resolve("read", { path: ".env" });
-
-      expect(pm.checkPermission).toHaveBeenCalledWith(
-        "read",
-        { path: ".env" },
-        undefined,
-        [],
-      );
-    });
-
-    it("applies a recorded session approval on the next resolve", () => {
-      const pm = makePermissionManager();
-      const { session } = createSession({ permissionManager: pm });
-
-      session.recordSessionApproval(SessionApproval.single("bash", "git *"));
-      session.resolve("bash", { command: "git status" });
-
-      const sessionRules = vi.mocked(pm.checkPermission).mock.calls[0][3];
-      expect(sessionRules).toHaveLength(1);
-      expect(sessionRules?.[0]).toMatchObject({
-        surface: "bash",
-        pattern: "git *",
-        action: "allow",
-      });
-    });
-
-    it("returns the PermissionManager's check result", () => {
-      const pm = makePermissionManager();
-      vi.mocked(pm.checkPermission).mockReturnValue({
-        state: "deny",
-        toolName: "bash",
-        source: "bash",
-        origin: "global",
-        matchedPattern: "rm *",
-      });
-      const { session } = createSession({ permissionManager: pm });
-
-      const result = session.resolve("bash", { command: "rm -rf /" });
-
-      expect(result).toEqual({
-        state: "deny",
-        toolName: "bash",
-        source: "bash",
-        origin: "global",
-        matchedPattern: "rm *",
-      });
-    });
-  });
-
   describe("activate and deactivate", () => {
     it("stores the context on activate", () => {
       const { session, forwarding } = createSession();