@gotgenes/pi-permission-system 10.7.2 → 10.8.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.8.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.7.2...pi-permission-system-v10.8.0) (2026-06-10)
+
+
+### Features
+
+* add CacheKeyGate for agent-start cache keys ([#365](https://github.com/gotgenes/pi-packages/issues/365)) ([e99285c](https://github.com/gotgenes/pi-packages/commit/e99285c50fef3f6fd8ea7dac00080eeb9957adaa))
+
+
+### Documentation
+
+* mark Phase 5 Step 4 complete ([#365](https://github.com/gotgenes/pi-packages/issues/365)) ([4bd0e30](https://github.com/gotgenes/pi-packages/commit/4bd0e30fb4cb03d6cff76242f75955e9698c7d0d))
+
 ## [10.7.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.7.1...pi-permission-system-v10.7.2) (2026-06-10)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "10.7.2",
+  "version": "10.8.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/before-agent-start-cache.ts

@@ -35,10 +35,3 @@ export function createBeforeAgentStartPromptStateKey(
     normalizePrompt(input.systemPrompt),
   ]);
 }
-
-export function shouldApplyCachedAgentStartState(
-  previousKey: string | null,
-  nextKey: string,
-): boolean {
-  return previousKey !== nextKey;
-}

package/src/cache-key-gate.ts

@@ -0,0 +1,32 @@
+/**
+ * Owns a previous cache key and conditionally runs an effect when the key changes.
+ *
+ * Encapsulates the prev !== next comparison that previously lived in three places:
+ * the session's inline `!==`, the handler's ask-then-tell orchestration, and the
+ * (test-only-alive) `shouldApplyCachedAgentStartState` free function.
+ *
+ * Semantics:
+ * - On a changed key: runs `effect`, commits `nextKey`, returns the effect's value.
+ * - On an unchanged key: skips `effect`, returns `undefined`.
+ * - `reset()` re-arms the gate (used by session lifecycle: `resetForNewSession`,
+ *   `shutdown`, `reload`).
+ *
+ * Commit ordering is run-then-commit: the key is saved only after `effect` returns.
+ * If `effect` throws, the key stays uncommitted and the next call retries.
+ */
+export class CacheKeyGate {
+  private previousKey: string | null = null;
+
+  runIfChanged<T>(nextKey: string, effect: () => T): T | undefined {
+    if (this.previousKey === nextKey) {
+      return undefined;
+    }
+    const result = effect();
+    this.previousKey = nextKey;
+    return result;
+  }
+
+  reset(): void {
+    this.previousKey = null;
+  }
+}

package/src/handlers/before-agent-start.ts

@@ -74,10 +74,9 @@ export class AgentPrepHandler {
     }
 
     const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-    if (this.session.shouldUpdateActiveTools(activeToolsCacheKey)) {
+    this.session.activeToolsGate.runIfChanged(activeToolsCacheKey, () => {
       this.toolRegistry.setActive(allowedTools);
-      this.session.commitActiveToolsCacheKey(activeToolsCacheKey);
-    }
+    });
 
     const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
       agentName,
@@ -89,28 +88,25 @@ export class AgentPrepHandler {
       allowedToolNames: allowedTools,
     });
 
-    if (!this.session.shouldUpdatePromptState(promptStateCacheKey)) {
-      return {};
-    }
-
-    this.session.commitPromptStateCacheKey(promptStateCacheKey);
-
-    const toolPromptResult = sanitizeAvailableToolsSection(
-      event.systemPrompt,
-      allowedTools,
+    const promptResult = this.session.promptStateGate.runIfChanged(
+      promptStateCacheKey,
+      () => {
+        const toolPromptResult = sanitizeAvailableToolsSection(
+          event.systemPrompt,
+          allowedTools,
+        );
+        const skillPromptResult = resolveSkillPromptEntries(
+          toolPromptResult.prompt,
+          this.resolver,
+          agentName,
+          ctx.cwd,
+        );
+        this.session.setActiveSkillEntries(skillPromptResult.entries);
+        return skillPromptResult.prompt !== event.systemPrompt
+          ? { systemPrompt: skillPromptResult.prompt }
+          : {};
+      },
     );
-    const skillPromptResult = resolveSkillPromptEntries(
-      toolPromptResult.prompt,
-      this.resolver,
-      agentName,
-      ctx.cwd,
-    );
-    this.session.setActiveSkillEntries(skillPromptResult.entries);
-
-    if (skillPromptResult.prompt !== event.systemPrompt) {
-      return { systemPrompt: skillPromptResult.prompt };
-    }
-
-    return {};
+    return promptResult ?? {};
   }
 }

