@gotgenes/pi-permission-system 5.8.0 → 5.10.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.10.0](https://github.com/gotgenes/pi-permission-system/compare/v5.9.0...v5.10.0) (2026-05-08)
+
+
+### Features
+
+* PermissionSession class with delegation methods ([#129](https://github.com/gotgenes/pi-permission-system/issues/129)) ([a8486ce](https://github.com/gotgenes/pi-permission-system/commit/a8486ce1d0678a7617e3cc6d8131e5f3080a1bea))
+* PermissionSession lifecycle, cache, agent name, and infra methods ([#129](https://github.com/gotgenes/pi-permission-system/issues/129)) ([8f6edf7](https://github.com/gotgenes/pi-permission-system/commit/8f6edf727856a974dc8061c1ff6003838d916662))
+
+
+### Documentation
+
+* plan PermissionSession extraction ([#129](https://github.com/gotgenes/pi-permission-system/issues/129)) ([9dc21b4](https://github.com/gotgenes/pi-permission-system/commit/9dc21b457ff5ca5e95b920eed1e5b48511175cdf))
+* **retro:** add retro notes for issue [#128](https://github.com/gotgenes/pi-permission-system/issues/128) ([9794053](https://github.com/gotgenes/pi-permission-system/commit/979405305ee5ddeac97186ea949373aff947a210))
+* update architecture for PermissionSession ([#129](https://github.com/gotgenes/pi-permission-system/issues/129)) ([d452c50](https://github.com/gotgenes/pi-permission-system/commit/d452c50a7edb7ca1c2c7715836b007386814e1b3))
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.8.0",
+  "version": "5.10.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

@@ -11,12 +11,11 @@ interface BeforeAgentStartPayload {
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
-  shouldApplyCachedAgentStartState,
 } from "../before-agent-start-cache";
-import type { PermissionManager } from "../permission-manager";
 import { resolveSkillPromptEntries } from "../skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "../system-prompt-sanitizer";
 import { getToolNameFromValue } from "../tool-registry";
+import type { PermissionState } from "../types";
 import type { HandlerDeps } from "./types";
 
 /**
@@ -27,12 +26,9 @@ import type { HandlerDeps } from "./types";
 export function shouldExposeTool(
   toolName: string,
   agentName: string | null,
-  permissionManager: PermissionManager,
+  getToolPermission: (toolName: string, agentName?: string) => PermissionState,
 ): boolean {
-  const toolPermission = permissionManager.getToolPermission(
-    toolName,
-    agentName ?? undefined,
-  );
+  const toolPermission = getToolPermission(toolName, agentName ?? undefined);
   return toolPermission !== "deny";
 }
 
@@ -41,12 +37,11 @@ export async function handleBeforeAgentStart(
   event: BeforeAgentStartPayload,
   ctx: ExtensionContext,
 ): Promise<BeforeAgentStartEventResult> {
-  deps.session.runtimeContext = ctx;
-  deps.refreshExtensionConfig(ctx);
-  deps.startForwardedPermissionPolling(ctx);
+  const { session } = deps;
+  session.activate(ctx);
+  session.refreshConfig(ctx);
 
-  const agentName = deps.resolveAgentName(ctx, event.systemPrompt);
-  const { permissionManager } = deps.session;
+  const agentName = session.resolveAgentName(ctx, event.systemPrompt);
   const allTools = deps.getAllTools();
   const allowedTools: string[] = [];
 
@@ -55,42 +50,34 @@ export async function handleBeforeAgentStart(
     if (!toolName) {
       continue;
     }
-    if (shouldExposeTool(toolName, agentName, permissionManager)) {
+    if (
+      shouldExposeTool(toolName, agentName, (t, a) =>
+        session.getToolPermission(t, a),
+      )
+    ) {
       allowedTools.push(toolName);
     }
   }
 
   const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-  if (
-    shouldApplyCachedAgentStartState(
-      deps.session.lastActiveToolsCacheKey,
-      activeToolsCacheKey,
-    )
-  ) {
+  if (session.shouldUpdateActiveTools(activeToolsCacheKey)) {
     deps.setActiveTools(allowedTools);
-    deps.session.lastActiveToolsCacheKey = activeToolsCacheKey;
+    session.commitActiveToolsCacheKey(activeToolsCacheKey);
   }
 
   const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
     agentName,
     cwd: ctx.cwd,
-    permissionStamp: permissionManager.getPolicyCacheStamp(
-      agentName ?? undefined,
-    ),
+    permissionStamp: session.getPolicyCacheStamp(agentName ?? undefined),
     systemPrompt: event.systemPrompt,
     allowedToolNames: allowedTools,
   });
 
-  if (
-    !shouldApplyCachedAgentStartState(
-      deps.session.lastPromptStateCacheKey,
-      promptStateCacheKey,
-    )
-  ) {
+  if (!session.shouldUpdatePromptState(promptStateCacheKey)) {
     return {};
   }
 
-  deps.session.lastPromptStateCacheKey = promptStateCacheKey;
+  session.commitPromptStateCacheKey(promptStateCacheKey);
 
   const toolPromptResult = sanitizeAvailableToolsSection(
     event.systemPrompt,
@@ -98,11 +85,11 @@ export async function handleBeforeAgentStart(
   );
   const skillPromptResult = resolveSkillPromptEntries(
     toolPromptResult.prompt,
-    permissionManager,
+    session,
     agentName,
     ctx.cwd,
   );
-  deps.session.activeSkillEntries = skillPromptResult.entries;
+  session.setActiveSkillEntries(skillPromptResult.entries);
 
   if (skillPromptResult.prompt !== event.systemPrompt) {
     return { systemPrompt: skillPromptResult.prompt };

package/src/handlers/input.ts

@@ -40,16 +40,16 @@ export async function handleInput(
   event: InputPayload,
   ctx: ExtensionContext,
 ): Promise<InputEventResult> {
-  deps.session.runtimeContext = ctx;
-  deps.startForwardedPermissionPolling(ctx);
+  const { session } = deps;
+  session.activate(ctx);
 
   const skillName = extractSkillNameFromInput(event.text);
   if (!skillName) {
     return { action: "continue" };
   }
 
-  const agentName = deps.resolveAgentName(ctx);
-  const check = deps.session.permissionManager.checkPermission(
+  const agentName = session.resolveAgentName(ctx);
+  const check = session.checkPermission(
     "skill",
     { name: skillName },
     agentName ?? undefined,
@@ -82,7 +82,7 @@ export async function handleInput(
       skillInputAutoApproved = decision.autoApproved === true;
       return decision;
     },
-    writeLog: deps.logger.review,
+    writeLog: session.logger.review,
     logContext: {
       source: "skill_input",
       skillName,

package/src/handlers/lifecycle.ts

@@ -1,6 +1,5 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-import { getActiveAgentName } from "../active-agent";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "../status";
 import type { HandlerDeps } from "./types";
 
@@ -19,25 +18,19 @@ export async function handleSessionStart(
   event: SessionStartPayload,
   ctx: ExtensionContext,
 ): Promise<void> {
-  deps.session.runtimeContext = ctx;
-  deps.refreshExtensionConfig(ctx);
-  deps.session.permissionManager = deps.createPermissionManagerForCwd(ctx.cwd);
-  deps.session.activeSkillEntries = [];
-  deps.session.lastActiveToolsCacheKey = null;
-  deps.session.lastPromptStateCacheKey = null;
-  deps.session.lastKnownActiveAgentName = getActiveAgentName(ctx);
-  deps.startForwardedPermissionPolling(ctx);
-  deps.logResolvedConfigPaths();
+  const { session } = deps;
+  session.refreshConfig(ctx);
+  session.resetForNewSession(ctx);
+  session.logResolvedConfigPaths();
 
-  const agentName = deps.session.lastKnownActiveAgentName;
-  const policyIssues =
-    deps.session.permissionManager.getConfigIssues(agentName);
+  const agentName = session.resolveAgentName(ctx);
+  const policyIssues = session.getConfigIssues(agentName);
   for (const issue of policyIssues) {
-    deps.logger.warn(issue);
+    session.logger.warn(issue);
   }
 
   if (event.reason === "reload") {
-    deps.logger.debug("lifecycle.reload", {
+    session.logger.debug("lifecycle.reload", {
       triggeredBy: "session_start",
       reason: event.reason,
       cwd: ctx.cwd,
@@ -53,30 +46,21 @@ export async function handleResourcesDiscover(
     return;
   }
 
-  const { runtimeContext } = deps.session;
-  deps.session.permissionManager = deps.createPermissionManagerForCwd(
-    runtimeContext?.cwd,
-  );
-  deps.session.activeSkillEntries = [];
-  deps.session.lastActiveToolsCacheKey = null;
-  deps.session.lastPromptStateCacheKey = null;
-  deps.logger.debug("lifecycle.reload", {
+  const { session } = deps;
+  session.reload();
+  session.logger.debug("lifecycle.reload", {
     triggeredBy: "resources_discover",
     reason: event.reason,
-    cwd: runtimeContext?.cwd ?? null,
+    cwd: session.getRuntimeContext()?.cwd ?? null,
   });
 }
 
 export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
-  const { runtimeContext } = deps.session;
-  if (runtimeContext) {
-    runtimeContext.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+  const { session } = deps;
+  const ctx = session.getRuntimeContext();
+  if (ctx) {
+    ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
   }
-  deps.session.runtimeContext = null;
-  deps.session.activeSkillEntries = [];
-  deps.session.lastActiveToolsCacheKey = null;
-  deps.session.lastPromptStateCacheKey = null;
-  deps.session.sessionRules.clear();
-  deps.stopForwardedPermissionPolling();
+  session.shutdown();
   deps.stopPermissionRpcHandlers();
 }

package/src/handlers/tool-call.ts

@@ -43,10 +43,10 @@ export async function handleToolCall(
   event: unknown,
   ctx: ExtensionContext,
 ): Promise<{ block?: true; reason?: string }> {
-  deps.session.runtimeContext = ctx;
-  deps.startForwardedPermissionPolling(ctx);
+  const { session } = deps;
+  session.activate(ctx);
 
-  const agentName = deps.resolveAgentName(ctx);
+  const agentName = session.resolveAgentName(ctx);
   const toolName = getToolNameFromValue(event);
 
   if (!toolName) {
@@ -91,22 +91,16 @@ export async function handleToolCall(
     deps.promptPermission(ctx, details);
   const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
     emitDecisionEvent(deps.events, e);
-  const { review: writeReviewLog } = deps.logger;
+  const writeReviewLog = session.logger.review;
   const checkPermission: GateRunnerDeps["checkPermission"] = (
     surface,
     input,
     agent,
     sessionRules,
-  ) =>
-    deps.session.permissionManager.checkPermission(
-      surface,
-      input,
-      agent,
-      sessionRules,
-    );
-  const getSessionRuleset = () => deps.session.sessionRules.getRuleset();
+  ) => session.checkPermission(surface, input, agent, sessionRules);
+  const getSessionRuleset = () => session.getSessionRuleset();
   const approveSessionRule = (surface: string, pattern: string) =>
-    deps.session.sessionRules.approve(surface, pattern);
+    session.approveSessionRule(surface, pattern);
 
   // ── Shared runner deps (built once, reused for all gates) ─────────────
   const runnerDeps: GateRunnerDeps = {
@@ -120,9 +114,8 @@ export async function handleToolCall(
   };
 
   // ── Skill-read gate (descriptor + runner) ────────────────────────────────
-  const skillDescriptor = describeSkillReadGate(
-    tcc,
-    () => deps.session.activeSkillEntries,
+  const skillDescriptor = describeSkillReadGate(tcc, () =>
+    session.getActiveSkillEntries(),
   );
   if (skillDescriptor) {
     const skillResult = await runGateCheck(
@@ -138,8 +131,8 @@ export async function handleToolCall(
 
   // ── External-directory gate (descriptor + runner) ─────────────────────────
   const infraDirs = [
-    ...deps.piInfrastructureDirs,
-    ...deps.getPiInfrastructureReadPaths(),
+    ...session.getInfrastructureDirs(),
+    ...session.getInfrastructureReadPaths(),
   ];
   const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
   if (extDirDesc) {

package/src/handlers/types.ts

@@ -2,9 +2,7 @@ import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
 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";
+import type { PermissionSession } from "../permission-session";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
@@ -28,46 +26,23 @@ export interface PromptPermissionDetails {
 /**
  * Explicit dependency bag passed to each extracted event handler.
  *
- * Mutable session state lives in `session`; handlers read and write
- * `deps.session.*` directly. Logging, infrastructure paths, and the
- * event bus are promoted to top-level fields so handlers and gate
- * adapters never reach through nested objects for leaf operations.
+ * `session` is a `PermissionSession` that encapsulates all mutable state
+ * and exposes operations instead of fields — eliminating LoD violations,
+ * output arguments, and scattered field resets.
+ *
+ * Remaining top-level fields are things the session does not own:
+ * event bus, RPC cleanup, Pi tool API, and permission request ID generation.
  */
 export interface HandlerDeps {
-  // ── Session state ─────────────────────────────────────────────────────
-  /** Mutable session state: permissionManager, sessionRules, cache keys. */
-  readonly session: SessionState;
-
-  // ── Logging ────────────────────────────────────────────────────────────
-  readonly logger: SessionLogger;
-
-  // ── Immutable infrastructure paths ───────────────────────────────────
-  readonly piInfrastructureDirs: readonly string[];
-  /** Returns config-derived infrastructure read paths (current at call time). */
-  getPiInfrastructureReadPaths(): string[];
+  // ── Session ─────────────────────────────────────────────────────────
+  /** Encapsulates all mutable session state and permission operations. */
+  readonly session: PermissionSession;
 
   // ── Event bus ────────────────────────────────────────────────────────
   /** Event bus for emitting permissions:decision broadcast events. */
   readonly events: PermissionEventBus;
 
-  // ── Factories ──────────────────────────────────────────────────────────
-  /** Create a new PermissionManager scoped to cwd's config hierarchy. */
-  createPermissionManagerForCwd(
-    cwd: string | undefined | null,
-  ): PermissionManager;
-
-  // ── Config & lifecycle helpers ─────────────────────────────────────────
-  /** Reload merged config from disk; optionally update the stored runtime context. */
-  refreshExtensionConfig(ctx?: ExtensionContext): void;
-  /** Write the resolved config path set to the review and debug logs. */
-  logResolvedConfigPaths(): void;
-
   // ── Permission helpers ─────────────────────────────────────────────────
-  /**
-   * Resolve the active agent name from the session context or system prompt.
-   * Updates session.lastKnownActiveAgentName as a side effect.
-   */
-  resolveAgentName(ctx: ExtensionContext, systemPrompt?: string): string | null;
   /** Whether the current context can show an interactive permission prompt. */
   canRequestPermissionConfirmation(ctx: ExtensionContext): boolean;
   /** Prompt the user for a permission decision, log the outcome, and return it. */
@@ -78,9 +53,7 @@ export interface HandlerDeps {
   /** Generate a unique ID for a permission request. */
   createPermissionRequestId(prefix: string): string;
 
-  // ── Forwarding ─────────────────────────────────────────────────────────
-  startForwardedPermissionPolling(ctx: ExtensionContext): void;
-  stopForwardedPermissionPolling(): void;
+  // ── Lifecycle ───────────────────────────────────────────────────────────
   /** 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,
@@ -15,15 +16,12 @@ import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { emitReadyEvent } from "./permission-events";
 import { PermissionPrompter } from "./permission-prompter";
+import { PermissionSession } from "./permission-session";
 import {
   createExtensionRuntime,
-  createPermissionManagerForCwd,
   logResolvedConfigPaths,
   refreshExtensionConfig,
-  resolveAgentName,
   saveExtensionConfig,
-  startForwardedPermissionPolling,
-  stopForwardedPermissionPolling,
 } from "./runtime";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
@@ -57,6 +55,18 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   refreshExtensionConfig(runtime);
+
+  const session = new PermissionSession(
+    runtime,
+    createSessionLogger(runtime),
+    new ForwardingManager(runtime.subagentSessionsDir, forwardingDeps),
+    {
+      refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
+      logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
+      getConfig: () => runtime.config,
+    },
+  );
+
   registerPermissionSystemCommand(pi, {
     getConfig: () => runtime.config,
     setConfig: (next, ctx) => saveExtensionConfig(runtime, next, ctx),
@@ -79,18 +89,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   const deps: HandlerDeps = {
-    session: runtime,
-    logger: createSessionLogger(runtime),
-    piInfrastructureDirs: runtime.piInfrastructureDirs,
-    getPiInfrastructureReadPaths: () =>
-      runtime.config.piInfrastructureReadPaths ?? [],
+    session,
     events: pi.events,
-    createPermissionManagerForCwd: (cwd) =>
-      createPermissionManagerForCwd(runtime.agentDir, cwd),
-    refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
-    logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
-    resolveAgentName: (ctx, systemPrompt) =>
-      resolveAgentName(runtime, ctx, systemPrompt),
     canRequestPermissionConfirmation: (ctx) =>
       canResolveAskPermissionRequest({
         config: runtime.config,
@@ -102,10 +102,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       }),
     promptPermission: (ctx, details) => prompter.prompt(ctx, details),
     createPermissionRequestId,
-    startForwardedPermissionPolling: (ctx) =>
-      startForwardedPermissionPolling(runtime, forwardingDeps, ctx),
-    stopForwardedPermissionPolling: () =>
-      stopForwardedPermissionPolling(runtime),
     stopPermissionRpcHandlers: () => {
       rpcHandles.unsubCheck();
       rpcHandles.unsubPrompt();