@komarspn/pi-permission-system 16.0.2

package/src/handlers/lifecycle.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { DecisionSummaryWriter } from "#src/decision-audit";
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { PermissionSession } from "#src/permission-session";
+import type { ServiceLifecycle } from "#src/service-lifecycle";
+import type { SessionLogger } from "#src/session-logger";
+import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/status";
+
+/** Minimal subset of SessionStartEvent used by this handler. */
+interface SessionStartPayload {
+  reason: string;
+}
+
+/** Minimal subset of ResourcesDiscoverEvent used by this handler. */
+interface ResourcesDiscoverPayload {
+  reason: string;
+}
+
+/**
+ * Handles session lifecycle events: start, reload, and shutdown.
+ *
+ * Constructor deps:
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getConfigIssues`
+ * - `serviceLifecycle` — owns the process-global service publication;
+ *   `activate` publishes (skipped for registered subagent children) and emits
+ *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
+ * - `logger` — injected directly; replaces the former `session.logger` reach-through
+ * - `audit` — per-session decision counters; its summary is written on shutdown
+ */
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
+    private readonly serviceLifecycle: ServiceLifecycle,
+    private readonly logger: SessionLogger,
+    private readonly audit: DecisionSummaryWriter,
+  ) {}
+
+  handleSessionStart(
+    event: SessionStartPayload,
+    ctx: ExtensionContext,
+  ): Promise<void> {
+    this.session.refreshConfig(ctx);
+    this.session.resetForNewSession(ctx);
+    this.session.logResolvedConfigPaths();
+
+    const agentName = this.session.resolveAgentName(ctx);
+    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
+    for (const issue of policyIssues) {
+      this.logger.warn(issue);
+    }
+
+    if (event.reason === "reload") {
+      this.logger.debug("lifecycle.reload", {
+        triggeredBy: "session_start",
+        reason: event.reason,
+        cwd: ctx.cwd,
+      });
+    }
+
+    // Publish the process-global service now that a ctx (and therefore the
+    // session id) is available, so an in-process subagent child can be
+    // identified and excluded. Emitting ready here keeps the
+    // service-resolvable-when-ready ordering contract.
+    this.serviceLifecycle.activate(ctx);
+    return Promise.resolve();
+  }
+
+  handleResourcesDiscover(event: ResourcesDiscoverPayload): Promise<void> {
+    if (event.reason !== "reload") {
+      return Promise.resolve();
+    }
+
+    this.session.reload();
+    this.logger.debug("lifecycle.reload", {
+      triggeredBy: "resources_discover",
+      reason: event.reason,
+      cwd: this.session.getRuntimeContext()?.cwd ?? null,
+    });
+    return Promise.resolve();
+  }
+
+  handleSessionShutdown(): Promise<void> {
+    const ctx = this.session.getRuntimeContext();
+    if (ctx) {
+      ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+    }
+    this.audit.writeSummary(this.logger);
+    this.session.shutdown();
+    this.serviceLifecycle.teardown();
+    return Promise.resolve();
+  }
+}

package/src/handlers/permission-gate-handler.ts