package/src/permission-session.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
+import { CacheKeyGate } from "#src/cache-key-gate";
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
@@ -38,8 +38,8 @@ export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
-  private toolsCacheKey: string | null = null;
-  private promptCacheKey: string | null = null;
+  readonly activeToolsGate = new CacheKeyGate();
+  readonly promptStateGate = new CacheKeyGate();
 
   constructor(
     private readonly paths: ExtensionPaths,
@@ -89,8 +89,8 @@ export class PermissionSession implements ToolCallGateInputs {
   resetForNewSession(ctx: ExtensionContext): void {
     this.permissionManager.configureForCwd(ctx.cwd);
     this.skillEntries = [];
-    this.toolsCacheKey = null;
-    this.promptCacheKey = null;
+    this.activeToolsGate.reset();
+    this.promptStateGate.reset();
     this.activate(ctx);
   }
 
@@ -101,8 +101,8 @@ export class PermissionSession implements ToolCallGateInputs {
   shutdown(): void {
     this.sessionRules.clear();
     this.skillEntries = [];
-    this.toolsCacheKey = null;
-    this.promptCacheKey = null;
+    this.activeToolsGate.reset();
+    this.promptStateGate.reset();
     this.deactivate();
   }
 
@@ -113,26 +113,8 @@ export class PermissionSession implements ToolCallGateInputs {
   reload(): void {
     this.permissionManager.configureForCwd(this.context?.cwd);
     this.skillEntries = [];
-    this.toolsCacheKey = null;
-    this.promptCacheKey = null;
-  }
-
-  // ── Agent-start caching ────────────────────────────────────────────────
-
-  shouldUpdateActiveTools(cacheKey: string): boolean {
-    return this.toolsCacheKey !== cacheKey;
-  }
-
-  commitActiveToolsCacheKey(cacheKey: string): void {
-    this.toolsCacheKey = cacheKey;
-  }
-
-  shouldUpdatePromptState(cacheKey: string): boolean {
-    return this.promptCacheKey !== cacheKey;
-  }
-
-  commitPromptStateCacheKey(cacheKey: string): void {
-    this.promptCacheKey = cacheKey;
+    this.activeToolsGate.reset();
+    this.promptStateGate.reset();
   }
 
   // ── Skill entries ──────────────────────────────────────────────────────

package/test/before-agent-start-cache.test.ts

@@ -1,33 +1,8 @@
 import { writeFileSync } from "node:fs";
 import { expect, test } from "vitest";
-import {
-  createActiveToolsCacheKey,
-  createBeforeAgentStartPromptStateKey,
-  shouldApplyCachedAgentStartState,
-} from "#src/before-agent-start-cache";
+import { createBeforeAgentStartPromptStateKey } from "#src/before-agent-start-cache";
 import { createManager } from "#test/helpers/manager-harness";
 
-test("Before-agent-start cache dedupes unchanged active-tool exposure and prompt state", () => {
-  const allowedTools = ["read", "mcp"];
-  const activeToolsKey = createActiveToolsCacheKey(allowedTools);
-  const promptStateKey = createBeforeAgentStartPromptStateKey({
-    agentName: "code",
-    cwd: "C:/workspace/project",
-    permissionStamp: "permissions-v1",
-    systemPrompt: "Available tools:\n- read\n- mcp",
-    allowedToolNames: allowedTools,
-  });
-
-  expect(shouldApplyCachedAgentStartState(null, activeToolsKey)).toBe(true);
-  expect(shouldApplyCachedAgentStartState(activeToolsKey, activeToolsKey)).toBe(
-    false,
-  );
-  expect(shouldApplyCachedAgentStartState(null, promptStateKey)).toBe(true);
-  expect(shouldApplyCachedAgentStartState(promptStateKey, promptStateKey)).toBe(
-    false,
-  );
-});
-
 test("Before-agent-start prompt cache invalidates on permission changes while runtime enforcement stays authoritative", () => {
   const { manager, globalConfigPath, cleanup } = createManager({
     permission: { "*": "allow", write: "deny" },
@@ -43,9 +18,6 @@ test("Before-agent-start prompt cache invalidates on permission changes while ru
       allowedToolNames: ["read"],
     });
 
-    expect(shouldApplyCachedAgentStartState(baselineKey, baselineKey)).toBe(
-      false,
-    );
     expect(manager.checkPermission("write", {}, undefined).state).toBe("deny");
 
     const updatedConfig = `${JSON.stringify(
@@ -79,9 +51,7 @@ test("Before-agent-start prompt cache invalidates on permission changes while ru
       allowedToolNames: ["read", "write"],
     });
 
-    expect(shouldApplyCachedAgentStartState(baselineKey, invalidatedKey)).toBe(
-      true,
-    );
+    expect(invalidatedKey).not.toBe(baselineKey);
     expect(manager.checkPermission("write", {}, undefined).state).toBe("allow");
   } finally {
     cleanup();

package/test/cache-key-gate.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { CacheKeyGate } from "#src/cache-key-gate";
+
+describe("CacheKeyGate", () => {
+  describe("runIfChanged", () => {
+    it("runs the effect and returns its value when the key is new (null previous)", () => {
+      const gate = new CacheKeyGate();
+      const effect = vi.fn(() => "result");
+
+      const result = gate.runIfChanged("key-a", effect);
+
+      expect(effect).toHaveBeenCalledOnce();
+      expect(result).toBe("result");
+    });
+
+    it("commits the key so a second call with the same key skips the effect", () => {
+      const gate = new CacheKeyGate();
+      const effect = vi.fn(() => "result");
+
+      gate.runIfChanged("key-a", effect);
+      const result = gate.runIfChanged("key-a", effect);
+
+      expect(effect).toHaveBeenCalledOnce();
+      expect(result).toBeUndefined();
+    });
+
+    it("runs the effect when the key changes", () => {
+      const gate = new CacheKeyGate();
+      const effect = vi.fn((n: number) => n);
+
+      gate.runIfChanged("key-a", () => effect(1));
+      const result = gate.runIfChanged("key-b", () => effect(2));
+
+      expect(effect).toHaveBeenCalledTimes(2);
+      expect(result).toBe(2);
+    });
+
+    it("returns undefined when the key is unchanged", () => {
+      const gate = new CacheKeyGate();
+      gate.runIfChanged("key-a", vi.fn());
+
+      const result = gate.runIfChanged("key-a", vi.fn());
+
+      expect(result).toBeUndefined();
+    });
+
+    it("does not commit the key if the effect throws", () => {
+      const gate = new CacheKeyGate();
+      const throwing = vi.fn(() => {
+        throw new Error("oops");
+      });
+      const fallback = vi.fn(() => "ok");
+
+      expect(() => gate.runIfChanged("key-a", throwing)).toThrow("oops");
+
+      // Same key should run again since the first call threw
+      gate.runIfChanged("key-a", fallback);
+      expect(fallback).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("reset", () => {
+    it("re-arms the gate so the same key runs again on the next call", () => {
+      const gate = new CacheKeyGate();
+      const effect = vi.fn(() => "ok");
+
+      gate.runIfChanged("key-a", effect);
+      gate.reset();
+      gate.runIfChanged("key-a", effect);
+
+      expect(effect).toHaveBeenCalledTimes(2);
+    });
+
+    it("is idempotent when called on a fresh gate", () => {
+      const gate = new CacheKeyGate();
+      gate.reset();
+      const effect = vi.fn(() => "ok");
+
+      gate.runIfChanged("key-a", effect);
+
+      expect(effect).toHaveBeenCalledOnce();
+    });
+  });
+});

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

@@ -143,42 +143,24 @@ describe("AgentPrepHandler.handle", () => {
     expect(toolRegistry.setActive).toHaveBeenCalledWith(["read", "write"]);
   });
 
-  it("commits active-tools cache key after applying", async () => {
-    const { handler, session } = makeSetup({
+  it("calls setActive once across repeated calls with the same allowed tools", async () => {
+    const { handler, toolRegistry } = makeSetup({
       toolRegistry: {
         getAll: vi.fn().mockReturnValue([{ name: "read" }]),
       },
     });
-    const spy = vi.spyOn(session, "commitActiveToolsCacheKey");
     await handler.handle(makeEvent(), makeCtx());
-    expect(spy).toHaveBeenCalled();
-  });
-
-  it("skips setActive when cache key is unchanged", async () => {
-    const { handler, session, toolRegistry } = makeSetup({
-      toolRegistry: {
-        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
-      },
-    });
-    vi.spyOn(session, "shouldUpdateActiveTools").mockReturnValue(false);
     await handler.handle(makeEvent(), makeCtx());
-    expect(toolRegistry.setActive).not.toHaveBeenCalled();
+    expect(toolRegistry.setActive).toHaveBeenCalledOnce();
   });
 
-  it("returns empty object when prompt cache is unchanged", async () => {
-    const { handler, session } = makeSetup();
-    vi.spyOn(session, "shouldUpdatePromptState").mockReturnValue(false);
+  it("returns empty object on repeated calls with unchanged inputs", async () => {
+    const { handler } = makeSetup();
+    await handler.handle(makeEvent(), makeCtx());
     const result = await handler.handle(makeEvent(), makeCtx());
     expect(result).toEqual({});
   });
 
-  it("commits prompt-state cache key and processes prompt when cache is new", async () => {
-    const { handler, session } = makeSetup();
-    const spy = vi.spyOn(session, "commitPromptStateCacheKey");
-    await handler.handle(makeEvent(), makeCtx());
-    expect(spy).toHaveBeenCalled();
-  });
-
   it("stores resolved skill entries on the session", async () => {
     const { handler, session } = makeSetup();
     const spy = vi.spyOn(session, "setActiveSkillEntries");

package/test/permission-session.test.ts

@@ -105,16 +105,19 @@ describe("PermissionSession", () => {
 
     it("clears cache keys", () => {
       const { session } = createSession();
-      session.commitActiveToolsCacheKey("key-1");
-      session.commitPromptStateCacheKey("key-2");
-      expect(session.shouldUpdateActiveTools("key-1")).toBe(false);
-      expect(session.shouldUpdatePromptState("key-2")).toBe(false);
+      // Prime both gates with a key
+      session.activeToolsGate.runIfChanged("key-1", () => {});
+      session.promptStateGate.runIfChanged("key-2", () => {});
 
       session.resetForNewSession(makeCtx());
 
-      // After reset, same keys should be treated as new
-      expect(session.shouldUpdateActiveTools("key-1")).toBe(true);
-      expect(session.shouldUpdatePromptState("key-2")).toBe(true);
+      // After reset, the same keys should run the effect again
+      const toolsEffect = vi.fn();
+      const promptEffect = vi.fn();
+      session.activeToolsGate.runIfChanged("key-1", toolsEffect);
+      session.promptStateGate.runIfChanged("key-2", promptEffect);
+      expect(toolsEffect).toHaveBeenCalledOnce();
+      expect(promptEffect).toHaveBeenCalledOnce();
     });
 
     it("clears skill entries", () => {
@@ -162,13 +165,19 @@ describe("PermissionSession", () => {
 
     it("clears cache keys", () => {
       const { session } = createSession();
-      session.commitActiveToolsCacheKey("k1");
-      session.commitPromptStateCacheKey("k2");
+      // Prime both gates with a key
+      session.activeToolsGate.runIfChanged("k1", () => {});
+      session.promptStateGate.runIfChanged("k2", () => {});
 
       session.shutdown();
 
-      expect(session.shouldUpdateActiveTools("k1")).toBe(true);
-      expect(session.shouldUpdatePromptState("k2")).toBe(true);
+      // After shutdown, the same keys should run the effect again
+      const toolsEffect = vi.fn();
+      const promptEffect = vi.fn();
+      session.activeToolsGate.runIfChanged("k1", toolsEffect);
+      session.promptStateGate.runIfChanged("k2", promptEffect);
+      expect(toolsEffect).toHaveBeenCalledOnce();
+      expect(promptEffect).toHaveBeenCalledOnce();
     });
 
     it("clears skill entries", () => {
@@ -190,36 +199,6 @@ describe("PermissionSession", () => {
     });
   });
 
-  describe("cache key methods", () => {
-    it("shouldUpdateActiveTools returns true for new key", () => {
-      const { session } = createSession();
-      expect(session.shouldUpdateActiveTools("key-1")).toBe(true);
-    });
-
-    it("shouldUpdateActiveTools returns false for committed key", () => {
-      const { session } = createSession();
-      session.commitActiveToolsCacheKey("key-1");
-      expect(session.shouldUpdateActiveTools("key-1")).toBe(false);
-    });
-
-    it("shouldUpdateActiveTools returns true for different key", () => {
-      const { session } = createSession();
-      session.commitActiveToolsCacheKey("key-1");
-      expect(session.shouldUpdateActiveTools("key-2")).toBe(true);
-    });
-
-    it("shouldUpdatePromptState returns true for new key", () => {
-      const { session } = createSession();
-      expect(session.shouldUpdatePromptState("key-1")).toBe(true);
-    });
-
-    it("shouldUpdatePromptState returns false for committed key", () => {
-      const { session } = createSession();
-      session.commitPromptStateCacheKey("key-1");
-      expect(session.shouldUpdatePromptState("key-1")).toBe(false);
-    });
-  });
-
   describe("skill entries", () => {
     it("get/set skill entries", () => {
       const { session } = createSession();
@@ -356,14 +335,20 @@ describe("PermissionSession", () => {
 
     it("clears caches and skill entries", () => {
       const { session } = createSession();
-      session.commitActiveToolsCacheKey("k1");
-      session.commitPromptStateCacheKey("k2");
+      // Prime both gates with a key
+      session.activeToolsGate.runIfChanged("k1", () => {});
+      session.promptStateGate.runIfChanged("k2", () => {});
       session.setActiveSkillEntries([makeSkillEntry("s")]);
 
       session.reload();
 
-      expect(session.shouldUpdateActiveTools("k1")).toBe(true);
-      expect(session.shouldUpdatePromptState("k2")).toBe(true);
+      // After reload, the same keys should run the effect again
+      const toolsEffect = vi.fn();
+      const promptEffect = vi.fn();
+      session.activeToolsGate.runIfChanged("k1", toolsEffect);
+      session.promptStateGate.runIfChanged("k2", promptEffect);
+      expect(toolsEffect).toHaveBeenCalledOnce();
+      expect(promptEffect).toHaveBeenCalledOnce();
       expect(session.getActiveSkillEntries()).toEqual([]);
     });
   });