@gotgenes/pi-permission-system 10.5.0 → 10.5.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.5.0...pi-permission-system-v10.5.1) (2026-06-07)
+
+
+### Documentation
+
+* correct SkillPermissionChecker comment after resolver rewire ([#341](https://github.com/gotgenes/pi-packages/issues/341)) ([1528382](https://github.com/gotgenes/pi-packages/commit/15283820a920fead92b348410828332b69f0a0d9))
+
 ## [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)
 
 

package/package.json

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

package/src/handlers/before-agent-start.ts

@@ -2,11 +2,12 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentPrepSession } from "#src/agent-prep-session";
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
 } from "#src/before-agent-start-cache";
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
@@ -35,12 +36,14 @@ export function shouldExposeTool(
  * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
  *
  * Constructor deps:
- * - `session` — encapsulates all mutable session state
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getToolPermission`, `getPolicyCacheStamp`, skill check
  * - `toolRegistry` — Pi tool API subset (getAll + setActive)
  */
 export class AgentPrepHandler {
   constructor(
-    private readonly session: AgentPrepSession,
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
   ) {}
 
@@ -63,7 +66,7 @@ export class AgentPrepHandler {
       }
       if (
         shouldExposeTool(toolName, agentName, (t, a) =>
-          this.session.getToolPermission(t, a),
+          this.resolver.getToolPermission(t, a),
         )
       ) {
         allowedTools.push(toolName);
@@ -79,7 +82,9 @@ export class AgentPrepHandler {
     const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
       agentName,
       cwd: ctx.cwd,
-      permissionStamp: this.session.getPolicyCacheStamp(agentName ?? undefined),
+      permissionStamp: this.resolver.getPolicyCacheStamp(
+        agentName ?? undefined,
+      ),
       systemPrompt: event.systemPrompt,
       allowedToolNames: allowedTools,
     });
@@ -96,7 +101,7 @@ export class AgentPrepHandler {
     );
     const skillPromptResult = resolveSkillPromptEntries(
       toolPromptResult.prompt,
-      this.session,
+      this.resolver,
       agentName,
       ctx.cwd,
     );

package/src/handlers/lifecycle.ts

@@ -1,7 +1,8 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { PermissionSession } from "#src/permission-session";
 import type { ServiceLifecycle } from "#src/service-lifecycle";
-import type { SessionLifecycleSession } from "#src/session-lifecycle-session";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/status";
 
 /** Minimal subset of SessionStartEvent used by this handler. */
@@ -18,14 +19,16 @@ interface ResourcesDiscoverPayload {
  * Handles session lifecycle events: start, reload, and shutdown.
  *
  * Constructor deps:
- * - `session` — encapsulates all mutable session state
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getConfigIssues`
  * - `serviceLifecycle` — owns the process-global service publication;
  *   `activate` publishes (skipped for registered subagent children) and emits
  *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
  */
 export class SessionLifecycleHandler {
   constructor(
-    private readonly session: SessionLifecycleSession,
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
     private readonly serviceLifecycle: ServiceLifecycle,
   ) {}
 
@@ -38,7 +41,7 @@ export class SessionLifecycleHandler {
     this.session.logResolvedConfigPaths();
 
     const agentName = this.session.resolveAgentName(ctx);
-    const policyIssues = this.session.getConfigIssues(agentName ?? undefined);
+    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
     for (const issue of policyIssues) {
       this.session.logger.warn(issue);
     }

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

@@ -4,11 +4,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import { toRecord } from "#src/common";
-import type { GateHandlerSession } from "#src/gate-handler-session";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
 } from "#src/permission-prompts";
+import type { PermissionSession } from "#src/permission-session";
 import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
@@ -31,7 +31,7 @@ interface InputPayload {
  * Handles permission gate events: tool_call and input.
  *
  * Constructor deps:
- * - `session` — narrow two-method context role: bind per-event context, resolve agent name
+ * - `session` — state/lifecycle owner: bind per-event context, resolve agent name
  * - `toolRegistry` — Pi tool API subset (getAll + setActive)
  * - `pipeline` — owns tool-call gate-producer assembly and the run loop
  * - `skillInputPipeline` — owns skill-input gate assembly (pre-check, notify, run)
@@ -39,7 +39,7 @@ interface InputPayload {
  */
 export class PermissionGateHandler {
   constructor(
-    private readonly session: GateHandlerSession,
+    private readonly session: PermissionSession,
     private readonly toolRegistry: ToolRegistry,
     private readonly pipeline: ToolCallGatePipeline,
     private readonly skillInputPipeline: SkillInputGatePipeline,

package/src/index.ts

@@ -157,12 +157,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
-  const lifecycle = new SessionLifecycleHandler(session, serviceLifecycle);
-  const agentPrep = new AgentPrepHandler(session, toolRegistry);
   const resolver = new PermissionResolver(permissionManager, sessionRules);
 
+  const lifecycle = new SessionLifecycleHandler(
+    session,
+    resolver,
+    serviceLifecycle,
+  );
+  const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
+
   const reporter = new GateDecisionReporter(session.logger, pi.events);
-  const gateRunner = new GateRunner(resolver, session, gateway, reporter);
+  const gateRunner = new GateRunner(resolver, sessionRules, gateway, reporter);
   const toolCallGatePipeline = new ToolCallGatePipeline(
     resolver,
     session,

package/src/permission-resolver.ts

@@ -67,17 +67,14 @@ export class PermissionResolver implements ScopedPermissionResolver {
     );
   }
 
-  // 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

@@ -4,18 +4,15 @@ import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
-import type { AgentPrepSession } from "./agent-prep-session";
+
 import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
-import type { GateHandlerSession } from "./gate-handler-session";
+import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PromptingGatewayLifecycle } from "./prompting-gateway";
-import type { Rule } from "./rule";
-import type { SessionApproval } from "./session-approval";
-import type { SessionApprovalRecorder } from "./session-approval-recorder";
-import type { SessionLifecycleSession } from "./session-lifecycle-session";
+
 import type { SessionLogger } from "./session-logger";
 import type { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
@@ -23,7 +20,6 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
-import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -40,13 +36,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
  * - `SessionConfigStore` — owns extension config; provides refresh, log, read
  * - `PromptingGatewayLifecycle` — prompting lifecycle forwarded via activate/deactivate
  */
-export class PermissionSession
-  implements
-    SessionApprovalRecorder,
-    GateHandlerSession,
-    AgentPrepSession,
-    SessionLifecycleSession
-{
+export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
@@ -84,44 +74,6 @@ export class PermissionSession
     return this.context;
   }
 
-  // ── Permission checking (delegates to PermissionManager) ───────────────
-
-  checkPermission(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-    sessionRules?: Rule[],
-  ): PermissionCheckResult {
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
-      sessionRules,
-    );
-  }
-
-  getToolPermission(toolName: string, agentName?: string): PermissionState {
-    return this.permissionManager.getToolPermission(toolName, agentName);
-  }
-
-  getConfigIssues(agentName?: string): string[] {
-    return this.permissionManager.getConfigIssues(agentName);
-  }
-
-  getPolicyCacheStamp(agentName?: string): string {
-    return this.permissionManager.getPolicyCacheStamp(agentName);
-  }
-
-  // ── Session rules (delegates to SessionRules) ──────────────────────────
-
-  getSessionRuleset(): Rule[] {
-    return this.sessionRules.getRuleset();
-  }
-
-  recordSessionApproval(approval: SessionApproval): void {
-    this.sessionRules.record(approval);
-  }
-
   // ── Session lifecycle ────────────────────────────────────────────────────
 
   /**
@@ -212,6 +164,10 @@ export class PermissionSession
     return this.knownAgentName;
   }
 
+  // Read by config-modal (`controller.session.lastKnownActiveAgentName`).
+  // fallow cannot trace the getter through the command's object-literal
+  // wiring, so it reports a false positive here.
+  // fallow-ignore-next-line unused-class-member
   get lastKnownActiveAgentName(): string | null {
     return this.knownAgentName;
   }

package/src/session-rules.ts

@@ -2,6 +2,7 @@ import { dirname, sep } from "node:path";
 
 import type { Ruleset } from "./rule";
 import type { SessionApproval } from "./session-approval";
+import type { SessionApprovalRecorder } from "./session-approval-recorder";
 
 /**
  * Ephemeral in-memory store of session-scoped permission approvals.
@@ -11,7 +12,7 @@ import type { SessionApproval } from "./session-approval";
  *
  * Cleared on session_shutdown — never persisted to disk.
  */
-export class SessionRules {
+export class SessionRules implements SessionApprovalRecorder {
   private rules: Ruleset = [];
 
   /** Record a wildcard pattern as approved for the given surface. */
@@ -36,7 +37,7 @@ export class SessionRules {
    * 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 {
+  recordSessionApproval(approval: SessionApproval): void {
     for (const pattern of approval.patterns) {
       this.approve(approval.surface, pattern);
     }

package/src/skill-prompt-sanitizer.ts

@@ -8,7 +8,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
  * Narrow interface for the permission checker used by skill prompt resolution.
- * Both `PermissionManager` and `PermissionSession` satisfy this structurally.
+ * Both `PermissionManager` and `PermissionResolver` satisfy this structurally.
  */
 export interface SkillPermissionChecker {
   checkPermission(

package/test/handlers/before-agent-start.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
 
-import type { AgentPrepSession } from "#src/agent-prep-session";
 import {
   AgentPrepHandler,
   shouldExposeTool,
@@ -8,6 +7,10 @@ import {
 import type { ToolRegistry } from "#src/tool-registry";
 
 import { makeCheckResult, makeCtx } from "#test/helpers/handler-fixtures";
+import {
+  makeRealResolver,
+  makeRealSession,
+} from "#test/helpers/session-fixtures";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
 vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {
@@ -25,51 +28,6 @@ function makeEvent(systemPrompt = "You are an assistant.") {
   return { systemPrompt };
 }
 
-function makeSession(
-  overrides: Partial<AgentPrepSession> = {},
-): AgentPrepSession {
-  return {
-    activate: overrides.activate ?? vi.fn<AgentPrepSession["activate"]>(),
-    refreshConfig:
-      overrides.refreshConfig ?? vi.fn<AgentPrepSession["refreshConfig"]>(),
-    resolveAgentName:
-      overrides.resolveAgentName ??
-      vi.fn<AgentPrepSession["resolveAgentName"]>().mockReturnValue(null),
-    checkPermission:
-      overrides.checkPermission ??
-      vi
-        .fn<AgentPrepSession["checkPermission"]>()
-        .mockReturnValue(makeCheckResult()),
-    getToolPermission:
-      overrides.getToolPermission ??
-      vi.fn<AgentPrepSession["getToolPermission"]>().mockReturnValue("allow"),
-    shouldUpdateActiveTools:
-      overrides.shouldUpdateActiveTools ??
-      vi
-        .fn<AgentPrepSession["shouldUpdateActiveTools"]>()
-        .mockReturnValue(true),
-    commitActiveToolsCacheKey:
-      overrides.commitActiveToolsCacheKey ??
-      vi.fn<AgentPrepSession["commitActiveToolsCacheKey"]>(),
-    getPolicyCacheStamp:
-      overrides.getPolicyCacheStamp ??
-      vi
-        .fn<AgentPrepSession["getPolicyCacheStamp"]>()
-        .mockReturnValue("stamp-1"),
-    shouldUpdatePromptState:
-      overrides.shouldUpdatePromptState ??
-      vi
-        .fn<AgentPrepSession["shouldUpdatePromptState"]>()
-        .mockReturnValue(true),
-    commitPromptStateCacheKey:
-      overrides.commitPromptStateCacheKey ??
-      vi.fn<AgentPrepSession["commitPromptStateCacheKey"]>(),
-    setActiveSkillEntries:
-      overrides.setActiveSkillEntries ??
-      vi.fn<AgentPrepSession["setActiveSkillEntries"]>(),
-  };
-}
-
 function makeToolRegistry(overrides: Partial<ToolRegistry> = {}): ToolRegistry {
   return {
     getAll: vi.fn().mockReturnValue([]),
@@ -78,18 +36,33 @@ function makeToolRegistry(overrides: Partial<ToolRegistry> = {}): ToolRegistry {
   };
 }
 
-function makeHandler(overrides?: {
-  session?: Partial<AgentPrepSession>;
+function makeSetup(opts?: {
+  toolPermission?: "allow" | "deny" | "ask";
   toolRegistry?: Partial<ToolRegistry>;
-}): {
-  handler: AgentPrepHandler;
-  session: AgentPrepSession;
-  toolRegistry: ToolRegistry;
-} {
-  const session = makeSession(overrides?.session);
-  const toolRegistry = makeToolRegistry(overrides?.toolRegistry);
-  const handler = new AgentPrepHandler(session, toolRegistry);
-  return { handler, session, toolRegistry };
+}) {
+  const { session, permissionManager, sessionRules, configStore, forwarding } =
+    makeRealSession();
+  const { resolver } = makeRealResolver(permissionManager, sessionRules);
+  if (opts?.toolPermission !== undefined) {
+    vi.mocked(permissionManager.getToolPermission).mockReturnValue(
+      opts.toolPermission,
+    );
+  }
+  // Default checkPermission returns allow (for skill-prompt sanitizer)
+  vi.mocked(permissionManager.checkPermission).mockReturnValue(
+    makeCheckResult(),
+  );
+  const toolRegistry = makeToolRegistry(opts?.toolRegistry);
+  const handler = new AgentPrepHandler(session, resolver, toolRegistry);
+  return {
+    handler,
+    session,
+    resolver,
+    permissionManager,
+    configStore,
+    forwarding,
+    toolRegistry,
+  };
 }
 
 // ── shouldExposeTool (pure helper) ─────────────────────────────────────────
@@ -128,31 +101,30 @@ describe("shouldExposeTool", () => {
 describe("AgentPrepHandler.handle", () => {
   it("activates the session with ctx", async () => {
     const ctx = makeCtx();
-    const { handler, session } = makeHandler();
+    const { handler, forwarding } = makeSetup();
     await handler.handle(makeEvent(), ctx);
-    expect(session.activate).toHaveBeenCalledWith(ctx);
+    // Real session.activate calls forwarding.start
+    expect(forwarding.start).toHaveBeenCalledWith(ctx);
   });
 
   it("refreshes config with ctx", async () => {
     const ctx = makeCtx();
-    const { handler, session } = makeHandler();
+    const { handler, configStore } = makeSetup();
     await handler.handle(makeEvent(), ctx);
-    expect(session.refreshConfig).toHaveBeenCalledWith(ctx);
+    expect(configStore.refresh).toHaveBeenCalledWith(ctx);
   });
 
   it("resolves agent name using systemPrompt", async () => {
     const ctx = makeCtx();
-    const { handler, session } = makeHandler();
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "resolveAgentName");
     await handler.handle(makeEvent("<active_agent name='x'>"), ctx);
-    expect(session.resolveAgentName).toHaveBeenCalledWith(
-      ctx,
-      "<active_agent name='x'>",
-    );
+    expect(spy).toHaveBeenCalledWith(ctx, "<active_agent name='x'>");
   });
 
   it("filters out denied tools from allowed list", async () => {
-    const { handler, toolRegistry } = makeHandler({
-      session: { getToolPermission: vi.fn().mockReturnValue("deny") },
+    const { handler, toolRegistry } = makeSetup({
+      toolPermission: "deny",
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "write" }, { name: "read" }]),
       },
@@ -162,7 +134,7 @@ describe("AgentPrepHandler.handle", () => {
   });
 
   it("includes allowed and ask tools in the active list", async () => {
-    const { handler, toolRegistry } = makeHandler({
+    const { handler, toolRegistry } = makeSetup({
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "write" }]),
       },
@@ -172,60 +144,58 @@ describe("AgentPrepHandler.handle", () => {
   });
 
   it("commits active-tools cache key after applying", async () => {
-    const { handler, session } = makeHandler({
+    const { handler, session } = makeSetup({
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "read" }]),
       },
     });
+    const spy = vi.spyOn(session, "commitActiveToolsCacheKey");
     await handler.handle(makeEvent(), makeCtx());
-    expect(session.commitActiveToolsCacheKey).toHaveBeenCalled();
+    expect(spy).toHaveBeenCalled();
   });
 
   it("skips setActive when cache key is unchanged", async () => {
-    const { handler, session, toolRegistry } = makeHandler({
-      session: { shouldUpdateActiveTools: vi.fn().mockReturnValue(false) },
+    const { handler, session, toolRegistry } = makeSetup({
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "read" }]),
       },
     });
+    vi.spyOn(session, "shouldUpdateActiveTools").mockReturnValue(false);
     await handler.handle(makeEvent(), makeCtx());
     expect(toolRegistry.setActive).not.toHaveBeenCalled();
-    expect(session.commitActiveToolsCacheKey).not.toHaveBeenCalled();
   });
 
   it("returns empty object when prompt cache is unchanged", async () => {
-    const { handler, session } = makeHandler({
-      session: { shouldUpdatePromptState: vi.fn().mockReturnValue(false) },
-    });
+    const { handler, session } = makeSetup();
+    vi.spyOn(session, "shouldUpdatePromptState").mockReturnValue(false);
     const result = await handler.handle(makeEvent(), makeCtx());
     expect(result).toEqual({});
-    expect(session.commitPromptStateCacheKey).not.toHaveBeenCalled();
   });
 
   it("commits prompt-state cache key and processes prompt when cache is new", async () => {
-    const { handler, session } = makeHandler();
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "commitPromptStateCacheKey");
     await handler.handle(makeEvent(), makeCtx());
-    expect(session.commitPromptStateCacheKey).toHaveBeenCalled();
+    expect(spy).toHaveBeenCalled();
   });
 
   it("stores resolved skill entries on the session", async () => {
-    const { handler, session } = makeHandler();
+    const { handler, session } = makeSetup();
+    const spy = vi.spyOn(session, "setActiveSkillEntries");
     await handler.handle(makeEvent(), makeCtx());
-    expect(session.setActiveSkillEntries).toHaveBeenCalledWith(
-      expect.any(Array),
-    );
+    expect(spy).toHaveBeenCalledWith(expect.any(Array));
   });
 
   it("returns modified systemPrompt when prompt changes", async () => {
     const systemPrompt = `You are an assistant.\n\nAvailable tools:\n- read\n- write\n`;
-    const { handler } = makeHandler();
+    const { handler } = makeSetup();
     const result = await handler.handle(makeEvent(systemPrompt), makeCtx());
     expect(result).toHaveProperty("systemPrompt");
   });
 
   it("returns empty object when systemPrompt is unchanged", async () => {
     const prompt = "No tools section here.";
-    const { handler } = makeHandler();
+    const { handler } = makeSetup();
     const result = await handler.handle(makeEvent(prompt), makeCtx());
     expect(result).toEqual({});
   });