@komarspn/pi-permission-system 16.0.2

package/src/system-prompt-sanitizer.ts

@@ -0,0 +1,274 @@
+export interface SanitizeSystemPromptResult {
+  prompt: string;
+  removed: boolean;
+}
+
+type LineSection = {
+  start: number;
+  end: number;
+};
+
+type GuidelineRule = {
+  matches: (guideline: string) => boolean;
+  shouldKeep: (allowedTools: ReadonlySet<string>) => boolean;
+};
+
+const AVAILABLE_TOOLS_SECTION_HEADER = "Available tools:";
+const GUIDELINES_SECTION_HEADER = "Guidelines:";
+
+const TOOL_GUIDELINE_RULES: readonly GuidelineRule[] = [
+  {
+    matches: (guideline) =>
+      guideline === "use bash for file operations like ls, rg, find",
+    shouldKeep: (allowedTools) => allowedTools.has("bash"),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+      "prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
+    shouldKeep: (allowedTools) =>
+      allowedTools.has("bash") &&
+      (allowedTools.has("grep") ||
+        allowedTools.has("find") ||
+        allowedTools.has("ls")),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+        "use read to examine files before editing. you must use this tool instead of cat or sed." ||
+      guideline === "use read to examine files instead of cat or sed.",
+    shouldKeep: (allowedTools) => allowedTools.has("read"),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+      "use edit for precise changes (old text must match exactly)",
+    shouldKeep: (allowedTools) => allowedTools.has("edit"),
+  },
+  {
+    matches: (guideline) =>
+      guideline === "use write only for new files or complete rewrites",
+    shouldKeep: (allowedTools) => allowedTools.has("write"),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+      "when summarizing your actions, output plain text directly - do not use cat or bash to display what you did",
+    shouldKeep: (allowedTools) =>
+      allowedTools.has("edit") || allowedTools.has("write"),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+      "use task when work should be delegated to one or more specialized agents instead of handled entirely in the current session.",
+    shouldKeep: (allowedTools) => allowedTools.has("task"),
+  },
+  {
+    matches: (guideline) =>
+      guideline ===
+      "use mcp for mcp discovery first: search by capability, describe one exact tool name, then call it.",
+    shouldKeep: (allowedTools) => allowedTools.has("mcp"),
+  },
+];
+
+function normalizePrompt(prompt: string): string {
+  return (prompt || "").replace(/\r\n/g, "\n");
+}
+
+function collapseExtraBlankLines(text: string): string {
+  return text.replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function normalizeGuidelineText(line: string): string {
+  return line
+    .trim()
+    .replace(/^[-*]\s+/, "")
+    .replace(/\s+/g, " ")
+    .toLowerCase();
+}
+
+function isTopLevelSectionHeader(line: string): boolean {
+  const trimmed = line.trim();
+  return (
+    trimmed.length > 0 && trimmed.endsWith(":") && !trimmed.startsWith("-")
+  );
+}
+
+function isSectionBodyLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return true; // blank line
+  if (trimmed.startsWith("- ")) return true; // bullet
+  if (line !== line.trimStart()) return true; // indented
+  return false;
+}
+
+function findSection(
+  lines: readonly string[],
+  header: string,
+): LineSection | null {
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) {
+    return null;
+  }
+
+  // If a subsequent recognised section header exists, use it as the boundary.
+  // This preserves the original behaviour for the common case where sections
+  // are adjacent (e.g. "Available tools:" followed by "Guidelines:") and
+  // ensures any prose continuation between the two headers is also removed.
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (isTopLevelSectionHeader(lines[index])) {
+      return { start, end: index };
+    }
+  }
+
+  // No subsequent section header — stop at the first non-body line so that
+  // content after the section (e.g. custom user notes) is not silently deleted.
+  let end = start + 1;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (!isSectionBodyLine(lines[index])) {
+      end = index;
+      break;
+    }
+    end = index + 1;
+  }
+
+  return { start, end };
+}
+
+/**
+ * Tool name from an `Available tools:` bullet (`- read: …` -> `read`), or
+ * `null` for non-tool lines (blank lines, boilerplate prose). Matches the
+ * first token after the bullet marker, with or without a trailing colon.
+ */
+function extractToolBulletName(line: string): string | null {
+  const match = /^\s*-\s+([A-Za-z0-9_-]+)/.exec(line);
+  return match ? match[1] : null;
+}
+
+/**
+ * Narrow the `Available tools:` section to the allowed tools: keep allowed-tool
+ * bullet lines and any non-tool prose, drop denied/inactive bullet lines. When
+ * no tool bullet survives, remove the section header too. This mirrors what Pi
+ * itself renders for the active tool set, so the result is byte-stable across
+ * turns regardless of whether the input still carries the full default listing.
+ */
+function narrowAvailableToolsSection(
+  lines: readonly string[],
+  allowedTools: ReadonlySet<string>,
+): { lines: string[]; removed: boolean } {
+  const section = findSection(lines, AVAILABLE_TOOLS_SECTION_HEADER);
+  if (!section) {
+    return { lines: [...lines], removed: false };
+  }
+
+  const before = lines.slice(0, section.start);
+  const header = lines[section.start];
+  const body = lines.slice(section.start + 1, section.end);
+  const after = lines.slice(section.end);
+
+  const filteredBody = body.filter((line) => {
+    const toolName = extractToolBulletName(line);
+    if (toolName === null) {
+      return true; // keep blank lines and non-tool boilerplate
+    }
+    return allowedTools.has(toolName);
+  });
+
+  const removed = filteredBody.length !== body.length;
+  if (!removed) {
+    return { lines: [...lines], removed: false };
+  }
+
+  const hasToolBullet = filteredBody.some(
+    (line) => extractToolBulletName(line) !== null,
+  );
+  if (!hasToolBullet) {
+    return { lines: [...before, ...after], removed: true };
+  }
+
+  return {
+    lines: [...before, header, ...filteredBody, ...after],
+    removed: true,
+  };
+}
+
+function shouldKeepGuideline(
+  line: string,
+  allowedTools: ReadonlySet<string>,
+): boolean {
+  const normalized = normalizeGuidelineText(line);
+
+  for (const rule of TOOL_GUIDELINE_RULES) {
+    if (rule.matches(normalized)) {
+      return rule.shouldKeep(allowedTools);
+    }
+  }
+
+  return true;
+}
+
+function sanitizeGuidelinesSection(
+  lines: readonly string[],
+  allowedTools: ReadonlySet<string>,
+): { lines: string[]; removed: boolean } {
+  const section = findSection(lines, GUIDELINES_SECTION_HEADER);
+  if (!section) {
+    return { lines: [...lines], removed: false };
+  }
+
+  const before = lines.slice(0, section.start + 1);
+  const after = lines.slice(section.end);
+  const body = lines.slice(section.start + 1, section.end);
+  const filteredBody = body.filter((line) => {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("- ")) {
+      return true;
+    }
+
+    return shouldKeepGuideline(line, allowedTools);
+  });
+
+  const removed = filteredBody.length !== body.length;
+  if (!removed) {
+    return { lines: [...lines], removed: false };
+  }
+
+  const hasBullet = filteredBody.some((line) => line.trim().startsWith("- "));
+  if (!hasBullet) {
+    return {
+      lines: [...lines.slice(0, section.start), ...after],
+      removed: true,
+    };
+  }
+
+  return {
+    lines: [...before, ...filteredBody, ...after],
+    removed: true,
+  };
+}
+
+export function sanitizeAvailableToolsSection(
+  systemPrompt: string,
+  allowedToolNames: readonly string[],
+): SanitizeSystemPromptResult {
+  const allowedTools = new Set(
+    allowedToolNames.map((toolName) => toolName.trim()).filter(Boolean),
+  );
+  const normalizedLines = normalizePrompt(systemPrompt).split("\n");
+  const narrowedToolsSection = narrowAvailableToolsSection(
+    normalizedLines,
+    allowedTools,
+  );
+  const sanitizedGuidelines = sanitizeGuidelinesSection(
+    narrowedToolsSection.lines,
+    allowedTools,
+  );
+  const removed = narrowedToolsSection.removed || sanitizedGuidelines.removed;
+
+  return {
+    prompt: removed
+      ? collapseExtraBlankLines(sanitizedGuidelines.lines.join("\n"))
+      : systemPrompt,
+    removed,
+  };
+}

