@gotgenes/pi-permission-system 3.6.0 → 3.7.0

package/src/handlers/tool-call.ts

@@ -0,0 +1,400 @@
+import type {
+  ExtensionContext,
+  ToolCallEvent,
+} from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+
+import { getNonEmptyString, toRecord } from "../common";
+import {
+  extractExternalPathsFromBashCommand,
+  formatBashExternalDirectoryAskPrompt,
+  formatBashExternalDirectoryDenyReason,
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryHardStopHint,
+  formatExternalDirectoryUserDeniedReason,
+  getPathBearingToolPath,
+  isPathOutsideWorkingDirectory,
+  normalizePathForComparison,
+  PATH_BEARING_TOOLS,
+} from "../external-directory";
+import type { PermissionPromptDecision } from "../permission-dialog";
+import { applyPermissionGate } from "../permission-gate";
+import {
+  formatAskPrompt,
+  formatDenyReason,
+  formatMissingToolNameReason,
+  formatSkillPathAskPrompt,
+  formatSkillPathDenyReason,
+  formatUnknownToolReason,
+  formatUserDeniedReason,
+} from "../permission-prompts";
+import { deriveApprovalPrefix } from "../session-approval-cache";
+import { findSkillPathMatch } from "../skill-prompt-sanitizer";
+import { getPermissionLogContext } from "../tool-input-preview";
+import {
+  checkRequestedToolRegistration,
+  getToolNameFromValue,
+} from "../tool-registry";
+import type { HandlerDeps } from "./types";
+
+/**
+ * Extract the tool input from an event, checking both `input` and `arguments`
+ * fields (different Pi SDK versions use different names).
+ */
+export function getEventInput(event: unknown): unknown {
+  const record = toRecord(event);
+
+  if (record.input !== undefined) {
+    return record.input;
+  }
+
+  if (record.arguments !== undefined) {
+    return record.arguments;
+  }
+
+  return {};
+}
+
+export async function handleToolCall(
+  deps: HandlerDeps,
+  event: unknown,
+  ctx: ExtensionContext,
+): Promise<{ block?: true; reason?: string }> {
+  deps.setRuntimeContext(ctx);
+  deps.startForwardedPermissionPolling(ctx);
+
+  const agentName = deps.resolveAgentName(ctx);
+  const toolName = getToolNameFromValue(event);
+
+  if (!toolName) {
+    return { block: true, reason: formatMissingToolNameReason() };
+  }
+
+  const registrationCheck = checkRequestedToolRegistration(
+    toolName,
+    deps.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,
+      ),
+    };
+  }
+
+  // ── Skill-read gate ──────────────────────────────────────────────────────
+  if (
+    isToolCallEventType("read", event as ToolCallEvent) &&
+    deps.getActiveSkillEntries().length > 0
+  ) {
+    const normalizedReadPath = normalizePathForComparison(
+      (event as ToolCallEvent & { input: { path: string } }).input.path,
+      ctx.cwd,
+    );
+    const matchedSkill = findSkillPathMatch(
+      normalizedReadPath,
+      deps.getActiveSkillEntries(),
+    );
+
+    if (matchedSkill) {
+      const readEvent = event as ToolCallEvent & { input: { path: string } };
+      const skillReadMessage = formatSkillPathAskPrompt(
+        matchedSkill,
+        readEvent.input.path,
+        agentName ?? undefined,
+      );
+      const skillReadGate = await applyPermissionGate({
+        state: matchedSkill.state,
+        canConfirm: deps.canRequestPermissionConfirmation(ctx),
+        promptForApproval: () =>
+          deps.promptPermission(ctx, {
+            requestId: (readEvent as { toolCallId: string }).toolCallId,
+            source: "skill_read",
+            agentName,
+            message: skillReadMessage,
+            toolCallId: (readEvent as { toolCallId: string }).toolCallId,
+            toolName,
+            skillName: matchedSkill.name,
+            path: readEvent.input.path,
+          }),
+        writeLog: deps.writeReviewLog,
+        logContext: {
+          source: "skill_read",
+          skillName: matchedSkill.name,
+          agentName,
+          path: readEvent.input.path,
+          message: skillReadMessage,
+        },
+        messages: {
+          denyReason: formatSkillPathDenyReason(
+            matchedSkill,
+            readEvent.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);
+
+  // ── External-directory gate (file tools) ─────────────────────────────────
+  const externalDirectoryPath = ctx.cwd
+    ? getPathBearingToolPath(toolName, input)
+    : null;
+
+  if (
+    ctx.cwd &&
+    externalDirectoryPath &&
+    isPathOutsideWorkingDirectory(externalDirectoryPath, ctx.cwd)
+  ) {
+    const normalizedExtPath = normalizePathForComparison(
+      externalDirectoryPath,
+      ctx.cwd,
+    );
+    const sessionPrefix = deps.sessionApprovalCache.findMatchingPrefix(
+      "external_directory",
+      normalizedExtPath,
+    );
+
+    if (sessionPrefix) {
+      deps.writeReviewLog("permission_request.session_approved", {
+        source: "tool_call",
+        toolCallId: (event as { toolCallId: string }).toolCallId,
+        toolName,
+        agentName,
+        path: externalDirectoryPath,
+        resolution: "session_approved",
+        sessionApprovalPrefix: sessionPrefix,
+      });
+      // Fall through to normal permission check
+    } else {
+      const extCheck = deps
+        .getPermissionManager()
+        .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: deps.canRequestPermissionConfirmation(ctx),
+        promptForApproval: async () => {
+          const decision = await deps.promptPermission(ctx, {
+            requestId: (event as { toolCallId: string }).toolCallId,
+            source: "tool_call",
+            agentName,
+            message: extDirMessage,
+            toolCallId: (event as { toolCallId: string }).toolCallId,
+            toolName,
+            path: externalDirectoryPath,
+          });
+          extDirDecision = decision;
+          return decision;
+        },
+        writeLog: deps.writeReviewLog,
+        logContext: {
+          source: "tool_call",
+          toolCallId: (event as { toolCallId: string }).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);
+        deps.sessionApprovalCache.approve("external_directory", prefix);
+      }
+    }
+    // Fall through to normal permission check
+  }
+
+  // ── Bash external-directory gate ─────────────────────────────────────────
+  if (ctx.cwd && toolName === "bash") {
+    const command = getNonEmptyString(toRecord(input).command);
+    if (command) {
+      const externalPaths = extractExternalPathsFromBashCommand(
+        command,
+        ctx.cwd,
+      );
+      if (externalPaths.length > 0) {
+        const uncoveredPaths = externalPaths.filter(
+          (p) => !deps.sessionApprovalCache.has("external_directory", p),
+        );
+
+        if (uncoveredPaths.length === 0) {
+          deps.writeReviewLog("permission_request.session_approved", {
+            source: "tool_call",
+            toolCallId: (event as { toolCallId: string }).toolCallId,
+            toolName,
+            agentName,
+            command,
+            externalPaths,
+            resolution: "session_approved",
+          });
+          // Fall through to normal bash permission check
+        } else {
+          const extCheck = deps
+            .getPermissionManager()
+            .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: deps.canRequestPermissionConfirmation(ctx),
+            promptForApproval: async () => {
+              const decision = await deps.promptPermission(ctx, {
+                requestId: (event as { toolCallId: string }).toolCallId,
+                source: "tool_call",
+                agentName,
+                message: bashExtMessage,
+                toolCallId: (event as { toolCallId: string }).toolCallId,
+                toolName,
+                command,
+              });
+              bashExtDecision = decision;
+              return decision;
+            },
+            writeLog: deps.writeReviewLog,
+            logContext: {
+              source: "tool_call",
+              toolCallId: (event as { toolCallId: string }).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);
+              deps.sessionApprovalCache.approve("external_directory", prefix);
+            }
+          }
+        }
+        // Fall through to normal bash permission check
+      }
+    }
+  }
+
+  // ── Normal tool permission gate ───────────────────────────────────────────
+  const check = deps
+    .getPermissionManager()
+    .checkPermission(toolName, input, agentName ?? undefined);
+  const permissionLogContext = getPermissionLogContext(
+    check,
+    input,
+    PATH_BEARING_TOOLS,
+  );
+
+  const toolUnavailableReason =
+    toolName === "bash" && isToolCallEventType("bash", event as ToolCallEvent)
+      ? `Running bash command '${(event as ToolCallEvent & { input: { command: string } }).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: deps.canRequestPermissionConfirmation(ctx),
+    promptForApproval: () =>
+      deps.promptPermission(ctx, {
+        requestId: (event as { toolCallId: string }).toolCallId,
+        source: "tool_call",
+        agentName,
+        message: toolAskMessage,
+        toolCallId: (event as { toolCallId: string }).toolCallId,
+        toolName,
+        ...permissionLogContext,
+      }),
+    writeLog: deps.writeReviewLog,
+    logContext: {
+      source: "tool_call",
+      toolCallId: (event as { toolCallId: string }).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 };
+  }
+
+  return {};
+}

package/src/handlers/types.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import type { PermissionPromptDecision } from "../permission-dialog";
+import type { PermissionManager } from "../permission-manager";
+import type { SessionApprovalCache } from "../session-approval-cache";
+import type { SkillPromptEntry } from "../skill-prompt-sanitizer";
+
+export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
+
+/** Details passed when prompting the user for a permission decision. */
+export interface PromptPermissionDetails {
+  requestId: string;
+  source: PermissionReviewSource;
+  agentName: string | null;
+  message: string;
+  toolCallId?: string;
+  toolName?: string;
+  skillName?: string;
+  path?: string;
+  command?: string;
+  target?: string;
+  toolInputPreview?: string;
+}
+
+/**
+ * Explicit dependency bag passed to each extracted event handler.
+ *
+ * All mutable shared state is wrapped in getter/setter pairs so that:
+ * - Tests can construct a plain object with stubs and exercise handlers in
+ *   isolation without importing src/index.ts.
+ * - Issue #43 can replace this interface with ExtensionRuntime without
+ *   changing handler signatures — only the deps object construction in
+ *   index.ts needs to change.
+ */
+export interface HandlerDeps {
+  // ── Mutable state accessors ────────────────────────────────────────────
+  getPermissionManager(): PermissionManager;
+  setPermissionManager(pm: PermissionManager): void;
+  getRuntimeContext(): ExtensionContext | null;
+  setRuntimeContext(ctx: ExtensionContext | null): void;
+  getActiveSkillEntries(): SkillPromptEntry[];
+  setActiveSkillEntries(entries: SkillPromptEntry[]): void;
+  getLastKnownActiveAgentName(): string | null;
+  setLastKnownActiveAgentName(name: string | null): void;
+  /** Cache key for the last set of active tools passed to setActiveTools(). */
+  getLastActiveToolsCacheKey(): string | null;
+  setLastActiveToolsCacheKey(key: string | null): void;
+  /** Cache key for the last before_agent_start prompt state. */
+  getLastPromptStateCacheKey(): string | null;
+  setLastPromptStateCacheKey(key: string | null): void;
+  /** Session-scoped approval cache (passed by reference; mutations are visible). */
+  sessionApprovalCache: SessionApprovalCache;
+
+  // ── Factories ──────────────────────────────────────────────────────────
+  /** Create a new PermissionManager scoped to cwd's config hierarchy. */
+  createPermissionManagerForCwd(
+    cwd: string | undefined | null,
+  ): PermissionManager;
+
+  // ── Config & lifecycle helpers ─────────────────────────────────────────
+  /** Reload merged config from disk; optionally update the stored runtime context. */
+  refreshExtensionConfig(ctx?: ExtensionContext): void;
+  /** Show a warning notification to the user (no-op when no UI is available). */
+  notifyWarning(message: string): void;
+  /** Write the resolved config path set to the review and debug logs. */
+  logResolvedConfigPaths(): void;
+
+  // ── Permission helpers ─────────────────────────────────────────────────
+  /**
+   * Resolve the active agent name from the session context or system prompt.
+   * Updates the stored lastKnownActiveAgentName as a side effect.
+   */
+  resolveAgentName(ctx: ExtensionContext, systemPrompt?: string): string | null;
+  /** Whether the current context can show an interactive permission prompt. */
+  canRequestPermissionConfirmation(ctx: ExtensionContext): boolean;
+  /** Prompt the user for a permission decision, log the outcome, and return it. */
+  promptPermission(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
+  /** Generate a unique ID for a permission request. */
+  createPermissionRequestId(prefix: string): string;
+
+  // ── Forwarding ─────────────────────────────────────────────────────────
+  startForwardedPermissionPolling(ctx: ExtensionContext): void;
+  stopForwardedPermissionPolling(): void;
+
+  // ── Logging ────────────────────────────────────────────────────────────
+  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+  writeDebugLog(event: string, details?: Record<string, unknown>): void;
+
+  // ── Pi API subset ──────────────────────────────────────────────────────
+  getAllTools(): unknown[];
+  setActiveTools(names: string[]): void;
+}