@gotgenes/pi-permission-system 10.5.0 → 10.5.2

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.5.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.5.1...pi-permission-system-v10.5.2) (2026-06-08)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** expand $HOME in normalizePathForComparison ([#350](https://github.com/gotgenes/pi-packages/issues/350)) ([1b92ed3](https://github.com/gotgenes/pi-packages/commit/1b92ed3d2364174d3287171c58ce8452239b3e8d))
+* **pi-permission-system:** home-expand path values before matching ([#350](https://github.com/gotgenes/pi-packages/issues/350)) ([48a7b37](https://github.com/gotgenes/pi-packages/commit/48a7b3783857b449442d30edefe04f8255e5f4f8))
+
+
+### Documentation
+
+* **pi-permission-system:** note path values are home-expanded for matching ([#350](https://github.com/gotgenes/pi-packages/issues/350)) ([e9c264d](https://github.com/gotgenes/pi-packages/commit/e9c264de85d327a0bfbcd84401a259cb509a5dfa))
+
+## [10.5.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.5.0...pi-permission-system-v10.5.1) (2026-06-07)
+
+
+### Documentation
+
+* correct SkillPermissionChecker comment after resolver rewire ([#341](https://github.com/gotgenes/pi-packages/issues/341)) ([1528382](https://github.com/gotgenes/pi-packages/commit/15283820a920fead92b348410828332b69f0a0d9))
+
 ## [10.5.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.4.0...pi-permission-system-v10.5.0) (2026-06-07)
 
 

package/package.json

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

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

@@ -2,11 +2,12 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentPrepSession } from "#src/agent-prep-session";
 import {
   createActiveToolsCacheKey,
   createBeforeAgentStartPromptStateKey,
 } from "#src/before-agent-start-cache";
+import type { PermissionResolver } from "#src/permission-resolver";
+import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
@@ -35,12 +36,14 @@ export function shouldExposeTool(
  * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
  *
  * Constructor deps:
- * - `session` — encapsulates all mutable session state
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getToolPermission`, `getPolicyCacheStamp`, skill check
  * - `toolRegistry` — Pi tool API subset (getAll + setActive)
  */
 export class AgentPrepHandler {
   constructor(
-    private readonly session: AgentPrepSession,
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
   ) {}
 
@@ -63,7 +66,7 @@ export class AgentPrepHandler {
       }
       if (
         shouldExposeTool(toolName, agentName, (t, a) =>
-          this.session.getToolPermission(t, a),
+          this.resolver.getToolPermission(t, a),
         )
       ) {
         allowedTools.push(toolName);
@@ -79,7 +82,9 @@ export class AgentPrepHandler {
     const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
       agentName,
       cwd: ctx.cwd,
-      permissionStamp: this.session.getPolicyCacheStamp(agentName ?? undefined),
+      permissionStamp: this.resolver.getPolicyCacheStamp(
+        agentName ?? undefined,
+      ),
       systemPrompt: event.systemPrompt,
       allowedToolNames: allowedTools,
     });
@@ -96,7 +101,7 @@ export class AgentPrepHandler {
     );
     const skillPromptResult = resolveSkillPromptEntries(
       toolPromptResult.prompt,
-      this.session,
+      this.resolver,
       agentName,
       ctx.cwd,
     );

package/src/handlers/lifecycle.ts

@@ -1,7 +1,8 @@
 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 { SessionLifecycleSession } from "#src/session-lifecycle-session";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/status";
 
 /** Minimal subset of SessionStartEvent used by this handler. */
@@ -18,14 +19,16 @@ interface ResourcesDiscoverPayload {
  * Handles session lifecycle events: start, reload, and shutdown.
  *
  * Constructor deps:
- * - `session` — encapsulates all mutable session state
+ * - `session` — encapsulates all mutable session state and lifecycle operations
+ * - `resolver` — owns permission-query surface: `getConfigIssues`
  * - `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
  */
 export class SessionLifecycleHandler {
   constructor(
-    private readonly session: SessionLifecycleSession,
+    private readonly session: PermissionSession,
+    private readonly resolver: PermissionResolver,
     private readonly serviceLifecycle: ServiceLifecycle,
   ) {}
 
@@ -38,7 +41,7 @@ export class SessionLifecycleHandler {
     this.session.logResolvedConfigPaths();
 
     const agentName = this.session.resolveAgentName(ctx);
-    const policyIssues = this.session.getConfigIssues(agentName ?? undefined);
+    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
     for (const issue of policyIssues) {
       this.session.logger.warn(issue);
     }

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

@@ -4,11 +4,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import { toRecord } from "#src/common";
-import type { GateHandlerSession } from "#src/gate-handler-session";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
 } from "#src/permission-prompts";
+import type { PermissionSession } from "#src/permission-session";
 import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
@@ -31,7 +31,7 @@ interface InputPayload {
  * Handles permission gate events: tool_call and input.
  *
  * Constructor deps:
- * - `session` — narrow two-method context role: bind per-event context, resolve agent name
+ * - `session` — state/lifecycle owner: bind per-event context, resolve agent name
  * - `toolRegistry` — Pi tool API subset (getAll + setActive)
  * - `pipeline` — owns tool-call gate-producer assembly and the run loop
  * - `skillInputPipeline` — owns skill-input gate assembly (pre-check, notify, run)
@@ -39,7 +39,7 @@ interface InputPayload {
  */
 export class PermissionGateHandler {
   constructor(
-    private readonly session: GateHandlerSession,
+    private readonly session: PermissionSession,
     private readonly toolRegistry: ToolRegistry,
     private readonly pipeline: ToolCallGatePipeline,
     private readonly skillInputPipeline: SkillInputGatePipeline,

package/src/index.ts

@@ -157,12 +157,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
-  const lifecycle = new SessionLifecycleHandler(session, serviceLifecycle);
-  const agentPrep = new AgentPrepHandler(session, toolRegistry);
   const resolver = new PermissionResolver(permissionManager, sessionRules);
 
+  const lifecycle = new SessionLifecycleHandler(
+    session,
+    resolver,
+    serviceLifecycle,
+  );
+  const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
+
   const reporter = new GateDecisionReporter(session.logger, pi.events);
-  const gateRunner = new GateRunner(resolver, session, gateway, reporter);
+  const gateRunner = new GateRunner(resolver, sessionRules, gateway, reporter);
   const toolCallGatePipeline = new ToolCallGatePipeline(
     resolver,
     session,

package/src/input-normalizer.ts

@@ -1,6 +1,7 @@
-import { toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./common";
+import { expandHomePath } from "./expand-home";
 import { createMcpPermissionTargets } from "./mcp-targets";
-import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "./path-utils";
+import { PATH_BEARING_TOOLS } from "./path-utils";
 
 /**
  * Construct a surface-appropriate input object from a raw value string.
@@ -66,13 +67,11 @@ export function normalizeInput(
   input: unknown,
   configuredMcpServerNames: readonly string[],
 ): NormalizedInput {
-  // --- Special surfaces (external_directory) ---
+  // --- Special surfaces (path, external_directory) ---
   if (SPECIAL_PERMISSION_KEYS.has(toolName)) {
-    const record = toRecord(input);
-    const pathValue = typeof record.path === "string" ? record.path : null;
     return {
       surface: toolName,
-      values: [pathValue ?? "*"],
+      values: [normalizePathSurfaceValue(input)],
       resultExtras: {},
     };
   }
@@ -116,10 +115,9 @@ export function normalizeInput(
 
   // --- Path-bearing tools (read, write, edit, grep, find, ls) ---
   if (PATH_BEARING_TOOLS.has(toolName)) {
-    const path = getPathBearingToolPath(toolName, input);
     return {
       surface: toolName,
-      values: [path ?? "*"],
+      values: [normalizePathSurfaceValue(input)],
       resultExtras: {},
     };
   }
@@ -131,3 +129,17 @@ export function normalizeInput(
     resultExtras: {},
   };
 }
+
+/**
+ * Extract and home-expand the `input.path` lookup value shared by every path
+ * surface (`path`, `external_directory`, and the path-bearing tools).
+ *
+ * Missing, empty, or whitespace-only paths collapse to the surface catch-all
+ * `"*"`; otherwise `~/…` and `$HOME/…` prefixes are expanded to the OS home
+ * directory so values match home-anchored patterns symmetrically with how
+ * `compileWildcardPattern` expands the patterns themselves (#350).
+ */
+function normalizePathSurfaceValue(input: unknown): string {
+  const path = getNonEmptyString(toRecord(input).path);
+  return path === null ? "*" : expandHomePath(path);
+}

package/src/path-utils.ts

@@ -1,4 +1,3 @@
-import { homedir } from "node:os";
 import { join, normalize, resolve, sep } from "node:path";
 
 import { getNonEmptyString, toRecord } from "./common";
@@ -15,15 +14,7 @@ export function normalizePathForComparison(
   }
 
   let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-
-  if (normalizedPath === "~") {
-    normalizedPath = homedir();
-  } else if (
-    normalizedPath.startsWith("~/") ||
-    normalizedPath.startsWith("~\\")
-  ) {
-    normalizedPath = join(homedir(), normalizedPath.slice(2));
-  }
+  normalizedPath = expandHomePath(normalizedPath);
 
   const absolutePath = resolve(cwd, normalizedPath);
   const normalizedAbsolutePath = normalize(absolutePath);

package/src/permission-resolver.ts

@@ -67,17 +67,14 @@ export class PermissionResolver implements ScopedPermissionResolver {
     );
   }
 
-  // fallow-ignore-next-line unused-class-member
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     return this.permissionManager.getToolPermission(toolName, agentName);
   }
 
-  // fallow-ignore-next-line unused-class-member
   getConfigIssues(agentName?: string): string[] {
     return this.permissionManager.getConfigIssues(agentName);
   }
 
-  // fallow-ignore-next-line unused-class-member
   getPolicyCacheStamp(agentName?: string): string {
     return this.permissionManager.getPolicyCacheStamp(agentName);
   }

package/src/permission-session.ts

@@ -4,18 +4,15 @@ import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
-import type { AgentPrepSession } from "./agent-prep-session";
+
 import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
-import type { GateHandlerSession } from "./gate-handler-session";
+import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { PromptingGatewayLifecycle } from "./prompting-gateway";
-import type { Rule } from "./rule";
-import type { SessionApproval } from "./session-approval";
-import type { SessionApprovalRecorder } from "./session-approval-recorder";
-import type { SessionLifecycleSession } from "./session-lifecycle-session";
+
 import type { SessionLogger } from "./session-logger";
 import type { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
@@ -23,7 +20,6 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
-import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -40,13 +36,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
  * - `SessionConfigStore` — owns extension config; provides refresh, log, read
  * - `PromptingGatewayLifecycle` — prompting lifecycle forwarded via activate/deactivate
  */
-export class PermissionSession
-  implements
-    SessionApprovalRecorder,
-    GateHandlerSession,
-    AgentPrepSession,
-    SessionLifecycleSession
-{
+export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
@@ -84,44 +74,6 @@ export class PermissionSession
     return this.context;
   }
 
-  // ── Permission checking (delegates to PermissionManager) ───────────────
-
-  checkPermission(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-    sessionRules?: Rule[],
-  ): PermissionCheckResult {
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
-      sessionRules,
-    );
-  }
-
-  getToolPermission(toolName: string, agentName?: string): PermissionState {
-    return this.permissionManager.getToolPermission(toolName, agentName);
-  }
-
-  getConfigIssues(agentName?: string): string[] {
-    return this.permissionManager.getConfigIssues(agentName);
-  }
-
-  getPolicyCacheStamp(agentName?: string): string {
-    return this.permissionManager.getPolicyCacheStamp(agentName);
-  }
-
-  // ── Session rules (delegates to SessionRules) ──────────────────────────
-
-  getSessionRuleset(): Rule[] {
-    return this.sessionRules.getRuleset();
-  }
-
-  recordSessionApproval(approval: SessionApproval): void {
-    this.sessionRules.record(approval);
-  }
-
   // ── Session lifecycle ────────────────────────────────────────────────────
 
   /**
@@ -212,6 +164,10 @@ export class PermissionSession
     return this.knownAgentName;
   }
 
+  // Read by config-modal (`controller.session.lastKnownActiveAgentName`).
+  // fallow cannot trace the getter through the command's object-literal
+  // wiring, so it reports a false positive here.
+  // fallow-ignore-next-line unused-class-member
   get lastKnownActiveAgentName(): string | null {
     return this.knownAgentName;
   }

package/src/session-rules.ts

@@ -2,6 +2,7 @@ import { dirname, sep } from "node:path";
 
 import type { Ruleset } from "./rule";
 import type { SessionApproval } from "./session-approval";
+import type { SessionApprovalRecorder } from "./session-approval-recorder";
 
 /**
  * Ephemeral in-memory store of session-scoped permission approvals.
@@ -11,7 +12,7 @@ import type { SessionApproval } from "./session-approval";
  *
  * Cleared on session_shutdown — never persisted to disk.
  */
-export class SessionRules {
+export class SessionRules implements SessionApprovalRecorder {
   private rules: Ruleset = [];
 
   /** Record a wildcard pattern as approved for the given surface. */
@@ -36,7 +37,7 @@ export class SessionRules {
    * The loop lives here so callers never need to know whether an approval
    * carries one pattern or many — they just tell the store to record it.
    */
-  record(approval: SessionApproval): void {
+  recordSessionApproval(approval: SessionApproval): void {
     for (const pattern of approval.patterns) {
       this.approve(approval.surface, pattern);
     }

package/src/skill-prompt-sanitizer.ts

@@ -8,7 +8,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
  * Narrow interface for the permission checker used by skill prompt resolution.
- * Both `PermissionManager` and `PermissionSession` satisfy this structurally.
+ * Both `PermissionManager` and `PermissionResolver` satisfy this structurally.
  */
 export interface SkillPermissionChecker {
   checkPermission(

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

@@ -0,0 +1,89 @@
+import { writeFileSync } from "node:fs";
+import { expect, test } from "vitest";
+import {
+  createActiveToolsCacheKey,
+  createBeforeAgentStartPromptStateKey,
+  shouldApplyCachedAgentStartState,
+} 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" },
+  });
+
+  try {
+    const baselineStamp = manager.getPolicyCacheStamp();
+    const baselineKey = createBeforeAgentStartPromptStateKey({
+      agentName: null,
+      cwd: "C:/workspace/project",
+      permissionStamp: baselineStamp,
+      systemPrompt: "Available tools:\n- read\n- write",
+      allowedToolNames: ["read"],
+    });
+
+    expect(shouldApplyCachedAgentStartState(baselineKey, baselineKey)).toBe(
+      false,
+    );
+    expect(manager.checkPermission("write", {}, undefined).state).toBe("deny");
+
+    const updatedConfig = `${JSON.stringify(
+      { permission: { "*": "allow", write: "allow" } },
+      null,
+      2,
+    )}\n`;
+
+    let updatedStamp = baselineStamp;
+    for (
+      let attempt = 0;
+      attempt < 10 && updatedStamp === baselineStamp;
+      attempt += 1
+    ) {
+      const waitUntil = Date.now() + 2;
+      while (Date.now() < waitUntil) {
+        // Wait for the filesystem timestamp granularity to advance.
+      }
+
+      writeFileSync(globalConfigPath, updatedConfig, "utf8");
+      updatedStamp = manager.getPolicyCacheStamp();
+    }
+
+    expect(updatedStamp).not.toBe(baselineStamp);
+
+    const invalidatedKey = createBeforeAgentStartPromptStateKey({
+      agentName: null,
+      cwd: "C:/workspace/project",
+      permissionStamp: updatedStamp,
+      systemPrompt: "Available tools:\n- read\n- write",
+      allowedToolNames: ["read", "write"],
+    });
+
+    expect(shouldApplyCachedAgentStartState(baselineKey, invalidatedKey)).toBe(
+      true,
+    );
+    expect(manager.checkPermission("write", {}, undefined).state).toBe("allow");
+  } finally {
+    cleanup();
+  }
+});