@komarspn/pi-permission-system 16.0.2

package/src/permission-gate.ts

@@ -0,0 +1,94 @@
+import type { PermissionPromptDecision } from "./permission-dialog";
+
+/** Result of applying the permission gate. */
+export type PermissionGateResult =
+  | {
+      action: "allow";
+      sessionApproval?: { surface: string; pattern: string };
+      persistentApprovalScope?: "project" | "global";
+    }
+  | { action: "block"; reason: string };
+
+/** Everything the gate needs — no direct dependency on ExtensionContext. */
+export interface PermissionGateParams {
+  /** The resolved permission state from checkPermission(). */
+  state: "allow" | "deny" | "ask";
+
+  /** Whether the current context supports interactive prompts. */
+  canConfirm: boolean;
+
+  /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
+  promptForApproval: () => Promise<PermissionPromptDecision>;
+
+  /**
+   * Session approval suggestion to record when the user selects
+   * "for this session". When present and the decision is `approved_for_session`,
+   * the result carries the suggestion back to the caller for recording.
+   */
+  sessionApproval?: { surface: string; pattern: string };
+
+  /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
+  writeLog: (event: string, extra: Record<string, unknown>) => void;
+
+  /** Log context fields shared across all log calls for this gate. */
+  logContext: Record<string, unknown>;
+
+  /** Message strings/factories for each outcome. */
+  messages: {
+    denyReason: string;
+    unavailableReason: string;
+    userDeniedReason: (decision: PermissionPromptDecision) => string;
+  };
+}
+
+/**
+ * Apply the deny/ask/allow permission gate.
+ *
+ * This is a pure decision function: all IO is injected via callbacks.
+ */
+export async function applyPermissionGate(
+  params: PermissionGateParams,
+): Promise<PermissionGateResult> {
+  const {
+    state,
+    canConfirm,
+    promptForApproval,
+    writeLog,
+    logContext,
+    messages,
+  } = params;
+
+  if (state === "deny") {
+    writeLog("permission_request.blocked", {
+      ...logContext,
+      resolution: "policy_denied",
+    });
+    return { action: "block", reason: messages.denyReason };
+  }
+
+  if (state === "ask") {
+    if (!canConfirm) {
+      writeLog("permission_request.blocked", {
+        ...logContext,
+        resolution: "confirmation_unavailable",
+      });
+      return { action: "block", reason: messages.unavailableReason };
+    }
+
+    const decision = await promptForApproval();
+    if (!decision.approved) {
+      return { action: "block", reason: messages.userDeniedReason(decision) };
+    }
+    if (decision.state === "approved_for_session" && params.sessionApproval) {
+      return { action: "allow", sessionApproval: params.sessionApproval };
+    }
+    if (decision.state === "approved_for_project") {
+      return { action: "allow", persistentApprovalScope: "project" };
+    }
+    if (decision.state === "approved_globally") {
+      return { action: "allow", persistentApprovalScope: "global" };
+    }
+  }
+
+  return { action: "allow" };
+}

package/src/permission-manager.ts

