@gotgenes/pi-permission-system 5.10.0 → 5.11.1

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.11.1](https://github.com/gotgenes/pi-permission-system/compare/v5.11.0...v5.11.1) (2026-05-08)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#130](https://github.com/gotgenes/pi-permission-system/issues/130) ([e2ed7cb](https://github.com/gotgenes/pi-permission-system/commit/e2ed7cbbabe2dabf5689704c14b59fc662c1e7d4))
+
+
+### Miscellaneous Chores
+
+* migrate @mariozechner/* deps to @earendil-works/* ([8908be1](https://github.com/gotgenes/pi-permission-system/commit/8908be17624a60ff3272b9e0e0a720a239de2de5))
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.10.0",
+  "version": "5.11.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [
@@ -48,13 +48,13 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@mariozechner/pi-coding-agent": "^0.72.1",
-    "@mariozechner/pi-tui": "^0.72.1",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
     "@types/node": "^25.6.0",
     "markdownlint-cli2": "^0.22.1",
     "typescript": "6.0.3",

package/src/active-agent.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 /**
  * Matches the `<active_agent name="...">` tag injected by pi-agent-router

package/src/config-modal.ts

@@ -2,8 +2,8 @@ import {
   type ExtensionAPI,
   type ExtensionCommandContext,
   getSettingsListTheme,
-} from "@mariozechner/pi-coding-agent";
-import { type SettingItem, SettingsList } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { type SettingItem, SettingsList } from "@earendil-works/pi-tui";
 
 import {
   DEFAULT_EXTENSION_CONFIG,

package/src/forwarded-permissions/polling.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
   getActiveAgentName,

package/src/forwarding-manager.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
 import { processForwardedPermissionRequests } from "./forwarded-permissions/polling";
@@ -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

@@ -1,22 +1,22 @@
 import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
-} from "@mariozechner/pi-coding-agent";
-
-/** Minimal subset of BeforeAgentStartEvent used by this handler. */
-interface BeforeAgentStartPayload {
-  systemPrompt: string;
-}
+} from "@earendil-works/pi-coding-agent";
 
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
 } from "../before-agent-start-cache";
+import type { PermissionSession } from "../permission-session";
 import { resolveSkillPromptEntries } from "../skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "../system-prompt-sanitizer";
-import { getToolNameFromValue } from "../tool-registry";
+import { getToolNameFromValue, type ToolRegistry } from "../tool-registry";
 import type { PermissionState } from "../types";
-import type { HandlerDeps } 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.
@@ -32,68 +32,81 @@ export function shouldExposeTool(
   return toolPermission !== "deny";
 }
 
-export async function handleBeforeAgentStart(
-  deps: HandlerDeps,
-  event: BeforeAgentStartPayload,
-  ctx: ExtensionContext,
-): Promise<BeforeAgentStartEventResult> {
-  const { session } = deps;
-  session.activate(ctx);
-  session.refreshConfig(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 = session.resolveAgentName(ctx, event.systemPrompt);
-  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, (t, a) =>
-        session.getToolPermission(t, a),
-      )
-    ) {
-      allowedTools.push(toolName);
+
+    const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
+    if (session.shouldUpdateActiveTools(activeToolsCacheKey)) {
+      this.toolRegistry.setActive(allowedTools);
+      session.commitActiveToolsCacheKey(activeToolsCacheKey);
     }
-  }
 
-  const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-  if (session.shouldUpdateActiveTools(activeToolsCacheKey)) {
-    deps.setActiveTools(allowedTools);
-    session.commitActiveToolsCacheKey(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: session.getPolicyCacheStamp(agentName ?? undefined),
-    systemPrompt: event.systemPrompt,
-    allowedToolNames: allowedTools,
-  });
+    if (!session.shouldUpdatePromptState(promptStateCacheKey)) {
+      return {};
+    }
 
-  if (!session.shouldUpdatePromptState(promptStateCacheKey)) {
-    return {};
-  }
+    session.commitPromptStateCacheKey(promptStateCacheKey);
 
-  session.commitPromptStateCacheKey(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,
-    session,
-    agentName,
-    ctx.cwd,
-  );
-  session.setActiveSkillEntries(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,7 +1,7 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-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 {
@@ -13,54 +13,66 @@ interface ResourcesDiscoverPayload {
   reason: string;
 }
 
-export async function handleSessionStart(
-  deps: HandlerDeps,
-  event: SessionStartPayload,
-  ctx: ExtensionContext,
-): Promise<void> {
-  const { session } = deps;
-  session.refreshConfig(ctx);
-  session.resetForNewSession(ctx);
-  session.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 = session.resolveAgentName(ctx);
-  const policyIssues = session.getConfigIssues(agentName);
-  for (const issue of policyIssues) {
-    session.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") {
+  async handleResourcesDiscover(
+    event: ResourcesDiscoverPayload,
+  ): Promise<void> {
+    if (event.reason !== "reload") {
+      return;
+    }
+
+    const { session } = this;
+    session.reload();
     session.logger.debug("lifecycle.reload", {
-      triggeredBy: "session_start",
+      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 { session } = deps;
-  session.reload();
-  session.logger.debug("lifecycle.reload", {
-    triggeredBy: "resources_discover",
-    reason: event.reason,
-    cwd: session.getRuntimeContext()?.cwd ?? null,
-  });
-}
 
-export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
-  const { session } = deps;
-  const ctx = session.getRuntimeContext();
-  if (ctx) {
-    ctx.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();
   }
-  session.shutdown();
-  deps.stopPermissionRpcHandlers();
 }