@gotgenes/pi-permission-system 5.9.0 → 5.11.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.11.0](https://github.com/gotgenes/pi-permission-system/compare/v5.10.0...v5.11.0) (2026-05-08)
+
+
+### Features
+
+* add ToolRegistry interface ([#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([5e886fd](https://github.com/gotgenes/pi-permission-system/commit/5e886fd4bc67ddac56a7f2b7b445f6f172e60668))
+* PermissionSession absorbs prompting methods ([#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([4ae81e6](https://github.com/gotgenes/pi-permission-system/commit/4ae81e6e32164926202633ec7831a4f3db69fc70))
+
+
+### Documentation
+
+* plan handler classes to replace HandlerDeps ([#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([e8bc1a4](https://github.com/gotgenes/pi-permission-system/commit/e8bc1a40596aa6a032b367e642d19a03ca622394))
+* **retro:** add retro notes for issue [#129](https://github.com/gotgenes/pi-permission-system/issues/129) ([23c29a2](https://github.com/gotgenes/pi-permission-system/commit/23c29a2148f6647565e6997d9c56341b43e74118))
+* update architecture for handler classes ([#130](https://github.com/gotgenes/pi-permission-system/issues/130)) ([02d02b6](https://github.com/gotgenes/pi-permission-system/commit/02d02b647ec366eee3dc572afbaf436b1264b052))
+
+## [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)
 
 

package/package.json

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

package/src/forwarding-manager.ts

@@ -6,7 +6,7 @@ import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding"
 import { isSubagentExecutionContext } from "./subagent-context";
 
 /**
- * Narrow interface for the forwarding lifecycle used by `HandlerDeps`.
+ * Narrow interface for the forwarding lifecycle used by `PermissionSession`.
  * `ForwardingManager` satisfies it; tests can provide a plain object mock.
  */
 export interface ForwardingController {

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

@@ -3,21 +3,20 @@ import type {
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
 
-/** Minimal subset of BeforeAgentStartEvent used by this handler. */
-interface BeforeAgentStartPayload {
-  systemPrompt: string;
-}
-
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
-  shouldApplyCachedAgentStartState,
 } from "../before-agent-start-cache";
-import type { PermissionManager } from "../permission-manager";
+import type { PermissionSession } from "../permission-session";
 import { resolveSkillPromptEntries } from "../skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "../system-prompt-sanitizer";
-import { getToolNameFromValue } from "../tool-registry";
-import type { HandlerDeps } from "./types";
+import { getToolNameFromValue, type ToolRegistry } from "../tool-registry";
+import type { PermissionState } from "../types";
+
+/** Minimal subset of BeforeAgentStartEvent used by this handler. */
+interface BeforeAgentStartPayload {
+  systemPrompt: string;
+}
 
 /**
  * Pure helper: returns true when the tool should be exposed to the agent.
@@ -27,86 +26,87 @@ 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";
 }
 
-export async function handleBeforeAgentStart(
-  deps: HandlerDeps,
-  event: BeforeAgentStartPayload,
-  ctx: ExtensionContext,
-): Promise<BeforeAgentStartEventResult> {
-  deps.session.runtimeContext = ctx;
-  deps.refreshExtensionConfig(ctx);
-  deps.forwarding.start(ctx);
+/**
+ * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
+ *
+ * Constructor deps:
+ * - `session` — encapsulates all mutable session state
+ * - `toolRegistry` — Pi tool API subset (getAll + setActive)
+ */
+export class AgentPrepHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly toolRegistry: ToolRegistry,
+  ) {}
+
+  async handle(
+    event: BeforeAgentStartPayload,
+    ctx: ExtensionContext,
+  ): Promise<BeforeAgentStartEventResult> {
+    const { session } = this;
+    session.activate(ctx);
+    session.refreshConfig(ctx);
 
-  const agentName = deps.resolveAgentName(ctx, event.systemPrompt);
-  const { permissionManager } = deps.session;
-  const allTools = deps.getAllTools();
-  const allowedTools: string[] = [];
+    const agentName = session.resolveAgentName(ctx, event.systemPrompt);
+    const allTools = this.toolRegistry.getAll();
+    const allowedTools: string[] = [];
 
-  for (const tool of allTools) {
-    const toolName = getToolNameFromValue(tool);
-    if (!toolName) {
-      continue;
+    for (const tool of allTools) {
+      const toolName = getToolNameFromValue(tool);
+      if (!toolName) {
+        continue;
+      }
+      if (
+        shouldExposeTool(toolName, agentName, (t, a) =>
+          session.getToolPermission(t, a),
+        )
+      ) {
+        allowedTools.push(toolName);
+      }
     }
-    if (shouldExposeTool(toolName, agentName, permissionManager)) {
-      allowedTools.push(toolName);
+
+    const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
+    if (session.shouldUpdateActiveTools(activeToolsCacheKey)) {
+      this.toolRegistry.setActive(allowedTools);
+      session.commitActiveToolsCacheKey(activeToolsCacheKey);
     }
-  }
 
-  const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-  if (
-    shouldApplyCachedAgentStartState(
-      deps.session.lastActiveToolsCacheKey,
-      activeToolsCacheKey,
-    )
-  ) {
-    deps.setActiveTools(allowedTools);
-    deps.session.lastActiveToolsCacheKey = activeToolsCacheKey;
-  }
+    const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
+      agentName,
+      cwd: ctx.cwd,
+      permissionStamp: session.getPolicyCacheStamp(agentName ?? undefined),
+      systemPrompt: event.systemPrompt,
+      allowedToolNames: allowedTools,
+    });
 
-  const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
-    agentName,
-    cwd: ctx.cwd,
-    permissionStamp: permissionManager.getPolicyCacheStamp(
-      agentName ?? undefined,
-    ),
-    systemPrompt: event.systemPrompt,
-    allowedToolNames: allowedTools,
-  });
+    if (!session.shouldUpdatePromptState(promptStateCacheKey)) {
+      return {};
+    }
 
-  if (
-    !shouldApplyCachedAgentStartState(
-      deps.session.lastPromptStateCacheKey,
-      promptStateCacheKey,
-    )
-  ) {
-    return {};
-  }
+    session.commitPromptStateCacheKey(promptStateCacheKey);
 
-  deps.session.lastPromptStateCacheKey = promptStateCacheKey;
+    const toolPromptResult = sanitizeAvailableToolsSection(
+      event.systemPrompt,
+      allowedTools,
+    );
+    const skillPromptResult = resolveSkillPromptEntries(
+      toolPromptResult.prompt,
+      session,
+      agentName,
+      ctx.cwd,
+    );
+    session.setActiveSkillEntries(skillPromptResult.entries);
 
-  const toolPromptResult = sanitizeAvailableToolsSection(
-    event.systemPrompt,
-    allowedTools,
-  );
-  const skillPromptResult = resolveSkillPromptEntries(
-    toolPromptResult.prompt,
-    permissionManager,
-    agentName,
-    ctx.cwd,
-  );
-  deps.session.activeSkillEntries = skillPromptResult.entries;
+    if (skillPromptResult.prompt !== event.systemPrompt) {
+      return { systemPrompt: skillPromptResult.prompt };
+    }
 
-  if (skillPromptResult.prompt !== event.systemPrompt) {
-    return { systemPrompt: skillPromptResult.prompt };
+    return {};
   }
-
-  return {};
 }

package/src/handlers/gates/descriptor.ts

@@ -3,9 +3,9 @@ import type {
   PermissionDecisionEvent,
   PermissionDecisionResolution,
 } from "../../permission-events";
+import type { PromptPermissionDetails } from "../../permission-prompter";
 import type { Rule } from "../../rule";
 import type { PermissionCheckResult, PermissionState } from "../../types";
-import type { PromptPermissionDetails } from "../types";
 
 // ── Descriptor types ───────────────────────────────────────────────────────
 

package/src/handlers/index.ts

@@ -1,16 +1,7 @@
+export { AgentPrepHandler, shouldExposeTool } from "./before-agent-start";
+export { SessionLifecycleHandler } from "./lifecycle";
 export {
-  handleBeforeAgentStart,
-  shouldExposeTool,
-} from "./before-agent-start";
-export { extractSkillNameFromInput, handleInput } from "./input";
-export {
-  handleResourcesDiscover,
-  handleSessionShutdown,
-  handleSessionStart,
-} from "./lifecycle";
-export { getEventInput, handleToolCall } from "./tool-call";
-export type {
-  HandlerDeps,
-  PermissionReviewSource,
-  PromptPermissionDetails,
-} from "./types";
+  extractSkillNameFromInput,
+  getEventInput,
+  PermissionGateHandler,
+} from "./permission-gate-handler";

package/src/handlers/lifecycle.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-import { getActiveAgentName } from "../active-agent";
+import type { PermissionSession } from "../permission-session";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "../status";
-import type { HandlerDeps } from "./types";
 
 /** Minimal subset of SessionStartEvent used by this handler. */
 interface SessionStartPayload {
@@ -14,69 +13,66 @@ interface ResourcesDiscoverPayload {
   reason: string;
 }
 
-export async function handleSessionStart(
-  deps: HandlerDeps,
-  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.forwarding.start(ctx);
-  deps.logResolvedConfigPaths();
+/**
+ * Handles session lifecycle events: start, reload, and shutdown.
+ *
+ * Constructor deps:
+ * - `session` — encapsulates all mutable session state
+ * - `cleanupRpc` — unsubscribes RPC handlers on shutdown
+ */
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly cleanupRpc: () => void,
+  ) {}
 
-  const agentName = deps.session.lastKnownActiveAgentName;
-  const policyIssues =
-    deps.session.permissionManager.getConfigIssues(agentName);
-  for (const issue of policyIssues) {
-    deps.logger.warn(issue);
+  async handleSessionStart(
+    event: SessionStartPayload,
+    ctx: ExtensionContext,
+  ): Promise<void> {
+    const { session } = this;
+    session.refreshConfig(ctx);
+    session.resetForNewSession(ctx);
+    session.logResolvedConfigPaths();
+
+    const agentName = session.resolveAgentName(ctx);
+    const policyIssues = session.getConfigIssues(agentName);
+    for (const issue of policyIssues) {
+      session.logger.warn(issue);
+    }
+
+    if (event.reason === "reload") {
+      session.logger.debug("lifecycle.reload", {
+        triggeredBy: "session_start",
+        reason: event.reason,
+        cwd: ctx.cwd,
+      });
+    }
   }
 
-  if (event.reason === "reload") {
-    deps.logger.debug("lifecycle.reload", {
-      triggeredBy: "session_start",
+  async handleResourcesDiscover(
+    event: ResourcesDiscoverPayload,
+  ): Promise<void> {
+    if (event.reason !== "reload") {
+      return;
+    }
+
+    const { session } = this;
+    session.reload();
+    session.logger.debug("lifecycle.reload", {
+      triggeredBy: "resources_discover",
       reason: event.reason,
-      cwd: ctx.cwd,
+      cwd: session.getRuntimeContext()?.cwd ?? null,
     });
   }
-}
-
-export async function handleResourcesDiscover(
-  deps: HandlerDeps,
-  event: ResourcesDiscoverPayload,
-): Promise<void> {
-  if (event.reason !== "reload") {
-    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", {
-    triggeredBy: "resources_discover",
-    reason: event.reason,
-    cwd: runtimeContext?.cwd ?? null,
-  });
-}
 
-export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
-  const { runtimeContext } = deps.session;
-  if (runtimeContext) {
-    runtimeContext.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+  async handleSessionShutdown(): Promise<void> {
+    const { session } = this;
+    const ctx = session.getRuntimeContext();
+    if (ctx) {
+      ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+    }
+    session.shutdown();
+    this.cleanupRpc();
   }
-  deps.session.runtimeContext = null;
-  deps.session.activeSkillEntries = [];
-  deps.session.lastActiveToolsCacheKey = null;
-  deps.session.lastPromptStateCacheKey = null;
-  deps.session.sessionRules.clear();
-  deps.forwarding.stop();
-  deps.stopPermissionRpcHandlers();
 }