@komarspn/pi-permission-system 16.0.2

package/src/skill-prompt-sanitizer.ts

@@ -0,0 +1,292 @@
+import { dirname } from "node:path";
+
+import {
+  isPathWithinDirectory,
+  normalizePathForComparison,
+} from "./path-utils";
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+/**
+ * Narrow interface for the permission checker used by skill prompt resolution.
+ * Both `PermissionManager` and `PermissionResolver` satisfy this structurally.
+ */
+export interface SkillPermissionChecker {
+  checkPermission(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult;
+}
+
+const AVAILABLE_SKILLS_OPEN_TAG = "<available_skills>";
+const AVAILABLE_SKILLS_CLOSE_TAG = "</available_skills>";
+const SKILL_BLOCK_PATTERN = "<skill>([\\s\\S]*?)<\\/skill>";
+const SKILL_NAME_REGEX = /<name>([\s\S]*?)<\/name>/;
+const SKILL_DESCRIPTION_REGEX = /<description>([\s\S]*?)<\/description>/;
+const SKILL_LOCATION_REGEX = /<location>([\s\S]*?)<\/location>/;
+
+type ParsedSkillPromptEntry = {
+  name: string;
+  description: string;
+  location: string;
+};
+
+export type SkillPromptEntry = {
+  name: string;
+  description: string;
+  location: string;
+  state: PermissionState;
+  normalizedLocation: string;
+  normalizedBaseDir: string;
+};
+
+export type SkillPromptSection = {
+  start: number;
+  end: number;
+  entries: ParsedSkillPromptEntry[];
+};
+
+function decodeXml(value: string): string {
+  return value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function encodeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function parseSkillEntries(sectionBody: string): ParsedSkillPromptEntry[] {
+  const entries: ParsedSkillPromptEntry[] = [];
+  const skillBlockRegex = new RegExp(SKILL_BLOCK_PATTERN, "g");
+
+  for (const match of sectionBody.matchAll(skillBlockRegex)) {
+    const block = match[1];
+    const nameMatch = SKILL_NAME_REGEX.exec(block);
+    const descriptionMatch = SKILL_DESCRIPTION_REGEX.exec(block);
+    const locationMatch = SKILL_LOCATION_REGEX.exec(block);
+
+    if (!nameMatch || !descriptionMatch || !locationMatch) {
+      continue;
+    }
+
+    const name = decodeXml(nameMatch[1].trim());
+    const description = decodeXml(descriptionMatch[1].trim());
+    const location = decodeXml(locationMatch[1].trim());
+
+    if (!name || !location) {
+      continue;
+    }
+
+    entries.push({ name, description, location });
+  }
+
+  return entries;
+}
+
+export function parseAllSkillPromptSections(
+  prompt: string,
+): SkillPromptSection[] {
+  const sections: SkillPromptSection[] = [];
+  let searchStart = 0;
+
+  while (searchStart < prompt.length) {
+    const start = prompt.indexOf(AVAILABLE_SKILLS_OPEN_TAG, searchStart);
+    if (start === -1) {
+      break;
+    }
+
+    const closeStart = prompt.indexOf(
+      AVAILABLE_SKILLS_CLOSE_TAG,
+      start + AVAILABLE_SKILLS_OPEN_TAG.length,
+    );
+    if (closeStart === -1) {
+      break;
+    }
+
+    const end = closeStart + AVAILABLE_SKILLS_CLOSE_TAG.length;
+    const sectionBody = prompt.slice(
+      start + AVAILABLE_SKILLS_OPEN_TAG.length,
+      closeStart,
+    );
+    sections.push({
+      start,
+      end,
+      entries: parseSkillEntries(sectionBody),
+    });
+    searchStart = end;
+  }
+
+  return sections;
+}
+
+function resolvePermissionState(
+  skillName: string,
+  permissionManager: SkillPermissionChecker,
+  agentName: string | null,
+  cache: Map<string, PermissionState>,
+): PermissionState {
+  const cachedState = cache.get(skillName);
+  if (cachedState) {
+    return cachedState;
+  }
+
+  const state = permissionManager.checkPermission(
+    "skill",
+    { name: skillName },
+    agentName ?? undefined,
+  ).state;
+  cache.set(skillName, state);
+  return state;
+}
+
+function createResolvedSkillEntry(
+  entry: ParsedSkillPromptEntry,
+  state: PermissionState,
+  cwd: string,
+): SkillPromptEntry {
+  return {
+    name: entry.name,
+    description: entry.description,
+    location: entry.location,
+    state,
+    normalizedLocation: normalizePathForComparison(entry.location, cwd),
+    normalizedBaseDir: normalizePathForComparison(dirname(entry.location), cwd),
+  };
+}
+
+function renderAvailableSkillsSection(
+  entries: readonly SkillPromptEntry[],
+): string {
+  return [
+    AVAILABLE_SKILLS_OPEN_TAG,
+    ...entries.flatMap((entry) => [
+      "  <skill>",
+      `    <name>${encodeXml(entry.name)}</name>`,
+      `    <description>${encodeXml(entry.description)}</description>`,
+      `    <location>${encodeXml(entry.location)}</location>`,
+      "  </skill>",
+    ]),
+    AVAILABLE_SKILLS_CLOSE_TAG,
+  ].join("\n");
+}
+
+function removePromptRange(prompt: string, start: number, end: number): string {
+  const beforeSection = prompt.slice(0, start).replace(/\n+$/, "");
+  const afterSection = prompt.slice(end);
+  return `${beforeSection}${afterSection}`;
+}
+
+export function resolveSkillPromptEntries(
+  prompt: string,
+  permissionManager: SkillPermissionChecker,
+  agentName: string | null,
+  cwd: string,
+): { prompt: string; entries: SkillPromptEntry[] } {
+  const sections = parseAllSkillPromptSections(prompt);
+  if (sections.length === 0) {
+    return { prompt, entries: [] };
+  }
+
+  const permissionCache = new Map<string, PermissionState>();
+  const visibleEntries: SkillPromptEntry[] = [];
+  const replacements: Array<{ start: number; end: number; content: string }> =
+    [];
+
+  for (const section of sections) {
+    const resolvedEntries = section.entries.map((entry) => {
+      const state = resolvePermissionState(
+        entry.name,
+        permissionManager,
+        agentName,
+        permissionCache,
+      );
+      return createResolvedSkillEntry(entry, state, cwd);
+    });
+
+    const visibleSectionEntries = resolvedEntries.filter(
+      (entry) => entry.state !== "deny",
+    );
+    visibleEntries.push(...visibleSectionEntries);
+
+    if (visibleSectionEntries.length === resolvedEntries.length) {
+      continue;
+    }
+
+    replacements.push({
+      start: section.start,
+      end: section.end,
+      content:
+        visibleSectionEntries.length > 0
+          ? renderAvailableSkillsSection(visibleSectionEntries)
+          : "",
+    });
+  }
+
+  if (replacements.length === 0) {
+    return { prompt, entries: visibleEntries };
+  }
+
+  let sanitizedPrompt = prompt;
+  for (let i = replacements.length - 1; i >= 0; i--) {
+    const replacement = replacements[i];
+    sanitizedPrompt =
+      replacement.content.length > 0
+        ? `${sanitizedPrompt.slice(0, replacement.start)}${replacement.content}${sanitizedPrompt.slice(replacement.end)}`
+        : removePromptRange(
+            sanitizedPrompt,
+            replacement.start,
+            replacement.end,
+          );
+  }
+
+  return {
+    prompt: sanitizedPrompt,
+    entries: visibleEntries,
+  };
+}
+
+export function findSkillPathMatch(
+  normalizedPath: string,
+  entries: readonly SkillPromptEntry[],
+): SkillPromptEntry | null {
+  if (!normalizedPath || entries.length === 0) {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (
+      entry.normalizedLocation &&
+      normalizedPath === entry.normalizedLocation
+    ) {
+      return entry;
+    }
+  }
+
+  let bestMatch: SkillPromptEntry | null = null;
+  for (const entry of entries) {
+    if (
+      !entry.normalizedBaseDir ||
+      !isPathWithinDirectory(normalizedPath, entry.normalizedBaseDir)
+    ) {
+      continue;
+    }
+
+    if (
+      !bestMatch ||
+      entry.normalizedBaseDir.length > bestMatch.normalizedBaseDir.length
+    ) {
+      bestMatch = entry;
+    }
+  }
+
+  return bestMatch;
+}

package/src/status.ts

@@ -0,0 +1,35 @@
+import type {
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  EXTENSION_ID,
+  type PermissionSystemExtensionConfig,
+} from "./extension-config";
+import { isYoloModeEnabled } from "./yolo-mode";
+
+export const PERMISSION_SYSTEM_STATUS_KEY = EXTENSION_ID;
+export const PERMISSION_SYSTEM_YOLO_STATUS_VALUE = "yolo";
+
+type PermissionStatusContext =
+  | Pick<ExtensionContext, "hasUI" | "ui">
+  | Pick<ExtensionCommandContext, "ui">;
+
+export function getPermissionSystemStatus(
+  config: PermissionSystemExtensionConfig,
+): string | undefined {
+  return isYoloModeEnabled(config)
+    ? PERMISSION_SYSTEM_YOLO_STATUS_VALUE
+    : undefined;
+}
+
+export function syncPermissionSystemStatus(
+  ctx: PermissionStatusContext,
+  config: PermissionSystemExtensionConfig,
+): void {
+  ctx.ui.setStatus(
+    PERMISSION_SYSTEM_STATUS_KEY,
+    getPermissionSystemStatus(config),
+  );
+}

package/src/subagent-context.ts

@@ -0,0 +1,104 @@
+import { normalize } from "node:path";
+
+import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/**
+ * Narrow context for subagent detection — the only session-manager readers
+ * {@link isSubagentExecutionContext} and {@link isRegisteredSubagentChild}
+ * consume. A full `ExtensionContext` satisfies this structurally.
+ */
+export interface SubagentDetectionContext {
+  sessionManager: {
+    getSessionId(): string;
+    getSessionDir(): string;
+  };
+}
+
+export function normalizeFilesystemPath(pathValue: string): string {
+  const normalizedPath = normalize(pathValue);
+  return process.platform === "win32"
+    ? normalizedPath.toLowerCase()
+    : normalizedPath;
+}
+
+function isPathWithinDirectoryForSubagent(
+  pathValue: string,
+  directory: string,
+): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const sep = process.platform === "win32" ? "\\" : "/";
+  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
+  return pathValue.startsWith(prefix);
+}
+
+/**
+ * Return `true` when `ctx` belongs to an in-process subagent child registered
+ * in `registry` by its session id.
+ *
+ * This is the only signal that identifies an **in-process** child (one sharing
+ * the parent's `globalThis`); env-hint and filesystem heuristics identify
+ * **process-based** subagents instead. The composition root uses this to decide
+ * whether the instance owns the process-global service slot — a registered
+ * child must not publish over its parent.
+ */
+export function isRegisteredSubagentChild(
+  ctx: SubagentDetectionContext,
+  registry: SubagentSessionRegistry,
+): boolean {
+  try {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (!sessionId) {
+      return false;
+    }
+    return registry.has(sessionId);
+  } catch {
+    // getSessionId() unavailable — treat as not-a-registered-child.
+    return false;
+  }
+}
+
+export function isSubagentExecutionContext(
+  ctx: SubagentDetectionContext,
+  subagentSessionsDir: string,
+  registry?: SubagentSessionRegistry,
+): boolean {
+  // 1. Explicit registry — in-process subagent extensions register by child
+  //    session id before bindExtensions(); checked first so it takes priority
+  //    over heuristics. Each concurrent sibling has a unique session id, so
+  //    one sibling's disposed event cannot affect another's registration.
+  if (registry && isRegisteredSubagentChild(ctx, registry)) {
+    return true;
+  }
+
+  const sessionDir = ctx.sessionManager.getSessionDir();
+
+  // 2. Env vars — process-based subagent extensions (nicobailon/pi-subagents,
+  //    HazAT/pi-interactive-subagents, pi-agent-router, etc.).
+  for (const key of SUBAGENT_ENV_HINT_KEYS) {
+    const value = process.env[key];
+    if (typeof value === "string" && value.trim()) {
+      return true;
+    }
+  }
+
+  // 3. Filesystem path — fallback heuristic for extensions that store sessions
+  //    under a known subagent root directory.
+  if (!sessionDir) {
+    return false;
+  }
+
+  const normalizedSessionDir = normalizeFilesystemPath(sessionDir);
+  const normalizedSubagentRoot = normalizeFilesystemPath(subagentSessionsDir);
+  return isPathWithinDirectoryForSubagent(
+    normalizedSessionDir,
+    normalizedSubagentRoot,
+  );
+}

package/src/subagent-lifecycle-events.ts

@@ -0,0 +1,72 @@
+/**
+ * subagent-lifecycle-events.ts — Subscribe to @gotgenes/pi-subagents' child
+ * lifecycle events and keep the SubagentSessionRegistry in sync.
+ *
+ * @gotgenes/pi-subagents publishes its child-execution lifecycle on the Pi
+ * event bus (ADR 0002): it no longer calls this package's service directly.
+ * We register the child on `session-created` and unregister it on `disposed`.
+ *
+ * The channel names and payload shapes are declared independently here (the two
+ * packages must not depend on each other under jiti) and MUST match the
+ * publisher in `@gotgenes/pi-subagents` (`src/lifecycle/child-lifecycle.ts`).
+ *
+ * The `session-created` handler MUST stay synchronous: the core emits it on the
+ * same synchronous call stack immediately before `bindExtensions()`, and the
+ * event bus dispatches listeners synchronously, so a synchronous handler lands
+ * the registry entry before binding proceeds. Introducing an `await` before
+ * `registry.register(...)` would break the pre-bind ordering.
+ */
+
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** Emitted by the core after session creation, before `bindExtensions()`. */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted by the core in the run's `finally` (success and error). */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Minimal event-bus surface this module needs (subscribe only). */
+interface LifecycleEventBus {
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+/** Fields read from the `session-created` payload (ISP). */
+interface ChildSessionCreatedEvent {
+  /** Child session id — the registry key. Must match the publisher. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
+/** Fields read from the `disposed` payload (ISP). */
+interface ChildDisposedEvent {
+  /** Child session id — the registry key. Must match the publisher. */
+  sessionId: string;
+}
+
+/**
+ * Subscribe to the subagent child lifecycle.
+ *
+ * @returns an unsubscribe that detaches both handlers (call during
+ *          `session_shutdown`).
+ */
+export function subscribeSubagentLifecycle(
+  events: LifecycleEventBus,
+  registry: SubagentSessionRegistry,
+): () => void {
+  const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
+    const event = data as ChildSessionCreatedEvent;
+    registry.register(event.sessionId, {
+      parentSessionId: event.parentSessionId,
+    });
+  });
+
+  const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
+    const event = data as ChildDisposedEvent;
+    registry.unregister(event.sessionId);
+  });
+
+  return () => {
+    unsubCreated();
+    unsubDisposed();
+  };
+}

