@gotgenes/pi-permission-system 5.6.3 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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)
+
+
+### Features
+
+* extract ExtensionPaths value object ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([85bc347](https://github.com/gotgenes/pi-permission-system/commit/85bc347d3ed487210ffbed4c1c53616b5cf0d978))
+
+
+### Documentation
+
+* add handler decomposition plan ([#126](https://github.com/gotgenes/pi-permission-system/issues/126), [#127](https://github.com/gotgenes/pi-permission-system/issues/127), [#128](https://github.com/gotgenes/pi-permission-system/issues/128), [#129](https://github.com/gotgenes/pi-permission-system/issues/129), [#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([5a116a6](https://github.com/gotgenes/pi-permission-system/commit/5a116a6cf2f6ef29f5e6550821bb26b6e1c3a90f))
+* add structural design heuristics, design-review skill, and plan-issue hook ([d8e3233](https://github.com/gotgenes/pi-permission-system/commit/d8e32330baa25fa5a5abaf75f8e442ce650fe5a9))
+* extract code-style, testing, and markdown-conventions skills from AGENTS.md ([9d5ba7a](https://github.com/gotgenes/pi-permission-system/commit/9d5ba7a4a4a7a9e9fbdfe869fb42840238351b81))
+* plan ExtensionPaths value object extraction ([#126](https://github.com/gotgenes/pi-permission-system/issues/126)) ([d76e6cc](https://github.com/gotgenes/pi-permission-system/commit/d76e6cc255dc124a7a914e8d178113e5b7c8bddd))
+* rename target-architecture to architecture, strip progress indicators ([9776550](https://github.com/gotgenes/pi-permission-system/commit/9776550351f3b59f96bdad614cc5129a7be52a51))
+* **retro:** add retro notes for issue [#110](https://github.com/gotgenes/pi-permission-system/issues/110) ([5597de3](https://github.com/gotgenes/pi-permission-system/commit/5597de3c9c64c3d672a1fc77ba7910e952545824))
+
 ## [5.6.3](https://github.com/gotgenes/pi-permission-system/compare/v5.6.2...v5.6.3) (2026-05-07)
 
 

package/package.json

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

package/src/extension-paths.ts

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import { getGlobalLogsDir } from "./config-paths";
+import { discoverGlobalNodeModulesRoot } from "./node-modules-discovery";
+
+/**
+ * Immutable path constants derived from `agentDir` at construction time.
+ *
+ * Computed once at startup in `computeExtensionPaths()` and embedded into
+ * `ExtensionRuntime`. Later refactorings (#129 PermissionSession, #130
+ * handler classes) consume this as a single dep instead of individual fields.
+ */
+export interface ExtensionPaths {
+  readonly agentDir: string;
+  readonly sessionsDir: string;
+  readonly subagentSessionsDir: string;
+  readonly forwardingDir: string;
+  readonly globalLogsDir: string;
+  /**
+   * Static Pi infrastructure directories used for external-directory
+   * read auto-allow. Computed once from `agentDir` and
+   * `discoverGlobalNodeModulesRoot()`. Config-based extras
+   * (`piInfrastructureReadPaths`) are read from `runtime.config` at
+   * call time in the handler so they pick up config reloads.
+   */
+  readonly piInfrastructureDirs: readonly string[];
+}
+
+/**
+ * Compute all immutable path constants from `agentDir`.
+ *
+ * Calls `discoverGlobalNodeModulesRoot()` internally so the result is
+ * self-contained. Call this once at extension startup, not at module scope.
+ */
+export function computeExtensionPaths(agentDir: string): ExtensionPaths {
+  const sessionsDir = join(agentDir, "sessions");
+  const subagentSessionsDir = join(agentDir, "subagent-sessions");
+  const forwardingDir = join(sessionsDir, "permission-forwarding");
+  const globalLogsDir = getGlobalLogsDir(agentDir);
+
+  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
+  const piInfrastructureDirs: string[] = [
+    agentDir,
+    join(agentDir, "git"),
+    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
+  ];
+
+  return {
+    agentDir,
+    sessionsDir,
+    subagentSessionsDir,
+    forwardingDir,
+    globalLogsDir,
+    piInfrastructureDirs,
+  };
+}

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

@@ -1,14 +1,14 @@
 import { getNonEmptyString, toRecord } from "../../common";
-import {
-  extractExternalPathsFromBashCommand,
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-} from "../../external-directory";
 import type { Rule } from "../../rule";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { PermissionCheckResult } from "../../types";
+import { extractExternalPathsFromBashCommand } from "./bash-path-extractor";
 import type { GateResult } from "./descriptor";
+import {
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /** Function type for checkPermission used by the descriptor factory. */

package/src/{bash-path-extractor.ts → handlers/gates/bash-path-extractor.ts}

@@ -4,7 +4,7 @@ import { basename } from "node:path";
 import {
   isPathOutsideWorkingDirectory,
   normalizePathForComparison,
-} from "./path-utils";
+} from "../../path-utils";
 
 // ── tree-sitter-bash lazy parser ───────────────────────────────────────────
 

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

@@ -1,14 +1,16 @@
 import {
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryUserDeniedReason,
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPiInfrastructureRead,
-} from "../../external-directory";
-import { normalizePathForComparison } from "../../path-utils";
+  normalizePathForComparison,
+} from "../../path-utils";
 import { deriveApprovalPattern } from "../../session-rules";
 import type { GateResult } from "./descriptor";
+import {
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryUserDeniedReason,
+} from "./external-directory-messages";
 import type { ToolCallContext } from "./types";
 
 /**

package/src/handlers/gates/tool.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "../../external-directory";
+import { PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
 import {
   formatAskPrompt,

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,12 +38,11 @@ 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: string[];
+  readonly piInfrastructureDirs: readonly string[];
   /** Returns config-derived infrastructure read paths (current at call time). */
   getPiInfrastructureReadPaths(): 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/runtime.ts

@@ -11,6 +11,7 @@ import {
   type ExtensionContext,
   getAgentDir,
 } from "@mariozechner/pi-coding-agent";
+
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
@@ -19,7 +20,6 @@ import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
 import {
   DEBUG_LOG_FILENAME,
   getGlobalConfigPath,
-  getGlobalLogsDir,
   getLegacyExtensionConfigPath,
   getLegacyGlobalPolicyPath,
   getLegacyProjectPolicyPath,
@@ -34,7 +34,10 @@ import {
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
-import { discoverGlobalNodeModulesRoot } from "./external-directory";
+import { computeExtensionPaths, type ExtensionPaths } from "./extension-paths";
+
+export type { ExtensionPaths } from "./extension-paths";
+
 import {
   type PermissionForwardingDeps,
   processForwardedPermissionRequests,
@@ -73,22 +76,7 @@ export interface SessionState {
  * Tests construct this via `createExtensionRuntime({ agentDir: tmpDir })`
  * without timing issues around `PI_CODING_AGENT_DIR`.
  */
-export interface ExtensionRuntime extends SessionState {
-  // ── Immutable paths (derived from agentDir at construction) ───────────
-  readonly agentDir: string;
-  readonly sessionsDir: string;
-  readonly subagentSessionsDir: string;
-  readonly forwardingDir: string;
-  readonly globalLogsDir: string;
-  /**
-   * Static Pi infrastructure directories used for external-directory
-   * read auto-allow. Computed once at construction from `agentDir` and
-   * `discoverGlobalNodeModulesRoot()`. Config-based extras
-   * (`piInfrastructureReadPaths`) are read from `runtime.config` at
-   * call time in the handler so they pick up config reloads.
-   */
-  readonly piInfrastructureDirs: string[];
-
+export interface ExtensionRuntime extends ExtensionPaths, SessionState {
   // ── Mutable state (beyond SessionState) ───────────────────────────────────
   config: PermissionSystemExtensionConfig;
   lastConfigWarning: string | null;
@@ -353,27 +341,12 @@ export function createExtensionRuntime(options?: {
   agentDir?: string;
 }): ExtensionRuntime {
   const agentDir = options?.agentDir ?? getAgentDir();
-  const sessionsDir = join(agentDir, "sessions");
-  const subagentSessionsDir = join(agentDir, "subagent-sessions");
-  const forwardingDir = join(sessionsDir, "permission-forwarding");
-  const globalLogsDir = getGlobalLogsDir(agentDir);
-
-  const globalNodeModulesRoot = discoverGlobalNodeModulesRoot();
-  const piInfrastructureDirs: string[] = [
-    agentDir,
-    join(agentDir, "git"),
-    ...(globalNodeModulesRoot ? [globalNodeModulesRoot] : []),
-  ];
+  const paths = computeExtensionPaths(agentDir);
 
   // Build a plain-object runtime first so the logger's `getConfig` closure
   // can reference `runtime.config` directly (always reads current value).
   const runtime: ExtensionRuntime = {
-    agentDir,
-    sessionsDir,
-    subagentSessionsDir,
-    forwardingDir,
-    globalLogsDir,
-    piInfrastructureDirs,
+    ...paths,
     config: { ...DEFAULT_EXTENSION_CONFIG },
     runtimeContext: null,
     permissionManager: createPermissionManagerForCwd(agentDir, undefined),
@@ -395,10 +368,10 @@ export function createExtensionRuntime(options?: {
   const logger = createPermissionSystemLogger({
     // Reads runtime.config at call time — always current.
     getConfig: () => runtime.config,
-    debugLogPath: join(globalLogsDir, DEBUG_LOG_FILENAME),
-    reviewLogPath: join(globalLogsDir, REVIEW_LOG_FILENAME),
+    debugLogPath: join(paths.globalLogsDir, DEBUG_LOG_FILENAME),
+    reviewLogPath: join(paths.globalLogsDir, REVIEW_LOG_FILENAME),
     ensureLogsDirectory: () =>
-      ensurePermissionSystemLogsDirectory(globalLogsDir),
+      ensurePermissionSystemLogsDirectory(paths.globalLogsDir),
   });
 
   const reportLoggingWarning = (message: string): void => {

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/bash-external-directory.test.ts

@@ -9,11 +9,11 @@ vi.mock("node:os", () => {
   };
 });
 
+import { extractExternalPathsFromBashCommand } from "../src/handlers/gates/bash-path-extractor";
 import {
-  extractExternalPathsFromBashCommand,
   formatBashExternalDirectoryAskPrompt,
   formatBashExternalDirectoryDenyReason,
-} from "../src/external-directory";
+} from "../src/handlers/gates/external-directory-messages";
 
 afterEach(() => {
   vi.restoreAllMocks();

package/tests/extension-paths.test.ts

@@ -0,0 +1,89 @@
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockDiscoverGlobalNodeModulesRoot } = vi.hoisted(() => ({
+  mockDiscoverGlobalNodeModulesRoot: vi.fn<() => string | null>(),
+}));
+
+vi.mock("../src/node-modules-discovery", () => ({
+  discoverGlobalNodeModulesRoot: mockDiscoverGlobalNodeModulesRoot,
+}));
+
+import { getGlobalLogsDir } from "../src/config-paths";
+import { computeExtensionPaths } from "../src/extension-paths";
+
+describe("computeExtensionPaths", () => {
+  beforeEach(() => {
+    mockDiscoverGlobalNodeModulesRoot.mockReset();
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(
+      "/mock/global/node_modules",
+    );
+  });
+
+  it("sets agentDir from argument", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.agentDir).toBe("/test/agent");
+  });
+
+  it("derives sessionsDir as agentDir/sessions", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.sessionsDir).toBe("/test/agent/sessions");
+  });
+
+  it("derives subagentSessionsDir as agentDir/subagent-sessions", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.subagentSessionsDir).toBe("/test/agent/subagent-sessions");
+  });
+
+  it("derives forwardingDir as sessionsDir/permission-forwarding", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.forwardingDir).toBe(
+      join("/test/agent/sessions", "permission-forwarding"),
+    );
+  });
+
+  it("derives globalLogsDir via getGlobalLogsDir(agentDir)", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.globalLogsDir).toBe(getGlobalLogsDir("/test/agent"));
+  });
+
+  it("includes agentDir in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent");
+  });
+
+  it("includes agentDir/git in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
+  it("includes discovered global node_modules root in piInfrastructureDirs", () => {
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/mock/global/node_modules");
+  });
+
+  it("omits global node_modules from piInfrastructureDirs when discovery returns null", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const paths = computeExtensionPaths("/test/agent");
+    expect(paths.piInfrastructureDirs).toHaveLength(2);
+    expect(paths.piInfrastructureDirs).toContain("/test/agent");
+    expect(paths.piInfrastructureDirs).toContain("/test/agent/git");
+  });
+
+  it("all entries in piInfrastructureDirs are strings (no null)", () => {
+    mockDiscoverGlobalNodeModulesRoot.mockReturnValue(null);
+    const paths = computeExtensionPaths("/test/agent");
+    for (const dir of paths.piInfrastructureDirs) {
+      expect(typeof dir).toBe("string");
+    }
+  });
+
+  it("two calls with different agentDirs produce independent results", () => {
+    const a = computeExtensionPaths("/agent/a");
+    const b = computeExtensionPaths("/agent/b");
+    expect(a.agentDir).toBe("/agent/a");
+    expect(b.agentDir).toBe("/agent/b");
+    expect(a.sessionsDir).toBe("/agent/a/sessions");
+    expect(b.sessionsDir).toBe("/agent/b/sessions");
+  });
+});

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/{external-directory-messages.test.ts → handlers/gates/external-directory-messages.test.ts}

@@ -7,7 +7,7 @@ import {
   formatExternalDirectoryDenyReason,
   formatExternalDirectoryHardStopHint,
   formatExternalDirectoryUserDeniedReason,
-} from "../src/external-directory-messages";
+} from "../../../src/handlers/gates/external-directory-messages";
 
 describe("formatExternalDirectoryHardStopHint", () => {
   test("returns the hard stop instruction string", () => {

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/pi-infrastructure-read.test.ts

@@ -14,10 +14,8 @@ vi.mock("node:child_process", () => ({
   default: { spawnSync: mockSpawnSync },
 }));
 
-import {
-  discoverGlobalNodeModulesRoot,
-  isPiInfrastructureRead,
-} from "../src/external-directory";
+import { discoverGlobalNodeModulesRoot } from "../src/node-modules-discovery";
+import { isPiInfrastructureRead } from "../src/path-utils";
 
 // ── discoverGlobalNodeModulesRoot ──────────────────────────────────────────
 

package/tests/runtime.test.ts

@@ -67,7 +67,7 @@ vi.mock("../src/subagent-context", () => ({
   isSubagentExecutionContext: vi.fn().mockReturnValue(false),
 }));
 
-vi.mock("../src/external-directory", () => ({
+vi.mock("../src/node-modules-discovery", () => ({
   discoverGlobalNodeModulesRoot: mockDiscoverGlobalNodeModulesRoot,
 }));
 

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");
+    });
+  });
+});

package/src/external-directory.ts

@@ -1,24 +0,0 @@
-export {
-  extractExternalPathsFromBashCommand,
-  resetParserForTesting,
-} from "./bash-path-extractor";
-export {
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-  formatExternalDirectoryUserDeniedReason,
-} from "./external-directory-messages";
-export { discoverGlobalNodeModulesRoot } from "./node-modules-discovery";
-export {
-  getPathBearingToolPath,
-  isPathOutsideWorkingDirectory,
-  isPathWithinDirectory,
-  isPiInfrastructureRead,
-  isSafeSystemPath,
-  normalizePathForComparison,
-  PATH_BEARING_TOOLS,
-  READ_ONLY_PATH_BEARING_TOOLS,
-  SAFE_SYSTEM_PATHS,
-} from "./path-utils";