@gotgenes/pi-permission-system 3.6.0 → 3.7.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.7.0](https://github.com/gotgenes/pi-permission-system/compare/v3.6.0...v3.7.0) (2026-05-03)
+
+
+### Features
+
+* define HandlerDeps interface for handler extraction ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([a71e553](https://github.com/gotgenes/pi-permission-system/commit/a71e553ec988b4b222177f90a21519757cb62380))
+* extract before_agent_start handler into src/handlers/before-agent-start.ts ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([9443a99](https://github.com/gotgenes/pi-permission-system/commit/9443a99b0e60b17868fc240782c2b31f53f409af))
+* extract input handler into src/handlers/input.ts ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([196862a](https://github.com/gotgenes/pi-permission-system/commit/196862a86b270628b77f23049eb4902f85cde617))
+* extract lifecycle handlers into src/handlers/lifecycle.ts ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([0edb194](https://github.com/gotgenes/pi-permission-system/commit/0edb194be90b5c5b5465acb4be38fbd2f749cdf9))
+* extract tool_call handler into src/handlers/tool-call.ts ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([a4b81ca](https://github.com/gotgenes/pi-permission-system/commit/a4b81caa34da4959988ac311952a881ffdad72fe))
+
+
+### Documentation
+
+* align handler extraction plan with architecture docs ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([4d91e03](https://github.com/gotgenes/pi-permission-system/commit/4d91e03b9ba11beccc5855d81f1f15be707495b0))
+* **retro:** add retro notes for issue [#55](https://github.com/gotgenes/pi-permission-system/issues/55) ([ee763ff](https://github.com/gotgenes/pi-permission-system/commit/ee763ffccfbf19b9ec3627ea29847251e1505020))
+* update plan with implementation notes for handler extraction ([#42](https://github.com/gotgenes/pi-permission-system/issues/42)) ([73603b2](https://github.com/gotgenes/pi-permission-system/commit/73603b25f5b5a53b0dd4300620b1f8ef8c844353))
+
 ## [3.6.0](https://github.com/gotgenes/pi-permission-system/compare/v3.5.0...v3.6.0) (2026-05-03)
 
 

package/package.json

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

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

@@ -0,0 +1,112 @@
+import type {
+  BeforeAgentStartEventResult,
+  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 { resolveSkillPromptEntries } from "../skill-prompt-sanitizer";
+import { sanitizeAvailableToolsSection } from "../system-prompt-sanitizer";
+import { getToolNameFromValue } from "../tool-registry";
+import type { HandlerDeps } from "./types";
+
+/**
+ * Pure helper: returns true when the tool should be exposed to the agent.
+ * Checks the tool-level permission (not command-level) so that a blanket
+ * `bash: deny` hides the tool entirely before any invocation is attempted.
+ */
+export function shouldExposeTool(
+  toolName: string,
+  agentName: string | null,
+  permissionManager: PermissionManager,
+): boolean {
+  const toolPermission = permissionManager.getToolPermission(
+    toolName,
+    agentName ?? undefined,
+  );
+  return toolPermission !== "deny";
+}
+
+export async function handleBeforeAgentStart(
+  deps: HandlerDeps,
+  event: BeforeAgentStartPayload,
+  ctx: ExtensionContext,
+): Promise<BeforeAgentStartEventResult> {
+  deps.setRuntimeContext(ctx);
+  deps.refreshExtensionConfig(ctx);
+  deps.startForwardedPermissionPolling(ctx);
+
+  const agentName = deps.resolveAgentName(ctx, event.systemPrompt);
+  const permissionManager = deps.getPermissionManager();
+  const allTools = deps.getAllTools();
+  const allowedTools: string[] = [];
+
+  for (const tool of allTools) {
+    const toolName = getToolNameFromValue(tool);
+    if (!toolName) {
+      continue;
+    }
+    if (shouldExposeTool(toolName, agentName, permissionManager)) {
+      allowedTools.push(toolName);
+    }
+  }
+
+  const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
+  if (
+    shouldApplyCachedAgentStartState(
+      deps.getLastActiveToolsCacheKey(),
+      activeToolsCacheKey,
+    )
+  ) {
+    deps.setActiveTools(allowedTools);
+    deps.setLastActiveToolsCacheKey(activeToolsCacheKey);
+  }
+
+  const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
+    agentName,
+    cwd: ctx.cwd,
+    permissionStamp: permissionManager.getPolicyCacheStamp(
+      agentName ?? undefined,
+    ),
+    systemPrompt: event.systemPrompt,
+    allowedToolNames: allowedTools,
+  });
+
+  if (
+    !shouldApplyCachedAgentStartState(
+      deps.getLastPromptStateCacheKey(),
+      promptStateCacheKey,
+    )
+  ) {
+    return {};
+  }
+
+  deps.setLastPromptStateCacheKey(promptStateCacheKey);
+
+  const toolPromptResult = sanitizeAvailableToolsSection(
+    event.systemPrompt,
+    allowedTools,
+  );
+  const skillPromptResult = resolveSkillPromptEntries(
+    toolPromptResult.prompt,
+    permissionManager,
+    agentName,
+    ctx.cwd,
+  );
+  deps.setActiveSkillEntries(skillPromptResult.entries);
+
+  if (skillPromptResult.prompt !== event.systemPrompt) {
+    return { systemPrompt: skillPromptResult.prompt };
+  }
+
+  return {};
+}

package/src/handlers/index.ts

@@ -0,0 +1,16 @@
+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";

package/src/handlers/input.ts

@@ -0,0 +1,97 @@
+import type {
+  ExtensionContext,
+  InputEventResult,
+} from "@mariozechner/pi-coding-agent";
+
+/** Minimal subset of InputEvent used by this handler. */
+interface InputPayload {
+  text: string;
+}
+
+import { applyPermissionGate } from "../permission-gate";
+import { formatSkillAskPrompt } from "../permission-prompts";
+import type { HandlerDeps } from "./types";
+
+/**
+ * Parse a `/skill:<name>` prefix from user input.
+ * Returns the skill name, or null if the text is not a skill invocation.
+ */
+export function extractSkillNameFromInput(text: string): string | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/skill:")) {
+    return null;
+  }
+
+  const afterPrefix = trimmed.slice("/skill:".length);
+  if (!afterPrefix) {
+    return null;
+  }
+
+  const firstWhitespace = afterPrefix.search(/\s/);
+  const skillName = (
+    firstWhitespace === -1 ? afterPrefix : afterPrefix.slice(0, firstWhitespace)
+  ).trim();
+  return skillName || null;
+}
+
+export async function handleInput(
+  deps: HandlerDeps,
+  event: InputPayload,
+  ctx: ExtensionContext,
+): Promise<InputEventResult> {
+  deps.setRuntimeContext(ctx);
+  deps.startForwardedPermissionPolling(ctx);
+
+  const skillName = extractSkillNameFromInput(event.text);
+  if (!skillName) {
+    return { action: "continue" };
+  }
+
+  const agentName = deps.resolveAgentName(ctx);
+  const check = deps
+    .getPermissionManager()
+    .checkPermission("skill", { name: skillName }, agentName ?? undefined);
+
+  if (check.state === "deny" && ctx.hasUI) {
+    const notifyMessage = agentName
+      ? `Skill '${skillName}' is not permitted for agent '${agentName}'.`
+      : `Skill '${skillName}' is not permitted by the current skill policy.`;
+    ctx.ui.notify(notifyMessage, "warning");
+  }
+
+  const skillInputMessage = formatSkillAskPrompt(
+    skillName,
+    agentName ?? undefined,
+  );
+  const skillInputGate = await applyPermissionGate({
+    state: check.state,
+    canConfirm: deps.canRequestPermissionConfirmation(ctx),
+    promptForApproval: () =>
+      deps.promptPermission(ctx, {
+        requestId: deps.createPermissionRequestId("skill-input"),
+        source: "skill_input",
+        agentName,
+        message: skillInputMessage,
+        skillName,
+      }),
+    writeLog: deps.writeReviewLog,
+    logContext: {
+      source: "skill_input",
+      skillName,
+      agentName,
+      message: skillInputMessage,
+    },
+    messages: {
+      denyReason: skillInputMessage,
+      unavailableReason:
+        "Skill requires approval, but no interactive UI is available.",
+      userDeniedReason: () => "User denied skill.",
+    },
+  });
+
+  if (skillInputGate.action === "block") {
+    return { action: "handled" };
+  }
+
+  return { action: "continue" };
+}

package/src/handlers/lifecycle.ts

@@ -0,0 +1,80 @@
+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";
+
+/** Minimal subset of SessionStartEvent used by this handler. */
+interface SessionStartPayload {
+  reason: string;
+}
+
+/** Minimal subset of ResourcesDiscoverEvent used by this handler. */
+interface ResourcesDiscoverPayload {
+  reason: string;
+}
+
+export async function handleSessionStart(
+  deps: HandlerDeps,
+  event: SessionStartPayload,
+  ctx: ExtensionContext,
+): Promise<void> {
+  deps.setRuntimeContext(ctx);
+  deps.refreshExtensionConfig(ctx);
+  deps.setPermissionManager(deps.createPermissionManagerForCwd(ctx.cwd));
+  deps.setActiveSkillEntries([]);
+  deps.setLastActiveToolsCacheKey(null);
+  deps.setLastPromptStateCacheKey(null);
+  deps.setLastKnownActiveAgentName(getActiveAgentName(ctx));
+  deps.startForwardedPermissionPolling(ctx);
+  deps.logResolvedConfigPaths();
+
+  const agentName = deps.getLastKnownActiveAgentName();
+  const policyIssues = deps.getPermissionManager().getConfigIssues(agentName);
+  for (const issue of policyIssues) {
+    deps.notifyWarning(issue);
+  }
+
+  if (event.reason === "reload") {
+    deps.writeDebugLog("lifecycle.reload", {
+      triggeredBy: "session_start",
+      reason: event.reason,
+      cwd: ctx.cwd,
+    });
+  }
+}
+
+export async function handleResourcesDiscover(
+  deps: HandlerDeps,
+  event: ResourcesDiscoverPayload,
+): Promise<void> {
+  if (event.reason !== "reload") {
+    return;
+  }
+
+  const runtimeContext = deps.getRuntimeContext();
+  deps.setPermissionManager(
+    deps.createPermissionManagerForCwd(runtimeContext?.cwd),
+  );
+  deps.setActiveSkillEntries([]);
+  deps.setLastActiveToolsCacheKey(null);
+  deps.setLastPromptStateCacheKey(null);
+  deps.writeDebugLog("lifecycle.reload", {
+    triggeredBy: "resources_discover",
+    reason: event.reason,
+    cwd: runtimeContext?.cwd ?? null,
+  });
+}
+
+export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
+  const ctx = deps.getRuntimeContext();
+  if (ctx) {
+    ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+  }
+  deps.setRuntimeContext(null);
+  deps.setActiveSkillEntries([]);
+  deps.setLastActiveToolsCacheKey(null);
+  deps.setLastPromptStateCacheKey(null);
+  deps.sessionApprovalCache.clear();
+  deps.stopForwardedPermissionPolling();
+}