@@ -0,0 +1,392 @@
+import { join } from "node:path";
+import { isPermissionState } from "./common";
+import {
+  getGlobalConfigPath,
+  getProjectAgentsDir,
+  getProjectConfigPath,
+} from "./config-paths";
+import { normalizeInput } from "./input-normalizer";
+import { normalizeFlatConfig } from "./normalize";
+import { PATH_SURFACES } from "./path-utils";
+import {
+  FilePolicyLoader,
+  type PolicyLoader,
+  type PolicyLoaderOptions,
+  type ResolvedPolicyPaths,
+} from "./policy-loader";
+import type { Rule, RuleOrigin, Ruleset } from "./rule";
+import { evaluate, evaluateAnyValue, evaluateFirst } from "./rule";
+import { mergeScopesWithOrigins } from "./scope-merge";
+import {
+  composeRuleset,
+  synthesizeBaseline,
+  synthesizeDefaults,
+} from "./synthesize";
+import type {
+  FlatPermissionConfig,
+  PermissionCheckResult,
+  PermissionState,
+} from "./types";
+
+const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
+  "bash",
+  "read",
+  "write",
+  "edit",
+  "grep",
+  "find",
+  "ls",
+]);
+const SPECIAL_PERMISSION_KEYS = new Set(["external_directory", "path"]);
+
+/** Universal fallback when permission["*"] is absent from all scopes. */
+const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";
+
+type FileCacheEntry<TValue> = {
+  stamp: string;
+  value: TValue;
+};
+
+type ResolvedPermissions = {
+  /**
+   * Fully composed ruleset: synthesized defaults → baseline → config.
+   * Session rules are appended at call-time inside checkPermission().
+   */
+  composedRules: Ruleset;
+};
+
+/**
+ * Narrow interface for session-scoped permission checking.
+ * `PermissionSession` depends on this — not the full concrete class — so
+ * test mocks can satisfy it without an `as unknown as PermissionManager` cast.
+ */
+export interface ScopedPermissionManager {
+  configureForCwd(cwd: string | undefined | null): void;
+  checkPermission(
+    toolName: string,
+    input: unknown,
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult;
+  /**
+   * Evaluate a path-shaped surface (`path` or `external_directory`) against a
+   * caller-supplied set of equivalent policy values (e.g. bash tokens already
+   * resolved against a preceding literal `cd`, or a path's typed and
+   * symlink-resolved aliases). The values are trusted because they are computed
+   * internally, never read from a field on raw tool input. `surface` defaults
+   * to `path`.
+   */
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+    surface?: string,
+  ): PermissionCheckResult;
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
+  getConfigIssues(agentName?: string): string[];
+}
+
+export interface PermissionManagerOptions extends PolicyLoaderOptions {
+  policyLoader?: PolicyLoader;
+  /**
+   * Pi agent directory.  When provided, the manager derives all loader paths
+   * from this value and supports {@link PermissionManager.configureForCwd}.
+   */
+  agentDir?: string;
+}
+
+export class PermissionManager implements ScopedPermissionManager {
+  private readonly agentDir: string | undefined;
+  private currentCwd: string | undefined;
+  private loader: PolicyLoader;
+  private readonly resolvedPermissionsCache = new Map<
+    string,
+    FileCacheEntry<ResolvedPermissions>
+  >();
+
+  constructor(options: PermissionManagerOptions = {}) {
+    this.agentDir = options.agentDir;
+    this.loader =
+      options.policyLoader ??
+      new FilePolicyLoader(
+        options.agentDir !== undefined
+          ? derivePolicyLoaderOptions(options.agentDir, undefined)
+          : options,
+      );
+  }
+
+  /**
+   * Rebuild the policy loader for a new working directory and clear the
+   * resolved-permissions cache.
+   *
+   * When `agentDir` was not provided at construction (e.g. test managers
+   * built with explicit paths), only the cache is cleared.
+   */
+  configureForCwd(cwd: string | undefined | null): void {
+    this.currentCwd =
+      typeof cwd === "string" && cwd.trim().length > 0 ? cwd : undefined;
+    if (this.agentDir !== undefined) {
+      this.loader = new FilePolicyLoader(
+        derivePolicyLoaderOptions(this.agentDir, cwd),
+      );
+    }
+    this.resolvedPermissionsCache.clear();
+  }
+
+  getConfigIssues(agentName?: string): string[] {
+    // Trigger a load/resolve to ensure issues are collected.
+    this.resolvePermissions(agentName);
+    return [...this.loader.getConfigIssues()];
+  }
+
+  getResolvedPolicyPaths(): ResolvedPolicyPaths {
+    return this.loader.getResolvedPolicyPaths();
+  }
+
+  private resolvePermissions(agentName?: string): ResolvedPermissions {
+    const cacheKey = agentName ?? "__global__";
+    const stamp = this.loader.getCacheStamp(agentName);
+    const cached = this.resolvedPermissionsCache.get(cacheKey);
+    if (cached?.stamp === stamp) {
+      return cached.value;
+    }
+
+    const globalConfig = this.loader.loadGlobalConfig();
+    const projectConfig = this.loader.loadProjectConfig();
+    const agentConfig = this.loader.loadAgentConfig(agentName);
+    const projectAgentConfig = this.loader.loadProjectAgentConfig(agentName);
+
+    // Merge permission objects across scopes (lowest → highest precedence),
+    // building a parallel origin map that tracks which scope contributed each
+    // (surface, pattern) entry.
+    const { mergedPermission, origins } = mergeScopesWithOrigins([
+      ["global", globalConfig],
+      ["project", projectConfig],
+      ["agent", agentConfig],
+      ["project-agent", projectAgentConfig],
+    ]);
+
+    // Extract the universal fallback from permission["*"].
+    // The "*" key feeds synthesizeDefaults() only — it is NOT included as a
+    // config rule so that extension tools fall through to source:"default".
+    const universalFallback = isPermissionState(mergedPermission["*"])
+      ? mergedPermission["*"]
+      : DEFAULT_UNIVERSAL_FALLBACK;
+    // Track which scope contributed the universal fallback.
+    const universalFallbackOrigin: RuleOrigin =
+      origins.get("*")?.get("*") ?? "builtin";
+
+    // Build config rules from everything except the universal "*" key.
+    const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
+      Object.entries(mergedPermission).filter(([k]) => k !== "*"),
+    );
+
+    // Normalize to config rules, tagged with "config" layer and their origin.
+    const configRules: Ruleset = normalizeFlatConfig(
+      permissionWithoutUniversal,
+    ).map(
+      (r): Rule => ({
+        ...r,
+        layer: "config",
+        origin: origins.get(r.surface)?.get(r.pattern) ?? "builtin",
+      }),
+    );
+
+    const composedRules = composeRuleset(
+      synthesizeDefaults(universalFallback, universalFallbackOrigin),
+      synthesizeBaseline(configRules),
+      configRules,
+    );
+
+    const value: ResolvedPermissions = { composedRules };
+    this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
+    return value;
+  }
+
+  /**
+   * Return the composed config-layer rules for the given agent scope.
+   * Used by the `/permission-system show` command to display effective rules
+   * with their origin annotations.
+   * Session rules are not included — they are runtime-only.
+   */
+  getComposedConfigRules(agentName?: string): Ruleset {
+    const { composedRules } = this.resolvePermissions(agentName);
+    return composedRules.filter((r) => r.layer === "config");
+  }
+
+  /**
+   * Get the tool-level permission state for a tool, without considering
+   * command-level rules. Used for tool injection decisions.
+   */
+  getToolPermission(toolName: string, agentName?: string): PermissionState {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const normalizedToolName = toolName.trim();
+
+    // Special surfaces (external_directory): evaluate directly by surface name.
+    if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
+      return evaluate(normalizedToolName, "*", composedRules).action;
+    }
+
+    // Bash, MCP, skill: evaluate with "*" value — the per-surface catch-all
+    // (or universal default) handles this correctly.
+    if (normalizedToolName === "bash") {
+      return evaluate("bash", "*", composedRules).action;
+    }
+    if (normalizedToolName === "mcp") {
+      return evaluate("mcp", "*", composedRules).action;
+    }
+    if (normalizedToolName === "skill") {
+      return evaluate("skill", "*", composedRules).action;
+    }
+
+    // Tool-name surfaces (read, write, etc. and extension tools).
+    return evaluate(normalizedToolName, "*", composedRules).action;
+  }
+
+  checkPermission(
+    toolName: string,
+    input: unknown,
+    agentName?: string,
+    sessionRules?: Ruleset,
+  ): PermissionCheckResult {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const normalizedToolName = toolName.trim();
+
+    // Append session rules at the end (highest priority) so evaluate() handles
+    // them via last-match-wins — no separate per-branch pre-check needed.
+    const fullRules: Ruleset = sessionRules?.length
+      ? [...composedRules, ...sessionRules]
+      : composedRules;
+
+    const { surface, values, resultExtras } = normalizeInput(
+      normalizedToolName,
+      input,
+      this.loader.getConfiguredMcpServerNames(),
+      this.currentCwd,
+    );
+
+    return buildCheckResult(
+      surface,
+      values,
+      resultExtras,
+      normalizedToolName,
+      toolName,
+      fullRules,
+    );
+  }
+
+  checkPathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    sessionRules?: Ruleset,
+    surface = "path",
+  ): PermissionCheckResult {
+    const { composedRules } = this.resolvePermissions(agentName);
+    const fullRules: Ruleset = sessionRules?.length
+      ? [...composedRules, ...sessionRules]
+      : composedRules;
+
+    const lookupValues = values.length > 0 ? [...values] : ["*"];
+    return buildCheckResult(
+      surface,
+      lookupValues,
+      {},
+      surface,
+      surface,
+      fullRules,
+    );
+  }
+}
+
+/**
+ * Evaluate a normalized surface/values triple and shape the result.
+ *
+ * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
+ * aliases); every other surface keeps {@link evaluateFirst}. Shared by
+ * `checkPermission` and `checkPathPolicy`.
+ */
+function buildCheckResult(
+  surface: string,
+  values: string[],
+  resultExtras: Record<string, unknown>,
+  normalizedToolName: string,
+  toolName: string,
+  fullRules: Ruleset,
+): PermissionCheckResult {
+  const { rule, value } = PATH_SURFACES.has(surface)
+    ? evaluateAnyValue(surface, values, fullRules)
+    : evaluateFirst(surface, values, fullRules);
+
+  // For MCP, replace the normalizer's fallback target with the actual
+  // matched candidate value so PermissionCheckResult.target is accurate.
+  const extras =
+    surface === "mcp" ? { ...resultExtras, target: value } : resultExtras;
+
+  return {
+    toolName,
+    state: rule.action,
+    reason: rule.reason,
+    matchedPattern:
+      rule.layer === "config" || rule.layer === "session"
+        ? rule.pattern
+        : undefined,
+    source: deriveSource(rule, normalizedToolName),
+    origin: rule.origin,
+    ...extras,
+  };
+}
+
+/**
+ * Derive `PolicyLoaderOptions` from an agentDir + an optional cwd.
+ * Setting agentsDir explicitly from agentDir removes the hidden
+ * `getAgentDir()` env-read that FilePolicyLoader's default would perform.
+ */
+function derivePolicyLoaderOptions(
+  agentDir: string,
+  cwd: string | undefined | null,
+): PolicyLoaderOptions {
+  return {
+    globalConfigPath: getGlobalConfigPath(agentDir),
+    agentsDir: join(agentDir, "agents"),
+    projectGlobalConfigPath: cwd ? getProjectConfigPath(cwd) : undefined,
+    projectAgentsDir: cwd ? getProjectAgentsDir(cwd) : undefined,
+  };
+}
+
+/**
+ * Map a matched rule + tool name to the correct PermissionCheckResult.source.
+ *
+ * Mirrors the source-derivation logic from the former per-branch
+ * checkPermission() implementation:
+ *
+ * - session          → "session" (always, all surfaces)
+ * - mcp + default    → "default"
+ * - mcp + other      → "mcp"
+ * - special          → "special" (always)
+ * - skill            → "skill" (always)
+ * - bash             → "bash" (always)
+ * - built-in tool    → "tool" (always)
+ * - extension tool   → "default" when default layer, "tool" otherwise
+ */
+function deriveSource(
+  rule: Rule,
+  toolName: string,
+): PermissionCheckResult["source"] {
+  if (rule.layer === "session") return "session";
+
+  if (toolName === "mcp") {
+    if (rule.layer === "default") return "default";
+    return "mcp";
+  }
+
+  if (SPECIAL_PERMISSION_KEYS.has(toolName)) return "special";
+  if (toolName === "skill") return "skill";
+  if (toolName === "bash") return "bash";
+
+  // Built-in tools always report "tool"; extension tools distinguish default.
+  if (BUILT_IN_TOOL_PERMISSION_NAMES.has(toolName)) return "tool";
+  return rule.layer === "default" ? "default" : "tool";
+}
+
+// Re-export types that external modules import from this file.
+export type { PolicyLoader, ResolvedPolicyPaths } from "./policy-loader";

