@gotgenes/pi-permission-system 10.5.1 → 10.5.2

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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)
 
 

package/package.json

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

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/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();
+  }
+});

package/test/handlers/external-directory-session-dedup.test.ts

@@ -300,3 +300,99 @@ describe("external-directory session dedup", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Moved from permission-system.test.ts catch-all (#342)
+// ---------------------------------------------------------------------------
+
+describe("session shutdown clears external-directory approvals", () => {
+  it("re-prompts for the same path after session shutdown", async () => {
+    // Build a fully wired handler inline so we can access session directly.
+    const { session, permissionManager, sessionRules, logger } =
+      makeRealSession();
+    const { resolver } = makeRealResolver(permissionManager, sessionRules);
+
+    // external_directory=ask; session-covered paths return allow/session.
+    vi.mocked(permissionManager.checkPermission).mockImplementation(
+      (surface, input, _agentName, rules): PermissionCheckResult => {
+        if (surface === "external_directory") {
+          const record = (input ?? {}) as Record<string, unknown>;
+          const pathValue =
+            typeof record.path === "string" ? record.path : null;
+          if (pathValue && rules && rules.length > 0) {
+            const match = rules.findLast(
+              (r) =>
+                r.surface === "external_directory" &&
+                wildcardMatch(r.pattern, pathValue),
+            );
+            if (match) {
+              return {
+                state: "allow",
+                toolName: surface,
+                source: "session",
+                origin: "session",
+                matchedPattern: match.pattern,
+              };
+            }
+          }
+          return {
+            state: "ask",
+            toolName: surface,
+            source: "special",
+            origin: "global",
+          };
+        }
+        return {
+          state: "allow",
+          toolName: surface,
+          source: "tool",
+          origin: "builtin",
+        };
+      },
+    );
+
+    const events = makeEvents();
+    const reporter = new GateDecisionReporter(logger, events);
+    const prompter: GatePrompter = {
+      canConfirm: vi.fn().mockReturnValue(true),
+      // Simulate "Yes, for this session" on first call, "Yes" on subsequent.
+      prompt: vi
+        .fn<GatePrompter["prompt"]>()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    };
+    const runner = new GateRunner(resolver, sessionRules, prompter, reporter);
+    const handler = new PermissionGateHandler(
+      session,
+      makeToolRegistry({
+        getAll: vi.fn().mockReturnValue([{ name: "read" }]),
+      }),
+      new ToolCallGatePipeline(resolver, session),
+      new SkillInputGatePipeline(resolver),
+      runner,
+    );
+
+    const externalPath = "/tmp/sibling/foo.ts";
+    const ctx = makeCtx();
+    const event = {
+      type: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "read",
+      input: { path: externalPath },
+    };
+
+    // First access: prompt fires and records session approval.
+    await handler.handleToolCall(event, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(1);
+
+    // Second access: covered by session approval — no re-prompt.
+    await handler.handleToolCall({ ...event, toolCallId: "tc-2" }, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(1);
+
+    // Shutdown clears session approvals.
+    session.shutdown();
+
+    // Third access: session rules cleared — must re-prompt.
+    await handler.handleToolCall({ ...event, toolCallId: "tc-3" }, ctx);
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(2);
+  });
+});

package/test/handlers/gates/bash-path.test.ts

@@ -216,3 +216,60 @@ describe("describeBashPathGate", () => {
     expect(desc.decision.value).toBe(".env");
   });
 });
+
+// Home-relative path characterization (#350) ──────────────────────────────
+//
+// The parser extracts ~/... tokens from bash commands; the resolver receives
+// the raw token and normalizeInput handles expansion. These tests verify the
+// gate correctly dispatches ~/... tokens through the deny/ask path.
+
+describe("describeBashPathGate — home-relative paths", () => {
+  it("extracts ~/... token and builds descriptor on deny", async () => {
+    // node:os is mocked: homedir() returns "/mock/home".
+    // cat ~/.ssh/config → token "~/.ssh/config" extracted.
+    const resolver = makePathDispatchResolver(
+      {
+        "~/.ssh/config": makeCheckResult({
+          state: "deny",
+          matchedPattern: "~/.ssh/*",
+        }),
+      },
+      makeCheckResult({ state: "allow" }),
+    );
+    const result = (await describeGate(
+      makeTcc({ input: { command: "cat ~/.ssh/config" } }),
+      resolver,
+    )) as GateDescriptor;
+
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(result.preCheck?.state).toBe("deny");
+    expect(result.denialContext).toMatchObject({
+      kind: "bash_path",
+      command: "cat ~/.ssh/config",
+      pathValue: "~/.ssh/config",
+    });
+  });
+
+  it("extracts $HOME/... token and builds descriptor on deny", async () => {
+    const resolver = makePathDispatchResolver(
+      {
+        "$HOME/.ssh/config": makeCheckResult({
+          state: "deny",
+          matchedPattern: "$HOME/.ssh/*",
+        }),
+      },
+      makeCheckResult({ state: "allow" }),
+    );
+    const result = (await describeGate(
+      makeTcc({ input: { command: "cat $HOME/.ssh/config" } }),
+      resolver,
+    )) as GateDescriptor;
+
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(result.preCheck?.state).toBe("deny");
+    expect(result.denialContext).toMatchObject({
+      kind: "bash_path",
+      pathValue: "$HOME/.ssh/config",
+    });
+  });
+});

package/test/handlers/gates/path.test.ts

@@ -148,3 +148,61 @@ describe("describePathGate", () => {
     );
   });
 });