@@ -0,0 +1,190 @@
+import type {
+  ExtensionContext,
+  InputEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { toRecord } from "#src/common";
+import {
+  formatMissingToolNameReason,
+  formatUnknownToolReason,
+} from "#src/permission-prompts";
+import type { PermissionSession } from "#src/permission-session";
+import {
+  checkRequestedToolRegistration,
+  getToolNameFromValue,
+  type ToolRegistry,
+} from "#src/tool-registry";
+import type { GateRunner } from "./gates/runner";
+import type {
+  GateNotifier,
+  SkillInputGatePipeline,
+} from "./gates/skill-input-gate-pipeline";
+import type { ToolCallGatePipeline } from "./gates/tool-call-gate-pipeline";
+import type { GateOutcome, ToolCallContext } from "./gates/types";
+
+/** Minimal subset of InputEvent used by handleInput. */
+interface InputPayload {
+  text: string;
+}
+
+/**
+ * Handles permission gate events: tool_call and input.
+ *
+ * Constructor deps:
+ * - `session` — state/lifecycle owner: bind per-event context, resolve agent name
+ * - `toolRegistry` — Pi tool API subset (getAll + setActive)
+ * - `pipeline` — owns tool-call gate-producer assembly and the run loop
+ * - `skillInputPipeline` — owns skill-input gate assembly (pre-check, notify, run)
+ * - `runner` — pre-built gate runner (constructed in the composition root)
+ */
+export class PermissionGateHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly toolRegistry: ToolRegistry,
+    private readonly pipeline: ToolCallGatePipeline,
+    private readonly skillInputPipeline: SkillInputGatePipeline,
+    private readonly runner: GateRunner,
+  ) {}
+
+  async handleToolCall(
+    event: unknown,
+    ctx: ExtensionContext,
+  ): Promise<GateOutcome> {
+    this.session.activate(ctx);
+
+    const validation = validateRequestedTool(event, this.toolRegistry.getAll());
+    if (validation.status === "block") {
+      return { action: "block", reason: validation.reason };
+    }
+    const toolName = validation.toolName;
+
+    const agentName = this.session.resolveAgentName(ctx);
+
+    const input = getEventInput(event);
+    const toolCallId =
+      typeof (event as Record<string, unknown>).toolCallId === "string"
+        ? ((event as Record<string, unknown>).toolCallId as string)
+        : "";
+
+    const tcc: ToolCallContext = {
+      toolName,
+      agentName,
+      input,
+      toolCallId,
+      cwd: ctx.cwd,
+    };
+
+    return await this.pipeline.evaluate(tcc, this.runner);
+  }
+
+  async handleInput(
+    event: InputPayload,
+    ctx: ExtensionContext,
+  ): Promise<InputEventResult> {
+    this.session.activate(ctx);
+
+    const skillName = extractSkillNameFromInput(event.text);
+    if (!skillName) {
+      return { action: "continue" };
+    }
+
+    const agentName = this.session.resolveAgentName(ctx);
+    const notifier: GateNotifier = {
+      warn: (message) => {
+        if (ctx.hasUI) {
+          ctx.ui.notify(message, "warning");
+        }
+      },
+    };
+    const outcome = await this.skillInputPipeline.evaluate(
+      skillName,
+      agentName,
+      notifier,
+      this.runner,
+    );
+    return outcome.action === "block"
+      ? { action: "handled" }
+      : { action: "continue" };
+  }
+}
+
+// ── Pure helpers ─────────────────────────────────────────────────────────
+
+/** Discriminated result of validating a tool-call event's name and registration. */
+export type RequestedToolValidation =
+  | { status: "ok"; toolName: string }
+  | { status: "block"; reason: string };
+
+/**
+ * Validate the tool name from a raw event against the registered tool list.
+ *
+ * Composes `getToolNameFromValue` + `checkRequestedToolRegistration` + the
+ * two reason formatters and returns a discriminated result so `handleToolCall`
+ * reads as a straight validate → proceed path without nested early-returns.
+ *
+ * Returns the **raw** tool name (not the normalised form) so that
+ * `ToolCallContext.toolName` stays identical to the pre-extraction behaviour.
+ */
+export function validateRequestedTool(
+  event: unknown,
+  availableTools: readonly unknown[],
+): RequestedToolValidation {
+  const toolName = getToolNameFromValue(event);
+  if (!toolName) {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  const check = checkRequestedToolRegistration(toolName, availableTools);
+  if (check.status === "missing-tool-name") {
+    return { status: "block", reason: formatMissingToolNameReason() };
+  }
+  if (check.status === "unregistered") {
+    return {
+      status: "block",
+      reason: formatUnknownToolReason(
+        check.requestedToolName,
+        check.availableToolNames,
+      ),
+    };
+  }
+  return { status: "ok", toolName };
+}
+
+/**
+ * Extract the tool input from an event, checking both `input` and `arguments`
+ * fields (different Pi SDK versions use different names).
+ */
+export function getEventInput(event: unknown): unknown {
+  const record = toRecord(event);
+
+  if (record.input !== undefined) {
+    return record.input;
+  }
+
+  if (record.arguments !== undefined) {
+    return record.arguments;
+  }
+
+  return {};
+}
+
+/**
+ * Parse a `/skill:<name>` prefix from user input.
+ * Returns the skill name, or null if the text is not a skill invocation.
+ */
+export function extractSkillNameFromInput(text: string): string | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/skill:")) {
+    return null;
+  }
+
+  const afterPrefix = trimmed.slice("/skill:".length);
+  if (!afterPrefix) {
+    return null;
+  }
+
+  const firstWhitespace = afterPrefix.search(/\s/);
+  const skillName = (
+    firstWhitespace === -1 ? afterPrefix : afterPrefix.slice(0, firstWhitespace)
+  ).trim();
+  return skillName || null;
+}

