@komarspn/pi-permission-system 16.0.2

package/src/handlers/before-agent-start.ts

@@ -0,0 +1,94 @@
+import type {
+  BeforeAgentStartEventResult,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { PermissionSession } from "#src/permission-session";
+import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
+import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
+import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
+import type { PermissionState } from "#src/types";
+
+/** Minimal subset of BeforeAgentStartEvent used by this handler. */
+interface BeforeAgentStartPayload {
+  systemPrompt: string;
+}
+
+/**
+ * Pure helper: returns true when the tool should be exposed to the agent.
+ * Checks the tool-level permission (not command-level) so that a blanket
+ * `bash: deny` hides the tool entirely before any invocation is attempted.
+ */
+export function shouldExposeTool(
+  toolName: string,
+  agentName: string | null,
+  getToolPermission: (toolName: string, agentName?: string) => PermissionState,
+): boolean {
+  const toolPermission = getToolPermission(toolName, agentName ?? undefined);
+  return toolPermission !== "deny";
+}
+
+/**
+ * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
+ *
+ * Recomputes the active tool set and the returned system-prompt override on
+ * every fire (no memoization): the override must be returned each turn so that
+ * skill filtering is reapplied and the wire prompt stays byte-stable, rather
+ * than letting Pi reset to its skill-unfiltered base prompt on a cache hit.
+ *
+ * Constructor deps:
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
+ * - `toolRegistry` — Pi tool API subset (getActive + setActive)
+ */
+export class AgentPrepHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
+    private readonly toolRegistry: ToolRegistry,
+  ) {}
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async handle(
+    event: BeforeAgentStartPayload,
+    ctx: ExtensionContext,
+  ): Promise<BeforeAgentStartEventResult> {
+    this.session.activate(ctx);
+    this.session.refreshConfig(ctx);
+
+    const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
+    const activeTools = this.toolRegistry.getActive();
+    const allowedTools: string[] = [];
+
+    for (const tool of activeTools) {
+      const toolName = getToolNameFromValue(tool);
+      if (!toolName) {
+        continue;
+      }
+      if (
+        shouldExposeTool(toolName, agentName, (t, a) =>
+          this.resolver.getToolPermission(t, a),
+        )
+      ) {
+        allowedTools.push(toolName);
+      }
+    }
+
+    this.toolRegistry.setActive(allowedTools);
+
+    const toolPromptResult = sanitizeAvailableToolsSection(
+      event.systemPrompt,
+      allowedTools,
+    );
+    const skillPromptResult = resolveSkillPromptEntries(
+      toolPromptResult.prompt,
+      this.resolver,
+      agentName,
+      ctx.cwd,
+    );
+    this.session.setActiveSkillEntries(skillPromptResult.entries);
+    return skillPromptResult.prompt !== event.systemPrompt
+      ? { systemPrompt: skillPromptResult.prompt }
+      : {};
+  }
+}

package/src/handlers/gates/bash-command.ts

