@komarspn/pi-permission-system 16.0.2

package/src/permission-prompts.ts

@@ -0,0 +1,93 @@
+import { getNonEmptyString, toRecord } from "./common";
+import { matchQualifier } from "./denial-messages";
+import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
+import type { ToolPreviewFormatter } from "./tool-preview-formatter";
+import type { PermissionCheckResult } from "./types";
+
+// NOTE: formatDenyReason, formatUserDeniedReason, and
+// formatPermissionHardStopHint have been moved to denial-messages.ts.
+// This module retains only pre-check messages and user-facing ask prompts.
+
+export function formatMissingToolNameReason(): string {
+  return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";
+}
+
+export 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}.`;
+}
+
+export function formatAskPrompt(
+  result: PermissionCheckResult,
+  agentName?: string,
+  input?: unknown,
+  formatter?: ToolPreviewFormatter,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+
+  if (result.toolName === "bash") {
+    const subCommand = result.command ?? "";
+    const qualifier = matchQualifier(
+      result.matchedPattern,
+      result.commandContext,
+    );
+    const qualifierInfo = qualifier ? ` ${qualifier}` : "";
+    const fullCommand = getNonEmptyString(toRecord(input).command);
+    const fullCommandInfo =
+      fullCommand && fullCommand !== subCommand
+        ? ` (full command: '${fullCommand}')`
+        : "";
+    return `${subject} requested bash command '${subCommand}'${qualifierInfo}${fullCommandInfo}. Allow this command?`;
+  }
+
+  if ((result.source === "mcp" || result.toolName === "mcp") && result.target) {
+    const patternInfo = result.matchedPattern
+      ? ` (matched '${result.matchedPattern}')`
+      : "";
+    const mcpPreview = formatter
+      ? formatter.formatToolInputForPrompt("mcp", input)
+      : "";
+    const previewSuffix = mcpPreview ? ` ${mcpPreview}` : "";
+    return `${subject} requested MCP target '${result.target}'${patternInfo}${previewSuffix}. Allow this call?`;
+  }
+
+  const patternInfo = result.matchedPattern
+    ? ` (matched '${result.matchedPattern}')`
+    : "";
+  const inputPreview = formatter
+    ? formatter.formatToolInputForPrompt(result.toolName, input)
+    : "";
+  const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
+  return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
+}
+
+export function formatSkillAskPrompt(
+  skillName: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested skill '${skillName}'. Allow loading this skill?`;
+}
+
+export 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?`;
+}
+
+// formatSkillPathDenyReason has been moved to denial-messages.ts.

package/src/permission-resolver.ts

@@ -0,0 +1,109 @@
+import type { ScopedPermissionManager } from "./permission-manager";
+import type { Rule } from "./rule";
+import type { SessionRules } from "./session-rules";
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+/**
+ * Resolves the effective permission for a surface/input, applying the current
+ * session rules internally.
+ *
+ * Collapses the `checkPermission` + `getSessionRuleset` relay that every gate
+ * previously threaded by hand: the ruleset was only ever fetched to be passed
+ * straight back into `checkPermission`, so the two are one operation.
+ */
+export interface ScopedPermissionResolver {
+  resolve(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult;
+  /**
+   * Resolve a path-shaped surface against a caller-supplied set of equivalent
+   * policy values, applying the current session rules. Used by the bash path
+   * gate (`path`) and the external-directory gates (`external_directory`),
+   * which compute equivalent path aliases per token. `surface` defaults to
+   * `path`.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    surface?: string,
+  ): PermissionCheckResult;
+}
+
+/**
+ * Concrete collaborator that owns the resolution surface.
+ *
+ * Holds a `ScopedPermissionManager` and a `SessionRules` store, composing
+ * them so callers never thread the session ruleset by hand.
+ *
+ * Constructor deps:
+ * - `permissionManager` — the narrow session-scoped permission-checking interface
+ * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
+ */
+export class PermissionResolver implements ScopedPermissionResolver {
+  constructor(
+    private readonly permissionManager: ScopedPermissionManager,
+    private readonly sessionRules: Pick<SessionRules, "getRuleset">,
+  ) {}
+
+  /**
+   * Resolve the effective permission for a surface/input, applying the current
+   * session rules. Composes `checkPermission` with `getRuleset()` so callers
+   * never thread the ruleset by hand.
+   */
+  resolve(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult {
+    return this.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
+  /**
+   * Resolve a path-shaped surface (`path` or `external_directory`) for
+   * precomputed policy values, composing the current session ruleset so callers
+   * never thread it by hand. `surface` defaults to `path`; the external-directory
+   * gates pass `external_directory` so a path's typed and symlink-resolved
+   * aliases match against the `external_directory` rules.
+   */
+  resolvePathPolicy(
+    values: readonly string[],
+    agentName?: string,
+    surface = "path",
+  ): PermissionCheckResult {
+    return this.permissionManager.checkPathPolicy(
+      values,
+      agentName,
+      this.sessionRules.getRuleset(),
+      surface,
+    );
+  }
+
+  checkPermission(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+    sessionRules?: Rule[],
+  ): PermissionCheckResult {
+    return this.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName,
+      sessionRules,
+    );
+  }
+
+  getToolPermission(toolName: string, agentName?: string): PermissionState {
+    return this.permissionManager.getToolPermission(toolName, agentName);
+  }
+
+  getConfigIssues(agentName?: string): string[] {
+    return this.permissionManager.getConfigIssues(agentName);
+  }
+}

package/src/permission-session.ts

@@ -0,0 +1,189 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  getActiveAgentName,
+  getActiveAgentNameFromSystemPrompt,
+} from "./active-agent";
+
+import type { SessionConfigStore } from "./config-store";
+import type { PermissionSystemExtensionConfig } from "./extension-config";
+import type { ExtensionPaths } from "./extension-paths";
+import type { ForwardingController } from "./forwarding-manager";
+import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
+import type { ScopedPermissionManager } from "./permission-manager";
+import type { PromptingGatewayLifecycle } from "./prompting-gateway";
+
+import type { SessionRules } from "./session-rules";
+import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
+import {
+  resolveToolPreviewLimits,
+  type ToolPreviewFormatterOptions,
+} from "./tool-preview-formatter";
+
+/**
+ * Encapsulates all mutable session state and exposes operations instead of
+ * fields.
+ *
+ * Replaces the `SessionState` interface + scattered handler field mutations
+ * with a single class that owns the `PermissionManager`, `SessionRules`,
+ * cache keys, skill entries, and runtime context.
+ *
+ * Constructor deps:
+ * - `ExtensionPaths` — immutable path constants
+ * - `ForwardingController` — polling lifecycle
+ * - `SessionConfigStore` — owns extension config; provides refresh, log, read
+ * - `PromptingGatewayLifecycle` — prompting lifecycle forwarded via activate/deactivate
+ */
+export class PermissionSession implements ToolCallGateInputs {
+  private context: ExtensionContext | null = null;
+  private skillEntries: SkillPromptEntry[] = [];
+  private knownAgentName: string | null = null;
+
+  constructor(
+    private readonly paths: ExtensionPaths,
+    private readonly forwarding: ForwardingController,
+    private readonly permissionManager: ScopedPermissionManager,
+    private readonly sessionRules: SessionRules,
+    private readonly configStore: SessionConfigStore,
+    private readonly gateway: PromptingGatewayLifecycle,
+  ) {}
+
+  // ── Context lifecycle ──────────────────────────────────────────────────
+
+  /** Store the current extension context, start forwarding, and activate the gateway. */
+  activate(ctx: ExtensionContext): void {
+    this.context = ctx;
+    this.forwarding.start(ctx);
+    this.gateway.activate(ctx);
+  }
+
+  /** Clear the context, stop forwarding, and deactivate the gateway. */
+  deactivate(): void {
+    this.context = null;
+    this.forwarding.stop();
+    this.gateway.deactivate();
+  }
+
+  /** Return the current runtime context, or null if not activated. */
+  getRuntimeContext(): ExtensionContext | null {
+    return this.context;
+  }
+
+  // ── UI notifications ────────────────────────────────────────────────────
+
+  /** Surface a warning message to the user via the active UI context, if any. */
+  notify(message: string): void {
+    this.context?.ui.notify(message, "warning");
+  }
+
+  // ── Session lifecycle ────────────────────────────────────────────────────
+
+  /**
+   * Reset all mutable state for a new session.
+   *
+   * Configures the injected PermissionManager for `ctx.cwd`, clears skill
+   * entries, and activates the new context.
+   */
+  resetForNewSession(ctx: ExtensionContext): void {
+    this.permissionManager.configureForCwd(ctx.cwd);
+    this.skillEntries = [];
+    this.activate(ctx);
+  }
+
+  /**
+   * Shut down the session: clear rules, skill entries, and deactivate
+   * context + forwarding.
+   */
+  shutdown(): void {
+    this.sessionRules.clear();
+    this.skillEntries = [];
+    this.deactivate();
+  }
+
+  /**
+   * Reload permission manager and clear skill entries for the current context.
+   * Used on config reload (e.g. `resources_discover` with reason "reload").
+   */
+  reload(): void {
+    this.permissionManager.configureForCwd(this.context?.cwd);
+    this.skillEntries = [];
+  }
+
+  // ── Skill entries ──────────────────────────────────────────────────────
+
+  getActiveSkillEntries(): SkillPromptEntry[] {
+    return this.skillEntries;
+  }
+
+  setActiveSkillEntries(entries: SkillPromptEntry[]): void {
+    this.skillEntries = entries;
+  }
+
+  // ── Agent name ─────────────────────────────────────────────────────────
+
+  /**
+   * Resolve the active agent name from the session context, system prompt,
+   * or last known name. Updates lastKnownActiveAgentName as a side effect.
+   */
+  resolveAgentName(
+    ctx: ExtensionContext,
+    systemPrompt?: string,
+  ): string | null {
+    const fromSession = getActiveAgentName(ctx);
+    if (fromSession) {
+      this.knownAgentName = fromSession;
+      return fromSession;
+    }
+    const fromSystemPrompt = getActiveAgentNameFromSystemPrompt(systemPrompt);
+    if (fromSystemPrompt) {
+      this.knownAgentName = fromSystemPrompt;
+      return fromSystemPrompt;
+    }
+    return this.knownAgentName;
+  }
+
+  // Read by the `index.ts` config-modal adapter closure:
+  // `permissionManager.getComposedConfigRules(session.lastKnownActiveAgentName ?? undefined)`.
+  get lastKnownActiveAgentName(): string | null {
+    return this.knownAgentName;
+  }
+
+  // ── Config ─────────────────────────────────────────────────────────────
+
+  /** Reload merged config from disk; optionally update the stored runtime context. */
+  refreshConfig(ctx?: ExtensionContext): void {
+    this.configStore.refresh(ctx);
+  }
+
+  /** Write the resolved config path set to the review and debug logs. */
+  logResolvedConfigPaths(): void {
+    this.configStore.logResolvedPaths(this.context?.cwd);
+  }
+
+  /** Read current extension config. */
+  get config(): PermissionSystemExtensionConfig {
+    return this.configStore.current();
+  }
+
+  // ── Infrastructure paths ───────────────────────────────────────────────
+
+  /**
+   * Combined infrastructure read directories: static paths from
+   * `ExtensionPaths` plus config-derived paths.
+   */
+  getInfrastructureReadDirs(): string[] {
+    return [
+      ...this.paths.piInfrastructureDirs,
+      ...(this.config.piInfrastructureReadPaths ?? []),
+    ];
+  }
+
+  /**
+   * Resolved tool-preview formatter options from the current config.
+   *
+   * Replaces the handler's `resolveToolPreviewLimits(session.config)` reach
+   * so the pipeline reads a clean value rather than pulling raw config.
+   */
+  getToolPreviewLimits(): ToolPreviewFormatterOptions {
+    return resolveToolPreviewLimits(this.config);
+  }
+}

package/src/permission-ui-prompt.ts

@@ -0,0 +1,127 @@
+/**
+ * Centralized construction for `permissions:ui_prompt` payloads.
+ *
+ * Every emit site builds its event through one of these functions, so the
+ * public contract's shape — including the normalized `surface`/`value`
+ * projection — lives in exactly one place and cannot drift by source.
+ *
+ * This module is a leaf: it owns narrow input types that each call site's
+ * domain object satisfies structurally, so it imports nothing from the
+ * prompter, RPC, or forwarding modules (no import cycles, correct layering).
+ */
+
+import type {
+  PermissionUiPromptEvent,
+  PermissionUiPromptSource,
+} from "./permission-events";
+
+/** Input for a direct (non-forwarded) tool or skill prompt. */
+export interface DirectPromptInput {
+  requestId: string;
+  source: "tool_call" | "skill_input" | "skill_read";
+  agentName: string | null;
+  message: string;
+  toolName?: string;
+  skillName?: string;
+  path?: string;
+  command?: string;
+  target?: string;
+}
+
+/** Input for a `permissions:rpc:prompt` forwarded UI prompt. */
+export interface RpcPromptInput {
+  requestId: string;
+  surface?: string | null;
+  value?: string | null;
+  agentName?: string | null;
+  message: string;
+}
+
+/** Input for a file-forwarded subagent prompt shown by the parent UI. */
+export interface ForwardedPromptInput {
+  requestId: string;
+  message: string;
+  requesterAgentName: string | null;
+  requesterSessionId: string | null;
+  /** Original prompt origin, when the forwarded request carries it. */
+  source?: PermissionUiPromptSource | null;
+  /** Original normalized surface, when the forwarded request carries it. */
+  surface?: string | null;
+  /** Original normalized value, when the forwarded request carries it. */
+  value?: string | null;
+}
+
+/** Normalized display surface for a direct prompt. */
+function directSurface(input: DirectPromptInput): string | null {
+  if (input.source === "skill_input" || input.source === "skill_read") {
+    return "skill";
+  }
+  return input.toolName ?? null;
+}
+
+/** Normalized display value for a direct prompt. */
+function directValue(input: DirectPromptInput): string | null {
+  return (
+    input.command ??
+    input.path ??
+    input.target ??
+    input.skillName ??
+    input.toolName ??
+    null
+  );
+}
+
+/** Build the UI prompt event for a direct tool/skill prompt. */
+export function buildDirectUiPrompt(
+  input: DirectPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: input.source,
+    surface: directSurface(input),
+    value: directValue(input),
+    agentName: input.agentName,
+    message: input.message,
+    forwarding: null,
+  };
+}
+
+/** Build the UI prompt event for an RPC-forwarded prompt. */
+export function buildRpcUiPrompt(
+  input: RpcPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: "rpc_prompt",
+    surface: input.surface ?? null,
+    value: input.value ?? null,
+    agentName: input.agentName ?? null,
+    message: input.message,
+    forwarding: null,
+  };
+}
+
+/**
+ * Build the UI prompt event for a file-forwarded subagent prompt.
+ *
+ * `source` defaults to `"tool_call"` (the dominant forwarded origin) when the
+ * persisted request predates carrying it — a parent on a newer version may read
+ * a request written by an older child during an upgrade. The consumer still
+ * receives the notify-now signal, message, and forwarding context.
+ */
+export function buildForwardedUiPrompt(
+  input: ForwardedPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: input.source ?? "tool_call",
+    surface: input.surface ?? null,
+    value: input.value ?? null,
+    agentName: input.requesterAgentName,
+    message: input.message,
+    forwarding: {
+      requesterAgentName: input.requesterAgentName,
+      requesterSessionId: input.requesterSessionId,
+    },
+  };
+}

package/src/permissions-service.ts

@@ -0,0 +1,63 @@
+import { buildInputForSurface } from "./input-normalizer";
+import type { ScopedPermissionManager } from "./permission-manager";
+import type { PermissionsService } from "./service";
+import type { SessionRules } from "./session-rules";
+import type {
+  ToolAccessExtractor,
+  ToolAccessExtractorRegistrar,
+} from "./tool-access-extractor-registry";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterRegistrar,
+} from "./tool-input-formatter-registry";
+
+/**
+ * In-process implementation of the cross-extension {@link PermissionsService}.
+ *
+ * Constructed once in the composition root and backed by the single shared
+ * `PermissionManager` and `SessionRules` instances that `PermissionSession`
+ * also uses — so service queries and gate-path approvals see the same state.
+ */
+export class LocalPermissionsService implements PermissionsService {
+  constructor(
+    private readonly permissionManager: ScopedPermissionManager,
+    private readonly sessionRules: Pick<SessionRules, "getRuleset">,
+    private readonly formatterRegistry: ToolInputFormatterRegistrar,
+    private readonly accessExtractorRegistry: ToolAccessExtractorRegistrar,
+  ) {}
+
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["checkPermission"]> {
+    const input = buildInputForSurface(surface, value);
+    return this.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
+  getToolPermission(
+    toolName: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["getToolPermission"]> {
+    return this.permissionManager.getToolPermission(toolName, agentName);
+  }
+
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: ToolInputFormatter,
+  ): ReturnType<PermissionsService["registerToolInputFormatter"]> {
+    return this.formatterRegistry.register(toolName, formatter);
+  }
+
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: ToolAccessExtractor,
+  ): ReturnType<PermissionsService["registerToolAccessExtractor"]> {
+    return this.accessExtractorRegistry.register(toolName, extractor);
+  }
+}