+
+// Home-relative path characterization (#350) ──────────────────────────────
+//
+// The gate passes the raw path to the resolver; home expansion is handled
+// downstream by normalizeInput. These tests lock in that the gate works
+// correctly when the tool input contains a ~/... or $HOME/... path.
+
+describe("describePathGate — home-relative paths", () => {
+  it("passes raw ~/... path to resolver and builds descriptor on deny", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "deny", matchedPattern: "~/.ssh/*" }),
+    );
+    const result = describePathGate(
+      makeTcc({ input: { path: "~/.ssh/config" } }),
+      resolver,
+    ) as GateDescriptor;
+
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(result.preCheck?.state).toBe("deny");
+    // Raw path preserved in denial context for display.
+    expect(result.denialContext).toMatchObject({
+      kind: "path",
+      toolName: "read",
+      pathValue: "~/.ssh/config",
+    });
+    expect(resolver.resolve).toHaveBeenCalledWith(
+      "path",
+      { path: "~/.ssh/config" },
+      undefined,
+    );
+  });
+
+  it("passes raw $HOME/... path to resolver and builds descriptor on deny", () => {
+    const resolver = makeResolver(
+      makeCheckResult({ state: "deny", matchedPattern: "$HOME/.ssh/*" }),
+    );
+    const result = describePathGate(
+      makeTcc({ input: { path: "$HOME/.ssh/config" } }),
+      resolver,
+    ) as GateDescriptor;
+
+    expect(isGateDescriptor(result)).toBe(true);
+    expect(result.preCheck?.state).toBe("deny");
+    expect(result.denialContext).toMatchObject({
+      kind: "path",
+      pathValue: "$HOME/.ssh/config",
+    });
+  });
+
+  it("returns null when home-relative path resolves to allow", () => {
+    const resolver = makeResolver(makeCheckResult({ state: "allow" }));
+    const result = describePathGate(
+      makeTcc({ input: { path: "~/.ssh/config" } }),
+      resolver,
+    );
+    expect(result).toBeNull();
+  });
+});

package/test/handlers/tool-call.test.ts

@@ -290,3 +290,106 @@ describe("handleToolCall — bash command chain gate", () => {
     expect(result).toEqual({});
   });
 });
