@gotgenes/pi-permission-system 10.7.1 → 10.8.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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)
+
+
+### Miscellaneous Chores
+
+* **deps:** bump tooling dependencies to latest minor/patch ([8b9105d](https://github.com/gotgenes/pi-packages/commit/8b9105d4011816fe8085dfed3a3b9d7bc9918c56))
+
 ## [10.7.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.7.0...pi-permission-system-v10.7.1) (2026-06-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "10.7.1",
+  "version": "10.8.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -60,17 +60,17 @@
     "@earendil-works/pi-tui": ">=0.75.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.14",
+    "@biomejs/biome": "^2.4.16",
     "@earendil-works/pi-coding-agent": "0.75.4",
     "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
-    "rumdl": "^0.1.93",
+    "rumdl": "^0.2.10",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.8"
   },
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",
-    "web-tree-sitter": "^0.26.8"
+    "web-tree-sitter": "^0.26.9"
   },
   "scripts": {
     "check": "tsc --noEmit",

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/handlers/lifecycle.ts

@@ -3,6 +3,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 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. */
@@ -24,12 +25,14 @@ interface ResourcesDiscoverPayload {
  * - `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
  */
 export class SessionLifecycleHandler {
   constructor(
     private readonly session: PermissionSession,
     private readonly resolver: PermissionResolver,
     private readonly serviceLifecycle: ServiceLifecycle,
+    private readonly logger: SessionLogger,
   ) {}
 
   handleSessionStart(
@@ -43,11 +46,11 @@ export class SessionLifecycleHandler {
     const agentName = this.session.resolveAgentName(ctx);
     const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
     for (const issue of policyIssues) {
-      this.session.logger.warn(issue);
+      this.logger.warn(issue);
     }
 
     if (event.reason === "reload") {
-      this.session.logger.debug("lifecycle.reload", {
+      this.logger.debug("lifecycle.reload", {
         triggeredBy: "session_start",
         reason: event.reason,
         cwd: ctx.cwd,
@@ -68,7 +71,7 @@ export class SessionLifecycleHandler {
     }
 
     this.session.reload();
-    this.session.logger.debug("lifecycle.reload", {
+    this.logger.debug("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: event.reason,
       cwd: this.session.getRuntimeContext()?.cwd ?? null,

package/src/index.ts

@@ -28,7 +28,7 @@ import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
 import { PromptingGateway } from "./prompting-gateway";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
-import { createSessionLogger } from "./session-logger";
+import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./subagent-registry";
@@ -43,22 +43,19 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const formatterRegistry = new ToolInputFormatterRegistry();
   registerBuiltinToolInputFormatters(formatterRegistry);
 
-  // Forward reference: configStore is declared before the logger so the
-  // logger's getConfig thunk can close over the variable; assigned immediately
-  // after. Typed via cast so the closure compiles without assertions.
-  // The same null-at-init pattern used in the former createExtensionRuntime.
-  let configStore = null as unknown as ConfigStore;
+  // 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;
 
-  // sessionNotify is a mutable holder so the logger's notify closure can
-  // reach the UI once PermissionSession is constructed. Starts as null;
-  // notify is a best-effort sink (no-op at factory-init when there is no UI).
-  let sessionNotify: PermissionSession | null = null;
-
-  const logger = createSessionLogger({
+  const logger = new PermissionSessionLogger({
     globalLogsDir: paths.globalLogsDir,
     getConfig: () => configStore.current(),
-    notify: (message) =>
-      sessionNotify?.getRuntimeContext()?.ui.notify(message, "warning"),
+    notify: (message) => session.notify(message),
   });
 
   configStore = new ConfigStore({
@@ -85,8 +82,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     forwarder,
   });
 
-  configStore.refresh();
-
   const gateway = new PromptingGateway({
     config: configStore,
     subagentSessionsDir: paths.subagentSessionsDir,
@@ -94,9 +89,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     prompter,
   });
 
-  const session = new PermissionSession(
+  session = new PermissionSession(
     paths,
-    logger,
     new ForwardingManager(
       paths.subagentSessionsDir,
       forwarder,
@@ -108,8 +102,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     gateway,
   );
 
-  // Connect the notify sink now that session is available.
-  sessionNotify = session;
+  // 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, {
@@ -163,10 +159,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     session,
     resolver,
     serviceLifecycle,
+    logger,
   );
   const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
 
-  const reporter = new GateDecisionReporter(session.logger, pi.events);
+  const reporter = new GateDecisionReporter(logger, pi.events);
   const gateRunner = new GateRunner(resolver, sessionRules, gateway, reporter);
   const toolCallGatePipeline = new ToolCallGatePipeline(
     resolver,

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,
@@ -13,7 +13,6 @@ import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipelin
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PromptingGatewayLifecycle } from "./prompting-gateway";
 
-import type { SessionLogger } from "./session-logger";
 import type { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import {
@@ -31,7 +30,6 @@ import {
  *
  * Constructor deps:
  * - `ExtensionPaths` — immutable path constants
- * - `SessionLogger` — debug + review + warn
  * - `ForwardingController` — polling lifecycle
  * - `SessionConfigStore` — owns extension config; provides refresh, log, read
  * - `PromptingGatewayLifecycle` — prompting lifecycle forwarded via activate/deactivate
@@ -40,12 +38,11 @@ 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,
-    readonly logger: SessionLogger,
     private readonly forwarding: ForwardingController,
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: SessionRules,
@@ -74,6 +71,13 @@ export class PermissionSession implements ToolCallGateInputs {
     return this.context;
   }
 
+  // ── UI notifications ────────────────────────────────────────────────────
+
+  /** Surface a warning message to the user via the active UI context, if any. */
+  notify(message: string): void {
+    this.context?.ui.notify(message, "warning");
+  }
+
   // ── Session lifecycle ────────────────────────────────────────────────────
 
   /**
@@ -85,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);
   }
 
@@ -97,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();
   }
 
@@ -109,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/src/session-logger.ts

@@ -4,7 +4,10 @@ import {
   ensurePermissionSystemLogsDirectory,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
-import { createPermissionSystemLogger } from "./logging";
+import {
+  createPermissionSystemLogger,
+  type PermissionSystemLogger,
+} from "./logging";
 
 /**
  * Narrowest logging seam — consumers that only write review-log entries.
@@ -44,37 +47,45 @@ export interface SessionLoggerDeps {
 }
 
 /**
- * Create a SessionLogger from narrow dependencies.
+ * Concrete `SessionLogger` implementation.
  *
- * Composes the JSONL log writer, owns the IO-failure warning dedup Set,
- * and routes both IO-failure warnings and explicit warn() calls through
- * the injected notify sink. No ExtensionRuntime reference required.
+ * Composes the JSONL log writer, privately owns the IO-failure warning
+ * dedup Set, and routes both IO-failure warnings and explicit warn() calls
+ * through the injected notify sink. No ExtensionRuntime reference required.
  */
-export function createSessionLogger(deps: SessionLoggerDeps): SessionLogger {
-  const writer = createPermissionSystemLogger({
-    getConfig: deps.getConfig,
-    debugLogPath: join(deps.globalLogsDir, DEBUG_LOG_FILENAME),
-    reviewLogPath: join(deps.globalLogsDir, REVIEW_LOG_FILENAME),
-    ensureLogsDirectory: () =>
-      ensurePermissionSystemLogsDirectory(deps.globalLogsDir),
-  });
+export class PermissionSessionLogger implements SessionLogger {
+  private readonly writer: PermissionSystemLogger;
+  private readonly reported = new Set<string>();
+  private readonly notify: (message: string) => void;
+
+  constructor(deps: SessionLoggerDeps) {
+    this.writer = createPermissionSystemLogger({
+      getConfig: deps.getConfig,
+      debugLogPath: join(deps.globalLogsDir, DEBUG_LOG_FILENAME),
+      reviewLogPath: join(deps.globalLogsDir, REVIEW_LOG_FILENAME),
+      ensureLogsDirectory: () =>
+        ensurePermissionSystemLogsDirectory(deps.globalLogsDir),
+    });
+    this.notify = deps.notify;
+  }
+
+  debug(event: string, details?: Record<string, unknown>): void {
+    const warning = this.writer.debug(event, details);
+    if (warning) this.reportOnce(warning);
+  }
+
+  review(event: string, details?: Record<string, unknown>): void {
+    const warning = this.writer.review(event, details);
+    if (warning) this.reportOnce(warning);
+  }
 
-  const reported = new Set<string>();
-  const reportOnce = (warning: string): void => {
-    if (reported.has(warning)) return;
-    reported.add(warning);
-    deps.notify(warning);
-  };
+  warn(message: string): void {
+    this.notify(message);
+  }
 
-  return {
-    debug: (event, details) => {
-      const warning = writer.debug(event, details);
-      if (warning) reportOnce(warning);
-    },
-    review: (event, details) => {
-      const warning = writer.review(event, details);
-      if (warning) reportOnce(warning);
-    },
-    warn: (message) => deps.notify(message),
-  };
+  private reportOnce(warning: string): void {
+    if (this.reported.has(warning)) return;
+    this.reported.add(warning);
+    this.notify(warning);
+  }
 }

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/handlers/external-directory-integration.test.ts

@@ -191,14 +191,13 @@ describe("external_directory policy state — allow", () => {
   });
 
   it("does not write a block review-log entry when external_directory is allow", async () => {
-    const { handler, session } = makeHandler({
+    const { handler, logger } = makeHandler({
       session: { checkPermission: makeExtDirCheck("allow") },
       tools: ALL_TOOLS,
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     await handler.handleToolCall(event, makeCtx());
-    const reviewCalls = (session.logger.review as ReturnType<typeof vi.fn>).mock
-      .calls;
+    const reviewCalls = (logger.review as ReturnType<typeof vi.fn>).mock.calls;
     const blockEntries = reviewCalls.filter(
       ([eventName]: string[]) => eventName === "permission_request.blocked",
     );
@@ -301,14 +300,13 @@ describe("external_directory policy state — deny", () => {
   });
 
   it("writes review-log entry with resolution policy_denied", async () => {
-    const { handler, session } = makeHandler({
+    const { handler, logger } = makeHandler({
       session: { checkPermission: makeExtDirCheck("deny") },
       tools: ALL_TOOLS,
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     await handler.handleToolCall(event, makeCtx());
-    const reviewCalls = (session.logger.review as ReturnType<typeof vi.fn>).mock
-      .calls;
+    const reviewCalls = (logger.review as ReturnType<typeof vi.fn>).mock.calls;
     const blockEntries = reviewCalls.filter(
       ([eventName]: string[]) => eventName === "permission_request.blocked",
     );
@@ -458,7 +456,7 @@ describe("external_directory policy state — ask", () => {
   });
 
   it("writes review-log entry with confirmation_unavailable when no UI", async () => {
-    const { handler, session } = makeHandler({
+    const { handler, logger } = makeHandler({
       session: { checkPermission: makeExtDirCheck("ask") },
       prompter: {
         canConfirm: vi.fn().mockReturnValue(false),
@@ -468,8 +466,7 @@ describe("external_directory policy state — ask", () => {
     });
     const event = makeToolCallEvent("read", { input: { path: EXTERNAL_PATH } });
     await handler.handleToolCall(event, makeCtx({ hasUI: false }));
-    const reviewCalls = (session.logger.review as ReturnType<typeof vi.fn>).mock
-      .calls;
+    const reviewCalls = (logger.review as ReturnType<typeof vi.fn>).mock.calls;
     const blockEntries = reviewCalls.filter(
       ([eventName]: string[]) => eventName === "permission_request.blocked",
     );

package/test/handlers/lifecycle.test.ts

@@ -5,6 +5,7 @@ import type { ServiceLifecycle } from "#src/service-lifecycle";
 
 import { makeCtx } from "#test/helpers/handler-fixtures";
 import {
+  makeLogger,
   makeRealResolver,
   makeRealSession,
 } from "#test/helpers/session-fixtures";
@@ -19,14 +20,8 @@ vi.mock("../../src/status", () => ({
 // ── helpers ────────────────────────────────────────────────────────────────
 
 function makeSetup(opts?: { configIssues?: string[] }) {
-  const {
-    session,
-    permissionManager,
-    sessionRules,
-    logger,
-    forwarding,
-    configStore,
-  } = makeRealSession();
+  const { session, permissionManager, sessionRules, forwarding, configStore } =
+    makeRealSession();
   const { resolver } = makeRealResolver(permissionManager, sessionRules);
   if (opts?.configIssues) {
     vi.mocked(permissionManager.getConfigIssues).mockReturnValue(
@@ -37,10 +32,14 @@ function makeSetup(opts?: { configIssues?: string[] }) {
     activate: vi.fn<ServiceLifecycle["activate"]>(),
     teardown: vi.fn<ServiceLifecycle["teardown"]>(),
   };
+  // Use a session-independent logger so assertions verify direct injection,
+  // not reach-through to session.logger.
+  const logger = makeLogger();
   const handler = new SessionLifecycleHandler(
     session,
     resolver,
     serviceLifecycle,
+    logger,
   );
   return {
     handler,

package/test/helpers/handler-fixtures.ts

@@ -25,7 +25,6 @@ import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
 import type { Rule } from "#src/rule";
-import type { SessionLogger } from "#src/session-logger";
 import { SessionRules } from "#src/session-rules";
 import type { ToolRegistry } from "#src/tool-registry";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
@@ -49,8 +48,6 @@ import {
  */
 export type MockGateHandlerSession = ToolCallGateInputs &
   SkillInputGateInputs & {
-    /** Logger shape expected by GateDecisionReporter. */
-    logger: SessionLogger;
     /** 4-arg form so surface-check mocks can receive optional rules. */
     checkPermission(
       surface: string,
@@ -296,6 +293,7 @@ export function makeHandler(overrides?: {
     handler,
     events,
     session,
+    logger,
     toolRegistry,
     prompter,
     recorder,

package/test/helpers/session-fixtures.ts

@@ -150,7 +150,6 @@ export function makeRealSession(overrides?: {
   const gateway = overrides?.gateway ?? makeGateway();
   const session = new PermissionSession(
     paths,
-    logger,
     forwarding,
     permissionManager,
     sessionRules,

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([]);
     });
   });
@@ -388,4 +373,35 @@ describe("PermissionSession", () => {
       expect(session.getRuntimeContext()).toBeNull();
     });
   });
+
+  describe("notify", () => {
+    it("forwards the message to ctx.ui.notify with 'warning' severity after activation", () => {
+      const { session } = createSession();
+      const ctx = makeCtx();
+      session.activate(ctx);
+
+      session.notify("something went wrong");
+
+      expect(ctx.ui.notify).toHaveBeenCalledOnce();
+      expect(ctx.ui.notify).toHaveBeenCalledWith(
+        "something went wrong",
+        "warning",
+      );
+    });
+
+    it("is a no-op and does not throw before activation", () => {
+      const { session } = createSession();
+
+      expect(() => session.notify("msg")).not.toThrow();
+    });
+
+    it("is a no-op and does not throw after deactivation", () => {
+      const { session } = createSession();
+      const ctx = makeCtx();
+      session.activate(ctx);
+      session.deactivate();
+
+      expect(() => session.notify("msg")).not.toThrow();
+    });
+  });
 });

package/test/session-logger.test.ts

@@ -8,7 +8,7 @@ import {
   type PermissionSystemExtensionConfig,
 } from "#src/extension-config";
 import type { SessionLoggerDeps } from "#src/session-logger";
-import { createSessionLogger } from "#src/session-logger";
+import { PermissionSessionLogger } from "#src/session-logger";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 
@@ -42,9 +42,9 @@ function makeBlockedLogsDir(): string {
   return join(barrier, "logs");
 }
 
-// ── createSessionLogger ────────────────────────────────────────────────────
+// ── PermissionSessionLogger ────────────────────────────────────────────────────
 
-describe("createSessionLogger", () => {
+describe("PermissionSessionLogger", () => {
   // ── debug ────────────────────────────────────────────────────────────────
 
   describe("debug", () => {
@@ -52,7 +52,7 @@ describe("createSessionLogger", () => {
       const deps = makeDeps({
         getConfig: () => ({ ...DEFAULT_EXTENSION_CONFIG, debugLog: true }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.debug("test.event", { key: "value" });
 
@@ -63,7 +63,7 @@ describe("createSessionLogger", () => {
     it("does not write to the debug log when debugLog is false", () => {
       // DEFAULT_EXTENSION_CONFIG.debugLog === false
       const deps = makeDeps();
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.debug("test.event");
 
@@ -76,7 +76,7 @@ describe("createSessionLogger", () => {
       const deps = makeDeps({
         getConfig: () => ({ ...DEFAULT_EXTENSION_CONFIG, debugLog }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
       debugLog = false;
 
       logger.debug("test.event");
@@ -91,7 +91,7 @@ describe("createSessionLogger", () => {
     it("writes a JSONL line to the review log file when permissionReviewLog is true", () => {
       // DEFAULT_EXTENSION_CONFIG.permissionReviewLog === true
       const deps = makeDeps();
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.review("permission.granted", { agentName: "coder" });
 
@@ -106,7 +106,7 @@ describe("createSessionLogger", () => {
           permissionReviewLog: false,
         }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.review("permission.granted");
 
@@ -123,7 +123,7 @@ describe("createSessionLogger", () => {
         globalLogsDir: makeBlockedLogsDir(),
         getConfig: () => ({ ...DEFAULT_EXTENSION_CONFIG, debugLog: true }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.debug("test.event");
 
@@ -138,7 +138,7 @@ describe("createSessionLogger", () => {
         globalLogsDir: makeBlockedLogsDir(),
         getConfig: () => ({ ...DEFAULT_EXTENSION_CONFIG, debugLog: true }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.debug("event.one");
       logger.debug("event.two");
@@ -155,7 +155,7 @@ describe("createSessionLogger", () => {
           permissionReviewLog: true,
         }),
       });
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.debug("event.one"); // emits warning
       logger.review("event.two"); // same error message → suppressed
@@ -169,7 +169,7 @@ describe("createSessionLogger", () => {
   describe("warn", () => {
     it("calls notify with the message directly", () => {
       const deps = makeDeps();
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.warn("Something went wrong");
 
@@ -178,7 +178,7 @@ describe("createSessionLogger", () => {
 
     it("calls notify for every warn — not deduplicated", () => {
       const deps = makeDeps();
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       logger.warn("same message");
       logger.warn("same message");
@@ -192,7 +192,7 @@ describe("createSessionLogger", () => {
         getConfig: () => ({ ...DEFAULT_EXTENSION_CONFIG }),
         notify: () => {},
       };
-      const logger = createSessionLogger(deps);
+      const logger = new PermissionSessionLogger(deps);
 
       expect(() => logger.warn("test")).not.toThrow();
     });