package/src/subagent-registry.ts

@@ -0,0 +1,105 @@
+/**
+ * subagent-registry.ts — In-process subagent session registry.
+ *
+ * In-process subagent extensions (e.g. `@gotgenes/pi-subagents`) register
+ * each child session here before calling `bindExtensions()` so that
+ * `isSubagentExecutionContext()` and permission-forwarding target resolution
+ * can detect them without relying on environment variables or filesystem
+ * heuristics.
+ *
+ * The registry is keyed by the child's **session id**, which is unique per
+ * child and available to both producer (via `sessionManager.getSessionId()`
+ * after `newSession()` in `create-subagent-session.ts`) and consumer (via
+ * `ctx.sessionManager.getSessionId()`). Two concurrent siblings of the same
+ * parent therefore occupy distinct keys, so one sibling's `disposed` event
+ * cannot evict the entry the others depend on.
+ *
+ * The single registry instance is stored on `globalThis` (via `Symbol.for()`)
+ * so that the parent's permission-system instance (which registers children
+ * on the parent's event bus) and each child's separate jiti instance (which
+ * reads the registry to detect itself and resolve its forwarding target) share
+ * one store across per-session event buses. See `getSubagentSessionRegistry()`.
+ *
+ * When a future code path needs the child's agent name, read it from
+ * `tcc.agentName` (resolved from the `<active_agent>` system-prompt tag) —
+ * not from this registry.
+ */
+
+/** Process-global key for the shared registry slot. */
+const SUBAGENT_SESSION_REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
+/**
+ * Return the process-global SubagentSessionRegistry, creating it on first call.
+ *
+ * Backed by `globalThis` + `Symbol.for()` so the parent's permission-system
+ * instance (which registers children on the parent event bus) and each child's
+ * separate jiti instance (which reads the registry to detect itself and resolve
+ * its forwarding target) share one store across per-session event buses.
+ *
+ * Intentionally has no shutdown/unpublish hook — a child's `session_shutdown`
+ * must not be able to wipe the parent's registrations. Entries are added and
+ * removed exclusively by the parent's `subagents:child:session-created` /
+ * `subagents:child:disposed` subscription.
+ */
+export function getSubagentSessionRegistry(): SubagentSessionRegistry {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[SUBAGENT_SESSION_REGISTRY_KEY] as
+    | SubagentSessionRegistry
+    | undefined;
+  if (existing) {
+    return existing;
+  }
+  const registry = new SubagentSessionRegistry();
+  store[SUBAGENT_SESSION_REGISTRY_KEY] = registry;
+  return registry;
+}
+
+/** Signal stored per registered in-process subagent session. */
+export interface SubagentSessionInfo {
+  /** Parent session ID for permission forwarding. Omit when unknown. */
+  parentSessionId?: string;
+}
+
+/**
+ * Registry of active in-process subagent sessions.
+ *
+ * A process-global singleton — obtain it via `getSubagentSessionRegistry()`,
+ * never `new` (see that accessor for why). Written exclusively by
+ * `subscribeSubagentLifecycle` via the `subagents:child:session-created` /
+ * `subagents:child:disposed` event subscription (ADR 0002 — the core
+ * publishes, consumers observe).
+ *
+ * Keyed by child session id. Each concurrent child of the same parent receives
+ * a unique session id from `sessionManager.newSession()`, so siblings occupy
+ * distinct keys and one sibling's `disposed` cannot evict another's entry.
+ */
+export class SubagentSessionRegistry {
+  private readonly sessions = new Map<string, SubagentSessionInfo>();
+
+  /**
+   * Register an in-process subagent session.
+   *
+   * If a previous entry exists for `sessionId`, it is overwritten
+   * (last-write-wins; single-writer expected per key).
+   */
+  register(sessionId: string, info: SubagentSessionInfo): void {
+    this.sessions.set(sessionId, info);
+  }
+
+  /** Remove a previously registered session. No-op if the key is absent. */
+  unregister(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  /** Return the registered info for `sessionId`, or `undefined` if absent. */
+  get(sessionId: string): SubagentSessionInfo | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /** Return `true` when `sessionId` has a registered entry. */
+  has(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
+  }
+}

package/src/synthesize.ts

@@ -0,0 +1,92 @@
+import type { Rule, RuleOrigin, Ruleset } from "./rule";
+import type { PermissionState } from "./types";
+
+/**
+ * Synthesize a single universal catch-all rule from the universal default.
+ *
+ * Produces one rule:
+ * `{ surface: "*", pattern: "*", action: universalDefault, layer: "default" }`
+ *
+ * Per-surface catch-alls (`bash["*"]`, `mcp["*"]`, etc.) are expressed as
+ * regular config rules from `normalizeFlatConfig()` and sit at higher indices
+ * in the composed array, so they override this default via last-match-wins.
+ */
+export function synthesizeDefaults(
+  universalDefault: PermissionState,
+  origin: RuleOrigin = "builtin",
+): Ruleset {
+  return [
+    {
+      surface: "*",
+      pattern: "*",
+      action: universalDefault,
+      layer: "default",
+      origin,
+    },
+  ];
+}
+
+/**
+ * MCP metadata operation targets that are auto-allowed when any explicit MCP
+ * allow rule exists in the config layer.
+ */
+const MCP_BASELINE_TARGETS: readonly string[] = [
+  "mcp_status",
+  "mcp_list",
+  "mcp_search",
+  "mcp_describe",
+  "mcp_connect",
+];
+
+/**
+ * Conditionally synthesize MCP baseline auto-allow rules.
+ *
+ * Emits allow rules for the 5 MCP metadata targets only when `configRules`
+ * contains at least one `surface: "mcp", action: "allow"` rule. This replicates
+ * the `hasAnyMcpAllowRule` heuristic as actual rules.
+ *
+ * When `permission["mcp"]` is `"allow"` (or `mcp["*"]` is `"allow"`), the
+ * synthesized config catch-all already covers all MCP targets — no separate
+ * baseline rules are needed (and this function is not called in that case).
+ *
+ * Baseline rules are placed BEFORE config rules in the composed array so
+ * that explicit config deny rules can still override them.
+ *
+ * All rules carry `layer: "baseline"`.
+ */
+export function synthesizeBaseline(configRules: Ruleset): Ruleset {
+  const hasAnyMcpAllow = configRules.some(
+    (r) => r.surface === "mcp" && r.action === "allow",
+  );
+  if (!hasAnyMcpAllow) {
+    return [];
+  }
+  return MCP_BASELINE_TARGETS.map(
+    (target): Rule => ({
+      surface: "mcp",
+      pattern: target,
+      action: "allow",
+      layer: "baseline",
+      origin: "baseline",
+    }),
+  );
+}
+
+/**
+ * Concatenate all rule layers into a single flat ruleset.
+ *
+ * Priority order (lowest → highest, i.e. earlier index → later index):
+ *   defaults → baseline → config
+ *
+ * Session rules are NOT included here — they are appended at call-time inside
+ * `checkPermission()` so that the cached composed ruleset remains session-agnostic.
+ *
+ * `evaluate()` scans from the end, so later layers override earlier ones.
+ */
+export function composeRuleset(
+  defaults: Ruleset,
+  baseline: Ruleset,
+  config: Ruleset,
+): Ruleset {
+  return [...defaults, ...baseline, ...config];
+}