+
+// ---------------------------------------------------------------------------
+// Moved from permission-system.test.ts catch-all (#342)
+// ---------------------------------------------------------------------------
+
+describe("handleToolCall — bash external-directory policy states", () => {
+  it("allows bash command with only internal paths when external_directory is denied", async () => {
+    const { handler } = makeHandler({ tools: ["bash"] });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "cat src/index.ts" },
+    });
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toEqual({});
+  });
+
+  it("blocks bash command with external path when external_directory is ask and no UI", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: makeSurfaceCheck({
+          external_directory: { state: "ask", source: "special" },
+        }),
+      },
+      tools: ["bash"],
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(false),
+        prompt: vi.fn().mockResolvedValue({ approved: false, state: "denied" }),
+      },
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "cat /etc/hosts" },
+    });
+    const result = await handler.handleToolCall(
+      event,
+      makeCtx({ hasUI: false }),
+    );
+    expect(result).toMatchObject({ block: true });
+    expect(String((result as { reason?: unknown }).reason)).toMatch(
+      /no interactive UI/i,
+    );
+  });
+
+  it("allows bash command with external path when external_directory is allow", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: makeSurfaceCheck({
+          external_directory: { state: "allow", source: "special" },
+        }),
+      },
+      tools: ["bash"],
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "cat /etc/hosts" },
+    });
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toEqual({});
+  });
+
+  it("applies bash pattern deny after external_directory allow", async () => {
+    const { handler } = makeHandler({
+      session: {
+        checkPermission: makeSurfaceCheck(
+          {
+            external_directory: { state: "allow", source: "special" },
+            bash: { state: "deny", source: "bash" },
+          },
+          { state: "allow" },
+        ),
+      },
+      tools: ["bash"],
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "cat /etc/hosts" },
+    });
+    const result = await handler.handleToolCall(event, makeCtx());
+    expect(result).toMatchObject({ block: true });
+  });
+});
+
+describe("handleToolCall — generic ask prompt content", () => {
+  it("ask prompt includes serialized tool input for informed approval", async () => {
+    const { handler, prompter } = makeHandler({
+      session: {
+        checkPermission: makeSurfaceCheck({
+          weather_lookup: { state: "ask" },
+        }),
+      },
+      tools: ["weather_lookup"],
+      prompter: {
+        canConfirm: vi.fn().mockReturnValue(true),
+        prompt: vi.fn().mockResolvedValue({ approved: false, state: "denied" }),
+      },
+    });
+    const event = makeToolCallEvent("weather_lookup", {
+      input: { city: "Chicago", units: "metric" },
+    });
+    await handler.handleToolCall(event, makeCtx());
+    expect(vi.mocked(prompter.prompt)).toHaveBeenCalledTimes(1);
+    const promptDetails = vi.mocked(prompter.prompt).mock.calls[0][0];
+    expect(promptDetails.message).toMatch(
+      /\{"city":"Chicago","units":"metric"\}/,
+    );
+  });
+});

package/test/helpers/manager-harness.ts

@@ -15,6 +15,11 @@ export type CreateManagerOptions = {
   mcpServerNames?: readonly string[];
 };
 
+export type CreateManagerWithProjectOptions = CreateManagerOptions & {
+  projectConfig?: ScopeConfig;
+  projectAgentFiles?: Record<string, string>;
+};
+
 export function createManager(
   config: ScopeConfig,
   agentFiles: Record<string, string> = {},
@@ -49,3 +54,59 @@ export function createManager(
     },
   };
 }
+
+export function createManagerWithProject(
+  config: ScopeConfig,
+  agentFiles: Record<string, string> = {},
+  options: CreateManagerWithProjectOptions = {},
+) {
+  const baseDir = mkdtempSync(
+    join(tmpdir(), "pi-permission-system-proj-test-"),
+  );
+  const globalConfigPath = join(baseDir, "pi-permissions.jsonc");
+  const agentsDir = join(baseDir, "agents");
+  const projectRoot = join(baseDir, "project");
+  const projectGlobalConfigPath = join(projectRoot, "pi-permissions.jsonc");
+  const projectAgentsDir = join(projectRoot, "agents");
+
+  mkdirSync(agentsDir, { recursive: true });
+  mkdirSync(projectAgentsDir, { recursive: true });
+
+  writeFileSync(
+    globalConfigPath,
+    `${JSON.stringify(config, null, 2)}\n`,
+    "utf8",
+  );
+  if (options.projectConfig) {
+    writeFileSync(
+      projectGlobalConfigPath,
+      `${JSON.stringify(options.projectConfig, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  for (const [name, content] of Object.entries(agentFiles)) {
+    writeFileSync(join(agentsDir, `${name}.md`), content, "utf8");
+  }
+
+  for (const [name, content] of Object.entries(
+    options.projectAgentFiles ?? {},
+  )) {
+    writeFileSync(join(projectAgentsDir, `${name}.md`), content, "utf8");
+  }
+
+  const manager = new PermissionManager({
+    globalConfigPath,
+    agentsDir,
+    projectGlobalConfigPath,
+    projectAgentsDir,
+    mcpServerNames: options.mcpServerNames,
+  });
+
+  return {
+    manager,
+    cleanup: (): void => {
+      rmSync(baseDir, { recursive: true, force: true });
+    },
+  };
+}