@@ -0,0 +1,75 @@
+import type { BashCommand } from "#src/handlers/gates/bash-program";
+import { pickMostRestrictive } from "#src/handlers/gates/candidate-check";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PermissionCheckResult } from "#src/types";
+
+/**
+ * Resolve the bash command-pattern decision for a (possibly chained) command.
+ *
+ * A bash invocation may be a shell program with several commands joined by
+ * `&&`, `||`, `;`, `|`, `&`, or newlines. Matching the whole string against the
+ * bash patterns lets a denied command ride through on an allowed leading one
+ * (issue #301). Instead, the caller supplies the program's command units (from
+ * the shared `BashProgram.commands()` parse) — including those nested inside
+ * substitutions and subshells (#306); each is evaluated on the `bash` surface
+ * and the most restrictive result wins (`deny > ask > allow`).
+ *
+ * The selected result carries the offending sub-command in `command`, its rule
+ * in `matchedPattern`, and the offending command's execution context in
+ * `commandContext` (set only for a nested command), so the prompt,
+ * session-approval suggestion, and decision event scope to that command.
+ *
+ * When `commands` is empty there are two cases. A trivially-empty command (an
+ * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
+ * so the whole `command` is resolved as before. A non-empty command that parsed
+ * to zero command units (a parse anomaly or an opaque program) fails closed to
+ * a synthetic `ask` so a permissive top-level `*` cannot silently allow an
+ * unparseable command (e.g. `cd /repo && git push` riding a top-level allow on
+ * the empty-parse path) — #452.
+ *
+ * Pure and synchronous: the (async, tree-sitter) parse happens once in the
+ * handler, which passes the decomposed `commands` here.
+ */
+export function resolveBashCommandCheck(
+  command: string,
+  commands: BashCommand[],
+  agentName: string | undefined,
+  resolver: ScopedPermissionResolver,
+): PermissionCheckResult {
+  if (commands.length === 0) {
+    if (isTriviallyEmptyCommand(command)) {
+      return resolver.resolve("bash", { command }, agentName);
+    }
+    return {
+      state: "ask",
+      toolName: "bash",
+      source: "bash",
+      origin: "builtin",
+      command,
+      matchedPattern: "<unparseable-bash-command>",
+    };
+  }
+
+  const results = commands.map((cmd) => {
+    const result = resolver.resolve("bash", { command: cmd.text }, agentName);
+    return cmd.context ? { ...result, commandContext: cmd.context } : result;
+  });
+  return (
+    pickMostRestrictive(results) ??
+    resolver.resolve("bash", { command }, agentName)
+  );
+}
+
+/**
+ * True when a command has genuinely nothing to gate: it is empty,
+ * whitespace-only, or contains only comment lines (every non-blank line starts
+ * with `#`). Such a command yields zero command units legitimately, so the
+ * whole-string resolve is safe rather than a parse anomaly.
+ */
+function isTriviallyEmptyCommand(command: string): boolean {
+  const lines = command
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines.every((line) => line.startsWith("#"));
+}

package/src/handlers/gates/bash-external-directory.ts