package/src/handlers/tool-call-boundary.ts

@@ -0,0 +1,91 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { toRecord } from "#src/common";
+import type { DecisionRecorder } from "#src/decision-audit";
+import type { DecisionReporter } from "#src/decision-reporter";
+import type { GateOutcome } from "./gates/types";
+
+/** The SDK-facing result shape for a `tool_call` handler. */
+type ToolCallResult = { block?: true; reason?: string };
+
+/**
+ * Narrow debug surface for the per-call decision trace. The concrete logger
+ * self-gates on `debugLog`, so the boundary emits unconditionally and the
+ * entry is dropped when the toggle is off (no per-call spam in normal use).
+ */
+export interface DecisionTracer {
+  debug(event: string, details?: Record<string, unknown>): void;
+}
+
+/**
+ * The only `tool_call` handler the SDK sees.
+ *
+ * Guarantees fail-closed: it owns the `try/catch → block` and is the sole place
+ * an internal {@link GateOutcome} is translated to the SDK result shape, so
+ * "we didn't decide" can never silently mean "allow."
+ *
+ * The SDK's `emitToolCall` (`@earendil-works/pi-coding-agent`
+ * `dist/core/extensions/runner.js`) awaits the registered handler with **no**
+ * try/catch — unlike `emitUserBash` directly below it, which catches and
+ * continues. A thrown gate therefore yields no `{ block: true }` and the
+ * command runs ungated with nothing logged. This boundary absorbs that throw,
+ * blocks, and writes a `gate_error` review-log entry.
+ *
+ * Fail-closed = **block** (not `ask`) for an unexpected exception: the command
+ * may be unknown and the prompt infrastructure itself may be what threw, so a
+ * hard block is the unambiguous safe outcome.
+ */
+export function createFailClosedToolCall(
+  gate: (event: unknown, ctx: ExtensionContext) => Promise<GateOutcome>,
+  reporter: DecisionReporter,
+  audit: DecisionRecorder,
+  tracer: DecisionTracer,
+): (event: unknown, ctx: ExtensionContext) => Promise<ToolCallResult> {
+  return async (event, ctx) => {
+    try {
+      const outcome = await gate(event, ctx);
+      audit.recordDecision(outcome.action);
+      tracer.debug("permission.decision", {
+        toolName: bestEffortToolName(event),
+        action: outcome.action,
+        ...(outcome.action === "block" ? { reason: outcome.reason } : {}),
+      });
+      return outcome.action === "block"
+        ? { block: true, reason: outcome.reason }
+        : {};
+    } catch (error) {
+      audit.recordError();
+      reporter.writeReviewLog("permission_request.blocked", {
+        toolName: bestEffortToolName(event),
+        command: bestEffortCommand(event),
+        resolution: "gate_error",
+        error: errorMessage(error),
+      });
+      return { block: true, reason: formatGateErrorReason(error) };
+    }
+  };
+}
+
+// ── Defensive event readers (never throw) ──────────────────────────────────
+
+/** Best-effort tool name from a raw event; never throws. */
+function bestEffortToolName(event: unknown): string {
+  const record = toRecord(event);
+  const name = record.name ?? record.toolName;
+  return typeof name === "string" && name ? name : "<unknown>";
+}
+
+/** Best-effort bash command from a raw event; never throws. */
+function bestEffortCommand(event: unknown): string | undefined {
+  const record = toRecord(event);
+  const input = toRecord(record.input ?? record.arguments);
+  return typeof input.command === "string" ? input.command : undefined;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function formatGateErrorReason(error: unknown): string {
+  return `Permission gate failed and blocked the tool call (fail-closed): ${errorMessage(error)}`;
+}

package/src/index.ts

@@ -0,0 +1,225 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
+import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
+import { registerPermissionSystemCommand } from "./config-modal";
+import { getGlobalConfigPath } from "./config-paths";
+import { ConfigStore } from "./config-store";
+import { DecisionAudit } from "./decision-audit";
+import { GateDecisionReporter } from "./decision-reporter";
+import { computeExtensionPaths } from "./extension-paths";
+import {
+  PermissionForwarder,
+  type PermissionForwarderDeps,
+} from "./forwarded-permissions/permission-forwarder";
+import { ForwardingManager } from "./forwarding-manager";
+import {
+  AgentPrepHandler,
+  PermissionGateHandler,
+  SessionLifecycleHandler,
+} from "./handlers";
+import { GateRunner } from "./handlers/gates/runner";
+import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeline";
+import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
+import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
+import { requestPermissionDecisionFromUi } from "./permission-dialog";
+import { registerPermissionRpcHandlers } from "./permission-event-rpc";
+import { PermissionManager } from "./permission-manager";
+import { PermissionPrompter } from "./permission-prompter";
+import { PersistentApprovalRecorder } from "./persistent-approval-recorder";
+import { PermissionResolver } from "./permission-resolver";
+import { PermissionSession } from "./permission-session";
+import { LocalPermissionsService } from "./permissions-service";
+import { PromptingGateway } from "./prompting-gateway";
+import { PermissionServiceLifecycle } from "./service-lifecycle";
+import { PermissionSessionLogger } from "./session-logger";
+import { SessionRules } from "./session-rules";
+import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
+import { getSubagentSessionRegistry } from "./subagent-registry";
+import { ToolAccessExtractorRegistry } from "./tool-access-extractor-registry";
+import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
+
+export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
+  const agentDir = getAgentDir();
+  // getPackageDir() is Pi's own install dir; auto-allow it for read-only tools
+  // so the agent can read Pi's bundled docs/examples regardless of layout.
+  const paths = computeExtensionPaths(agentDir, getPackageDir());
+  const permissionManager = new PermissionManager({ agentDir });
+  const sessionRules = new SessionRules();
+  const subagentRegistry = getSubagentSessionRegistry();
+  const formatterRegistry = new ToolInputFormatterRegistry();
+  registerBuiltinToolInputFormatters(formatterRegistry);
+  const accessExtractorRegistry = new ToolAccessExtractorRegistry();
+
+  // Both `configStore` and `session` are forward-declared so the logger's
+  // lazy thunks can close over them without a cast or null-init holder.
+  // TypeScript exempts closure captures from definite-assignment analysis;
+  // all synchronous reads occur after the assignments below.
+  // eslint-disable-next-line prefer-const -- forward-declared let; `const` requires an initializer
+  let configStore: ConfigStore;
+  // eslint-disable-next-line prefer-const -- forward-declared let; `const` requires an initializer
+  let session: PermissionSession;
+
+  const logger = new PermissionSessionLogger({
+    globalLogsDir: paths.globalLogsDir,
+    getConfig: () => configStore.current(),
+    notify: (message) => session.notify(message),
+  });
+
+  configStore = new ConfigStore({
+    agentDir,
+    policyPaths: permissionManager,
+    logger,
+  });
+
+  const forwardingDeps: PermissionForwarderDeps = {
+    forwardingDir: paths.forwardingDir,
+    subagentSessionsDir: paths.subagentSessionsDir,
+    registry: subagentRegistry,
+    events: pi.events,
+    logger,
+    requestPermissionDecisionFromUi,
+    config: configStore,
+  };
+  const forwarder = new PermissionForwarder(forwardingDeps);
+
+  const prompter = new PermissionPrompter({
+    config: configStore,
+    logger,
+    events: pi.events,
+    forwarder,
+  });
+
+  const gateway = new PromptingGateway({
+    config: configStore,
+    subagentSessionsDir: paths.subagentSessionsDir,
+    registry: subagentRegistry,
+    prompter,
+  });
+
+  session = new PermissionSession(
+    paths,
+    new ForwardingManager(
+      paths.subagentSessionsDir,
+      forwarder,
+      subagentRegistry,
+    ),
+    permissionManager,
+    sessionRules,
+    configStore,
+    gateway,
+  );
+
+  // refresh() must run after `session` is assigned: a debug-write IO failure
+  // triggers the logger's notify sink — `session.notify(m)` — which no-ops
+  // on the null context but requires `session` to be bound.
+  configStore.refresh();
+
+  const configPath = getGlobalConfigPath(agentDir);
+  registerPermissionSystemCommand(pi, {
+    config: configStore,
+    configPath,
+    getActiveAgentConfigRules: () =>
+      permissionManager.getComposedConfigRules(
+        session.lastKnownActiveAgentName ?? undefined,
+      ),
+  });
+
+  const rpcHandles = registerPermissionRpcHandlers(pi.events, {
+    permissionManager,
+    sessionRules,
+    session,
+    requestPermissionDecisionFromUi,
+    logger,
+  });
+
+  const permissionsService = new LocalPermissionsService(
+    permissionManager,
+    sessionRules,
+    formatterRegistry,
+    accessExtractorRegistry,
+  );
+
+  // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
+  // sessions register/unregister without the core calling us (ADR 0002).
+  const unsubSubagentLifecycle = subscribeSubagentLifecycle(
+    pi.events,
+    subagentRegistry,
+  );
+
+  // PermissionServiceLifecycle owns the process-global service publication:
+  // activate() publishes (skipped for registered subagent children — see #302)
+  // and emits ready; teardown() unsubscribes all session listeners and
+  // unpublishes. Deferred to session_start because identifying a child
+  // requires the session id from ctx, unavailable at factory-init time.
+  const serviceLifecycle = new PermissionServiceLifecycle(
+    permissionsService,
+    subagentRegistry,
+    pi.events,
+    [rpcHandles.unsubCheck, rpcHandles.unsubPrompt, unsubSubagentLifecycle],
+  );
+
+  const toolRegistry = {
+    getAll: () => pi.getAllTools(),
+    getActive: () => pi.getActiveTools(),
+    setActive: (names: string[]) => pi.setActiveTools(names),
+  };
+
+  const resolver = new PermissionResolver(permissionManager, sessionRules);
+
+  const audit = new DecisionAudit();
+  const lifecycle = new SessionLifecycleHandler(
+    session,
+    resolver,
+    serviceLifecycle,
+    logger,
+    audit,
+  );
+  const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
+
+  const reporter = new GateDecisionReporter(logger, pi.events);
+  const persistentApprovalRecorder = new PersistentApprovalRecorder({
+    agentDir,
+    getCwd: () => session.getRuntimeContext()?.cwd,
+    logger,
+  });
+  const gateRunner = new GateRunner(
+    resolver,
+    sessionRules,
+    gateway,
+    reporter,
+    persistentApprovalRecorder,
+  );
+  const toolCallGatePipeline = new ToolCallGatePipeline(
+    resolver,
+    session,
+    formatterRegistry,
+    accessExtractorRegistry,
+  );
+  const skillInputGatePipeline = new SkillInputGatePipeline(resolver);
+  const gates = new PermissionGateHandler(
+    session,
+    toolRegistry,
+    toolCallGatePipeline,
+    skillInputGatePipeline,
+    gateRunner,
+  );
+
+  pi.on("session_start", (event, ctx) =>
+    lifecycle.handleSessionStart(event, ctx),
+  );
+  pi.on("resources_discover", (event) =>
+    lifecycle.handleResourcesDiscover(event),
+  );
+  pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
+  pi.on("before_agent_start", (event, ctx) => agentPrep.handle(event, ctx));
+  pi.on("input", (event, ctx) => gates.handleInput(event, ctx));
+  pi.on(
+    "tool_call",
+    createFailClosedToolCall(
+      (event, ctx) => gates.handleToolCall(event, ctx),
+      reporter,
+      audit,
+      logger,
+    ),
+  );
+}