@gotgenes/pi-permission-system 5.9.0 → 5.11.0

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

@@ -0,0 +1,346 @@
+import type {
+  ExtensionContext,
+  InputEventResult,
+} from "@mariozechner/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

@@ -4,24 +4,19 @@ 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";
 import { emitReadyEvent } from "./permission-events";
 import { PermissionPrompter } from "./permission-prompter";
+import { PermissionSession } from "./permission-session";
 import {
   createExtensionRuntime,
-  createPermissionManagerForCwd,
   logResolvedConfigPaths,
   refreshExtensionConfig,
-  resolveAgentName,
   saveExtensionConfig,
 } from "./runtime";
 import { createSessionLogger } from "./session-logger";
@@ -56,6 +51,28 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   refreshExtensionConfig(runtime);
+
+  const session = new PermissionSession(
+    runtime,
+    createSessionLogger(runtime),
+    new ForwardingManager(runtime.subagentSessionsDir, forwardingDeps),
+    {
+      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),
+    },
+  );
+
   registerPermissionSystemCommand(pi, {
     getConfig: () => runtime.config,
     setConfig: (next, ctx) => saveExtensionConfig(runtime, next, ctx),
@@ -66,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(),
@@ -77,50 +91,28 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     writeReviewLog: runtime.writeReviewLog.bind(runtime),
   });
 
-  const deps: HandlerDeps = {
-    session: runtime,
-    logger: createSessionLogger(runtime),
-    piInfrastructureDirs: runtime.piInfrastructureDirs,
-    getPiInfrastructureReadPaths: () =>
-      runtime.config.piInfrastructureReadPaths ?? [],
-    events: pi.events,
-    createPermissionManagerForCwd: (cwd) =>
-      createPermissionManagerForCwd(runtime.agentDir, cwd),
-    refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
-    logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
-    resolveAgentName: (ctx, systemPrompt) =>
-      resolveAgentName(runtime, ctx, systemPrompt),
-    canRequestPermissionConfirmation: (ctx) =>
-      canResolveAskPermissionRequest({
-        config: runtime.config,
-        hasUI: ctx.hasUI,
-        isSubagent: isSubagentExecutionContext(
-          ctx,
-          runtime.subagentSessionsDir,
-        ),
-      }),
-    promptPermission: (ctx, details) => prompter.prompt(ctx, details),
-    createPermissionRequestId,
-    forwarding: new ForwardingManager(
-      runtime.subagentSessionsDir,
-      forwardingDeps,
-    ),
-    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-prompter.ts

@@ -5,14 +5,32 @@ 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) {}