package/src/permission-merge.ts

@@ -0,0 +1,32 @@
+import type { FlatPermissionConfig } from "./types";
+
+/**
+ * Deep-shallow merge two flat permission configs.
+ * Both objects → shallow-merge the pattern maps.
+ * Otherwise → override replaces base.
+ */
+export function mergeFlatPermissions(
+  base: FlatPermissionConfig,
+  override: FlatPermissionConfig,
+): FlatPermissionConfig {
+  const merged: FlatPermissionConfig = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const baseVal = merged[key];
+    /* eslint-disable @typescript-eslint/no-unnecessary-condition -- defensive null/type checks; config values may differ at runtime */
+    if (
+      typeof baseVal === "object" &&
+      baseVal !== null &&
+      typeof value === "object" &&
+      value !== null
+    ) {
+      /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+      merged[key] = {
+        ...baseVal,
+        ...value,
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}

package/src/permission-prompter.ts

@@ -0,0 +1,142 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ConfigReader } from "./config-store";
+import type { ApprovalRequester } from "./forwarded-permissions/permission-forwarder";
+import type { PermissionPromptDecision } from "./permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "./permission-events";
+import { buildDirectUiPrompt } from "./permission-ui-prompt";
+import type { ReviewLogger } from "./session-logger";
+import { shouldAutoApprovePermissionState } from "./yolo-mode";
+
+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;
+  /** Override label for the "for this session" dialog option. */
+  sessionLabel?: string;
+}
+
+/** Mockable contract for permission prompting. */
+export interface PermissionPrompterApi {
+  prompt(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
+}
+
+/**
+ * Dependencies required by PermissionPrompter.
+ *
+ * Keeps the prompter's external surface narrow: callers provide config
+ * access, a review logger, the UI-prompt event bus, and the forwarder
+ * that owns the UI/subagent-forwarding branching logic.
+ */
+export interface PermissionPrompterDeps {
+  /** Read current config for yolo-mode check (called at prompt time). */
+  config: ConfigReader;
+  /** Write structured entries to the permission review log. */
+  logger: ReviewLogger;
+  /** Event bus used for UI prompt broadcasts. */
+  events: PermissionEventBus;
+  /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
+  forwarder: ApprovalRequester;
+}
+
+/**
+ * Encapsulates the full permission-prompt flow:
+ *   1. Yolo-mode auto-approval check.
+ *   2. Review-log "waiting" entry.
+ *   3. UI-present vs. subagent-forwarding branching (via confirmPermission).
+ *   4. Review-log "approved" / "denied" entry.
+ *
+ * Injecting a single PermissionPrompter instance means adding a new prompt
+ * parameter (e.g. a future sessionLabel variant) only requires changing
+ * PromptPermissionDetails and this class — not the full threading chain.
+ */
+export class PermissionPrompter implements PermissionPrompterApi {
+  constructor(private readonly deps: PermissionPrompterDeps) {}
+
+  async prompt(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    if (shouldAutoApprovePermissionState("ask", this.deps.config.current())) {
+      this.writeReviewEntry("permission_request.auto_approved", details);
+      return { approved: true, state: "approved", autoApproved: true };
+    }
+
+    this.writeReviewEntry("permission_request.waiting", details);
+
+    // Build the event once. When this session has UI it broadcasts directly;
+    // when it does not (a forwarding subagent), the display fields ride along
+    // to the parent so the parent emits a non-degraded event from the
+    // forwarded path instead of here.
+    const uiPrompt = buildDirectUiPrompt(details);
+    if (ctx.hasUI) {
+      emitUiPromptEvent(this.deps.events, uiPrompt);
+    }
+
+    const decision = await this.deps.forwarder.requestApproval(
+      ctx,
+      details.message,
+      details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+      {
+        source: uiPrompt.source,
+        surface: uiPrompt.surface,
+        value: uiPrompt.value,
+      },
+    );
+
+    this.writeReviewEntry(
+      decision.approved
+        ? "permission_request.approved"
+        : "permission_request.denied",
+      {
+        ...details,
+        resolution: decision.state,
+        denialReason: decision.denialReason,
+      },
+    );
+
+    return decision;
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private writeReviewEntry(
+    event: string,
+    details: PromptPermissionDetails & {
+      resolution?: string;
+      denialReason?: string;
+    },
+  ): void {
+    this.deps.logger.review(event, {
+      requestId: details.requestId,
+      source: details.source,
+      agentName: details.agentName,
+      message: details.message,
+      toolCallId: details.toolCallId ?? null,
+      toolName: details.toolName ?? null,
+      skillName: details.skillName ?? null,
+      path: details.path ?? null,
+      command: details.command ?? null,
+      target: details.target ?? null,
+      toolInputPreview: details.toolInputPreview ?? null,
+      resolution: details.resolution ?? null,
+      denialReason: details.denialReason ?? null,
+    });
+  }
+}