package/src/tool-access-extractor-registry.ts

@@ -0,0 +1,68 @@
+/**
+ * Registry for custom tool access-intent extractors.
+ *
+ * Lets sibling extensions declare the filesystem path a tool will access when
+ * the tool's input shape is not the default `input.path` convention, so the
+ * cross-cutting `path` and `external_directory` gates can see it.
+ * One extractor per tool name; duplicate registration throws.
+ */
+
+/** Returns the filesystem path this tool will access, or `undefined` to decline. */
+export type ToolAccessExtractor = (
+  input: Record<string, unknown>,
+) => string | undefined;
+
+/**
+ * Read-only lookup used by the gate pipeline (ISP — exposes only the read
+ * side, not the registration surface).
+ */
+export interface ToolAccessExtractorLookup {
+  get(toolName: string): ToolAccessExtractor | undefined;
+}
+
+/**
+ * Registration side of the extractor registry (ISP — exposes only the write
+ * surface, mirroring the read-only {@link ToolAccessExtractorLookup}).
+ */
+export interface ToolAccessExtractorRegistrar {
+  register(toolName: string, extractor: ToolAccessExtractor): () => void;
+}
+
+/**
+ * Persistent registry mapping tool names to custom access-intent extractors.
+ *
+ * Owned by the extension factory (`index.ts`) so it survives across the
+ * per-tool-call gate evaluation cycle.
+ * Exposed to sibling extensions via `PermissionsService.registerToolAccessExtractor`.
+ */
+export class ToolAccessExtractorRegistry
+  implements ToolAccessExtractorLookup, ToolAccessExtractorRegistrar
+{
+  private readonly extractors = new Map<string, ToolAccessExtractor>();
+
+  /**
+   * Register an extractor for `toolName`.
+   *
+   * Throws if an extractor is already registered for that name — keeps
+   * resolution deterministic (a pi-permission-system package priority).
+   * Returns a disposer that removes the extractor; the disposer is
+   * identity-guarded so a stale call cannot evict a later registration.
+   */
+  register(toolName: string, extractor: ToolAccessExtractor): () => void {
+    if (this.extractors.has(toolName)) {
+      throw new Error(
+        `A tool access extractor is already registered for '${toolName}'.`,
+      );
+    }
+    this.extractors.set(toolName, extractor);
+    return () => {
+      if (this.extractors.get(toolName) === extractor) {
+        this.extractors.delete(toolName);
+      }
+    };
+  }
+
+  get(toolName: string): ToolAccessExtractor | undefined {
+    return this.extractors.get(toolName);
+  }
+}

