@gotgenes/pi-permission-system 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [5.8.0](https://github.com/gotgenes/pi-permission-system/compare/v5.7.0...v5.8.0) (2026-05-08)
+
+
+### Features
+
+* add SessionLogger interface and createSessionLogger factory ([#127](https://github.com/gotgenes/pi-permission-system/issues/127)) ([8765ab8](https://github.com/gotgenes/pi-permission-system/commit/8765ab8cfe461324fc2a89c80486d3dde190d9d9))
+
+
+### Documentation
+
+* plan SessionLogger extraction ([#127](https://github.com/gotgenes/pi-permission-system/issues/127)) ([b13ac62](https://github.com/gotgenes/pi-permission-system/commit/b13ac62513d4b233ee4fc3f554324a54518f75ba))
+* **retro:** add retro notes for issue [#126](https://github.com/gotgenes/pi-permission-system/issues/126) ([3d8a38a](https://github.com/gotgenes/pi-permission-system/commit/3d8a38a09f9dfd2570178c856aec260ebdba89b1))
+* update architecture doc for SessionLogger ([#127](https://github.com/gotgenes/pi-permission-system/issues/127)) ([8fa4123](https://github.com/gotgenes/pi-permission-system/commit/8fa41237dc1b43cbe4487ba7d0acf75dc768ad9c))
+
 ## [5.7.0](https://github.com/gotgenes/pi-permission-system/compare/v5.6.3...v5.7.0) (2026-05-08)
 
 

package/package.json

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

package/src/handlers/input.ts

@@ -82,7 +82,7 @@ export async function handleInput(
       skillInputAutoApproved = decision.autoApproved === true;
       return decision;
     },
-    writeLog: deps.writeReviewLog,
+    writeLog: deps.logger.review,
     logContext: {
       source: "skill_input",
       skillName,

package/src/handlers/lifecycle.ts

@@ -33,11 +33,11 @@ export async function handleSessionStart(
   const policyIssues =
     deps.session.permissionManager.getConfigIssues(agentName);
   for (const issue of policyIssues) {
-    deps.notifyWarning(issue);
+    deps.logger.warn(issue);
   }
 
   if (event.reason === "reload") {
-    deps.writeDebugLog("lifecycle.reload", {
+    deps.logger.debug("lifecycle.reload", {
       triggeredBy: "session_start",
       reason: event.reason,
       cwd: ctx.cwd,
@@ -60,7 +60,7 @@ export async function handleResourcesDiscover(
   deps.session.activeSkillEntries = [];
   deps.session.lastActiveToolsCacheKey = null;
   deps.session.lastPromptStateCacheKey = null;
-  deps.writeDebugLog("lifecycle.reload", {
+  deps.logger.debug("lifecycle.reload", {
     triggeredBy: "resources_discover",
     reason: event.reason,
     cwd: runtimeContext?.cwd ?? null,

package/src/handlers/tool-call.ts

@@ -91,7 +91,7 @@ export async function handleToolCall(
     deps.promptPermission(ctx, details);
   const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
     emitDecisionEvent(deps.events, e);
-  const { writeReviewLog } = deps;
+  const { review: writeReviewLog } = deps.logger;
   const checkPermission: GateRunnerDeps["checkPermission"] = (
     surface,
     input,

package/src/handlers/types.ts

@@ -4,6 +4,7 @@ import type { PermissionPromptDecision } from "../permission-dialog";
 import type { PermissionEventBus } from "../permission-events";
 import type { PermissionManager } from "../permission-manager";
 import type { SessionState } from "../runtime";
+import type { SessionLogger } from "../session-logger";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
@@ -37,9 +38,8 @@ export interface HandlerDeps {
   /** Mutable session state: permissionManager, sessionRules, cache keys. */
   readonly session: SessionState;
 
-  // ── Logging (promoted from runtime) ───────────────────────────────────
-  writeDebugLog(event: string, details?: Record<string, unknown>): void;
-  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+  // ── Logging ────────────────────────────────────────────────────────────
+  readonly logger: SessionLogger;
 
   // ── Immutable infrastructure paths ───────────────────────────────────
   readonly piInfrastructureDirs: readonly string[];
@@ -59,8 +59,6 @@ export interface HandlerDeps {
   // ── Config & lifecycle helpers ─────────────────────────────────────────
   /** Reload merged config from disk; optionally update the stored runtime context. */
   refreshExtensionConfig(ctx?: ExtensionContext): void;
-  /** Show a warning notification to the user (no-op when no UI is available). */
-  notifyWarning(message: string): void;
   /** Write the resolved config path set to the review and debug logs. */
   logResolvedConfigPaths(): void;
 

package/src/index.ts

@@ -25,6 +25,7 @@ import {
   startForwardedPermissionPolling,
   stopForwardedPermissionPolling,
 } from "./runtime";
+import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import {
   canResolveAskPermissionRequest,
@@ -79,8 +80,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const deps: HandlerDeps = {
     session: runtime,
-    writeDebugLog: (event, details) => runtime.writeDebugLog(event, details),
-    writeReviewLog: (event, details) => runtime.writeReviewLog(event, details),
+    logger: createSessionLogger(runtime),
     piInfrastructureDirs: runtime.piInfrastructureDirs,
     getPiInfrastructureReadPaths: () =>
       runtime.config.piInfrastructureReadPaths ?? [],
@@ -88,8 +88,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     createPermissionManagerForCwd: (cwd) =>
       createPermissionManagerForCwd(runtime.agentDir, cwd),
     refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
-    notifyWarning: (message) =>
-      runtime.runtimeContext?.ui.notify(message, "warning"),
     logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
     resolveAgentName: (ctx, systemPrompt) =>
       resolveAgentName(runtime, ctx, systemPrompt),

package/src/session-logger.ts

@@ -0,0 +1,29 @@
+import type { ExtensionRuntime } from "./runtime";
+
+/**
+ * Unified logging + notification surface for handler deps.
+ *
+ * Replaces three separate HandlerDeps fields (`writeDebugLog`,
+ * `writeReviewLog`, `notifyWarning`) with a single typed collaborator.
+ * This is an intermediate abstraction on the path to PermissionSession (#129).
+ */
+export interface SessionLogger {
+  debug(event: string, details?: Record<string, unknown>): void;
+  review(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/**
+ * Create a SessionLogger backed by an ExtensionRuntime.
+ *
+ * Captures `runtime` by reference so `warn` always reads the current
+ * `runtimeContext` at call time — matching the behavior of the inline
+ * closures it replaces in `src/index.ts`.
+ */
+export function createSessionLogger(runtime: ExtensionRuntime): SessionLogger {
+  return {
+    debug: (event, details) => runtime.writeDebugLog(event, details),
+    review: (event, details) => runtime.writeReviewLog(event, details),
+    warn: (message) => runtime.runtimeContext?.ui.notify(message, "warning"),
+  };
+}

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

@@ -77,13 +77,11 @@ function makeSession(overrides: Partial<SessionState> = {}): SessionState {
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
     session: makeSession(),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     createPermissionManagerForCwd: vi.fn().mockReturnValue(makePm()),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(false),

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

@@ -68,14 +68,12 @@ function makeDeps(
 ): HandlerDeps {
   return {
     session: makeSession(state),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     events: makeEvents(),
     createPermissionManagerForCwd: vi.fn(),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),

package/tests/handlers/input.test.ts

@@ -56,13 +56,11 @@ function makeSession(overrides: Partial<SessionState> = {}): SessionState {
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
     session: makeSession(),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     createPermissionManagerForCwd: vi.fn(),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),

package/tests/handlers/lifecycle.test.ts

@@ -83,15 +83,13 @@ function makeSession(overrides: Partial<SessionState> = {}): SessionState {
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
     session: makeSession(),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     createPermissionManagerForCwd: vi
       .fn()
       .mockReturnValue(makePermissionManager()),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(false),
@@ -189,21 +187,21 @@ describe("handleSessionStart", () => {
       createPermissionManagerForCwd: vi.fn().mockReturnValue(pm),
     });
     await handleSessionStart(deps, { reason: "startup" }, makeCtx());
-    expect(deps.notifyWarning).toHaveBeenCalledWith("issue A");
-    expect(deps.notifyWarning).toHaveBeenCalledWith("issue B");
+    expect(deps.logger.warn).toHaveBeenCalledWith("issue A");
+    expect(deps.logger.warn).toHaveBeenCalledWith("issue B");
   });
 
   it("does not call notifyWarning when there are no policy issues", async () => {
     const deps = makeDeps();
     await handleSessionStart(deps, { reason: "startup" }, makeCtx());
-    expect(deps.notifyWarning).not.toHaveBeenCalled();
+    expect(deps.logger.warn).not.toHaveBeenCalled();
   });
 
   it("writes lifecycle.reload debug log when reason is reload", async () => {
     const ctx = makeCtx({ cwd: "/proj" });
     const deps = makeDeps();
     await handleSessionStart(deps, { reason: "reload" }, ctx);
-    expect(deps.writeDebugLog).toHaveBeenCalledWith("lifecycle.reload", {
+    expect(deps.logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
       triggeredBy: "session_start",
       reason: "reload",
       cwd: "/proj",
@@ -213,7 +211,7 @@ describe("handleSessionStart", () => {
   it("does not write lifecycle.reload debug log for non-reload reasons", async () => {
     const deps = makeDeps();
     await handleSessionStart(deps, { reason: "startup" }, makeCtx());
-    expect(deps.writeDebugLog).not.toHaveBeenCalled();
+    expect(deps.logger.debug).not.toHaveBeenCalled();
   });
 });
 
@@ -224,7 +222,7 @@ describe("handleResourcesDiscover", () => {
     const deps = makeDeps();
     await handleResourcesDiscover(deps, { reason: "startup" });
     expect(deps.createPermissionManagerForCwd).not.toHaveBeenCalled();
-    expect(deps.writeDebugLog).not.toHaveBeenCalled();
+    expect(deps.logger.debug).not.toHaveBeenCalled();
   });
 
   it("creates and stores a new PM using runtimeContext.cwd on reload", async () => {
@@ -259,7 +257,7 @@ describe("handleResourcesDiscover", () => {
     const ctx = makeCtx({ cwd: "/proj" });
     const deps = makeDeps({ session: makeSession({ runtimeContext: ctx }) });
     await handleResourcesDiscover(deps, { reason: "reload" });
-    expect(deps.writeDebugLog).toHaveBeenCalledWith("lifecycle.reload", {
+    expect(deps.logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: "reload",
       cwd: "/proj",
@@ -269,7 +267,7 @@ describe("handleResourcesDiscover", () => {
   it("logs cwd as null when runtimeContext is null on reload", async () => {
     const deps = makeDeps();
     await handleResourcesDiscover(deps, { reason: "reload" });
-    expect(deps.writeDebugLog).toHaveBeenCalledWith("lifecycle.reload", {
+    expect(deps.logger.debug).toHaveBeenCalledWith("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: "reload",
       cwd: null,

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

@@ -89,14 +89,12 @@ function makeSession(overrides: Partial<SessionState> = {}): SessionState {
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
     session: makeSession(),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     events: makeEvents(),
     createPermissionManagerForCwd: vi.fn(),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),

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

@@ -77,13 +77,11 @@ function makeSession(overrides: Partial<SessionState> = {}): SessionState {
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
     session: makeSession(),
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    logger: { debug: vi.fn(), review: vi.fn(), warn: vi.fn() },
     piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
     getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     createPermissionManagerForCwd: vi.fn(),
     refreshExtensionConfig: vi.fn(),
-    notifyWarning: vi.fn(),
     logResolvedConfigPaths: vi.fn(),
     resolveAgentName: vi.fn().mockReturnValue(null),
     canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),

package/tests/session-logger.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ExtensionRuntime } from "../src/runtime";
+import { createSessionLogger } from "../src/session-logger";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeRuntime(
+  overrides: Partial<ExtensionRuntime> = {},
+): ExtensionRuntime {
+  return {
+    runtimeContext: null,
+    writeDebugLog: vi.fn(),
+    writeReviewLog: vi.fn(),
+    ...overrides,
+  } as unknown as ExtensionRuntime;
+}
+
+// ── createSessionLogger ────────────────────────────────────────────────────
+
+describe("createSessionLogger", () => {
+  describe("debug", () => {
+    it("delegates to runtime.writeDebugLog with event and details", () => {
+      const runtime = makeRuntime();
+      const logger = createSessionLogger(runtime);
+
+      logger.debug("test.event", { key: "value" });
+
+      expect(runtime.writeDebugLog).toHaveBeenCalledWith("test.event", {
+        key: "value",
+      });
+    });
+
+    it("delegates to runtime.writeDebugLog with event and no details", () => {
+      const runtime = makeRuntime();
+      const logger = createSessionLogger(runtime);
+
+      logger.debug("test.event");
+
+      expect(runtime.writeDebugLog).toHaveBeenCalledWith(
+        "test.event",
+        undefined,
+      );
+    });
+  });
+
+  describe("review", () => {
+    it("delegates to runtime.writeReviewLog with event and details", () => {
+      const runtime = makeRuntime();
+      const logger = createSessionLogger(runtime);
+
+      logger.review("permission.granted", { agentName: "coder" });
+
+      expect(runtime.writeReviewLog).toHaveBeenCalledWith(
+        "permission.granted",
+        { agentName: "coder" },
+      );
+    });
+
+    it("delegates to runtime.writeReviewLog with event and no details", () => {
+      const runtime = makeRuntime();
+      const logger = createSessionLogger(runtime);
+
+      logger.review("permission.granted");
+
+      expect(runtime.writeReviewLog).toHaveBeenCalledWith(
+        "permission.granted",
+        undefined,
+      );
+    });
+  });
+
+  describe("warn", () => {
+    it("calls ui.notify with the message and 'warning' severity when runtimeContext is present", () => {
+      const notify = vi.fn();
+      const runtime = makeRuntime({
+        runtimeContext: {
+          ui: { notify, setStatus: vi.fn(), select: vi.fn(), input: vi.fn() },
+        } as unknown as ExtensionRuntime["runtimeContext"],
+      });
+      const logger = createSessionLogger(runtime);
+
+      logger.warn("Something went wrong");
+
+      expect(notify).toHaveBeenCalledWith("Something went wrong", "warning");
+    });
+
+    it("does not throw when runtimeContext is null", () => {
+      const runtime = makeRuntime({ runtimeContext: null });
+      const logger = createSessionLogger(runtime);
+
+      expect(() => logger.warn("no-op warning")).not.toThrow();
+    });
+
+    it("reads runtimeContext at call time, not at creation time", () => {
+      const runtime = makeRuntime({ runtimeContext: null });
+      const logger = createSessionLogger(runtime);
+
+      // runtimeContext is null at creation — warn should be a no-op now
+      logger.warn("early warning");
+
+      // Later runtimeContext is set
+      const notify = vi.fn();
+      runtime.runtimeContext = {
+        ui: { notify, setStatus: vi.fn(), select: vi.fn(), input: vi.fn() },
+      } as unknown as ExtensionRuntime["runtimeContext"];
+
+      logger.warn("late warning");
+
+      expect(notify).toHaveBeenCalledOnce();
+      expect(notify).toHaveBeenCalledWith("late warning", "warning");
+    });
+  });
+});