@gotgenes/pi-permission-system 5.5.0 → 5.6.0

package/src/handlers/tool-call.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
 import { toRecord } from "../common";
+import { emitDecisionEvent } from "../permission-events";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
@@ -9,12 +10,15 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../tool-registry";
-import { evaluateBashExternalDirectoryGate } from "./gates/bash-external-directory";
-import { evaluateExternalDirectoryGate } from "./gates/external-directory";
-import { evaluateSkillReadGate } from "./gates/skill-read";
-import { evaluateToolGate } from "./gates/tool";
+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";
-import type { HandlerDeps } from "./types";
+import type { HandlerDeps, PromptPermissionDetails } from "./types";
 
 /**
  * Extract the tool input from an event, checking both `input` and `arguments`
@@ -39,7 +43,7 @@ export async function handleToolCall(
   event: unknown,
   ctx: ExtensionContext,
 ): Promise<{ block?: true; reason?: string }> {
-  deps.runtime.runtimeContext = ctx;
+  deps.session.runtimeContext = ctx;
   deps.startForwardedPermissionPolling(ctx);
 
   const agentName = deps.resolveAgentName(ctx);
@@ -81,26 +85,123 @@ export async function handleToolCall(
     cwd: ctx.cwd,
   };
 
-  // ── Skill-read gate ──────────────────────────────────────────────────────
-  const skillResult = await evaluateSkillReadGate(tcc, deps);
-  if (skillResult?.action === "block") {
-    return { block: true, reason: skillResult.reason };
+  // ── Shared gate adapter closures ───────────────────────────────────────
+  const canConfirm = () => deps.canRequestPermissionConfirmation(ctx);
+  const promptPermission = (details: PromptPermissionDetails) =>
+    deps.promptPermission(ctx, details);
+  const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
+    emitDecisionEvent(deps.events, e);
+  const { writeReviewLog } = deps;
+  const checkPermission: GateRunnerDeps["checkPermission"] = (
+    surface,
+    input,
+    agent,
+    sessionRules,
+  ) =>
+    deps.session.permissionManager.checkPermission(
+      surface,
+      input,
+      agent,
+      sessionRules,
+    );
+  const getSessionRuleset = () => deps.session.sessionRules.getRuleset();
+  const approveSessionRule = (surface: string, pattern: string) =>
+    deps.session.sessionRules.approve(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,
+    () => deps.session.activeSkillEntries,
+  );
+  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 (file tools) ─────────────────────────────────
-  const extDirResult = await evaluateExternalDirectoryGate(tcc, deps);
-  if (extDirResult?.action === "block") {
-    return { block: true, reason: extDirResult.reason };
+  // ── External-directory gate (descriptor + runner) ─────────────────────────
+  const infraDirs = [
+    ...deps.piInfrastructureDirs,
+    ...deps.getPiInfrastructureReadPaths(),
+  ];
+  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 ─────────────────────────────────────────
-  const bashExtResult = await evaluateBashExternalDirectoryGate(tcc, deps);
-  if (bashExtResult?.action === "block") {
-    return { block: true, reason: bashExtResult.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 ──────────────────────────────────────────
-  const toolResult = await evaluateToolGate(tcc, deps);
+  // ── 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 };
   }

package/src/handlers/types.ts

@@ -3,7 +3,7 @@ import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { PermissionPromptDecision } from "../permission-dialog";
 import type { PermissionEventBus } from "../permission-events";
 import type { PermissionManager } from "../permission-manager";
-import type { ExtensionRuntime } from "../runtime";
+import type { SessionState } from "../runtime";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
@@ -27,13 +27,26 @@ export interface PromptPermissionDetails {
 /**
  * Explicit dependency bag passed to each extracted event handler.
  *
- * Mutable state lives in `runtime`; handlers read and write `deps.runtime.*`
- * directly instead of going through getter/setter pairs.
+ * Mutable session state lives in `session`; handlers read and write
+ * `deps.session.*` directly. Logging, infrastructure paths, and the
+ * event bus are promoted to top-level fields so handlers and gate
+ * adapters never reach through nested objects for leaf operations.
  */
 export interface HandlerDeps {
-  // ── Runtime context ────────────────────────────────────────────────────
-  /** All mutable extension state and log-writing methods. */
-  readonly runtime: ExtensionRuntime;
+  // ── Session state ─────────────────────────────────────────────────────
+  /** Mutable session state: permissionManager, sessionRules, cache keys. */
+  readonly session: SessionState;
+
+  // ── Logging (promoted from runtime) ───────────────────────────────────
+  writeDebugLog(event: string, details?: Record<string, unknown>): void;
+  writeReviewLog(event: string, details?: Record<string, unknown>): void;
+
+  // ── Immutable infrastructure paths ───────────────────────────────────
+  readonly piInfrastructureDirs: string[];
+  /** Returns config-derived infrastructure read paths (current at call time). */
+  getPiInfrastructureReadPaths(): string[];
+
+  // ── Event bus ────────────────────────────────────────────────────────
   /** Event bus for emitting permissions:decision broadcast events. */
   readonly events: PermissionEventBus;
 
@@ -54,7 +67,7 @@ export interface HandlerDeps {
   // ── Permission helpers ─────────────────────────────────────────────────
   /**
    * Resolve the active agent name from the session context or system prompt.
-   * Updates runtime.lastKnownActiveAgentName as a side effect.
+   * Updates session.lastKnownActiveAgentName as a side effect.
    */
   resolveAgentName(ctx: ExtensionContext, systemPrompt?: string): string | null;
   /** Whether the current context can show an interactive permission prompt. */

package/src/index.ts

@@ -78,7 +78,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   const deps: HandlerDeps = {
-    runtime,
+    session: runtime,
+    writeDebugLog: (event, details) => runtime.writeDebugLog(event, details),
+    writeReviewLog: (event, details) => runtime.writeReviewLog(event, details),
+    piInfrastructureDirs: runtime.piInfrastructureDirs,
+    getPiInfrastructureReadPaths: () =>
+      runtime.config.piInfrastructureReadPaths ?? [],
     events: pi.events,
     createPermissionManagerForCwd: (cwd) =>
       createPermissionManagerForCwd(runtime.agentDir, cwd),

package/src/runtime.ts

@@ -47,6 +47,21 @@ import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import { syncPermissionSystemStatus } from "./status";
 import { isSubagentExecutionContext } from "./subagent-context";
 
+/**
+ * Mutable session state — the subset of ExtensionRuntime that handlers
+ * read and write. Lifecycle handlers reset fields here on session
+ * start/shutdown; gate adapters read permissionManager and sessionRules.
+ */
+export interface SessionState {
+  runtimeContext: ExtensionContext | null;
+  permissionManager: PermissionManager;
+  readonly sessionRules: SessionRules;
+  activeSkillEntries: SkillPromptEntry[];
+  lastKnownActiveAgentName: string | null;
+  lastActiveToolsCacheKey: string | null;
+  lastPromptStateCacheKey: string | null;
+}
+
 /**
  * Runtime context object created once inside `piPermissionSystemExtension()`.
  *
@@ -58,7 +73,7 @@ import { isSubagentExecutionContext } from "./subagent-context";
  * Tests construct this via `createExtensionRuntime({ agentDir: tmpDir })`
  * without timing issues around `PI_CODING_AGENT_DIR`.
  */
-export interface ExtensionRuntime {
+export interface ExtensionRuntime extends SessionState {
   // ── Immutable paths (derived from agentDir at construction) ───────────
   readonly agentDir: string;
   readonly sessionsDir: string;
@@ -74,16 +89,9 @@ export interface ExtensionRuntime {
    */
   readonly piInfrastructureDirs: string[];
 
-  // ── Mutable state ──────────────────────────────────────────────────────
+  // ── Mutable state (beyond SessionState) ───────────────────────────────────
   config: PermissionSystemExtensionConfig;
-  runtimeContext: ExtensionContext | null;
-  permissionManager: PermissionManager;
-  activeSkillEntries: SkillPromptEntry[];
-  lastKnownActiveAgentName: string | null;
-  lastActiveToolsCacheKey: string | null;
-  lastPromptStateCacheKey: string | null;
   lastConfigWarning: string | null;
-  readonly sessionRules: SessionRules;
 
   // ── Forwarding polling state ───────────────────────────────────────────
   permissionForwardingContext: ExtensionContext | null;

package/tests/handlers/before-agent-start.test.ts

@@ -7,7 +7,7 @@ import {
 } from "../../src/handlers/before-agent-start";
 import type { HandlerDeps } from "../../src/handlers/types";
 import type { PermissionManager } from "../../src/permission-manager";
-import type { ExtensionRuntime } from "../../src/runtime";
+import type { SessionState } from "../../src/runtime";
 import type { SkillPromptEntry } from "../../src/skill-prompt-sanitizer";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
@@ -57,40 +57,30 @@ function makePm(
   } as unknown as PermissionManager;
 }
 
-function makeRuntime(
-  overrides: Partial<ExtensionRuntime> = {},
-): ExtensionRuntime {
+function makeSession(overrides: Partial<SessionState> = {}): SessionState {
   return {
-    agentDir: "/test/agent",
-    sessionsDir: "/test/agent/sessions",
-    subagentSessionsDir: "/test/agent/subagent-sessions",
-    forwardingDir: "/test/agent/sessions/permission-forwarding",
-    globalLogsDir: "/test/agent/extensions/pi-permission-system/logs",
-    config: { debugLog: false, permissionReviewLog: true, yoloMode: false },
     runtimeContext: null,
     permissionManager: makePm() as unknown as PermissionManager,
     activeSkillEntries: [] as SkillPromptEntry[],
     lastKnownActiveAgentName: null,
     lastActiveToolsCacheKey: null,
     lastPromptStateCacheKey: null,
-    lastConfigWarning: null,
     sessionRules: {
       approve: vi.fn(),
       getRuleset: vi.fn().mockReturnValue([]),
       clear: vi.fn(),
-    } as unknown as ExtensionRuntime["sessionRules"],
-    permissionForwardingContext: null,
-    permissionForwardingTimer: null,
-    isProcessingForwardedRequests: false,
-    writeDebugLog: vi.fn(),
-    writeReviewLog: vi.fn(),
+    } as unknown as SessionState["sessionRules"],
     ...overrides,
-  } as ExtensionRuntime;
+  };
 }
 
 function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
   return {
-    runtime: makeRuntime(),
+    session: makeSession(),
+    writeDebugLog: vi.fn(),
+    writeReviewLog: vi.fn(),
+    piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
+    getPiInfrastructureReadPaths: vi.fn().mockReturnValue([]),
     createPermissionManagerForCwd: vi.fn().mockReturnValue(makePm()),
     refreshExtensionConfig: vi.fn(),
     notifyWarning: vi.fn(),
@@ -176,7 +166,7 @@ describe("handleBeforeAgentStart", () => {
   it("filters out denied tools from allowed list", async () => {
     const pm = makePm("deny");
     const deps = makeDeps({
-      runtime: makeRuntime({
+      session: makeSession({
         permissionManager: pm as unknown as PermissionManager,
       }),
       getAllTools: vi
@@ -191,7 +181,7 @@ describe("handleBeforeAgentStart", () => {
   it("includes allowed and ask tools in the active list", async () => {
     const pm = makePm("allow");
     const deps = makeDeps({
-      runtime: makeRuntime({
+      session: makeSession({
         permissionManager: pm as unknown as PermissionManager,
       }),
       getAllTools: vi
@@ -207,7 +197,7 @@ describe("handleBeforeAgentStart", () => {
       getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
     });
     await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
-    expect(deps.runtime.lastActiveToolsCacheKey).not.toBeNull();
+    expect(deps.session.lastActiveToolsCacheKey).not.toBeNull();
   });
 
   it("skips setActiveTools when cache key is unchanged", async () => {
@@ -217,7 +207,7 @@ describe("handleBeforeAgentStart", () => {
     );
     const key = createActiveToolsCacheKey(["read"]);
     const deps = makeDeps({
-      runtime: makeRuntime({ lastActiveToolsCacheKey: key }),
+      session: makeSession({ lastActiveToolsCacheKey: key }),
       getAllTools: vi.fn().mockReturnValue([{ name: "read" }]),
     });
     await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
@@ -238,7 +228,7 @@ describe("handleBeforeAgentStart", () => {
     );
     // The prompt was modified, so systemPrompt should be returned
     expect(result).toHaveProperty("systemPrompt");
-    expect(deps.runtime.lastPromptStateCacheKey).not.toBeNull();
+    expect(deps.session.lastPromptStateCacheKey).not.toBeNull();
   });
 
   it("returns empty object when systemPrompt is unchanged", async () => {
@@ -259,7 +249,7 @@ describe("handleBeforeAgentStart", () => {
       getAllTools: vi.fn().mockReturnValue([]),
     });
     await handleBeforeAgentStart(deps, makeEvent(), makeCtx());
-    expect(deps.runtime.activeSkillEntries).toEqual(expect.any(Array));
+    expect(deps.session.activeSkillEntries).toEqual(expect.any(Array));
   });
 
   it("returns empty object and skips prompt work when prompt cache key is unchanged", async () => {
@@ -277,7 +267,7 @@ describe("handleBeforeAgentStart", () => {
       allowedToolNames: allowedTools,
     });
     const deps = makeDeps({
-      runtime: makeRuntime({
+      session: makeSession({
         permissionManager: pm as unknown as PermissionManager,
         lastPromptStateCacheKey: key,
       }),
@@ -286,6 +276,6 @@ describe("handleBeforeAgentStart", () => {
     const result = await handleBeforeAgentStart(deps, makeEvent("hello"), ctx);
     expect(result).toEqual({});
     // activeSkillEntries was not assigned by the handler (early return)
-    expect(deps.runtime.activeSkillEntries).toEqual([]);
+    expect(deps.session.activeSkillEntries).toEqual([]);
   });
 });