@gotgenes/pi-permission-system 3.0.0 → 3.0.2

package/src/index.ts

@@ -1,15 +1,11 @@
 import {
   existsSync,
   mkdirSync,
-  readdirSync,
-  readFileSync,
   renameSync,
-  rmdirSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, normalize, resolve, sep } from "node:path";
+import { dirname, join, normalize } from "node:path";
 import {
   type ExtensionAPI,
   type ExtensionCommandContext,
@@ -17,12 +13,16 @@ import {
   getAgentDir,
   isToolCallEventType,
 } from "@mariozechner/pi-coding-agent";
+import {
+  getActiveAgentName,
+  getActiveAgentNameFromSystemPrompt,
+} from "./active-agent.js";
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
   shouldApplyCachedAgentStartState,
 } from "./before-agent-start-cache.js";
-import { getNonEmptyString, toRecord } from "./common.js";
+import { toRecord } from "./common.js";
 import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader.js";
 import { registerPermissionSystemCommand } from "./config-modal.js";
 import {
@@ -43,24 +43,38 @@ import {
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config.js";
-import { createPermissionSystemLogger, safeJsonStringify } from "./logging.js";
 import {
-  isPermissionDecisionState,
+  formatExternalDirectoryAskPrompt,
+  formatExternalDirectoryDenyReason,
+  formatExternalDirectoryUserDeniedReason,
+  getPathBearingToolPath,
+  isPathOutsideWorkingDirectory,
+  normalizePathForComparison,
+  PATH_BEARING_TOOLS,
+} from "./external-directory.js";
+import { setForwardedPermissionLogger } from "./forwarded-permissions/io.js";
+import {
+  confirmPermission,
+  type PermissionForwardingDeps,
+  processForwardedPermissionRequests,
+} from "./forwarded-permissions/polling.js";
+import { createPermissionSystemLogger } from "./logging.js";
+import {
   type PermissionPromptDecision,
   requestPermissionDecisionFromUi,
 } from "./permission-dialog.js";
-import {
-  createPermissionForwardingLocation,
-  type ForwardedPermissionRequest,
-  type ForwardedPermissionResponse,
-  isForwardedPermissionRequestForSession,
-  PERMISSION_FORWARDING_POLL_INTERVAL_MS,
-  PERMISSION_FORWARDING_TIMEOUT_MS,
-  type PermissionForwardingLocation,
-  resolvePermissionForwardingTargetSessionId,
-  SUBAGENT_ENV_HINT_KEYS,
-} from "./permission-forwarding.js";
+import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding.js";
 import { PermissionManager } from "./permission-manager.js";
+import {
+  formatAskPrompt,
+  formatDenyReason,
+  formatMissingToolNameReason,
+  formatSkillAskPrompt,
+  formatSkillPathAskPrompt,
+  formatSkillPathDenyReason,
+  formatUnknownToolReason,
+  formatUserDeniedReason,
+} from "./permission-prompts.js";
 import {
   findSkillPathMatch,
   resolveSkillPromptEntries,
@@ -70,12 +84,13 @@ import {
   PERMISSION_SYSTEM_STATUS_KEY,
   syncPermissionSystemStatus,
 } from "./status.js";
+import { isSubagentExecutionContext } from "./subagent-context.js";
 import { sanitizeAvailableToolsSection } from "./system-prompt-sanitizer.js";
+import { getPermissionLogContext } from "./tool-input-preview.js";
 import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "./tool-registry.js";
-import type { PermissionCheckResult } from "./types.js";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -86,17 +101,7 @@ 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");
 
-const ACTIVE_AGENT_TAG_REGEX = /<active_agent\s+name=["']([^"']+)["'][^>]*>/i;
-
 type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
-const PATH_BEARING_TOOLS = new Set([
-  "read",
-  "write",
-  "edit",
-  "find",
-  "grep",
-  "ls",
-]);
 
 let extensionConfig: PermissionSystemExtensionConfig = {
   ...DEFAULT_EXTENSION_CONFIG,
@@ -151,67 +156,6 @@ function writeReviewLog(
   }
 }
 
-function normalizePathForComparison(pathValue: string, cwd: string): string {
-  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) {
-    return "";
-  }
-
-  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-
-  if (normalizedPath === "~") {
-    normalizedPath = homedir();
-  } else if (
-    normalizedPath.startsWith("~/") ||
-    normalizedPath.startsWith("~\\")
-  ) {
-    normalizedPath = join(homedir(), normalizedPath.slice(2));
-  }
-
-  const absolutePath = resolve(cwd, normalizedPath);
-  const normalizedAbsolutePath = normalize(absolutePath);
-  return process.platform === "win32"
-    ? normalizedAbsolutePath.toLowerCase()
-    : normalizedAbsolutePath;
-}
-
-function isPathWithinDirectory(pathValue: string, directory: string): boolean {
-  if (!pathValue || !directory) {
-    return false;
-  }
-
-  if (pathValue === directory) {
-    return true;
-  }
-
-  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
-  return pathValue.startsWith(prefix);
-}
-
-function getPathBearingToolPath(
-  toolName: string,
-  input: unknown,
-): string | null {
-  if (!PATH_BEARING_TOOLS.has(toolName)) {
-    return null;
-  }
-
-  return getNonEmptyString(toRecord(input).path);
-}
-
-function isPathOutsideWorkingDirectory(
-  pathValue: string,
-  cwd: string,
-): boolean {
-  const normalizedCwd = normalizePathForComparison(cwd, cwd);
-  const normalizedPath = normalizePathForComparison(pathValue, cwd);
-  return Boolean(
-    normalizedCwd &&
-      normalizedPath &&
-      !isPathWithinDirectory(normalizedPath, normalizedCwd),
-  );
-}
-
 function extractSkillNameFromInput(text: string): string | null {
   const trimmed = text.trim();
   if (!trimmed.startsWith("/skill:")) {
@@ -248,981 +192,14 @@ function getEventInput(event: unknown): unknown {
   return {};
 }
 
-function normalizeAgentName(value: unknown): string | null {
-  if (typeof value !== "string") {
-    return null;
-  }
-
-  const trimmed = value.trim();
-  return trimmed ? trimmed : null;
-}
-
-function getActiveAgentName(ctx: ExtensionContext): string | null {
-  const entries = ctx.sessionManager.getEntries();
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const entry = entries[i] as {
-      type: string;
-      customType?: string;
-      data?: unknown;
-    };
-    if (entry.type !== "custom" || entry.customType !== "active_agent") {
-      continue;
-    }
-
-    const data = entry.data as { name?: unknown } | undefined;
-    const normalizedName = normalizeAgentName(data?.name);
-    if (normalizedName) {
-      return normalizedName;
-    }
-
-    if (data?.name === null) {
-      return null;
-    }
-  }
-
-  return null;
-}
-
-function getActiveAgentNameFromSystemPrompt(
-  systemPrompt: string | undefined,
-): string | null {
-  if (!systemPrompt) {
-    return null;
-  }
-
-  const match = systemPrompt.match(ACTIVE_AGENT_TAG_REGEX);
-  if (!match?.[1]) {
-    return null;
-  }
-
-  return normalizeAgentName(match[1]);
-}
-
-function getContextSystemPrompt(ctx: ExtensionContext): string | undefined {
-  const getSystemPrompt = toRecord(ctx).getSystemPrompt;
-  if (typeof getSystemPrompt !== "function") {
-    return undefined;
-  }
-
-  try {
-    const systemPrompt = getSystemPrompt.call(ctx);
-    return typeof systemPrompt === "string" ? systemPrompt : undefined;
-  } catch (error) {
-    logPermissionForwardingWarning(
-      "Failed to read context system prompt for forwarded permission metadata",
-      error,
-    );
-    return undefined;
-  }
-}
-
-function formatMissingToolNameReason(): string {
-  return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";
-}
-
-function formatUnknownToolReason(
-  toolName: string,
-  availableToolNames: readonly string[],
-): string {
-  const preview = availableToolNames.slice(0, 10);
-  const suffix = availableToolNames.length > preview.length ? ", ..." : "";
-  const availableList =
-    preview.length > 0 ? `${preview.join(", ")}${suffix}` : "none";
-
-  const mcpHint =
-    toolName === "mcp"
-      ? ""
-      : ' If this was intended as an MCP server tool, call the registered \'mcp\' tool when available (for example: {"tool":"server:tool"}).';
-
-  return `Tool '${toolName}' is not registered in this runtime and was blocked before permission checks.${mcpHint} Registered tools: ${availableList}.`;
-}
-
-function formatPermissionHardStopHint(result: PermissionCheckResult): string {
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
-    return "Hard stop: this MCP permission denial is policy-enforced. Do not retry this target, do not run discovery/investigation to bypass it, and report the block to the user.";
-  }
-
-  return "Hard stop: this permission denial is policy-enforced. Do not retry or investigate bypasses; report the block to the user.";
-}
-
-function formatDenyReason(
-  result: PermissionCheckResult,
-  agentName?: string,
-): string {
-  const parts: string[] = [];
-
-  if (agentName) {
-    parts.push(`Agent '${agentName}'`);
-  }
-
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
-    parts.push(`is not permitted to run MCP target '${result.target}'`);
-  } else {
-    parts.push(`is not permitted to run '${result.toolName}'`);
-  }
-
-  if (result.command) {
-    parts.push(`command '${result.command}'`);
-  }
-
-  if (result.matchedPattern) {
-    parts.push(`(matched '${result.matchedPattern}')`);
-  }
-
-  return `${parts.join(" ")}. ${formatPermissionHardStopHint(result)}`;
-}
-
-function formatUserDeniedReason(
-  result: PermissionCheckResult,
-  denialReason?: string,
-): string {
-  const base =
-    (result.source === "mcp" || result.toolName === "mcp") && result.target
-      ? `User denied MCP target '${result.target}'.`
-      : result.toolName === "bash" && result.command
-        ? `User denied bash command '${result.command}'.`
-        : `User denied tool '${result.toolName}'.`;
-  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
-
-  return `${base}${reasonSuffix} ${formatPermissionHardStopHint(result)}`;
-}
-
-const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
-const TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH = 1000;
-const TOOL_TEXT_SUMMARY_MAX_LENGTH = 80;
-
-function truncateInlineText(value: string, maxLength: number): string {
-  return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
-}
-
-function sanitizeInlineText(
-  value: string,
-  maxLength = TOOL_TEXT_SUMMARY_MAX_LENGTH,
-): string {
-  const normalized = value.replace(/\s+/g, " ").trim();
-  return normalized ? truncateInlineText(normalized, maxLength) : "empty text";
-}
-
-function countTextLines(value: string): number {
-  if (!value) {
-    return 0;
-  }
-
-  return value.split(/\r\n|\r|\n/).length;
-}
-
-function formatCount(value: number, singular: string, plural: string): string {
-  return `${value} ${value === 1 ? singular : plural}`;
-}
-
-function getPromptPath(input: Record<string, unknown>): string | null {
-  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
-}
-
-function formatEditInputForPrompt(input: Record<string, unknown>): string {
-  const path = getPromptPath(input);
-  const rawEdits = Array.isArray(input.edits)
-    ? input.edits
-    : typeof input.oldText === "string" && typeof input.newText === "string"
-      ? [{ oldText: input.oldText, newText: input.newText }]
-      : [];
-
-  const edits = rawEdits
-    .map((edit) => toRecord(edit))
-    .filter(
-      (edit) =>
-        typeof edit.oldText === "string" && typeof edit.newText === "string",
-    );
-
-  const pathPart = path ? `for '${path}'` : "";
-  if (edits.length === 0) {
-    return pathPart ? `${pathPart} with edit input` : "with edit input";
-  }
-
-  const firstEdit = edits[0];
-  const oldText = String(firstEdit.oldText);
-  const newText = String(firstEdit.newText);
-  const firstEditSummary = `edit #1 replaces ${formatCount(countTextLines(oldText), "line", "lines")} with ${formatCount(countTextLines(newText), "line", "lines")}`;
-  const extraEdits =
-    edits.length > 1
-      ? `, plus ${formatCount(edits.length - 1, "additional edit", "additional edits")}`
-      : "";
-  const summary = `(${formatCount(edits.length, "replacement", "replacements")}: ${firstEditSummary}${extraEdits})`;
-  return pathPart ? `${pathPart} ${summary}` : summary;
-}
-
-function formatWriteInputForPrompt(input: Record<string, unknown>): string {
-  const path = getPromptPath(input);
-  const content = typeof input.content === "string" ? input.content : "";
-  const summary = `(${formatCount(countTextLines(content), "line", "lines")}, ${formatCount(content.length, "character", "characters")})`;
-  return path ? `for '${path}' ${summary}` : summary;
-}
-
-function formatReadInputForPrompt(input: Record<string, unknown>): string {
-  const path = getPromptPath(input);
-  const parts = path ? [`path '${path}'`] : [];
-  if (typeof input.offset === "number") {
-    parts.push(`offset ${input.offset}`);
-  }
-  if (typeof input.limit === "number") {
-    parts.push(`limit ${input.limit}`);
-  }
-  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
-}
-
-function formatSearchInputForPrompt(
-  toolName: string,
-  input: Record<string, unknown>,
-): string {
-  const parts: string[] = [];
-  const path = getPromptPath(input);
-  const pattern = getNonEmptyString(input.pattern);
-  const glob = getNonEmptyString(input.glob);
-
-  if (pattern) {
-    parts.push(`pattern '${sanitizeInlineText(pattern)}'`);
-  }
-  if (glob) {
-    parts.push(`glob '${sanitizeInlineText(glob)}'`);
-  }
-  if (path) {
-    parts.push(`path '${path}'`);
-  } else if (toolName === "find" || toolName === "grep" || toolName === "ls") {
-    parts.push("current working directory");
-  }
-
-  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
-}
-
-function serializeToolInputPreview(input: unknown): string {
-  const serialized = safeJsonStringify(input);
-  if (!serialized || serialized === "{}" || serialized === "null") {
-    return "";
-  }
-
-  return serialized.replace(/\s+/g, " ").trim();
-}
-
-function formatJsonInputForPrompt(input: unknown): string {
-  const inline = serializeToolInputPreview(input);
-  return inline
-    ? `with input ${truncateInlineText(inline, TOOL_INPUT_PREVIEW_MAX_LENGTH)}`
-    : "";
-}
-
-function formatToolInputForPrompt(toolName: string, input: unknown): string {
-  const inputRecord = toRecord(input);
-
-  switch (toolName) {
-    case "edit":
-      return formatEditInputForPrompt(inputRecord);
-    case "write":
-      return formatWriteInputForPrompt(inputRecord);
-    case "read":
-      return formatReadInputForPrompt(inputRecord);
-    case "find":
-    case "grep":
-    case "ls":
-      return formatSearchInputForPrompt(toolName, inputRecord);
-    default:
-      return formatJsonInputForPrompt(input);
-  }
-}
-
-function formatAskPrompt(
-  result: PermissionCheckResult,
-  agentName?: string,
-  input?: unknown,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-
-  if (result.toolName === "bash") {
-    const patternInfo = result.matchedPattern
-      ? ` (matched '${result.matchedPattern}')`
-      : "";
-    return `${subject} requested bash command '${result.command || ""}'${patternInfo}. Allow this command?`;
-  }
-
-  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
-    const patternInfo = result.matchedPattern
-      ? ` (matched '${result.matchedPattern}')`
-      : "";
-    return `${subject} requested MCP target '${result.target}'${patternInfo}. Allow this call?`;
-  }
-
-  const patternInfo = result.matchedPattern
-    ? ` (matched '${result.matchedPattern}')`
-    : "";
-  const inputPreview = formatToolInputForPrompt(result.toolName, input);
-  const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
-  return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
-}
-
-function formatSkillAskPrompt(skillName: string, agentName?: string): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested skill '${skillName}'. Allow loading this skill?`;
-}
-
-function formatSkillPathAskPrompt(
-  skill: SkillPromptEntry,
-  readPath: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested access to skill '${skill.name}' via '${readPath}'. Allow this read?`;
-}
-
-function formatSkillPathDenyReason(
-  skill: SkillPromptEntry,
-  readPath: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} is not permitted to access skill '${skill.name}' via '${readPath}'.`;
-}
-
-function formatExternalDirectoryHardStopHint(): string {
-  return "Hard stop: this external directory permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.";
-}
-
-function formatExternalDirectoryAskPrompt(
-  toolName: string,
-  pathValue: string,
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
-}
-
-function formatExternalDirectoryDenyReason(
-  toolName: string,
-  pathValue: string,
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} is not permitted to run tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. ${formatExternalDirectoryHardStopHint()}`;
-}
-
-function formatExternalDirectoryUserDeniedReason(
-  toolName: string,
-  pathValue: string,
-  denialReason?: string,
-): string {
-  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
-  return `User denied external directory access for tool '${toolName}' path '${pathValue}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
-}
-
-function formatGenericToolInputForLog(input: unknown): string | undefined {
-  const inline = serializeToolInputPreview(input);
-  return inline
-    ? `input ${truncateInlineText(inline, TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH)}`
-    : undefined;
-}
-
-function getToolInputPreviewForLog(
-  result: PermissionCheckResult,
-  input: unknown,
-): string | undefined {
-  if (
-    result.toolName === "bash" ||
-    result.toolName === "mcp" ||
-    result.source === "mcp"
-  ) {
-    return undefined;
-  }
-
-  if (PATH_BEARING_TOOLS.has(result.toolName)) {
-    const inputPreview = formatToolInputForPrompt(result.toolName, input);
-    return inputPreview
-      ? truncateInlineText(inputPreview, TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH)
-      : undefined;
-  }
-
-  return formatGenericToolInputForLog(input);
-}
-
-function getPermissionLogContext(
-  result: PermissionCheckResult,
-  input: unknown,
-): { command?: string; target?: string; toolInputPreview?: string } {
-  return {
-    command: result.command,
-    target: result.target,
-    toolInputPreview: getToolInputPreviewForLog(result, input),
-  };
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-function normalizeFilesystemPath(pathValue: string): string {
-  const normalizedPath = normalize(pathValue);
-  return process.platform === "win32"
-    ? normalizedPath.toLowerCase()
-    : normalizedPath;
-}
-
-function getSessionId(ctx: ExtensionContext): string {
-  try {
-    const sessionId = ctx.sessionManager.getSessionId();
-    if (typeof sessionId === "string" && sessionId.trim()) {
-      return sessionId.trim();
-    }
-  } catch {}
-
-  return "unknown";
-}
-
-function isSubagentExecutionContext(ctx: ExtensionContext): boolean {
-  for (const key of SUBAGENT_ENV_HINT_KEYS) {
-    const value = process.env[key];
-    if (typeof value === "string" && value.trim()) {
-      return true;
-    }
-  }
-
-  const sessionDir = ctx.sessionManager.getSessionDir();
-  if (!sessionDir) {
-    return false;
-  }
-
-  const normalizedSessionDir = normalizeFilesystemPath(sessionDir);
-  const normalizedSubagentRoot = normalizeFilesystemPath(SUBAGENT_SESSIONS_DIR);
-  return isPathWithinDirectory(normalizedSessionDir, normalizedSubagentRoot);
-}
-
 function canRequestPermissionConfirmation(ctx: ExtensionContext): boolean {
   return canResolveAskPermissionRequest({
     config: extensionConfig,
     hasUI: ctx.hasUI,
-    isSubagent: isSubagentExecutionContext(ctx),
+    isSubagent: isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR),
   });
 }
 
-function formatUnknownErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message) {
-    return error.message;
-  }
-  return String(error);
-}
-
-function isErrnoCode(error: unknown, code: string): boolean {
-  return Boolean(
-    error &&
-      typeof error === "object" &&
-      "code" in error &&
-      (error as { code?: string }).code === code,
-  );
-}
-
-function logPermissionForwardingWarning(
-  message: string,
-  error?: unknown,
-): void {
-  const details =
-    typeof error === "undefined"
-      ? { message }
-      : { message, error: formatUnknownErrorMessage(error) };
-
-  writeReviewLog("permission_forwarding.warning", details);
-  writeDebugLog("permission_forwarding.warning", details);
-}
-
-function logPermissionForwardingError(message: string, error?: unknown): void {
-  const details =
-    typeof error === "undefined"
-      ? { message }
-      : { message, error: formatUnknownErrorMessage(error) };
-
-  writeReviewLog("permission_forwarding.error", details);
-  writeDebugLog("permission_forwarding.error", details);
-}
-
-function ensureDirectoryExists(path: string, description: string): boolean {
-  try {
-    mkdirSync(path, { recursive: true });
-    return true;
-  } catch (error) {
-    logPermissionForwardingError(
-      `Failed to create ${description} directory '${path}'`,
-      error,
-    );
-    return false;
-  }
-}
-
-function getPermissionForwardingLocationForSession(
-  sessionId: string,
-): PermissionForwardingLocation {
-  return createPermissionForwardingLocation(
-    PERMISSION_FORWARDING_DIR,
-    sessionId,
-  );
-}
-
-function ensurePermissionForwardingLocation(
-  sessionId: string,
-): PermissionForwardingLocation | null {
-  let location: PermissionForwardingLocation;
-  try {
-    location = getPermissionForwardingLocationForSession(sessionId);
-  } catch (error) {
-    logPermissionForwardingError(
-      "Failed to resolve permission forwarding location",
-      error,
-    );
-    return null;
-  }
-
-  const sessionRootReady = ensureDirectoryExists(
-    location.sessionRootDir,
-    "permission forwarding session root",
-  );
-  const requestsReady = ensureDirectoryExists(
-    location.requestsDir,
-    "permission forwarding requests",
-  );
-  const responsesReady = ensureDirectoryExists(
-    location.responsesDir,
-    "permission forwarding responses",
-  );
-
-  return sessionRootReady && requestsReady && responsesReady ? location : null;
-}
-
-function getExistingPermissionForwardingLocation(
-  sessionId: string,
-): PermissionForwardingLocation | null {
-  let location: PermissionForwardingLocation;
-  try {
-    location = getPermissionForwardingLocationForSession(sessionId);
-  } catch {
-    return null;
-  }
-
-  return existsSync(location.requestsDir) ? location : null;
-}
-
-function tryRemoveDirectoryIfEmpty(path: string, description: string): void {
-  if (!existsSync(path)) {
-    return;
-  }
-
-  let entries: string[];
-  try {
-    entries = readdirSync(path);
-  } catch (error) {
-    logPermissionForwardingWarning(
-      `Failed to inspect ${description} directory '${path}'`,
-      error,
-    );
-    return;
-  }
-
-  if (entries.length > 0) {
-    return;
-  }
-
-  try {
-    rmdirSync(path);
-  } catch (error) {
-    if (isErrnoCode(error, "ENOENT") || isErrnoCode(error, "ENOTEMPTY")) {
-      return;
-    }
-
-    logPermissionForwardingWarning(
-      `Failed to remove empty ${description} directory '${path}'`,
-      error,
-    );
-  }
-}
-
-function cleanupPermissionForwardingLocationIfEmpty(
-  location: PermissionForwardingLocation,
-): void {
-  tryRemoveDirectoryIfEmpty(
-    location.requestsDir,
-    `${location.label} permission forwarding requests`,
-  );
-  tryRemoveDirectoryIfEmpty(
-    location.responsesDir,
-    `${location.label} permission forwarding responses`,
-  );
-  tryRemoveDirectoryIfEmpty(
-    location.sessionRootDir,
-    `${location.label} permission forwarding session root`,
-  );
-}
-
-function safeDeleteFile(filePath: string, description: string): void {
-  try {
-    unlinkSync(filePath);
-  } catch (error) {
-    if (isErrnoCode(error, "ENOENT")) {
-      return;
-    }
-
-    logPermissionForwardingWarning(
-      `Failed to delete ${description} file '${filePath}'`,
-      error,
-    );
-  }
-}
-
-function writeJsonFileAtomic(filePath: string, value: unknown): void {
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-
-  try {
-    writeFileSync(tempPath, JSON.stringify(value), "utf-8");
-    renameSync(tempPath, filePath);
-  } catch (error) {
-    safeDeleteFile(tempPath, "temporary permission-forwarding");
-    throw error;
-  }
-}
-
-function readForwardedPermissionRequest(
-  filePath: string,
-): ForwardedPermissionRequest | null {
-  try {
-    const raw = readFileSync(filePath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<ForwardedPermissionRequest>;
-    if (
-      !parsed ||
-      typeof parsed.id !== "string" ||
-      typeof parsed.createdAt !== "number" ||
-      typeof parsed.requesterSessionId !== "string" ||
-      typeof parsed.targetSessionId !== "string" ||
-      typeof parsed.requesterAgentName !== "string" ||
-      typeof parsed.message !== "string"
-    ) {
-      logPermissionForwardingWarning(
-        `Ignoring invalid forwarded permission request format in '${filePath}'`,
-      );
-      return null;
-    }
-
-    return {
-      id: parsed.id,
-      createdAt: parsed.createdAt,
-      requesterSessionId: parsed.requesterSessionId,
-      targetSessionId: parsed.targetSessionId,
-      requesterAgentName: parsed.requesterAgentName,
-      message: parsed.message,
-    };
-  } catch (error) {
-    logPermissionForwardingWarning(
-      `Failed to read forwarded permission request '${filePath}'`,
-      error,
-    );
-    return null;
-  }
-}
-
-function readForwardedPermissionResponse(
-  filePath: string,
-): ForwardedPermissionResponse | null {
-  try {
-    const raw = readFileSync(filePath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<ForwardedPermissionResponse>;
-    if (
-      !parsed ||
-      typeof parsed.approved !== "boolean" ||
-      !isPermissionDecisionState(parsed.state) ||
-      typeof parsed.responderSessionId !== "string"
-    ) {
-      logPermissionForwardingWarning(
-        `Ignoring invalid forwarded permission response format in '${filePath}'`,
-      );
-      return null;
-    }
-
-    return {
-      approved: parsed.approved,
-      state: parsed.state,
-      denialReason:
-        typeof parsed.denialReason === "string"
-          ? parsed.denialReason
-          : undefined,
-      responderSessionId: parsed.responderSessionId,
-      respondedAt:
-        typeof parsed.respondedAt === "number"
-          ? parsed.respondedAt
-          : Date.now(),
-    };
-  } catch (error) {
-    logPermissionForwardingWarning(
-      `Failed to read forwarded permission response '${filePath}'`,
-      error,
-    );
-    return null;
-  }
-}
-
-function formatForwardedPermissionPrompt(
-  request: ForwardedPermissionRequest,
-): string {
-  const agentName = request.requesterAgentName || "unknown";
-  const sessionId = request.requesterSessionId || "unknown";
-  return [
-    `Subagent '${agentName}' requested permission.`,
-    `Session ID: ${sessionId}`,
-    "",
-    request.message,
-  ].join("\n");
-}
-
-async function waitForForwardedPermissionApproval(
-  ctx: ExtensionContext,
-  message: string,
-): Promise<PermissionPromptDecision> {
-  const requesterSessionId = getSessionId(ctx);
-  const targetSessionId = resolvePermissionForwardingTargetSessionId({
-    hasUI: ctx.hasUI,
-    isSubagent: isSubagentExecutionContext(ctx),
-    currentSessionId: requesterSessionId,
-    env: process.env,
-  });
-
-  if (!targetSessionId) {
-    logPermissionForwardingError(
-      "Permission forwarding target session could not be resolved from subagent runtime metadata (expected PI_AGENT_ROUTER_PARENT_SESSION_ID)",
-    );
-    return { approved: false, state: "denied" };
-  }
-
-  const location = ensurePermissionForwardingLocation(targetSessionId);
-  if (!location) {
-    logPermissionForwardingError(
-      `Permission forwarding is unavailable because session-scoped directories could not be prepared for '${targetSessionId}'`,
-    );
-    return { approved: false, state: "denied" };
-  }
-
-  const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
-  const requesterAgentName =
-    getActiveAgentName(ctx) ||
-    getActiveAgentNameFromSystemPrompt(getContextSystemPrompt(ctx)) ||
-    "unknown";
-  const request: ForwardedPermissionRequest = {
-    id: requestId,
-    createdAt: Date.now(),
-    requesterSessionId,
-    targetSessionId,
-    requesterAgentName,
-    message,
-  };
-
-  const requestPath = join(location.requestsDir, `${requestId}.json`);
-  const responsePath = join(location.responsesDir, `${requestId}.json`);
-
-  writeReviewLog("forwarded_permission.request_created", {
-    requestId,
-    requesterAgentName,
-    requesterSessionId: request.requesterSessionId,
-    targetSessionId,
-    requestPath,
-    responsePath,
-  });
-
-  try {
-    writeJsonFileAtomic(requestPath, request);
-  } catch (error) {
-    logPermissionForwardingError(
-      `Failed to write forwarded permission request '${requestPath}'`,
-      error,
-    );
-    return { approved: false, state: "denied" };
-  }
-
-  const deadline = Date.now() + PERMISSION_FORWARDING_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    if (existsSync(responsePath)) {
-      const response = readForwardedPermissionResponse(responsePath);
-      writeReviewLog("forwarded_permission.response_received", {
-        requestId,
-        approved: response?.approved ?? null,
-        state: response?.state ?? null,
-        denialReason: response?.denialReason ?? null,
-        responderSessionId: response?.responderSessionId ?? null,
-        targetSessionId,
-        responsePath,
-      });
-      safeDeleteFile(responsePath, "forwarded permission response");
-      safeDeleteFile(requestPath, "forwarded permission request");
-      cleanupPermissionForwardingLocationIfEmpty(location);
-      return response ?? { approved: false, state: "denied" };
-    }
-
-    await sleep(PERMISSION_FORWARDING_POLL_INTERVAL_MS);
-  }
-
-  logPermissionForwardingWarning(
-    `Timed out waiting for forwarded permission response '${responsePath}'`,
-  );
-  writeReviewLog("forwarded_permission.response_timed_out", {
-    requestId,
-    requesterAgentName,
-    targetSessionId,
-    responsePath,
-  });
-  safeDeleteFile(requestPath, "forwarded permission request");
-  cleanupPermissionForwardingLocationIfEmpty(location);
-  return { approved: false, state: "denied" };
-}
-
-async function processForwardedPermissionRequests(
-  ctx: ExtensionContext,
-): Promise<void> {
-  if (!ctx.hasUI) {
-    return;
-  }
-
-  const currentSessionId = getSessionId(ctx);
-  const location = getExistingPermissionForwardingLocation(currentSessionId);
-  if (!location) {
-    return;
-  }
-
-  let requestFiles: string[] = [];
-  try {
-    requestFiles = readdirSync(location.requestsDir)
-      .filter((name) => name.endsWith(".json"))
-      .sort();
-  } catch (error) {
-    logPermissionForwardingWarning(
-      `Failed to read ${location.label} permission forwarding requests from '${location.requestsDir}'`,
-      error,
-    );
-    return;
-  }
-
-  for (const fileName of requestFiles) {
-    const requestPath = join(location.requestsDir, fileName);
-    const request = readForwardedPermissionRequest(requestPath);
-    if (!request) {
-      safeDeleteFile(
-        requestPath,
-        `${location.label} forwarded permission request`,
-      );
-      continue;
-    }
-
-    if (!isForwardedPermissionRequestForSession(request, currentSessionId)) {
-      logPermissionForwardingWarning(
-        `Ignoring forwarded permission request '${request.id}' because it targets session '${request.targetSessionId}' instead of '${currentSessionId}'`,
-      );
-      safeDeleteFile(
-        requestPath,
-        `${location.label} forwarded permission request`,
-      );
-      continue;
-    }
-
-    const forwardedPermissionLogDetails = {
-      requestId: request.id,
-      source: location.label,
-      requesterAgentName: request.requesterAgentName,
-      requesterSessionId: request.requesterSessionId,
-      targetSessionId: request.targetSessionId,
-      requestPath,
-    };
-
-    let decision: PermissionPromptDecision = {
-      approved: false,
-      state: "denied",
-    };
-    if (shouldAutoApprovePermissionState("ask", extensionConfig)) {
-      writeReviewLog(
-        "forwarded_permission.auto_approved",
-        forwardedPermissionLogDetails,
-      );
-      decision = { approved: true, state: "approved" };
-    } else {
-      writeReviewLog(
-        "forwarded_permission.prompted",
-        forwardedPermissionLogDetails,
-      );
-      try {
-        decision = await requestPermissionDecisionFromUi(
-          ctx.ui,
-          "Permission Required (Subagent)",
-          formatForwardedPermissionPrompt(request),
-        );
-      } catch (error) {
-        logPermissionForwardingError(
-          "Failed to show forwarded permission confirmation dialog",
-          error,
-        );
-        decision = { approved: false, state: "denied" };
-      }
-    }
-
-    const responsePath = join(location.responsesDir, `${request.id}.json`);
-    writeReviewLog(
-      decision.approved
-        ? "forwarded_permission.approved"
-        : "forwarded_permission.denied",
-      {
-        requestId: request.id,
-        source: location.label,
-        requesterAgentName: request.requesterAgentName,
-        requesterSessionId: request.requesterSessionId,
-        targetSessionId: request.targetSessionId,
-        responsePath,
-        resolution: decision.state,
-        denialReason: decision.denialReason ?? null,
-      },
-    );
-    try {
-      writeJsonFileAtomic(responsePath, {
-        approved: decision.approved,
-        state: decision.state,
-        denialReason: decision.denialReason,
-        responderSessionId: currentSessionId,
-        respondedAt: Date.now(),
-      } satisfies ForwardedPermissionResponse);
-    } catch (error) {
-      logPermissionForwardingError(
-        `Failed to write ${location.label} forwarded permission response '${responsePath}'`,
-        error,
-      );
-      continue;
-    }
-
-    safeDeleteFile(
-      requestPath,
-      `${location.label} forwarded permission request`,
-    );
-  }
-
-  cleanupPermissionForwardingLocationIfEmpty(location);
-}
-
-async function confirmPermission(
-  ctx: ExtensionContext,
-  message: string,
-): Promise<PermissionPromptDecision> {
-  if (ctx.hasUI) {
-    return requestPermissionDecisionFromUi(
-      ctx.ui,
-      "Permission Required",
-      message,
-    );
-  }
-
-  if (!isSubagentExecutionContext(ctx)) {
-    return { approved: false, state: "denied" };
-  }
-
-  return waitForForwardedPermissionApproval(ctx, message);
-}
-
 function derivePiProjectPaths(cwd: string | undefined | null): {
   projectGlobalConfigPath: string;
   projectAgentsDir: string;
@@ -1361,6 +338,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   setLoggingWarningReporter(notifyWarning);
+  setForwardedPermissionLogger({ writeReviewLog, writeDebugLog });
+
+  const forwardingDeps: PermissionForwardingDeps = {
+    forwardingDir: PERMISSION_FORWARDING_DIR,
+    subagentSessionsDir: SUBAGENT_SESSIONS_DIR,
+    writeReviewLog,
+    requestPermissionDecisionFromUi,
+    shouldAutoApprove: () =>
+      shouldAutoApprovePermissionState("ask", extensionConfig),
+  };
+
   refreshExtensionConfig();
   registerPermissionSystemCommand(pi, {
     getConfig: () => extensionConfig,
@@ -1430,7 +418,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
     reviewPermissionDecision("permission_request.waiting", details);
 
-    const decision = await confirmPermission(ctx, details.message);
+    const decision = await confirmPermission(
+      ctx,
+      details.message,
+      forwardingDeps,
+    );
     reviewPermissionDecision(
       decision.approved
         ? "permission_request.approved"
@@ -1455,7 +447,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   const startForwardedPermissionPolling = (ctx: ExtensionContext): void => {
-    if (!ctx.hasUI || isSubagentExecutionContext(ctx)) {
+    if (!ctx.hasUI || isSubagentExecutionContext(ctx, SUBAGENT_SESSIONS_DIR)) {
       stopForwardedPermissionPolling();
       return;
     }
@@ -1473,6 +465,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       isProcessingForwardedRequests = true;
       void processForwardedPermissionRequests(
         permissionForwardingContext,
+        forwardingDeps,
       ).finally(() => {
         isProcessingForwardedRequests = false;
       });
@@ -1909,7 +902,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       input,
       agentName ?? undefined,
     );
-    const permissionLogContext = getPermissionLogContext(check, input);
+    const permissionLogContext = getPermissionLogContext(
+      check,
+      input,
+      PATH_BEARING_TOOLS,
+    );
 
     if (check.state === "deny") {
       writeReviewLog("permission_request.blocked", {