@@ -0,0 +1,127 @@
+import { getNonEmptyString, toRecord } from "#src/common";
+import { getExternalDirectoryPolicyValues } from "#src/path-utils";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { SessionApproval } from "#src/session-approval";
+import { deriveApprovalPattern } from "#src/session-rules";
+import type { PermissionCheckResult } from "#src/types";
+import type { BashProgram } from "./bash-program";
+import { pickMostRestrictive } from "./candidate-check";
+import type { GateResult } from "./descriptor";
+import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
+import type { ToolCallContext } from "./types";
+
+/**
+ * Build a pure descriptor for the bash external-directory permission gate.
+ *
+ * Reads the external paths from the injected `BashProgram` and checks whether
+ * any reference directories outside the working directory. Returns `null` when the gate
+ * does not apply (tool is not bash, no CWD, or no external paths found).
+ * Returns a `GateBypass` when all paths are allowed (by config or session rule).
+ * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
+ */
+export function describeBashExternalDirectoryGate(
+  tcc: ToolCallContext,
+  bashProgram: BashProgram | null,
+  resolver: ScopedPermissionResolver,
+): GateResult {
+  if (tcc.toolName !== "bash" || !tcc.cwd) return null;
+
+  const command = getNonEmptyString(toRecord(tcc.input).command);
+  if (!command) return null;
+
+  if (!bashProgram) return null;
+
+  const externalPaths = bashProgram.externalPaths(tcc.cwd);
+  if (externalPaths.length === 0) return null;
+
+  // Collect paths whose resolved state is not already "allow".
+  // Checking state (not source) ensures config-level allow rules (source: "special")
+  // suppress the prompt just as session-level allow rules (source: "session") do.
+  const uncoveredEntries: Array<{
+    path: string;
+    check: PermissionCheckResult;
+  }> = [];
+  for (const p of externalPaths) {
+    // Match each path against both its typed and symlink-resolved aliases on
+    // the external_directory surface, so a config pattern on either form
+    // applies (#418).
+    const check = resolver.resolvePathPolicy(
+      getExternalDirectoryPolicyValues(p, tcc.cwd),
+      tcc.agentName ?? undefined,
+      "external_directory",
+    );
+    if (check.state !== "allow") {
+      uncoveredEntries.push({ path: p, check });
+    }
+  }
+  const uncoveredPaths = uncoveredEntries.map(({ path }) => path);
+
+  if (uncoveredPaths.length === 0) {
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.session_approved",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          command,
+          externalPaths,
+          resolution: "session_approved",
+        },
+      },
+    };
+  }
+
+  // Use the most restrictive check among uncovered paths as the pre-check result.
+  // This ensures a config-level "deny" rule is not downgraded to "ask" by the
+  // generic "*" catch-all that the old path-less checkPermission call returned.
+  const worstCheck =
+    pickMostRestrictive(uncoveredEntries.map(({ check }) => check)) ??
+    uncoveredEntries[0].check;
+
+  const bashExtMessage = formatBashExternalDirectoryAskPrompt(
+    command,
+    uncoveredPaths,
+    tcc.cwd,
+    tcc.agentName ?? undefined,
+  );
+
+  const patterns = uncoveredPaths.map((p) => deriveApprovalPattern(p));
+
+  return {
+    surface: "external_directory",
+    input: {},
+    denialContext: {
+      kind: "bash_external_directory",
+      command,
+      externalPaths: uncoveredPaths,
+      cwd: tcc.cwd,
+      agentName: tcc.agentName ?? undefined,
+    },
+    sessionApproval: SessionApproval.multiple("external_directory", patterns),
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: bashExtMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      command,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      command,
+      externalPaths: uncoveredPaths,
+      message: bashExtMessage,
+    },
+    decision: {
+      surface: "external_directory",
+      value: command,
+    },
+    preCheck: worstCheck,
+  };
+}

package/src/handlers/gates/bash-path-extractor.ts

@@ -0,0 +1,15 @@
+import { BashProgram } from "./bash-program";
+
+/**
+ * Extract paths from a bash command string that resolve outside CWD.
+ *
+ * Thin facade over {@link BashProgram.externalPaths}; parses the command and
+ * returns the cd-aware external paths. See `BashProgram` for the parsing and
+ * resolution semantics.
+ */
+export async function extractExternalPathsFromBashCommand(
+  command: string,
+  cwd: string,
+): Promise<string[]> {
+  return (await BashProgram.parse(command)).externalPaths(cwd);
+}

package/src/handlers/gates/bash-path.ts

