@gotgenes/pi-permission-system 3.5.0 → 3.7.0

package/src/index.ts

@@ -11,18 +11,11 @@ import {
   type ExtensionCommandContext,
   type ExtensionContext,
   getAgentDir,
-  isToolCallEventType,
 } from "@mariozechner/pi-coding-agent";
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
-import {
-  createActiveToolsCacheKey,
-  createBeforeAgentStartPromptStateKey,
-  shouldApplyCachedAgentStartState,
-} from "./before-agent-start-cache";
-import { getNonEmptyString, toRecord } from "./common";
 import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
 import { registerPermissionSystemCommand } from "./config-modal";
 import {
@@ -43,63 +36,36 @@ import {
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
-import {
-  extractExternalPathsFromBashCommand,
-  formatBashExternalDirectoryAskPrompt,
-  formatBashExternalDirectoryDenyReason,
-  formatExternalDirectoryAskPrompt,
-  formatExternalDirectoryDenyReason,
-  formatExternalDirectoryHardStopHint,
-  formatExternalDirectoryUserDeniedReason,
-  getPathBearingToolPath,
-  isPathOutsideWorkingDirectory,
-  normalizePathForComparison,
-  PATH_BEARING_TOOLS,
-} from "./external-directory";
 import { setForwardedPermissionLogger } from "./forwarded-permissions/io";
 import {
   confirmPermission,
   type PermissionForwardingDeps,
   processForwardedPermissionRequests,
 } from "./forwarded-permissions/polling";
+import {
+  type HandlerDeps,
+  handleBeforeAgentStart,
+  handleInput,
+  handleResourcesDiscover,
+  handleSessionShutdown,
+  handleSessionStart,
+  handleToolCall,
+} from "./handlers";
+import type { PromptPermissionDetails } from "./handlers/types";
 import { createPermissionSystemLogger } from "./logging";
 import {
   type PermissionPromptDecision,
   requestPermissionDecisionFromUi,
 } from "./permission-dialog";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
-import { applyPermissionGate } from "./permission-gate";
 import { PermissionManager } from "./permission-manager";
-import {
-  formatAskPrompt,
-  formatDenyReason,
-  formatMissingToolNameReason,
-  formatSkillAskPrompt,
-  formatSkillPathAskPrompt,
-  formatSkillPathDenyReason,
-  formatUnknownToolReason,
-  formatUserDeniedReason,
-} from "./permission-prompts";
-import {
-  deriveApprovalPrefix,
-  SessionApprovalCache,
-} from "./session-approval-cache";
-import {
-  findSkillPathMatch,
-  resolveSkillPromptEntries,
-  type SkillPromptEntry,
-} from "./skill-prompt-sanitizer";
+import { SessionApprovalCache } from "./session-approval-cache";
+import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import {
   PERMISSION_SYSTEM_STATUS_KEY,
   syncPermissionSystemStatus,
 } from "./status";
 import { isSubagentExecutionContext } from "./subagent-context";
-import { sanitizeAvailableToolsSection } from "./system-prompt-sanitizer";
-import { getPermissionLogContext } from "./tool-input-preview";
-import {
-  checkRequestedToolRegistration,
-  getToolNameFromValue,
-} from "./tool-registry";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -110,8 +76,6 @@ const SESSIONS_DIR = join(PI_AGENT_DIR, "sessions");
 const SUBAGENT_SESSIONS_DIR = join(PI_AGENT_DIR, "subagent-sessions");
 const PERMISSION_FORWARDING_DIR = join(SESSIONS_DIR, "permission-forwarding");
 
-type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
-
 let extensionConfig: PermissionSystemExtensionConfig = {
   ...DEFAULT_EXTENSION_CONFIG,
 };
@@ -140,7 +104,6 @@ function reportLoggingWarning(message: string): void {
   if (!loggingWarningReporter || reportedLoggingWarnings.has(message)) {
     return;
   }
-
   reportedLoggingWarnings.add(message);
   loggingWarningReporter(message);
 }
@@ -165,50 +128,6 @@ function writeReviewLog(
   }
 }
 
-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;
-}
-
-function getEventToolName(event: unknown): string | null {
-  return getToolNameFromValue(event);
-}
-
-function getEventInput(event: unknown): unknown {
-  const record = toRecord(event);
-
-  if (record.input !== undefined) {
-    return record.input;
-  }
-
-  if (record.arguments !== undefined) {
-    return record.arguments;
-  }
-
-  return {};
-}
-
-function canRequestPermissionConfirmation(ctx: ExtensionContext): boolean {
-  return canResolveAskPermissionRequest({
-    config: extensionConfig,
-    hasUI: ctx.hasUI,
-    isSubagent: isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR),
-  });
-}
-
 function derivePiProjectPaths(cwd: string | undefined | null): {
   projectGlobalConfigPath: string;
   projectAgentsDir: string;
@@ -216,7 +135,6 @@ function derivePiProjectPaths(cwd: string | undefined | null): {
   if (!cwd) {
     return null;
   }
-
   return {
     projectGlobalConfigPath: getProjectConfigPath(cwd),
     projectAgentsDir: join(cwd, ".pi", "agent", "agents"),
@@ -228,7 +146,6 @@ function createPermissionManagerForCwd(
 ): PermissionManager {
   const agentDir = getAgentDir();
   const projectPaths = derivePiProjectPaths(cwd);
-
   return new PermissionManager({
     globalConfigPath: getGlobalConfigPath(agentDir),
     projectGlobalConfigPath: projectPaths?.projectGlobalConfigPath,
@@ -249,17 +166,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   let runtimeContext: ExtensionContext | null = null;
   let lastConfigWarning: string | null = null;
 
-  const invalidateAgentStartCache = (): void => {
-    activeSkillEntries = [];
-    lastActiveToolsCacheKey = null;
-    lastPromptStateCacheKey = null;
-  };
-
   const notifyWarning = (message: string): void => {
     if (!runtimeContext?.hasUI) {
       return;
     }
-
     runtimeContext.ui.notify(message, "warning");
   };
 
@@ -267,7 +177,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     if (ctx) {
       runtimeContext = ctx;
     }
-
     const cwd = runtimeContext?.cwd ?? null;
     const agentDir = getAgentDir();
     const mergeResult = loadAndMergeConfigs(
@@ -306,7 +215,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     const normalized = normalizePermissionSystemConfig(next);
     const globalPath = getGlobalConfigPath(getAgentDir());
 
-    // Load existing global config and merge runtime knobs into it
     const existing = loadUnifiedConfig(globalPath);
     const merged = {
       ...existing.config,
@@ -366,24 +274,44 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     getConfigPath: () => getGlobalConfigPath(getAgentDir()),
   });
 
-  const createPermissionRequestId = (prefix: string): string => {
-    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+  const stopForwardedPermissionPolling = (): void => {
+    if (permissionForwardingTimer) {
+      clearInterval(permissionForwardingTimer);
+      permissionForwardingTimer = null;
+    }
+    permissionForwardingContext = null;
+    isProcessingForwardedRequests = false;
+  };
+
+  const startForwardedPermissionPolling = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI || isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR)) {
+      stopForwardedPermissionPolling();
+      return;
+    }
+    permissionForwardingContext = ctx;
+    if (permissionForwardingTimer) {
+      return;
+    }
+    permissionForwardingTimer = setInterval(() => {
+      if (!permissionForwardingContext || isProcessingForwardedRequests) {
+        return;
+      }
+      isProcessingForwardedRequests = true;
+      void processForwardedPermissionRequests(
+        permissionForwardingContext,
+        forwardingDeps,
+      ).finally(() => {
+        isProcessingForwardedRequests = false;
+      });
+    }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
   };
 
+  const createPermissionRequestId = (prefix: string): string =>
+    `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+
   const reviewPermissionDecision = (
     event: string,
-    details: {
-      requestId: string;
-      source: PermissionReviewSource;
-      agentName: string | null;
-      message: string;
-      toolCallId?: string;
-      toolName?: string;
-      skillName?: string;
-      path?: string;
-      command?: string;
-      target?: string;
-      toolInputPreview?: string;
+    details: PromptPermissionDetails & {
       resolution?: string;
       denialReason?: string;
     },
@@ -407,27 +335,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const promptPermission = async (
     ctx: ExtensionContext,
-    details: {
-      requestId: string;
-      source: PermissionReviewSource;
-      agentName: string | null;
-      message: string;
-      toolCallId?: string;
-      toolName?: string;
-      skillName?: string;
-      path?: string;
-      command?: string;
-      target?: string;
-      toolInputPreview?: string;
-    },
+    details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> => {
     if (shouldAutoApprovePermissionState("ask", extensionConfig)) {
       reviewPermissionDecision("permission_request.auto_approved", details);
       return { approved: true, state: "approved" };
     }
-
     reviewPermissionDecision("permission_request.waiting", details);
-
     const decision = await confirmPermission(
       ctx,
       details.message,
@@ -446,42 +360,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     return decision;
   };
 
-  const stopForwardedPermissionPolling = (): void => {
-    if (permissionForwardingTimer) {
-      clearInterval(permissionForwardingTimer);
-      permissionForwardingTimer = null;
-    }
-
-    permissionForwardingContext = null;
-    isProcessingForwardedRequests = false;
-  };
-
-  const startForwardedPermissionPolling = (ctx: ExtensionContext): void => {
-    if (!ctx.hasUI || isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR)) {
-      stopForwardedPermissionPolling();
-      return;
-    }
-
-    permissionForwardingContext = ctx;
-    if (permissionForwardingTimer) {
-      return;
-    }
-
-    permissionForwardingTimer = setInterval(() => {
-      if (!permissionForwardingContext || isProcessingForwardedRequests) {
-        return;
-      }
-
-      isProcessingForwardedRequests = true;
-      void processForwardedPermissionRequests(
-        permissionForwardingContext,
-        forwardingDeps,
-      ).finally(() => {
-        isProcessingForwardedRequests = false;
-      });
-    }, PERMISSION_FORWARDING_POLL_INTERVAL_MS);
-  };
-
   const resolveAgentName = (
     ctx: ExtensionContext,
     systemPrompt?: string,
@@ -491,35 +369,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       lastKnownActiveAgentName = fromSession;
       return fromSession;
     }
-
     const fromSystemPrompt = getActiveAgentNameFromSystemPrompt(systemPrompt);
     if (fromSystemPrompt) {
       lastKnownActiveAgentName = fromSystemPrompt;
       return fromSystemPrompt;
     }
-
     return lastKnownActiveAgentName;
   };
 
-  const shouldExposeTool = (
-    toolName: string,
-    agentName: string | null,
-  ): boolean => {
-    // Use tool-level permission check for tool injection decisions
-    // This ensures that agent-specific tool deny rules (e.g., bash: deny) are respected
-    // before any command-level permissions are considered
-    const toolPermission = permissionManager.getToolPermission(
-      toolName,
-      agentName ?? undefined,
-    );
-    return toolPermission !== "deny";
-  };
-
   const logResolvedConfigPaths = (): void => {
     const policyPaths = permissionManager.getResolvedPolicyPaths();
     const cwd = runtimeContext?.cwd ?? null;
-
-    // Detect legacy files for the log entry
     const agentDir = getAgentDir();
     const legacyGlobalPolicyDetected = existsSync(
       getLegacyGlobalPolicyPath(agentDir),
@@ -532,7 +392,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     const legacyExtensionConfigDetected =
       normalize(legacyExtConfigPath) !== normalize(newGlobalPath) &&
       existsSync(legacyExtConfigPath);
-
     const entry = buildResolvedConfigLogEntry({
       policyPaths,
       legacyGlobalPolicyDetected,
@@ -549,518 +408,59 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     );
   };
 
-  pi.on("session_start", async (event, ctx) => {
-    runtimeContext = ctx;
-    refreshExtensionConfig(ctx);
-    permissionManager = createPermissionManagerForCwd(ctx.cwd);
-    invalidateAgentStartCache();
-    lastKnownActiveAgentName = getActiveAgentName(ctx);
-    startForwardedPermissionPolling(ctx);
-    logResolvedConfigPaths();
-
-    const policyIssues = permissionManager.getConfigIssues(
-      lastKnownActiveAgentName,
-    );
-    for (const issue of policyIssues) {
-      notifyWarning(issue);
-    }
-
-    if (event.reason === "reload") {
-      writeDebugLog("lifecycle.reload", {
-        triggeredBy: "session_start",
-        reason: event.reason,
-        cwd: ctx.cwd,
-      });
-    }
-  });
-
-  pi.on("resources_discover", async (event, _ctx) => {
-    if (event.reason === "reload") {
-      permissionManager = runtimeContext
-        ? createPermissionManagerForCwd(runtimeContext.cwd)
-        : new PermissionManager();
-      invalidateAgentStartCache();
-      writeDebugLog("lifecycle.reload", {
-        triggeredBy: "resources_discover",
-        reason: event.reason,
-        cwd: runtimeContext?.cwd ?? null,
-      });
-    }
-  });
-
-  pi.on("session_shutdown", async () => {
-    runtimeContext?.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
-    runtimeContext = null;
-    invalidateAgentStartCache();
-    sessionApprovalCache.clear();
-    stopForwardedPermissionPolling();
-  });
-
-  pi.on("before_agent_start", async (event, ctx) => {
-    runtimeContext = ctx;
-    refreshExtensionConfig(ctx);
-    startForwardedPermissionPolling(ctx);
-    const agentName = resolveAgentName(ctx, event.systemPrompt);
-    const allTools = pi.getAllTools();
-    const allowedTools: string[] = [];
-
-    for (const tool of allTools) {
-      const toolName = getEventToolName(tool);
-      if (!toolName) {
-        continue;
-      }
-
-      if (shouldExposeTool(toolName, agentName)) {
-        allowedTools.push(toolName);
-      }
-    }
-
-    const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-    if (
-      shouldApplyCachedAgentStartState(
-        lastActiveToolsCacheKey,
-        activeToolsCacheKey,
-      )
-    ) {
-      pi.setActiveTools(allowedTools);
-      lastActiveToolsCacheKey = activeToolsCacheKey;
-    }
-
-    const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
-      agentName,
-      cwd: ctx.cwd,
-      permissionStamp: permissionManager.getPolicyCacheStamp(
-        agentName ?? undefined,
-      ),
-      systemPrompt: event.systemPrompt,
-      allowedToolNames: allowedTools,
-    });
-
-    if (
-      !shouldApplyCachedAgentStartState(
-        lastPromptStateCacheKey,
-        promptStateCacheKey,
-      )
-    ) {
-      return {};
-    }
-
-    lastPromptStateCacheKey = promptStateCacheKey;
-    const toolPromptResult = sanitizeAvailableToolsSection(
-      event.systemPrompt,
-      allowedTools,
-    );
-    const skillPromptResult = resolveSkillPromptEntries(
-      toolPromptResult.prompt,
-      permissionManager,
-      agentName,
-      ctx.cwd,
-    );
-    activeSkillEntries = skillPromptResult.entries;
-
-    if (skillPromptResult.prompt !== event.systemPrompt) {
-      return { systemPrompt: skillPromptResult.prompt };
-    }
-
-    return {};
-  });
-
-  pi.on("input", async (event, ctx) => {
-    runtimeContext = ctx;
-    startForwardedPermissionPolling(ctx);
-    const skillName = extractSkillNameFromInput(event.text);
-    if (!skillName) {
-      return { action: "continue" };
-    }
-
-    const agentName = resolveAgentName(ctx);
-    const check = permissionManager.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: canRequestPermissionConfirmation(ctx),
-      promptForApproval: () =>
-        promptPermission(ctx, {
-          requestId: createPermissionRequestId("skill-input"),
-          source: "skill_input",
-          agentName,
-          message: skillInputMessage,
-          skillName,
-        }),
-      writeLog: 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" };
-  });
-
-  pi.on("tool_call", async (event, ctx) => {
-    runtimeContext = ctx;
-    startForwardedPermissionPolling(ctx);
-    const agentName = resolveAgentName(ctx);
-    const toolName = getEventToolName(event);
-
-    if (!toolName) {
-      return { block: true, reason: formatMissingToolNameReason() };
-    }
-
-    const registrationCheck = checkRequestedToolRegistration(
-      toolName,
-      pi.getAllTools(),
-    );
-    if (registrationCheck.status === "missing-tool-name") {
-      return { block: true, reason: formatMissingToolNameReason() };
-    }
-
-    if (registrationCheck.status === "unregistered") {
-      return {
-        block: true,
-        reason: formatUnknownToolReason(
-          registrationCheck.requestedToolName,
-          registrationCheck.availableToolNames,
-        ),
-      };
-    }
-
-    if (isToolCallEventType("read", event) && activeSkillEntries.length > 0) {
-      const normalizedReadPath = normalizePathForComparison(
-        event.input.path,
-        ctx.cwd,
-      );
-      const matchedSkill = findSkillPathMatch(
-        normalizedReadPath,
-        activeSkillEntries,
-      );
-
-      if (matchedSkill) {
-        const skillReadMessage = formatSkillPathAskPrompt(
-          matchedSkill,
-          event.input.path,
-          agentName ?? undefined,
-        );
-        const skillReadGate = await applyPermissionGate({
-          state: matchedSkill.state,
-          canConfirm: canRequestPermissionConfirmation(ctx),
-          promptForApproval: () =>
-            promptPermission(ctx, {
-              requestId: event.toolCallId,
-              source: "skill_read",
-              agentName,
-              message: skillReadMessage,
-              toolCallId: event.toolCallId,
-              toolName: toolName,
-              skillName: matchedSkill.name,
-              path: event.input.path,
-            }),
-          writeLog: writeReviewLog,
-          logContext: {
-            source: "skill_read",
-            skillName: matchedSkill.name,
-            agentName,
-            path: event.input.path,
-            message: skillReadMessage,
-          },
-          messages: {
-            denyReason: formatSkillPathDenyReason(
-              matchedSkill,
-              event.input.path,
-              agentName ?? undefined,
-            ),
-            unavailableReason: `Accessing skill '${matchedSkill.name}' requires approval, but no interactive UI is available.`,
-            userDeniedReason: (decision) => {
-              const denialReason = decision.denialReason
-                ? ` Reason: ${decision.denialReason}.`
-                : "";
-              return `User denied access to skill '${matchedSkill.name}'.${denialReason}`;
-            },
-          },
-        });
-        if (skillReadGate.action === "block") {
-          return { block: true, reason: skillReadGate.reason };
-        }
-      }
-    }
-
-    const input = getEventInput(event);
-    const externalDirectoryPath = ctx.cwd
-      ? getPathBearingToolPath(toolName, input)
-      : null;
-
-    if (
-      ctx.cwd &&
-      externalDirectoryPath &&
-      isPathOutsideWorkingDirectory(externalDirectoryPath, ctx.cwd)
-    ) {
-      const normalizedExtPath = normalizePathForComparison(
-        externalDirectoryPath,
-        ctx.cwd,
-      );
-      const sessionPrefix = sessionApprovalCache.findMatchingPrefix(
-        "external_directory",
-        normalizedExtPath,
-      );
-
-      if (sessionPrefix) {
-        writeReviewLog("permission_request.session_approved", {
-          source: "tool_call",
-          toolCallId: event.toolCallId,
-          toolName,
-          agentName,
-          path: externalDirectoryPath,
-          resolution: "session_approved",
-          sessionApprovalPrefix: sessionPrefix,
-        });
-        // Fall through to normal permission check
-      } else {
-        const extCheck = permissionManager.checkPermission(
-          "external_directory",
-          {},
-          agentName ?? undefined,
-        );
-
-        let extDirDecision: PermissionPromptDecision | null = null;
-        const extDirMessage = formatExternalDirectoryAskPrompt(
-          toolName,
-          externalDirectoryPath,
-          ctx.cwd,
-          agentName ?? undefined,
-        );
-        const extDirGate = await applyPermissionGate({
-          state: extCheck.state,
-          canConfirm: canRequestPermissionConfirmation(ctx),
-          promptForApproval: async () => {
-            const decision = await promptPermission(ctx, {
-              requestId: event.toolCallId,
-              source: "tool_call",
-              agentName,
-              message: extDirMessage,
-              toolCallId: event.toolCallId,
-              toolName,
-              path: externalDirectoryPath,
-            });
-            extDirDecision = decision;
-            return decision;
-          },
-          writeLog: writeReviewLog,
-          logContext: {
-            source: "tool_call",
-            toolCallId: event.toolCallId,
-            toolName,
-            agentName,
-            path: externalDirectoryPath,
-            message: extDirMessage,
-          },
-          messages: {
-            denyReason: formatExternalDirectoryDenyReason(
-              toolName,
-              externalDirectoryPath,
-              ctx.cwd,
-              agentName ?? undefined,
-            ),
-            unavailableReason: `Accessing '${externalDirectoryPath}' outside the working directory requires approval, but no interactive UI is available.`,
-            userDeniedReason: (decision) =>
-              formatExternalDirectoryUserDeniedReason(
-                toolName,
-                externalDirectoryPath,
-                decision.denialReason,
-              ),
-          },
-        });
-        if (extDirGate.action === "block") {
-          return { block: true, reason: extDirGate.reason };
-        }
-
-        if (extDirDecision?.state === "approved_for_session") {
-          const prefix = deriveApprovalPrefix(normalizedExtPath);
-          sessionApprovalCache.approve("external_directory", prefix);
-        }
-      }
-      // Fall through to normal permission check
-    }
-
-    // Bash external directory gate: extract paths from bash commands
-    if (ctx.cwd && toolName === "bash") {
-      const command = getNonEmptyString(toRecord(input).command);
-      if (command) {
-        const externalPaths = extractExternalPathsFromBashCommand(
-          command,
-          ctx.cwd,
-        );
-        if (externalPaths.length > 0) {
-          // Filter out paths already covered by session approvals
-          const uncoveredPaths = externalPaths.filter(
-            (p) => !sessionApprovalCache.has("external_directory", p),
-          );
-
-          if (uncoveredPaths.length === 0) {
-            // All external paths are session-approved
-            writeReviewLog("permission_request.session_approved", {
-              source: "tool_call",
-              toolCallId: event.toolCallId,
-              toolName,
-              agentName,
-              command,
-              externalPaths,
-              resolution: "session_approved",
-            });
-            // Fall through to normal bash permission check
-          } else {
-            const extCheck = permissionManager.checkPermission(
-              "external_directory",
-              {},
-              agentName ?? undefined,
-            );
-
-            let bashExtDecision: PermissionPromptDecision | null = null;
-            const bashExtMessage = formatBashExternalDirectoryAskPrompt(
-              command,
-              uncoveredPaths,
-              ctx.cwd,
-              agentName ?? undefined,
-            );
-            const bashExtGate = await applyPermissionGate({
-              state: extCheck.state,
-              canConfirm: canRequestPermissionConfirmation(ctx),
-              promptForApproval: async () => {
-                const decision = await promptPermission(ctx, {
-                  requestId: event.toolCallId,
-                  source: "tool_call",
-                  agentName,
-                  message: bashExtMessage,
-                  toolCallId: event.toolCallId,
-                  toolName,
-                  command,
-                });
-                bashExtDecision = decision;
-                return decision;
-              },
-              writeLog: writeReviewLog,
-              logContext: {
-                source: "tool_call",
-                toolCallId: event.toolCallId,
-                toolName,
-                agentName,
-                command,
-                externalPaths: uncoveredPaths,
-                message: bashExtMessage,
-              },
-              messages: {
-                denyReason: formatBashExternalDirectoryDenyReason(
-                  command,
-                  uncoveredPaths,
-                  ctx.cwd,
-                  agentName ?? undefined,
-                ),
-                unavailableReason: `Bash command '${command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`,
-                userDeniedReason: (decision) => {
-                  const reasonSuffix = decision.denialReason
-                    ? ` Reason: ${decision.denialReason}.`
-                    : "";
-                  return `User denied external directory access for bash command '${command}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
-                },
-              },
-            });
-            if (bashExtGate.action === "block") {
-              return { block: true, reason: bashExtGate.reason };
-            }
-
-            if (bashExtDecision?.state === "approved_for_session") {
-              for (const extPath of uncoveredPaths) {
-                const prefix = deriveApprovalPrefix(extPath);
-                sessionApprovalCache.approve("external_directory", prefix);
-              }
-            }
-          }
-          // Fall through to normal bash permission check
-        }
-      }
-    }
-
-    const check = permissionManager.checkPermission(
-      toolName,
-      input,
-      agentName ?? undefined,
-    );
-    const permissionLogContext = getPermissionLogContext(
-      check,
-      input,
-      PATH_BEARING_TOOLS,
-    );
-
-    const toolUnavailableReason =
-      toolName === "bash" && isToolCallEventType("bash", event)
-        ? `Running bash command '${event.input.command}' requires approval, but no interactive UI is available.`
-        : toolName === "mcp"
-          ? "Using tool 'mcp' requires approval, but no interactive UI is available."
-          : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
-
-    const toolAskMessage = formatAskPrompt(
-      check,
-      agentName ?? undefined,
-      input,
-    );
-    const toolGate = await applyPermissionGate({
-      state: check.state,
-      canConfirm: canRequestPermissionConfirmation(ctx),
-      promptForApproval: () =>
-        promptPermission(ctx, {
-          requestId: event.toolCallId,
-          source: "tool_call",
-          agentName,
-          message: toolAskMessage,
-          toolCallId: event.toolCallId,
-          toolName,
-          ...permissionLogContext,
-        }),
-      writeLog: writeReviewLog,
-      logContext: {
-        source: "tool_call",
-        toolCallId: event.toolCallId,
-        toolName,
-        agentName,
-        message: toolAskMessage,
-        ...permissionLogContext,
-      },
-      messages: {
-        denyReason: formatDenyReason(check, agentName ?? undefined),
-        unavailableReason: toolUnavailableReason,
-        userDeniedReason: (decision) =>
-          formatUserDeniedReason(check, decision.denialReason),
-      },
-    });
-    if (toolGate.action === "block") {
-      return { block: true, reason: toolGate.reason };
-    }
+  const deps: HandlerDeps = {
+    getPermissionManager: () => permissionManager,
+    setPermissionManager: (pm) => {
+      permissionManager = pm;
+    },
+    getRuntimeContext: () => runtimeContext,
+    setRuntimeContext: (ctx) => {
+      runtimeContext = ctx;
+    },
+    getActiveSkillEntries: () => activeSkillEntries,
+    setActiveSkillEntries: (entries) => {
+      activeSkillEntries = entries;
+    },
+    getLastKnownActiveAgentName: () => lastKnownActiveAgentName,
+    setLastKnownActiveAgentName: (name) => {
+      lastKnownActiveAgentName = name;
+    },
+    getLastActiveToolsCacheKey: () => lastActiveToolsCacheKey,
+    setLastActiveToolsCacheKey: (key) => {
+      lastActiveToolsCacheKey = key;
+    },
+    getLastPromptStateCacheKey: () => lastPromptStateCacheKey,
+    setLastPromptStateCacheKey: (key) => {
+      lastPromptStateCacheKey = key;
+    },
+    sessionApprovalCache,
+    createPermissionManagerForCwd,
+    refreshExtensionConfig,
+    notifyWarning,
+    logResolvedConfigPaths,
+    resolveAgentName,
+    canRequestPermissionConfirmation: (ctx) =>
+      canResolveAskPermissionRequest({
+        config: extensionConfig,
+        hasUI: ctx.hasUI,
+        isSubagent: isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR),
+      }),
+    promptPermission,
+    createPermissionRequestId,
+    startForwardedPermissionPolling,
+    stopForwardedPermissionPolling,
+    writeReviewLog,
+    writeDebugLog,
+    getAllTools: () => pi.getAllTools(),
+    setActiveTools: (names) => pi.setActiveTools(names),
+  };
 
-    return {};
-  });
+  pi.on("session_start", (event, ctx) => handleSessionStart(deps, event, ctx));
+  pi.on("resources_discover", (event) => handleResourcesDiscover(deps, event));
+  pi.on("session_shutdown", () => handleSessionShutdown(deps));
+  pi.on("before_agent_start", (event, ctx) =>
+    handleBeforeAgentStart(deps, event, ctx),
+  );
+  pi.on("input", (event, ctx) => handleInput(deps, event, ctx));
+  pi.on("tool_call", (event, ctx) => handleToolCall(deps, event, ctx));
 }