@gotgenes/pi-permission-system 5.10.0 → 5.11.1

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

@@ -0,0 +1,346 @@
+import type {
+  ExtensionContext,
+  InputEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { toRecord } from "../common";
+import {
+  emitDecisionEvent,
+  type PermissionEventBus,
+} from "../permission-events";
+import { applyPermissionGate } from "../permission-gate";
+import type { PromptPermissionDetails } from "../permission-prompter";
+import {
+  formatMissingToolNameReason,
+  formatSkillAskPrompt,
+  formatUnknownToolReason,
+} from "../permission-prompts";
+import type { PermissionSession } from "../permission-session";
+import {
+  checkRequestedToolRegistration,
+  getToolNameFromValue,
+  type ToolRegistry,
+} from "../tool-registry";
+import { describeBashExternalDirectoryGate } from "./gates/bash-external-directory";
+import type { GateRunnerDeps } from "./gates/descriptor";
+import { isGateBypass } from "./gates/descriptor";
+import { describeExternalDirectoryGate } from "./gates/external-directory";
+import { runGateCheck } from "./gates/runner";
+import { describeSkillReadGate } from "./gates/skill-read";
+import { describeToolGate } from "./gates/tool";
+import type { 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` — encapsulates all mutable session state and permission operations
+ * - `events` — event bus for emitting permissions:decision broadcasts
+ * - `toolRegistry` — Pi tool API subset (getAll + setActive)
+ */
+export class PermissionGateHandler {
+  constructor(
+    private readonly session: PermissionSession,
+    private readonly events: PermissionEventBus,
+    private readonly toolRegistry: ToolRegistry,
+  ) {}
+
+  async handleToolCall(
+    event: unknown,
+    ctx: ExtensionContext,
+  ): Promise<{ block?: true; reason?: string }> {
+    const { session } = this;
+    session.activate(ctx);
+
+    const agentName = session.resolveAgentName(ctx);
+    const toolName = getToolNameFromValue(event);
+
+    if (!toolName) {
+      return { block: true, reason: formatMissingToolNameReason() };
+    }
+
+    const registrationCheck = checkRequestedToolRegistration(
+      toolName,
+      this.toolRegistry.getAll(),
+    );
+    if (registrationCheck.status === "missing-tool-name") {
+      return { block: true, reason: formatMissingToolNameReason() };
+    }
+
+    if (registrationCheck.status === "unregistered") {
+      return {
+        block: true,
+        reason: formatUnknownToolReason(
+          registrationCheck.requestedToolName,
+          registrationCheck.availableToolNames,
+        ),
+      };
+    }
+
+    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,
+    };
+
+    // ── Shared gate adapter closures ─────────────────────────────────────
+    const canConfirm = () => session.canPrompt(ctx);
+    const promptPermission = (details: PromptPermissionDetails) =>
+      session.prompt(ctx, details);
+    const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
+      emitDecisionEvent(this.events, e);
+    const writeReviewLog = session.logger.review;
+    const checkPermission: GateRunnerDeps["checkPermission"] = (
+      surface,
+      input,
+      agent,
+      sessionRules,
+    ) => session.checkPermission(surface, input, agent, sessionRules);
+    const getSessionRuleset = () => session.getSessionRuleset();
+    const approveSessionRule = (surface: string, pattern: string) =>
+      session.approveSessionRule(surface, pattern);
+
+    // ── Shared runner deps (built once, reused for all gates) ────────────
+    const runnerDeps: GateRunnerDeps = {
+      checkPermission,
+      getSessionRuleset,
+      approveSessionRule,
+      writeReviewLog,
+      emitDecision,
+      canConfirm,
+      promptPermission,
+    };
+
+    // ── Skill-read gate (descriptor + runner) ───────────────────────────────
+    const skillDescriptor = describeSkillReadGate(tcc, () =>
+      session.getActiveSkillEntries(),
+    );
+    if (skillDescriptor) {
+      const skillResult = await runGateCheck(
+        skillDescriptor,
+        tcc.agentName,
+        tcc.toolCallId,
+        runnerDeps,
+      );
+      if (skillResult.action === "block") {
+        return { block: true, reason: skillResult.reason };
+      }
+    }
+
+    // ── External-directory gate (descriptor + runner) ────────────────────────
+    const infraDirs = [
+      ...session.getInfrastructureDirs(),
+      ...session.getInfrastructureReadPaths(),
+    ];
+    const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
+    if (extDirDesc) {
+      if (isGateBypass(extDirDesc)) {
+        if (extDirDesc.log) {
+          writeReviewLog(extDirDesc.log.event, extDirDesc.log.details);
+        }
+        if (extDirDesc.decision) {
+          emitDecision(extDirDesc.decision);
+        }
+      } else {
+        const extDirResult = await runGateCheck(
+          extDirDesc,
+          tcc.agentName,
+          tcc.toolCallId,
+          runnerDeps,
+        );
+        if (extDirResult.action === "block") {
+          return { block: true, reason: extDirResult.reason };
+        }
+      }
+    }
+
+    // ── Bash external-directory gate (descriptor + runner) ───────────────────
+    const bashExtDesc = await describeBashExternalDirectoryGate(
+      tcc,
+      checkPermission,
+      getSessionRuleset,
+    );
+    if (bashExtDesc) {
+      if (isGateBypass(bashExtDesc)) {
+        if (bashExtDesc.log) {
+          writeReviewLog(bashExtDesc.log.event, bashExtDesc.log.details);
+        }
+      } else {
+        const bashExtResult = await runGateCheck(
+          bashExtDesc,
+          tcc.agentName,
+          tcc.toolCallId,
+          runnerDeps,
+        );
+        if (bashExtResult.action === "block") {
+          return { block: true, reason: bashExtResult.reason };
+        }
+      }
+    }
+
+    // ── Normal tool permission gate (descriptor + runner) ────────────────────
+    const toolCheck = checkPermission(
+      tcc.toolName,
+      tcc.input,
+      tcc.agentName ?? undefined,
+      getSessionRuleset(),
+    );
+    const toolDescriptor = describeToolGate(tcc, toolCheck);
+    toolDescriptor.preCheck = toolCheck;
+    const toolResult = await runGateCheck(
+      toolDescriptor,
+      tcc.agentName,
+      tcc.toolCallId,
+      runnerDeps,
+    );
+    if (toolResult.action === "block") {
+      return { block: true, reason: toolResult.reason };
+    }
+
+    return {};
+  }
+
+  async handleInput(
+    event: InputPayload,
+    ctx: ExtensionContext,
+  ): Promise<InputEventResult> {
+    const { session } = this;
+    session.activate(ctx);
+
+    const skillName = extractSkillNameFromInput(event.text);
+    if (!skillName) {
+      return { action: "continue" };
+    }
+
+    const agentName = session.resolveAgentName(ctx);
+    const check = session.checkPermission(
+      "skill",
+      { name: skillName },
+      agentName ?? undefined,
+    );
+
+    if (check.state === "deny" && ctx.hasUI) {
+      const notifyMessage = agentName
+        ? `Skill '${skillName}' is not permitted for agent '${agentName}'.`
+        : `Skill '${skillName}' is not permitted by the current skill policy.`;
+      ctx.ui.notify(notifyMessage, "warning");
+    }
+
+    const skillInputMessage = formatSkillAskPrompt(
+      skillName,
+      agentName ?? undefined,
+    );
+    const skillInputCanConfirm = session.canPrompt(ctx);
+    let skillInputAutoApproved = false;
+    const skillInputGate = await applyPermissionGate({
+      state: check.state,
+      canConfirm: skillInputCanConfirm,
+      promptForApproval: async () => {
+        const decision = await session.prompt(ctx, {
+          requestId: session.createPermissionRequestId("skill-input"),
+          source: "skill_input",
+          agentName,
+          message: skillInputMessage,
+          skillName,
+        });
+        skillInputAutoApproved = decision.autoApproved === true;
+        return decision;
+      },
+      writeLog: session.logger.review,
+      logContext: {
+        source: "skill_input",
+        skillName,
+        agentName,
+        message: skillInputMessage,
+      },
+      messages: {
+        denyReason: skillInputMessage,
+        unavailableReason:
+          "Skill requires approval, but no interactive UI is available.",
+        userDeniedReason: () => "User denied skill.",
+      },
+    });
+
+    emitDecisionEvent(this.events, {
+      surface: "skill",
+      value: skillName,
+      result: skillInputGate.action === "allow" ? "allow" : "deny",
+      resolution:
+        check.state === "allow"
+          ? "policy_allow"
+          : check.state === "deny"
+            ? "policy_deny"
+            : skillInputGate.action === "allow"
+              ? skillInputAutoApproved
+                ? "auto_approved"
+                : "user_approved"
+              : skillInputCanConfirm
+                ? "user_denied"
+                : "confirmation_unavailable",
+      origin: check.origin ?? null,
+      agentName: agentName ?? null,
+      matchedPattern: check.matchedPattern ?? null,
+    });
+
+    if (skillInputGate.action === "block") {
+      return { action: "handled" };
+    }
+
+    return { action: "continue" };
+  }
+}
+
+// ── Pure helpers (re-exported from original modules) ──────────────────────
+
+/**
+ * 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/index.ts

@@ -1,16 +1,12 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
 import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
 import { ForwardingManager } from "./forwarding-manager";
 import {
-  type HandlerDeps,
-  handleBeforeAgentStart,
-  handleInput,
-  handleResourcesDiscover,
-  handleSessionShutdown,
-  handleSessionStart,
-  handleToolCall,
+  AgentPrepHandler,
+  PermissionGateHandler,
+  SessionLifecycleHandler,
 } from "./handlers";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
@@ -64,6 +60,16 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
       logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
       getConfig: () => runtime.config,
+      canRequestPermissionConfirmation: (ctx) =>
+        canResolveAskPermissionRequest({
+          config: runtime.config,
+          hasUI: ctx.hasUI,
+          isSubagent: isSubagentExecutionContext(
+            ctx,
+            runtime.subagentSessionsDir,
+          ),
+        }),
+      promptPermission: (ctx, details) => prompter.prompt(ctx, details),
     },
   );
 
@@ -77,9 +83,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       ),
   });
 
-  const createPermissionRequestId = (prefix: string): string =>
-    `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
-
   const rpcHandles = registerPermissionRpcHandlers(pi.events, {
     getPermissionManager: () => runtime.permissionManager,
     getSessionRules: () => runtime.sessionRules.getRuleset(),
@@ -88,36 +91,28 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     writeReviewLog: runtime.writeReviewLog.bind(runtime),
   });
 
-  const deps: HandlerDeps = {
-    session,
-    events: pi.events,
-    canRequestPermissionConfirmation: (ctx) =>
-      canResolveAskPermissionRequest({
-        config: runtime.config,
-        hasUI: ctx.hasUI,
-        isSubagent: isSubagentExecutionContext(
-          ctx,
-          runtime.subagentSessionsDir,
-        ),
-      }),
-    promptPermission: (ctx, details) => prompter.prompt(ctx, details),
-    createPermissionRequestId,
-    stopPermissionRpcHandlers: () => {
-      rpcHandles.unsubCheck();
-      rpcHandles.unsubPrompt();
-    },
-    getAllTools: () => pi.getAllTools(),
-    setActiveTools: (names) => pi.setActiveTools(names),
+  emitReadyEvent(pi.events);
+
+  const toolRegistry = {
+    getAll: () => pi.getAllTools(),
+    setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
-  emitReadyEvent(pi.events);
+  const lifecycle = new SessionLifecycleHandler(session, () => {
+    rpcHandles.unsubCheck();
+    rpcHandles.unsubPrompt();
+  });
+  const agentPrep = new AgentPrepHandler(session, toolRegistry);
+  const gates = new PermissionGateHandler(session, pi.events, toolRegistry);
 
-  pi.on("session_start", (event, ctx) => handleSessionStart(deps, event, ctx));
-  pi.on("resources_discover", (event) => handleResourcesDiscover(deps, event));
-  pi.on("session_shutdown", () => handleSessionShutdown(deps));
-  pi.on("before_agent_start", (event, ctx) =>
-    handleBeforeAgentStart(deps, event, ctx),
+  pi.on("session_start", (event, ctx) =>
+    lifecycle.handleSessionStart(event, ctx),
+  );
+  pi.on("resources_discover", (event) =>
+    lifecycle.handleResourcesDiscover(event),
   );
-  pi.on("input", (event, ctx) => handleInput(deps, event, ctx));
-  pi.on("tool_call", (event, ctx) => handleToolCall(deps, event, ctx));
+  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", (event, ctx) => gates.handleToolCall(event, ctx));
 }

package/src/permission-event-rpc.ts

@@ -5,7 +5,7 @@
  * the Pi event bus so other extensions can query our policy and forward
  * permission prompts without importing this package.
  */
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,

package/src/permission-prompter.ts

@@ -1,18 +1,36 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ForwardedPermissionLogger } from "./forwarded-permissions/io";
 import {
   confirmPermission,
   type PermissionForwardingDeps,
 } from "./forwarded-permissions/polling";
-import type { PromptPermissionDetails } from "./handlers/types";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "./permission-dialog";
 import { shouldAutoApprovePermissionState } from "./yolo-mode";
 
-/** Mockable contract exposed to handlers via HandlerDeps. */
+export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
+
+/** Details passed when prompting the user for a permission decision. */
+export interface PromptPermissionDetails {
+  requestId: string;
+  source: PermissionReviewSource;
+  agentName: string | null;
+  message: string;
+  toolCallId?: string;
+  toolName?: string;
+  skillName?: string;
+  path?: string;
+  command?: string;
+  target?: string;
+  toolInputPreview?: string;
+  /** Override label for the "for this session" dialog option. */
+  sessionLabel?: string;
+}
+
+/** Mockable contract for permission prompting. */
 export interface PermissionPrompterApi {
   prompt(
     ctx: ExtensionContext,
@@ -52,10 +70,9 @@ export interface PermissionPrompterDeps {
  *   3. UI-present vs. subagent-forwarding branching (via confirmPermission).
  *   4. Review-log "approved" / "denied" entry.
  *
- * Injecting a single PermissionPrompter instance into HandlerDeps means
- * adding a new prompt parameter (e.g. a future sessionLabel variant) only
- * requires changing PromptPermissionDetails and this class — not the full
- * 4-file threading chain.
+ * Injecting a single PermissionPrompter instance means adding a new prompt
+ * parameter (e.g. a future sessionLabel variant) only requires changing
+ * PromptPermissionDetails and this class — not the full threading chain.
  */
 export class PermissionPrompter implements PermissionPrompterApi {
   constructor(private readonly deps: PermissionPrompterDeps) {}

package/src/permission-session.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
   getActiveAgentName,
@@ -7,7 +7,9 @@ import {
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
+import type { PermissionPromptDecision } from "./permission-dialog";
 import type { PermissionManager } from "./permission-manager";
+import type { PromptPermissionDetails } from "./permission-prompter";
 import type { Rule } from "./rule";
 import { createPermissionManagerForCwd } from "./runtime";
 import type { SessionLogger } from "./session-logger";
@@ -28,6 +30,13 @@ export interface PermissionSessionRuntimeDeps {
   logResolvedConfigPaths(): void;
   /** Read current extension config (called at query time). */
   getConfig(): PermissionSystemExtensionConfig;
+  /** Whether the current context can show an interactive permission prompt. */
+  canRequestPermissionConfirmation(ctx: ExtensionContext): boolean;
+  /** Prompt the user for a permission decision, log the outcome, and return it. */
+  promptPermission(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
 }
 
 /**
@@ -249,4 +258,24 @@ export class PermissionSession {
   getInfrastructureReadPaths(): string[] {
     return this.config.piInfrastructureReadPaths ?? [];
   }
+
+  // ── Prompting ──────────────────────────────────────────────────────────
+
+  /** Whether the current context can show an interactive permission prompt. */
+  canPrompt(ctx: ExtensionContext): boolean {
+    return this.runtimeDeps.canRequestPermissionConfirmation(ctx);
+  }
+
+  /** Prompt the user for a permission decision, log the outcome, and return it. */
+  prompt(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    return this.runtimeDeps.promptPermission(ctx, details);
+  }
+
+  /** Generate a unique ID for a permission request. */
+  createPermissionRequestId(prefix: string): string {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+  }
 }

package/src/policy-loader.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 import { extractFrontmatter, parseSimpleYamlMap, toRecord } from "./common";
 import {

package/src/runtime.ts

@@ -10,7 +10,7 @@ import {
   type ExtensionCommandContext,
   type ExtensionContext,
   getAgentDir,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
 import {

package/src/session-logger.ts

@@ -3,7 +3,7 @@ import type { ExtensionRuntime } from "./runtime";
 /**
  * Unified logging + notification surface for handler deps.
  *
- * Replaces three separate HandlerDeps fields (`writeDebugLog`,
+ * Replaces three separate logging fields (`writeDebugLog`,
  * `writeReviewLog`, `notifyWarning`) with a single typed collaborator.
  * This is an intermediate abstraction on the path to PermissionSession (#129).
  */

package/src/status.ts

@@ -1,7 +1,7 @@
 import type {
   ExtensionCommandContext,
   ExtensionContext,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 import {
   EXTENSION_ID,

package/src/subagent-context.ts

@@ -1,5 +1,5 @@
 import { normalize } from "node:path";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
 

package/src/tool-registry.ts

@@ -1,5 +1,11 @@
 import { getNonEmptyString, toRecord } from "./common";
 
+/** Narrow interface for the Pi tool API subset used by handler classes. */
+export interface ToolRegistry {
+  getAll(): unknown[];
+  setActive(names: string[]): void;
+}
+
 export type ToolRegistrationCheckResult =
   | {
       status: "missing-tool-name";

package/tests/active-agent.test.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { afterEach, describe, expect, test, vi } from "vitest";
 import {
   ACTIVE_AGENT_TAG_REGEX,

package/tests/config-modal.test.ts

@@ -12,11 +12,11 @@ import {
 } from "../src/extension-config";
 import type { Rule } from "../src/rule";
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   getSettingsListTheme: () => ({}),
 }));
 
-vi.mock("@mariozechner/pi-tui", () => ({
+vi.mock("@earendil-works/pi-tui", () => ({
   SettingsList: class {
     handleInput(): void {}
     updateValue(): void {}

package/tests/forwarding-manager.test.ts

@@ -24,7 +24,7 @@ function makeCtx(overrides: { hasUI?: boolean; sessionId?: string } = {}) {
       getSessionId: vi.fn().mockReturnValue(overrides.sessionId ?? "sess-1"),
     },
     cwd: "/project",
-  } as unknown as import("@mariozechner/pi-coding-agent").ExtensionContext;
+  } as unknown as import("@earendil-works/pi-coding-agent").ExtensionContext;
 }
 
 function makeForwardingDeps() {