@gotgenes/pi-permission-system 5.7.0 → 5.9.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.9.0](https://github.com/gotgenes/pi-permission-system/compare/v5.8.0...v5.9.0) (2026-05-08)
+
+
+### Features
+
+* add ForwardingManager class ([#128](https://github.com/gotgenes/pi-permission-system/issues/128)) ([7790380](https://github.com/gotgenes/pi-permission-system/commit/7790380eb0291f55724425a0bd6bd0b45cf15d91))
+
+
+### Documentation
+
+* plan ForwardingManager extraction ([#128](https://github.com/gotgenes/pi-permission-system/issues/128)) ([2f10450](https://github.com/gotgenes/pi-permission-system/commit/2f10450974adaedd7a43e8a7d986f8f61a0508db))
+* **retro:** add retro notes for issue [#127](https://github.com/gotgenes/pi-permission-system/issues/127) ([2dde534](https://github.com/gotgenes/pi-permission-system/commit/2dde53416c535331972367ca2a44ba302b25d2a0))
+
+## [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.9.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/forwarding-manager.ts

@@ -0,0 +1,76 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
+import { processForwardedPermissionRequests } from "./forwarded-permissions/polling";
+import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import { isSubagentExecutionContext } from "./subagent-context";
+
+/**
+ * Narrow interface for the forwarding lifecycle used by `HandlerDeps`.
+ * `ForwardingManager` satisfies it; tests can provide a plain object mock.
+ */
+export interface ForwardingController {
+  start(ctx: ExtensionContext): void;
+  stop(): void;
+}
+
+/**
+ * Encapsulates the forwarded-permission polling lifecycle.
+ *
+ * Owns the timer, current context, and processing-lock state that previously
+ * lived as 3 mutable fields on `ExtensionRuntime`. Call `start(ctx)` on each
+ * session event that may activate forwarding; call `stop()` on session
+ * shutdown.
+ */
+export class ForwardingManager {
+  private timer: NodeJS.Timeout | null = null;
+  private context: ExtensionContext | null = null;
+  private processing = false;
+
+  constructor(
+    private readonly subagentSessionsDir: string,
+    private readonly forwardingDeps: PermissionForwardingDeps,
+  ) {}
+
+  /**
+   * Start polling if `ctx` has UI and is not a subagent execution context.
+   * No-op (timer stays running) if already polling — updates the stored
+   * context so the next tick uses the latest session.
+   * Stops any existing poll when the context does not qualify for forwarding.
+   */
+  start(ctx: ExtensionContext): void {
+    if (
+      !ctx.hasUI ||
+      isSubagentExecutionContext(ctx, this.subagentSessionsDir)
+    ) {
+      this.stop();
+      return;
+    }
+    this.context = ctx;
+    if (this.timer) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      if (!this.context || this.processing) {
+        return;
+      }
+      this.processing = true;
+      void processForwardedPermissionRequests(
+        this.context,
+        this.forwardingDeps,
+      ).finally(() => {
+        this.processing = false;
+      });
+    }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
+  }
+
+  /** Stop polling and clear all internal state. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.context = null;
+    this.processing = false;
+  }
+}

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

@@ -43,7 +43,7 @@ export async function handleBeforeAgentStart(
 ): Promise<BeforeAgentStartEventResult> {
   deps.session.runtimeContext = ctx;
   deps.refreshExtensionConfig(ctx);
-  deps.startForwardedPermissionPolling(ctx);
+  deps.forwarding.start(ctx);
 
   const agentName = deps.resolveAgentName(ctx, event.systemPrompt);
   const { permissionManager } = deps.session;

package/src/handlers/input.ts

@@ -41,7 +41,7 @@ export async function handleInput(
   ctx: ExtensionContext,
 ): Promise<InputEventResult> {
   deps.session.runtimeContext = ctx;
-  deps.startForwardedPermissionPolling(ctx);
+  deps.forwarding.start(ctx);
 
   const skillName = extractSkillNameFromInput(event.text);
   if (!skillName) {
@@ -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

@@ -26,18 +26,18 @@ export async function handleSessionStart(
   deps.session.lastActiveToolsCacheKey = null;
   deps.session.lastPromptStateCacheKey = null;
   deps.session.lastKnownActiveAgentName = getActiveAgentName(ctx);
-  deps.startForwardedPermissionPolling(ctx);
+  deps.forwarding.start(ctx);
   deps.logResolvedConfigPaths();
 
   const agentName = deps.session.lastKnownActiveAgentName;
   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,
@@ -77,6 +77,6 @@ export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
   deps.session.lastActiveToolsCacheKey = null;
   deps.session.lastPromptStateCacheKey = null;
   deps.session.sessionRules.clear();
-  deps.stopForwardedPermissionPolling();
+  deps.forwarding.stop();
   deps.stopPermissionRpcHandlers();
 }

package/src/handlers/tool-call.ts

@@ -44,7 +44,7 @@ export async function handleToolCall(
   ctx: ExtensionContext,
 ): Promise<{ block?: true; reason?: string }> {
   deps.session.runtimeContext = ctx;
-  deps.startForwardedPermissionPolling(ctx);
+  deps.forwarding.start(ctx);
 
   const agentName = deps.resolveAgentName(ctx);
   const toolName = getToolNameFromValue(event);
@@ -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

@@ -1,9 +1,11 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
+import type { ForwardingController } from "../forwarding-manager";
 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 +39,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 +60,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;
 
@@ -81,8 +80,7 @@ export interface HandlerDeps {
   createPermissionRequestId(prefix: string): string;
 
   // ── Forwarding ─────────────────────────────────────────────────────────
-  startForwardedPermissionPolling(ctx: ExtensionContext): void;
-  stopForwardedPermissionPolling(): void;
+  readonly forwarding: ForwardingController;
   /** Unsubscribe the permissions:rpc:check and permissions:rpc:prompt handlers. */
   stopPermissionRpcHandlers(): void;
 

package/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
 import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
+import { ForwardingManager } from "./forwarding-manager";
 import {
   type HandlerDeps,
   handleBeforeAgentStart,
@@ -22,9 +23,8 @@ import {
   refreshExtensionConfig,
   resolveAgentName,
   saveExtensionConfig,
-  startForwardedPermissionPolling,
-  stopForwardedPermissionPolling,
 } from "./runtime";
+import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import {
   canResolveAskPermissionRequest,
@@ -79,8 +79,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 +87,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),
@@ -104,10 +101,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       }),
     promptPermission: (ctx, details) => prompter.prompt(ctx, details),
     createPermissionRequestId,
-    startForwardedPermissionPolling: (ctx) =>
-      startForwardedPermissionPolling(runtime, forwardingDeps, ctx),
-    stopForwardedPermissionPolling: () =>
-      stopForwardedPermissionPolling(runtime),
+    forwarding: new ForwardingManager(
+      runtime.subagentSessionsDir,
+      forwardingDeps,
+    ),
     stopPermissionRpcHandlers: () => {
       rpcHandles.unsubCheck();
       rpcHandles.unsubPrompt();

package/src/runtime.ts

@@ -38,17 +38,11 @@ import { computeExtensionPaths, type ExtensionPaths } from "./extension-paths";
 
 export type { ExtensionPaths } from "./extension-paths";
 
-import {
-  type PermissionForwardingDeps,
-  processForwardedPermissionRequests,
-} from "./forwarded-permissions/polling";
 import { createPermissionSystemLogger } from "./logging";
-import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
 import { PermissionManager } from "./permission-manager";
 import { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import { syncPermissionSystemStatus } from "./status";
-import { isSubagentExecutionContext } from "./subagent-context";
 
 /**
  * Mutable session state — the subset of ExtensionRuntime that handlers
@@ -81,11 +75,6 @@ export interface ExtensionRuntime extends ExtensionPaths, SessionState {
   config: PermissionSystemExtensionConfig;
   lastConfigWarning: string | null;
 
-  // ── Forwarding polling state ───────────────────────────────────────────
-  permissionForwardingContext: ExtensionContext | null;
-  permissionForwardingTimer: NodeJS.Timeout | null;
-  isProcessingForwardedRequests: boolean;
-
   // ── Logging (backed by logger created at construction) ─────────────────
   writeDebugLog(event: string, details?: Record<string, unknown>): void;
   writeReviewLog(event: string, details?: Record<string, unknown>): void;
@@ -277,58 +266,6 @@ export function logResolvedConfigPaths(runtime: ExtensionRuntime): void {
   );
 }
 
-// ── Forwarding polling lifecycle ───────────────────────────────────────────
-
-/** Stop the forwarded-permission polling interval and clear related state. */
-export function stopForwardedPermissionPolling(
-  runtime: ExtensionRuntime,
-): void {
-  if (runtime.permissionForwardingTimer) {
-    clearInterval(runtime.permissionForwardingTimer);
-    runtime.permissionForwardingTimer = null;
-  }
-  runtime.permissionForwardingContext = null;
-  runtime.isProcessingForwardedRequests = false;
-}
-
-/**
- * Start the forwarded-permission polling interval.
- * No-ops (and stops any existing poll) when the context has no UI or is a
- * subagent execution context.
- */
-export function startForwardedPermissionPolling(
-  runtime: ExtensionRuntime,
-  forwardingDeps: PermissionForwardingDeps,
-  ctx: ExtensionContext,
-): void {
-  if (
-    !ctx.hasUI ||
-    isSubagentExecutionContext(ctx, runtime.subagentSessionsDir)
-  ) {
-    stopForwardedPermissionPolling(runtime);
-    return;
-  }
-  runtime.permissionForwardingContext = ctx;
-  if (runtime.permissionForwardingTimer) {
-    return;
-  }
-  runtime.permissionForwardingTimer = setInterval(() => {
-    if (
-      !runtime.permissionForwardingContext ||
-      runtime.isProcessingForwardedRequests
-    ) {
-      return;
-    }
-    runtime.isProcessingForwardedRequests = true;
-    void processForwardedPermissionRequests(
-      runtime.permissionForwardingContext,
-      forwardingDeps,
-    ).finally(() => {
-      runtime.isProcessingForwardedRequests = false;
-    });
-  }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
-}
-
 // ── Factory ────────────────────────────────────────────────────────────────
 
 /**
@@ -356,9 +293,6 @@ export function createExtensionRuntime(options?: {
     lastPromptStateCacheKey: null,
     lastConfigWarning: null,
     sessionRules: new SessionRules(),
-    permissionForwardingContext: null,
-    permissionForwardingTimer: null,
-    isProcessingForwardedRequests: false,
     // Logging methods are replaced below after the logger is constructed.
     writeDebugLog: () => {},
     writeReviewLog: () => {},

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/forwarding-manager.test.ts

@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ForwardingManager } from "../src/forwarding-manager";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────
+
+const mockProcessForwardedPermissionRequests = vi.hoisted(() => vi.fn());
+const mockIsSubagentExecutionContext = vi.hoisted(() => vi.fn());
+
+vi.mock("../src/forwarded-permissions/polling", () => ({
+  processForwardedPermissionRequests: mockProcessForwardedPermissionRequests,
+}));
+
+vi.mock("../src/subagent-context", () => ({
+  isSubagentExecutionContext: mockIsSubagentExecutionContext,
+}));
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function makeCtx(overrides: { hasUI?: boolean; sessionId?: string } = {}) {
+  return {
+    hasUI: overrides.hasUI ?? true,
+    sessionManager: {
+      getSessionId: vi.fn().mockReturnValue(overrides.sessionId ?? "sess-1"),
+    },
+    cwd: "/project",
+  } as unknown as import("@mariozechner/pi-coding-agent").ExtensionContext;
+}
+
+function makeForwardingDeps() {
+  return {
+    forwardingDir: "/agent/sessions/permission-forwarding",
+    subagentSessionsDir: "/agent/subagent-sessions",
+    logger: { writeReviewLog: vi.fn(), writeDebugLog: vi.fn() },
+    writeReviewLog: vi.fn(),
+    requestPermissionDecisionFromUi: vi.fn(),
+    shouldAutoApprove: vi.fn().mockReturnValue(false),
+  } as unknown as import("../src/forwarded-permissions/polling").PermissionForwardingDeps;
+}
+
+function makeManager() {
+  return new ForwardingManager(
+    "/agent/subagent-sessions",
+    makeForwardingDeps(),
+  );
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe("ForwardingManager", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockIsSubagentExecutionContext.mockReset();
+    mockIsSubagentExecutionContext.mockReturnValue(false);
+    mockProcessForwardedPermissionRequests.mockReset();
+    mockProcessForwardedPermissionRequests.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("stop()", () => {
+    it("is a no-op when not started", () => {
+      const manager = makeManager();
+      expect(() => manager.stop()).not.toThrow();
+    });
+
+    it("clears the timer and processing state after start()", async () => {
+      const manager = makeManager();
+      const ctx = makeCtx();
+      manager.start(ctx);
+      manager.stop();
+
+      // After stop, the timer fires no more callbacks.
+      mockProcessForwardedPermissionRequests.mockClear();
+      await vi.advanceTimersByTimeAsync(500);
+      expect(mockProcessForwardedPermissionRequests).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("start()", () => {
+    it("does not start polling when hasUI is false", async () => {
+      const manager = makeManager();
+      const ctx = makeCtx({ hasUI: false });
+      manager.start(ctx);
+
+      await vi.advanceTimersByTimeAsync(500);
+      expect(mockProcessForwardedPermissionRequests).not.toHaveBeenCalled();
+    });
+
+    it("stops any existing poll and does not start a new one when hasUI is false", async () => {
+      const manager = makeManager();
+      const uiCtx = makeCtx({ hasUI: true });
+      const noUiCtx = makeCtx({ hasUI: false });
+
+      manager.start(uiCtx);
+      // Now stop the polling by calling start() with no-UI ctx.
+      manager.start(noUiCtx);
+
+      mockProcessForwardedPermissionRequests.mockClear();
+      await vi.advanceTimersByTimeAsync(500);
+      expect(mockProcessForwardedPermissionRequests).not.toHaveBeenCalled();
+    });
+
+    it("does not start polling when isSubagentExecutionContext returns true", async () => {
+      mockIsSubagentExecutionContext.mockReturnValue(true);
+      const manager = makeManager();
+      const ctx = makeCtx();
+      manager.start(ctx);
+
+      await vi.advanceTimersByTimeAsync(500);
+      expect(mockProcessForwardedPermissionRequests).not.toHaveBeenCalled();
+    });
+
+    it("stops any existing poll when called with a subagent context", async () => {
+      mockIsSubagentExecutionContext.mockReturnValueOnce(false);
+      const manager = makeManager();
+      const ctx1 = makeCtx();
+      manager.start(ctx1);
+
+      // Second call with a subagent context.
+      mockIsSubagentExecutionContext.mockReturnValue(true);
+      const ctx2 = makeCtx();
+      manager.start(ctx2);
+
+      mockProcessForwardedPermissionRequests.mockClear();
+      await vi.advanceTimersByTimeAsync(500);
+      expect(mockProcessForwardedPermissionRequests).not.toHaveBeenCalled();
+    });
+
+    it("starts polling and calls processForwardedPermissionRequests on tick", async () => {
+      const manager = makeManager();
+      const ctx = makeCtx();
+      manager.start(ctx);
+
+      await vi.advanceTimersByTimeAsync(250);
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledWith(
+        ctx,
+        expect.anything(),
+      );
+    });
+
+    it("is idempotent — calling start() twice does not create a second timer", async () => {
+      const manager = makeManager();
+      const ctx = makeCtx();
+      manager.start(ctx);
+      manager.start(ctx);
+
+      await vi.advanceTimersByTimeAsync(250);
+      // Only one tick should fire per interval, not two.
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledTimes(1);
+    });
+
+    it("updates the context when called again while already running", async () => {
+      const manager = makeManager();
+      const ctx1 = makeCtx({ sessionId: "sess-1" });
+      const ctx2 = makeCtx({ sessionId: "sess-2" });
+      manager.start(ctx1);
+      manager.start(ctx2);
+
+      await vi.advanceTimersByTimeAsync(250);
+      // The process call should use the newer context.
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledWith(
+        ctx2,
+        expect.anything(),
+      );
+    });
+
+    it("skips a tick while processing is in progress", async () => {
+      // Make processForwardedPermissionRequests hang so processing=true persists.
+      let resolveProcess: () => void;
+      mockProcessForwardedPermissionRequests.mockReturnValue(
+        new Promise<void>((resolve) => {
+          resolveProcess = resolve;
+        }),
+      );
+
+      const manager = makeManager();
+      const ctx = makeCtx();
+      manager.start(ctx);
+
+      // First tick starts processing.
+      await vi.advanceTimersByTimeAsync(250);
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledTimes(1);
+
+      // Second tick is skipped because processing flag is still true.
+      await vi.advanceTimersByTimeAsync(250);
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledTimes(1);
+
+      // Resolve and a third tick should fire.
+      resolveProcess!();
+      await vi.advanceTimersByTimeAsync(250);
+      expect(mockProcessForwardedPermissionRequests).toHaveBeenCalledTimes(2);
+    });
+
+    it("passes subagentSessionsDir from the constructor to isSubagentExecutionContext", () => {
+      const manager = new ForwardingManager(
+        "/custom/subagent-dir",
+        makeForwardingDeps(),
+      );
+      const ctx = makeCtx();
+      manager.start(ctx);
+
+      expect(mockIsSubagentExecutionContext).toHaveBeenCalledWith(
+        ctx,
+        "/custom/subagent-dir",
+      );
+    });
+  });
+});

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),
@@ -92,8 +90,7 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("test-id"),
     events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
@@ -146,7 +143,7 @@ describe("handleBeforeAgentStart", () => {
     const ctx = makeCtx();
     const deps = makeDeps();
     await handleBeforeAgentStart(deps, makeEvent(), ctx);
-    expect(deps.startForwardedPermissionPolling).toHaveBeenCalledWith(ctx);
+    expect(deps.forwarding.start).toHaveBeenCalledWith(ctx);
   });
 
   it("resolves agent name using systemPrompt", async () => {

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),
@@ -83,8 +81,7 @@ function makeDeps(
       .fn()
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),

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),
@@ -71,8 +69,7 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
     events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
@@ -128,7 +125,7 @@ describe("handleInput", () => {
     const ctx = makeCtx();
     const deps = makeDeps();
     await handleInput(deps, makeInputEvent("hello"), ctx);
-    expect(deps.startForwardedPermissionPolling).toHaveBeenCalledWith(ctx);
+    expect(deps.forwarding.start).toHaveBeenCalledWith(ctx);
   });
 
   it("returns continue for non-skill input", async () => {

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),
@@ -100,8 +98,7 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("test-id"),
     events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
@@ -173,7 +170,7 @@ describe("handleSessionStart", () => {
     const ctx = makeCtx();
     const deps = makeDeps();
     await handleSessionStart(deps, { reason: "startup" }, ctx);
-    expect(deps.startForwardedPermissionPolling).toHaveBeenCalledWith(ctx);
+    expect(deps.forwarding.start).toHaveBeenCalledWith(ctx);
   });
 
   it("logs resolved config paths", async () => {
@@ -189,21 +186,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 +210,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 +221,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 +256,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 +266,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,
@@ -321,7 +318,7 @@ describe("handleSessionShutdown", () => {
   it("stops forwarded permission polling", async () => {
     const deps = makeDeps();
     await handleSessionShutdown(deps);
-    expect(deps.stopForwardedPermissionPolling).toHaveBeenCalledOnce();
+    expect(deps.forwarding.stop).toHaveBeenCalledOnce();
   });
 
   it("calls stopPermissionRpcHandlers on shutdown", async () => {

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),
@@ -104,8 +102,7 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .fn()
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
     setActiveTools: vi.fn(),

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),
@@ -92,8 +90,7 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
     events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
-    startForwardedPermissionPolling: vi.fn(),
-    stopForwardedPermissionPolling: vi.fn(),
+    forwarding: { start: vi.fn(), stop: vi.fn() },
     stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
     setActiveTools: vi.fn(),
@@ -141,7 +138,7 @@ describe("handleToolCall", () => {
     const ctx = makeCtx();
     const deps = makeDeps();
     await handleToolCall(deps, makeToolCallEvent("read"), ctx);
-    expect(deps.startForwardedPermissionPolling).toHaveBeenCalledWith(ctx);
+    expect(deps.forwarding.start).toHaveBeenCalledWith(ctx);
   });
 
   it("blocks when tool name cannot be resolved", async () => {

package/tests/runtime.test.ts

@@ -212,21 +212,6 @@ describe("createExtensionRuntime", () => {
     expect(runtime.lastConfigWarning).toBeNull();
   });
 
-  it("initializes permissionForwardingContext to null", () => {
-    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
-    expect(runtime.permissionForwardingContext).toBeNull();
-  });
-
-  it("initializes permissionForwardingTimer to null", () => {
-    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
-    expect(runtime.permissionForwardingTimer).toBeNull();
-  });
-
-  it("initializes isProcessingForwardedRequests to false", () => {
-    const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
-    expect(runtime.isProcessingForwardedRequests).toBe(false);
-  });
-
   it("creates a sessionRules instance", () => {
     const runtime = createExtensionRuntime({ agentDir: "/test/agent" });
     expect(runtime.sessionRules).toBeDefined();

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