@gotgenes/pi-permission-system 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
+## [3.8.0](https://github.com/gotgenes/pi-permission-system/compare/v3.7.0...v3.8.0) (2026-05-03)
+
+
+### Features
+
+* define ExtensionRuntime and createExtensionRuntime factory ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([6ad3db6](https://github.com/gotgenes/pi-permission-system/commit/6ad3db6671629f6480a49e6be890dbaff211ad69))
+* eliminate module-scope state in src/index.ts ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([45b2bc1](https://github.com/gotgenes/pi-permission-system/commit/45b2bc1f4bff3693f295892c942328cc6a53f5e0))
+* relocate factory helpers into src/runtime.ts ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([88c1acd](https://github.com/gotgenes/pi-permission-system/commit/88c1acd4e99f24e808b60bbeee2cbed69c2a67ef))
+* simplify HandlerDeps to use ExtensionRuntime ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([2ff5971](https://github.com/gotgenes/pi-permission-system/commit/2ff59712f88c8bde2095df7e475ecb0c19cb3335))
+* thread logger through forwarded-permissions IO ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([66db158](https://github.com/gotgenes/pi-permission-system/commit/66db158cfe423cf503fc08fc472f31f595527381))
+
+
+### Documentation
+
+* plan eliminate module-scope mutable state ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([6a782d7](https://github.com/gotgenes/pi-permission-system/commit/6a782d7e8df871c15cf9d5c4b27c5e90f9e12d4d))
+* **retro:** add retro notes for issue [#42](https://github.com/gotgenes/pi-permission-system/issues/42) ([9b91110](https://github.com/gotgenes/pi-permission-system/commit/9b91110832e562440c3a881bb16e5f0a7989b33a))
+* update plan with implementation notes ([#43](https://github.com/gotgenes/pi-permission-system/issues/43)) ([d29a7c0](https://github.com/gotgenes/pi-permission-system/commit/d29a7c0d037f3e44791c713474190a1873a5d294))
+
 ## [3.7.0](https://github.com/gotgenes/pi-permission-system/compare/v3.6.0...v3.7.0) (2026-05-03)
 
 

package/package.json

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

package/src/forwarded-permissions/io.ts

@@ -24,14 +24,6 @@ export interface ForwardedPermissionLogger {
   writeDebugLog: LogFn;
 }
 
-let logger: ForwardedPermissionLogger | null = null;
-
-export function setForwardedPermissionLogger(
-  l: ForwardedPermissionLogger,
-): void {
-  logger = l;
-}
-
 export function formatUnknownErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message) {
     return error.message;
@@ -48,7 +40,12 @@ export function isErrnoCode(error: unknown, code: string): boolean {
   );
 }
 
+/**
+ * Log a warning to both the review and debug logs.
+ * Pass `null` for `logger` to silently no-op (e.g. in unit tests without IO).
+ */
 export function logPermissionForwardingWarning(
+  logger: ForwardedPermissionLogger | null,
   message: string,
   error?: unknown,
 ): void {
@@ -61,7 +58,12 @@ export function logPermissionForwardingWarning(
   logger?.writeDebugLog("permission_forwarding.warning", details);
 }
 
+/**
+ * Log an error to both the review and debug logs.
+ * Pass `null` for `logger` to silently no-op (e.g. in unit tests without IO).
+ */
 export function logPermissionForwardingError(
+  logger: ForwardedPermissionLogger | null,
   message: string,
   error?: unknown,
 ): void {
@@ -75,6 +77,7 @@ export function logPermissionForwardingError(
 }
 
 export function ensureDirectoryExists(
+  logger: ForwardedPermissionLogger | null,
   path: string,
   description: string,
 ): boolean {
@@ -83,6 +86,7 @@ export function ensureDirectoryExists(
     return true;
   } catch (error) {
     logPermissionForwardingError(
+      logger,
       `Failed to create ${description} directory '${path}'`,
       error,
     );
@@ -98,6 +102,7 @@ export function getPermissionForwardingLocationForSession(
 }
 
 export function ensurePermissionForwardingLocation(
+  logger: ForwardedPermissionLogger | null,
   forwardingDir: string,
   sessionId: string,
 ): PermissionForwardingLocation | null {
@@ -109,6 +114,7 @@ export function ensurePermissionForwardingLocation(
     );
   } catch (error) {
     logPermissionForwardingError(
+      logger,
       "Failed to resolve permission forwarding location",
       error,
     );
@@ -116,14 +122,17 @@ export function ensurePermissionForwardingLocation(
   }
 
   const sessionRootReady = ensureDirectoryExists(
+    logger,
     location.sessionRootDir,
     "permission forwarding session root",
   );
   const requestsReady = ensureDirectoryExists(
+    logger,
     location.requestsDir,
     "permission forwarding requests",
   );
   const responsesReady = ensureDirectoryExists(
+    logger,
     location.responsesDir,
     "permission forwarding responses",
   );
@@ -149,6 +158,7 @@ export function getExistingPermissionForwardingLocation(
 }
 
 export function tryRemoveDirectoryIfEmpty(
+  logger: ForwardedPermissionLogger | null,
   path: string,
   description: string,
 ): void {
@@ -161,6 +171,7 @@ export function tryRemoveDirectoryIfEmpty(
     entries = readdirSync(path);
   } catch (error) {
     logPermissionForwardingWarning(
+      logger,
       `Failed to inspect ${description} directory '${path}'`,
       error,
     );
@@ -179,6 +190,7 @@ export function tryRemoveDirectoryIfEmpty(
     }
 
     logPermissionForwardingWarning(
+      logger,
       `Failed to remove empty ${description} directory '${path}'`,
       error,
     );
@@ -186,23 +198,31 @@ export function tryRemoveDirectoryIfEmpty(
 }
 
 export function cleanupPermissionForwardingLocationIfEmpty(
+  logger: ForwardedPermissionLogger | null,
   location: PermissionForwardingLocation,
 ): void {
   tryRemoveDirectoryIfEmpty(
+    logger,
     location.requestsDir,
     `${location.label} permission forwarding requests`,
   );
   tryRemoveDirectoryIfEmpty(
+    logger,
     location.responsesDir,
     `${location.label} permission forwarding responses`,
   );
   tryRemoveDirectoryIfEmpty(
+    logger,
     location.sessionRootDir,
     `${location.label} permission forwarding session root`,
   );
 }
 
-export function safeDeleteFile(filePath: string, description: string): void {
+export function safeDeleteFile(
+  logger: ForwardedPermissionLogger | null,
+  filePath: string,
+  description: string,
+): void {
   try {
     unlinkSync(filePath);
   } catch (error) {
@@ -211,25 +231,31 @@ export function safeDeleteFile(filePath: string, description: string): void {
     }
 
     logPermissionForwardingWarning(
+      logger,
       `Failed to delete ${description} file '${filePath}'`,
       error,
     );
   }
 }
 
-export function writeJsonFileAtomic(filePath: string, value: unknown): void {
+export function writeJsonFileAtomic(
+  logger: ForwardedPermissionLogger | null,
+  filePath: string,
+  value: unknown,
+): void {
   const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
 
   try {
     writeFileSync(tempPath, JSON.stringify(value), "utf-8");
     renameSync(tempPath, filePath);
   } catch (error) {
-    safeDeleteFile(tempPath, "temporary permission-forwarding");
+    safeDeleteFile(logger, tempPath, "temporary permission-forwarding");
     throw error;
   }
 }
 
 export function readForwardedPermissionRequest(
+  logger: ForwardedPermissionLogger | null,
   filePath: string,
 ): ForwardedPermissionRequest | null {
   try {
@@ -245,6 +271,7 @@ export function readForwardedPermissionRequest(
       typeof parsed.message !== "string"
     ) {
       logPermissionForwardingWarning(
+        logger,
         `Ignoring invalid forwarded permission request format in '${filePath}'`,
       );
       return null;
@@ -260,6 +287,7 @@ export function readForwardedPermissionRequest(
     };
   } catch (error) {
     logPermissionForwardingWarning(
+      logger,
       `Failed to read forwarded permission request '${filePath}'`,
       error,
     );
@@ -268,6 +296,7 @@ export function readForwardedPermissionRequest(
 }
 
 export function readForwardedPermissionResponse(
+  logger: ForwardedPermissionLogger | null,
   filePath: string,
 ): ForwardedPermissionResponse | null {
   try {
@@ -280,6 +309,7 @@ export function readForwardedPermissionResponse(
       typeof parsed.responderSessionId !== "string"
     ) {
       logPermissionForwardingWarning(
+        logger,
         `Ignoring invalid forwarded permission response format in '${filePath}'`,
       );
       return null;
@@ -300,6 +330,7 @@ export function readForwardedPermissionResponse(
     };
   } catch (error) {
     logPermissionForwardingWarning(
+      logger,
       `Failed to read forwarded permission response '${filePath}'`,
       error,
     );
@@ -307,13 +338,17 @@ export function readForwardedPermissionResponse(
   }
 }
 
-export function listRequestFiles(requestsDir: string): string[] {
+export function listRequestFiles(
+  logger: ForwardedPermissionLogger | null,
+  requestsDir: string,
+): string[] {
   try {
     return readdirSync(requestsDir)
       .filter((name) => name.endsWith(".json"))
       .sort();
   } catch (error) {
     logPermissionForwardingWarning(
+      logger,
       `Failed to read permission forwarding requests from '${requestsDir}'`,
       error,
     );

package/src/forwarded-permissions/polling.ts

@@ -21,6 +21,7 @@ import { isSubagentExecutionContext } from "../subagent-context";
 import {
   cleanupPermissionForwardingLocationIfEmpty,
   ensurePermissionForwardingLocation,
+  type ForwardedPermissionLogger,
   getExistingPermissionForwardingLocation,
   listRequestFiles,
   logPermissionForwardingError,
@@ -35,6 +36,7 @@ import {
 export interface PermissionForwardingDeps {
   forwardingDir: string;
   subagentSessionsDir: string;
+  logger: ForwardedPermissionLogger;
   writeReviewLog: (event: string, details: Record<string, unknown>) => void;
   requestPermissionDecisionFromUi: (
     ui: ExtensionContext["ui"],
@@ -65,7 +67,9 @@ function getContextSystemPrompt(ctx: ExtensionContext): string | undefined {
     const systemPrompt = getSystemPrompt.call(ctx);
     return typeof systemPrompt === "string" ? systemPrompt : undefined;
   } catch (error) {
+    // No deps available in this helper — warning silently dropped.
     logPermissionForwardingWarning(
+      null,
       "Failed to read context system prompt for forwarded permission metadata",
       error,
     );
@@ -101,17 +105,20 @@ export async function waitForForwardedPermissionApproval(
 
   if (!targetSessionId) {
     logPermissionForwardingError(
+      deps.logger,
       "Permission forwarding target session could not be resolved from subagent runtime metadata (expected PI_AGENT_ROUTER_PARENT_SESSION_ID)",
     );
     return { approved: false, state: "denied" };
   }
 
   const location = ensurePermissionForwardingLocation(
+    deps.logger,
     deps.forwardingDir,
     targetSessionId,
   );
   if (!location) {
     logPermissionForwardingError(
+      deps.logger,
       `Permission forwarding is unavailable because session-scoped directories could not be prepared for '${targetSessionId}'`,
     );
     return { approved: false, state: "denied" };
@@ -144,9 +151,10 @@ export async function waitForForwardedPermissionApproval(
   });
 
   try {
-    writeJsonFileAtomic(requestPath, request);
+    writeJsonFileAtomic(deps.logger, requestPath, request);
   } catch (error) {
     logPermissionForwardingError(
+      deps.logger,
       `Failed to write forwarded permission request '${requestPath}'`,
       error,
     );
@@ -156,7 +164,10 @@ export async function waitForForwardedPermissionApproval(
   const deadline = Date.now() + PERMISSION_FORWARDING_TIMEOUT_MS;
   while (Date.now() < deadline) {
     if (existsSync(responsePath)) {
-      const response = readForwardedPermissionResponse(responsePath);
+      const response = readForwardedPermissionResponse(
+        deps.logger,
+        responsePath,
+      );
       deps.writeReviewLog("forwarded_permission.response_received", {
         requestId,
         approved: response?.approved ?? null,
@@ -166,9 +177,13 @@ export async function waitForForwardedPermissionApproval(
         targetSessionId,
         responsePath,
       });
-      safeDeleteFile(responsePath, "forwarded permission response");
-      safeDeleteFile(requestPath, "forwarded permission request");
-      cleanupPermissionForwardingLocationIfEmpty(location);
+      safeDeleteFile(
+        deps.logger,
+        responsePath,
+        "forwarded permission response",
+      );
+      safeDeleteFile(deps.logger, requestPath, "forwarded permission request");
+      cleanupPermissionForwardingLocationIfEmpty(deps.logger, location);
       return response ?? { approved: false, state: "denied" };
     }
 
@@ -176,6 +191,7 @@ export async function waitForForwardedPermissionApproval(
   }
 
   logPermissionForwardingWarning(
+    deps.logger,
     `Timed out waiting for forwarded permission response '${responsePath}'`,
   );
   deps.writeReviewLog("forwarded_permission.response_timed_out", {
@@ -184,8 +200,8 @@ export async function waitForForwardedPermissionApproval(
     targetSessionId,
     responsePath,
   });
-  safeDeleteFile(requestPath, "forwarded permission request");
-  cleanupPermissionForwardingLocationIfEmpty(location);
+  safeDeleteFile(deps.logger, requestPath, "forwarded permission request");
+  cleanupPermissionForwardingLocationIfEmpty(deps.logger, location);
   return { approved: false, state: "denied" };
 }
 
@@ -206,16 +222,17 @@ export async function processForwardedPermissionRequests(
     return;
   }
 
-  const requestFiles = listRequestFiles(location.requestsDir);
+  const requestFiles = listRequestFiles(deps.logger, location.requestsDir);
   if (requestFiles.length === 0) {
     return;
   }
 
   for (const fileName of requestFiles) {
     const requestPath = join(location.requestsDir, fileName);
-    const request = readForwardedPermissionRequest(requestPath);
+    const request = readForwardedPermissionRequest(deps.logger, requestPath);
     if (!request) {
       safeDeleteFile(
+        deps.logger,
         requestPath,
         `${location.label} forwarded permission request`,
       );
@@ -224,9 +241,11 @@ export async function processForwardedPermissionRequests(
 
     if (!isForwardedPermissionRequestForSession(request, currentSessionId)) {
       logPermissionForwardingWarning(
+        deps.logger,
         `Ignoring forwarded permission request '${request.id}' because it targets session '${request.targetSessionId}' instead of '${currentSessionId}'`,
       );
       safeDeleteFile(
+        deps.logger,
         requestPath,
         `${location.label} forwarded permission request`,
       );
@@ -265,6 +284,7 @@ export async function processForwardedPermissionRequests(
         );
       } catch (error) {
         logPermissionForwardingError(
+          deps.logger,
           "Failed to show forwarded permission confirmation dialog",
           error,
         );
@@ -289,7 +309,7 @@ export async function processForwardedPermissionRequests(
       },
     );
     try {
-      writeJsonFileAtomic(responsePath, {
+      writeJsonFileAtomic(deps.logger, responsePath, {
         approved: decision.approved,
         state: decision.state,
         denialReason: decision.denialReason,
@@ -298,6 +318,7 @@ export async function processForwardedPermissionRequests(
       } satisfies ForwardedPermissionResponse);
     } catch (error) {
       logPermissionForwardingError(
+        deps.logger,
         `Failed to write ${location.label} forwarded permission response '${responsePath}'`,
         error,
       );
@@ -305,12 +326,13 @@ export async function processForwardedPermissionRequests(
     }
 
     safeDeleteFile(
+      deps.logger,
       requestPath,
       `${location.label} forwarded permission request`,
     );
   }
 
-  cleanupPermissionForwardingLocationIfEmpty(location);
+  cleanupPermissionForwardingLocationIfEmpty(deps.logger, location);
 }
 
 export async function confirmPermission(

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

@@ -41,12 +41,12 @@ export async function handleBeforeAgentStart(
   event: BeforeAgentStartPayload,
   ctx: ExtensionContext,
 ): Promise<BeforeAgentStartEventResult> {
-  deps.setRuntimeContext(ctx);
+  deps.runtime.runtimeContext = ctx;
   deps.refreshExtensionConfig(ctx);
   deps.startForwardedPermissionPolling(ctx);
 
   const agentName = deps.resolveAgentName(ctx, event.systemPrompt);
-  const permissionManager = deps.getPermissionManager();
+  const { permissionManager } = deps.runtime;
   const allTools = deps.getAllTools();
   const allowedTools: string[] = [];
 
@@ -63,12 +63,12 @@ export async function handleBeforeAgentStart(
   const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
   if (
     shouldApplyCachedAgentStartState(
-      deps.getLastActiveToolsCacheKey(),
+      deps.runtime.lastActiveToolsCacheKey,
       activeToolsCacheKey,
     )
   ) {
     deps.setActiveTools(allowedTools);
-    deps.setLastActiveToolsCacheKey(activeToolsCacheKey);
+    deps.runtime.lastActiveToolsCacheKey = activeToolsCacheKey;
   }
 
   const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
@@ -83,14 +83,14 @@ export async function handleBeforeAgentStart(
 
   if (
     !shouldApplyCachedAgentStartState(
-      deps.getLastPromptStateCacheKey(),
+      deps.runtime.lastPromptStateCacheKey,
       promptStateCacheKey,
     )
   ) {
     return {};
   }
 
-  deps.setLastPromptStateCacheKey(promptStateCacheKey);
+  deps.runtime.lastPromptStateCacheKey = promptStateCacheKey;
 
   const toolPromptResult = sanitizeAvailableToolsSection(
     event.systemPrompt,
@@ -102,7 +102,7 @@ export async function handleBeforeAgentStart(
     agentName,
     ctx.cwd,
   );
-  deps.setActiveSkillEntries(skillPromptResult.entries);
+  deps.runtime.activeSkillEntries = skillPromptResult.entries;
 
   if (skillPromptResult.prompt !== event.systemPrompt) {
     return { systemPrompt: skillPromptResult.prompt };

package/src/handlers/input.ts

@@ -39,7 +39,7 @@ export async function handleInput(
   event: InputPayload,
   ctx: ExtensionContext,
 ): Promise<InputEventResult> {
-  deps.setRuntimeContext(ctx);
+  deps.runtime.runtimeContext = ctx;
   deps.startForwardedPermissionPolling(ctx);
 
   const skillName = extractSkillNameFromInput(event.text);
@@ -48,9 +48,11 @@ export async function handleInput(
   }
 
   const agentName = deps.resolveAgentName(ctx);
-  const check = deps
-    .getPermissionManager()
-    .checkPermission("skill", { name: skillName }, agentName ?? undefined);
+  const check = deps.runtime.permissionManager.checkPermission(
+    "skill",
+    { name: skillName },
+    agentName ?? undefined,
+  );
 
   if (check.state === "deny" && ctx.hasUI) {
     const notifyMessage = agentName
@@ -74,7 +76,7 @@ export async function handleInput(
         message: skillInputMessage,
         skillName,
       }),
-    writeLog: deps.writeReviewLog,
+    writeLog: deps.runtime.writeReviewLog,
     logContext: {
       source: "skill_input",
       skillName,

package/src/handlers/lifecycle.ts

@@ -19,24 +19,25 @@ export async function handleSessionStart(
   event: SessionStartPayload,
   ctx: ExtensionContext,
 ): Promise<void> {
-  deps.setRuntimeContext(ctx);
+  deps.runtime.runtimeContext = ctx;
   deps.refreshExtensionConfig(ctx);
-  deps.setPermissionManager(deps.createPermissionManagerForCwd(ctx.cwd));
-  deps.setActiveSkillEntries([]);
-  deps.setLastActiveToolsCacheKey(null);
-  deps.setLastPromptStateCacheKey(null);
-  deps.setLastKnownActiveAgentName(getActiveAgentName(ctx));
+  deps.runtime.permissionManager = deps.createPermissionManagerForCwd(ctx.cwd);
+  deps.runtime.activeSkillEntries = [];
+  deps.runtime.lastActiveToolsCacheKey = null;
+  deps.runtime.lastPromptStateCacheKey = null;
+  deps.runtime.lastKnownActiveAgentName = getActiveAgentName(ctx);
   deps.startForwardedPermissionPolling(ctx);
   deps.logResolvedConfigPaths();
 
-  const agentName = deps.getLastKnownActiveAgentName();
-  const policyIssues = deps.getPermissionManager().getConfigIssues(agentName);
+  const agentName = deps.runtime.lastKnownActiveAgentName;
+  const policyIssues =
+    deps.runtime.permissionManager.getConfigIssues(agentName);
   for (const issue of policyIssues) {
     deps.notifyWarning(issue);
   }
 
   if (event.reason === "reload") {
-    deps.writeDebugLog("lifecycle.reload", {
+    deps.runtime.writeDebugLog("lifecycle.reload", {
       triggeredBy: "session_start",
       reason: event.reason,
       cwd: ctx.cwd,
@@ -52,14 +53,14 @@ export async function handleResourcesDiscover(
     return;
   }
 
-  const runtimeContext = deps.getRuntimeContext();
-  deps.setPermissionManager(
-    deps.createPermissionManagerForCwd(runtimeContext?.cwd),
+  const { runtimeContext } = deps.runtime;
+  deps.runtime.permissionManager = deps.createPermissionManagerForCwd(
+    runtimeContext?.cwd,
   );
-  deps.setActiveSkillEntries([]);
-  deps.setLastActiveToolsCacheKey(null);
-  deps.setLastPromptStateCacheKey(null);
-  deps.writeDebugLog("lifecycle.reload", {
+  deps.runtime.activeSkillEntries = [];
+  deps.runtime.lastActiveToolsCacheKey = null;
+  deps.runtime.lastPromptStateCacheKey = null;
+  deps.runtime.writeDebugLog("lifecycle.reload", {
     triggeredBy: "resources_discover",
     reason: event.reason,
     cwd: runtimeContext?.cwd ?? null,
@@ -67,14 +68,14 @@ export async function handleResourcesDiscover(
 }
 
 export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
-  const ctx = deps.getRuntimeContext();
-  if (ctx) {
-    ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+  const { runtimeContext } = deps.runtime;
+  if (runtimeContext) {
+    runtimeContext.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
   }
-  deps.setRuntimeContext(null);
-  deps.setActiveSkillEntries([]);
-  deps.setLastActiveToolsCacheKey(null);
-  deps.setLastPromptStateCacheKey(null);
-  deps.sessionApprovalCache.clear();
+  deps.runtime.runtimeContext = null;
+  deps.runtime.activeSkillEntries = [];
+  deps.runtime.lastActiveToolsCacheKey = null;
+  deps.runtime.lastPromptStateCacheKey = null;
+  deps.runtime.sessionApprovalCache.clear();
   deps.stopForwardedPermissionPolling();
 }