package/src/tool-input-formatter-registry.ts

@@ -0,0 +1,67 @@
+/**
+ * Registry for custom tool-input preview formatters.
+ *
+ * Allows extensions to register a formatter for a specific tool name so
+ * permission prompts can show a human-readable summary instead of raw JSON.
+ * One formatter per tool name; duplicate registration throws.
+ */
+
+/** A custom preview formatter for one tool's input. Returns `undefined` to decline. */
+export type ToolInputFormatter = (
+  input: Record<string, unknown>,
+) => string | undefined;
+
+/**
+ * Read-only lookup used by `ToolPreviewFormatter` (ISP — exposes only the
+ * read side, not the registration surface).
+ */
+export interface ToolInputFormatterLookup {
+  get(toolName: string): ToolInputFormatter | undefined;
+}
+
+/**
+ * Registration side of the formatter registry (ISP — exposes only the
+ * write surface, mirroring the read-only {@link ToolInputFormatterLookup}).
+ */
+export interface ToolInputFormatterRegistrar {
+  register(toolName: string, formatter: ToolInputFormatter): () => void;
+}
+
+/**
+ * Persistent registry mapping tool names to custom preview formatters.
+ *
+ * Owned by the extension factory (`index.ts`) so it survives across the
+ * per-tool-call `ToolPreviewFormatter` construction cycle.
+ * Exposed to sibling extensions via `PermissionsService.registerToolInputFormatter`.
+ */
+export class ToolInputFormatterRegistry
+  implements ToolInputFormatterLookup, ToolInputFormatterRegistrar
+{
+  private readonly formatters = new Map<string, ToolInputFormatter>();
+
+  /**
+   * Register a formatter for `toolName`.
+   *
+   * Throws if a formatter is already registered for that name — keeps
+   * resolution deterministic (a pi-permission-system package priority).
+   * Returns a disposer that removes the formatter; the disposer is
+   * identity-guarded so a stale call cannot evict a later registration.
+   */
+  register(toolName: string, formatter: ToolInputFormatter): () => void {
+    if (this.formatters.has(toolName)) {
+      throw new Error(
+        `A tool input formatter is already registered for '${toolName}'.`,
+      );
+    }
+    this.formatters.set(toolName, formatter);
+    return () => {
+      if (this.formatters.get(toolName) === formatter) {
+        this.formatters.delete(toolName);
+      }
+    };
+  }
+
+  get(toolName: string): ToolInputFormatter | undefined {
+    return this.formatters.get(toolName);
+  }
+}

package/src/tool-input-preview.ts

@@ -0,0 +1,34 @@
+import { safeJsonStringify } from "./logging";
+
+export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
+export const TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH = 1000;
+export const TOOL_TEXT_SUMMARY_MAX_LENGTH = 80;
+
+export function truncateInlineText(value: string, maxLength: number): string {
+  return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
+}
+
+export function countTextLines(value: string): number {
+  if (!value) {
+    return 0;
+  }
+
+  return value.split(/\r\n|\r|\n/).length;
+}
+
+export function formatCount(
+  value: number,
+  singular: string,
+  plural: string,
+): string {
+  return `${value} ${value === 1 ? singular : plural}`;
+}
+
+export function serializeToolInputPreview(input: unknown): string {
+  const serialized = safeJsonStringify(input);
+  if (!serialized || serialized === "{}" || serialized === "null") {
+    return "";
+  }
+
+  return serialized.replace(/\s+/g, " ").trim();
+}

package/src/tool-input-prompt-formatters.ts

@@ -0,0 +1,63 @@
+import { getNonEmptyString, toRecord } from "./common";
+import { countTextLines, formatCount } from "./tool-input-preview";
+
+export function getPromptPath(input: Record<string, unknown>): string | null {
+  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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(", ")}` : "";
+}