@@ -0,0 +1,152 @@
+import { getNonEmptyString, toRecord } from "#src/common";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { SessionApproval } from "#src/session-approval";
+import { deriveApprovalPattern } from "#src/session-rules";
+import type { PermissionCheckResult } from "#src/types";
+import type { BashProgram } from "./bash-program";
+import { pickMostRestrictive } from "./candidate-check";
+import type { GateResult } from "./descriptor";
+import { formatPathAskPrompt } from "./path";
+import type { ToolCallContext } from "./types";
+
+/**
+ * Build a pure descriptor for the cross-cutting path permission gate (bash).
+ *
+ * Reads path-rule candidates from the injected `BashProgram` (the broader
+ * `path`-rule filter, accepting dot-files and relative paths). Each candidate
+ * pairs the raw token with cd-aware policy values; the gate evaluates those
+ * values against the `path` permission surface and returns the most
+ * restrictive result, while prompts, logs, and session approvals use the raw
+ * token.
+ *
+ * Returns `null` when the gate does not apply (tool is not bash, no command,
+ * no tokens extracted, or all tokens evaluate to `allow`).
+ * Returns a `GateBypass` when all tokens are session-covered.
+ * Returns a `GateDescriptor` for the most restrictive token needing a check.
+ */
+export function describeBashPathGate(
+  tcc: ToolCallContext,
+  bashProgram: BashProgram | null,
+  resolver: ScopedPermissionResolver,
+): GateResult {
+  if (tcc.toolName !== "bash") return null;
+
+  const command = getNonEmptyString(toRecord(tcc.input).command);
+  if (!command) return null;
+
+  if (!bashProgram) return null;
+
+  const candidates = bashProgram.pathRuleCandidates(tcc.cwd);
+  if (candidates.length === 0) return null;
+  const tokens = candidates.map(({ token }) => token);
+
+  // Tokens whose resolved state needs a check (deny/ask), paired with the raw
+  // token (prompt/decision display) and its policy values (the first of which
+  // is the canonical absolute path the approval pattern is derived from).
+  const uncovered: Array<{
+    token: string;
+    policyValues: readonly string[];
+    check: PermissionCheckResult;
+  }> = [];
+  let allSessionCovered = true;
+
+  for (const { token, policyValues } of candidates) {
+    const check = resolver.resolvePathPolicy(
+      policyValues,
+      tcc.agentName ?? undefined,
+    );
+
+    // No explicit path rule matched — only the universal default fired.
+    // Treat this token as unrestricted to preserve backward compatibility
+    // for configs without a "path" key (#58).
+    if (check.matchedPattern === undefined && check.source !== "session") {
+      allSessionCovered = false;
+      continue;
+    }
+
+    if (check.source !== "session") {
+      allSessionCovered = false;
+    }
+
+    if (check.state === "deny") {
+      uncovered.push({ token, policyValues, check });
+      break; // Short-circuit on deny.
+    }
+    if (check.state === "ask") {
+      uncovered.push({ token, policyValues, check });
+    }
+  }
+
+  // All tokens are session-covered — bypass.
+  if (allSessionCovered) {
+    return {
+      action: "allow",
+      log: {
+        event: "permission_request.session_approved",
+        details: {
+          source: "tool_call",
+          toolCallId: tcc.toolCallId,
+          toolName: tcc.toolName,
+          agentName: tcc.agentName,
+          command,
+          tokens,
+          resolution: "session_approved",
+        },
+      },
+    };
+  }
+
+  // Pick the most restrictive (deny > ask > allow, first-wins) uncovered token.
+  const worstCheck = pickMostRestrictive(uncovered.map(({ check }) => check));
+  const worstEntry = worstCheck
+    ? uncovered.find(({ check }) => check === worstCheck)
+    : undefined;
+  const worstToken = worstEntry?.token ?? null;
+
+  // All tokens evaluate to allow — no restriction.
+  if (!worstCheck || !worstToken || !worstEntry) return null;
+
+  // Derive the pattern from the canonical absolute policy value (the cd-aware
+  // resolved path), so it matches the values a later call produces. Falls back
+  // to the raw token only when no base was resolvable (no cwd / unknown cd).
+  const approvalBase = worstEntry.policyValues[0] ?? worstToken;
+  const pattern = deriveApprovalPattern(approvalBase);
+  const askMessage = formatPathAskPrompt(
+    tcc.toolName,
+    worstToken,
+    tcc.agentName ?? undefined,
+  );
+
+  return {
+    surface: "path",
+    input: { path: worstToken },
+    denialContext: {
+      kind: "bash_path",
+      command,
+      pathValue: worstToken,
+      agentName: tcc.agentName ?? undefined,
+    },
+    sessionApproval: SessionApproval.single("path", pattern),
+    promptDetails: {
+      source: "tool_call",
+      agentName: tcc.agentName,
+      message: askMessage,
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      command,
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: tcc.toolCallId,
+      toolName: tcc.toolName,
+      agentName: tcc.agentName,
+      command,
+      path: worstToken,
+    },
+    decision: {
+      surface: "path",
+      value: worstToken,
+    },
+    preCheck: worstCheck,
+  };
+}