@gotgenes/pi-permission-system 16.1.0 → 16.2.0

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).
 
+## [16.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.1.0...pi-permission-system-v16.2.0) (2026-06-26)
+
+
+### Features
+
+* **pi-permission-system:** add ScopedPermissionManager.check(intent) ([#478](https://github.com/gotgenes/pi-packages/issues/478)) ([7cb600a](https://github.com/gotgenes/pi-packages/commit/7cb600a11efd4bc60bd31c70d85550c7e1b28058))
+* **pi-permission-system:** narrow ScopedPermissionResolver to resolve(intent) ([#478](https://github.com/gotgenes/pi-packages/issues/478)) ([908176f](https://github.com/gotgenes/pi-packages/commit/908176f8341e05d9181d5cf22ede10a6d5a470d0))
+
+
+### Documentation
+
+* **pi-permission-system:** record resolve(intent) narrowing ([#478](https://github.com/gotgenes/pi-packages/issues/478)) ([fb8f986](https://github.com/gotgenes/pi-packages/commit/fb8f986e15e5db20d84030d0f77b2aa4aad39aab))
+
 ## [16.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.0.2...pi-permission-system-v16.1.0) (2026-06-26)
 
 

package/package.json

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

package/src/access-intent/access-intent.ts

@@ -0,0 +1,57 @@
+import type { AccessPath } from "#src/access-intent/access-path";
+
+/**
+ * Raw tool input the manager must normalize (path / bash / MCP / extension tools).
+ *
+ * The `surface` is the tool name fed to `normalizeInput` (e.g. `"read"`, `"bash"`,
+ * an MCP server name).
+ */
+export interface ToolAccessIntent {
+  kind: "tool";
+  /** Tool name fed to input normalization. */
+  surface: string;
+  input: unknown;
+  agentName?: string;
+}
+
+/**
+ * Precomputed equivalent policy values for a path-shaped surface.
+ *
+ * Used by the bash-path gate (`path` surface), whose cd-resolved lexical
+ * `string[]` carry no canonical-boundary notion.
+ */
+export interface PathValuesAccessIntent {
+  kind: "path-values";
+  /** `"path"` or `"external_directory"`. */
+  surface: string;
+  values: readonly string[];
+  agentName?: string;
+}
+
+/**
+ * An `AccessPath` value object for a path-shaped surface.
+ *
+ * Used by the external-directory gates; lets `AccessPath` flow into the
+ * resolver as a first-class variant so the resolver — not the gate — asks it
+ * for `matchValues()` (Tell-Don't-Ask).
+ */
+export interface AccessPathAccessIntent {
+  kind: "access-path";
+  surface: string;
+  path: AccessPath;
+  agentName?: string;
+}
+
+/** What a gate emits — the full three-variant union. */
+export type AccessIntent =
+  | ToolAccessIntent
+  | PathValuesAccessIntent
+  | AccessPathAccessIntent;
+
+/**
+ * What the manager consumes — the `access-path` variant has already been
+ * unwrapped to `path-values` by the resolver via `path.matchValues()`.
+ *
+ * The manager stays string-based and never imports `AccessPath`.
+ */
+export type ResolvedAccessIntent = ToolAccessIntent | PathValuesAccessIntent;

package/src/handlers/gates/bash-command.ts

@@ -38,7 +38,12 @@ export function resolveBashCommandCheck(
 ): PermissionCheckResult {
   if (commands.length === 0) {
     if (isTriviallyEmptyCommand(command)) {
-      return resolver.resolve("bash", { command }, agentName);
+      return resolver.resolve({
+        kind: "tool",
+        surface: "bash",
+        input: { command },
+        agentName,
+      });
     }
     return {
       state: "ask",
@@ -51,12 +56,22 @@ export function resolveBashCommandCheck(
   }
 
   const results = commands.map((cmd) => {
-    const result = resolver.resolve("bash", { command: cmd.text }, agentName);
+    const result = resolver.resolve({
+      kind: "tool",
+      surface: "bash",
+      input: { command: cmd.text },
+      agentName,
+    });
     return cmd.context ? { ...result, commandContext: cmd.context } : result;
   });
   return (
     pickMostRestrictive(results) ??
-    resolver.resolve("bash", { command }, agentName)
+    resolver.resolve({
+      kind: "tool",
+      surface: "bash",
+      input: { command },
+      agentName,
+    })
   );
 }
 

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

@@ -51,10 +51,12 @@ export function describeBashPathGate(
   let allSessionCovered = true;
 
   for (const { token, policyValues } of candidates) {
-    const check = resolver.resolvePathPolicy(
-      policyValues,
-      tcc.agentName ?? undefined,
-    );
+    const check = resolver.resolve({
+      kind: "path-values",
+      surface: "path",
+      values: policyValues,
+      agentName: tcc.agentName ?? undefined,
+    });
 
     // No explicit path rule matched — only the universal default fired.
     // Treat this token as unrestricted to preserve backward compatibility

package/src/handlers/gates/external-directory-policy.ts

@@ -19,10 +19,10 @@ export interface UncoveredExternalPaths {
 /**
  * Resolve one external path's policy on the `external_directory` surface.
  *
- * Matches against the typed and symlink-resolved aliases
- * ({@link AccessPath.matchValues}) so a config pattern on either form applies
- * (#418). This is the single source for the alias-derivation plus
- * surface-tagged resolve that the two external-directory gates previously
+ * Emits an `access-path` {@link AccessIntent}; the resolver unwraps it via
+ * {@link AccessPath.matchValues} so a config pattern on either the typed or
+ * symlink-resolved alias applies (#418). This is the single source for the
+ * external-directory resolve that the two external-directory gates previously
  * duplicated.
  */
 export function resolveExternalDirectoryPolicy(
@@ -30,11 +30,12 @@ export function resolveExternalDirectoryPolicy(
   resolver: ScopedPermissionResolver,
   agentName: string | undefined,
 ): PermissionCheckResult {
-  return resolver.resolvePathPolicy(
-    path.matchValues(),
+  return resolver.resolve({
+    kind: "access-path",
+    surface: "external_directory",
+    path,
     agentName,
-    "external_directory",
-  );
+  });
 }
 
 /**

package/src/handlers/gates/path.ts

@@ -22,11 +22,12 @@ export function describePathGate(
   const filePath = getToolInputPath(tcc.toolName, tcc.input, extractors);
   if (!filePath) return null;
 
-  const check = resolver.resolve(
-    "path",
-    { path: filePath },
-    tcc.agentName ?? undefined,
-  );
+  const check = resolver.resolve({
+    kind: "tool",
+    surface: "path",
+    input: { path: filePath },
+    agentName: tcc.agentName ?? undefined,
+  });
 
   if (check.state === "allow") return null;
 

package/src/handlers/gates/runner.ts

@@ -77,11 +77,12 @@ export class GateRunner {
         origin: "builtin",
       };
     } else {
-      check = this.resolver.resolve(
-        descriptor.surface,
-        descriptor.input,
-        agentName ?? undefined,
-      );
+      check = this.resolver.resolve({
+        kind: "tool",
+        surface: descriptor.surface,
+        input: descriptor.input,
+        agentName: agentName ?? undefined,
+      });
     }
 
     // 2. Session-hit fast path

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -102,11 +102,12 @@ export class ToolCallGatePipeline {
                 tcc.agentName ?? undefined,
                 this.resolver,
               )
-            : this.resolver.resolve(
-                tcc.toolName,
-                tcc.input,
-                tcc.agentName ?? undefined,
-              );
+            : this.resolver.resolve({
+                kind: "tool",
+                surface: tcc.toolName,
+                input: tcc.input,
+                agentName: tcc.agentName ?? undefined,
+              });
         const toolDescriptor = describeToolGate(tcc, toolCheck, formatter);
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;

package/src/permission-event-rpc.ts

@@ -26,7 +26,7 @@ import {
   PERMISSIONS_RPC_CHECK_CHANNEL,
   PERMISSIONS_RPC_PROMPT_CHANNEL,
 } from "./permission-events";
-import type { PermissionManager } from "./permission-manager";
+import type { ScopedPermissionManager } from "./permission-manager";
 import { buildRpcUiPrompt } from "./permission-ui-prompt";
 import type { ReviewLogger } from "./session-logger";
 import type { SessionRules } from "./session-rules";
@@ -34,7 +34,7 @@ import type { SessionRules } from "./session-rules";
 /** Dependencies injected into the RPC handler registry. */
 export interface PermissionRpcDeps {
   /** The shared PermissionManager instance. */
-  permissionManager: Pick<PermissionManager, "checkPermission">;
+  permissionManager: Pick<ScopedPermissionManager, "check">;
   /** The shared SessionRules instance. */
   sessionRules: Pick<SessionRules, "getRuleset">;
   /**
@@ -109,10 +109,8 @@ function handleCheckRpc(
 
     const input = buildInputForSurface(surface, value);
     const sessionRules = deps.sessionRules.getRuleset();
-    const result = deps.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName ?? undefined,
+    const result = deps.permissionManager.check(
+      { kind: "tool", surface, input, agentName: agentName ?? undefined },
       sessionRules,
     );
 

package/src/permission-manager.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import type { ResolvedAccessIntent } from "./access-intent/access-intent";
 import { isPermissionState } from "./common";
 import {
   getGlobalConfigPath,
@@ -50,7 +51,7 @@ type FileCacheEntry<TValue> = {
 type ResolvedPermissions = {
   /**
    * Fully composed ruleset: synthesized defaults → baseline → config.
-   * Session rules are appended at call-time inside checkPermission().
+   * Session rules are appended at call-time inside check().
    */
   composedRules: Ruleset;
 };
@@ -62,25 +63,16 @@ type ResolvedPermissions = {
  */
 export interface ScopedPermissionManager {
   configureForCwd(cwd: string | undefined | null): void;
-  checkPermission(
-    toolName: string,
-    input: unknown,
-    agentName?: string,
-    sessionRules?: Ruleset,
-  ): PermissionCheckResult;
   /**
-   * Evaluate a path-shaped surface (`path` or `external_directory`) against a
-   * caller-supplied set of equivalent policy values (e.g. bash tokens already
-   * resolved against a preceding literal `cd`, or a path's typed and
-   * symlink-resolved aliases). The values are trusted because they are computed
-   * internally, never read from a field on raw tool input. `surface` defaults
-   * to `path`.
+   * Unified resolution entry point (Phase 6 Step 6, #478).
+   *
+   * Replaces the former `checkPermission` + `checkPathPolicy` method pair with
+   * a single dispatched call, making it structurally impossible to stub one
+   * method and forget the other (the #393 false-green class).
    */
-  checkPathPolicy(
-    values: readonly string[],
-    agentName?: string,
+  check(
+    intent: ResolvedAccessIntent,
     sessionRules?: Ruleset,
-    surface?: string,
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
@@ -243,56 +235,48 @@ export class PermissionManager implements ScopedPermissionManager {
     return evaluate(normalizedToolName, "*", composedRules).action;
   }
 
-  checkPermission(
-    toolName: string,
-    input: unknown,
-    agentName?: string,
+  /**
+   * Unified resolution entry point — dispatches on intent kind.
+   *
+   * `"tool"` → normalizes raw input through `normalizeInput`.
+   * `"path-values"` → evaluates the precomputed values directly.
+   */
+  check(
+    intent: ResolvedAccessIntent,
     sessionRules?: Ruleset,
   ): PermissionCheckResult {
-    const { composedRules } = this.resolvePermissions(agentName);
-    const normalizedToolName = toolName.trim();
-
-    // Append session rules at the end (highest priority) so evaluate() handles
-    // them via last-match-wins — no separate per-branch pre-check needed.
+    const { composedRules } = this.resolvePermissions(intent.agentName);
     const fullRules: Ruleset = sessionRules?.length
       ? [...composedRules, ...sessionRules]
       : composedRules;
 
+    if (intent.kind === "path-values") {
+      const lookupValues =
+        intent.values.length > 0 ? [...intent.values] : ["*"];
+      return buildCheckResult(
+        intent.surface,
+        lookupValues,
+        {},
+        intent.surface,
+        intent.surface,
+        fullRules,
+      );
+    }
+
+    // kind === "tool"
+    const toolName = intent.surface.trim();
     const { surface, values, resultExtras } = normalizeInput(
-      normalizedToolName,
-      input,
+      toolName,
+      intent.input,
       this.loader.getConfiguredMcpServerNames(),
       this.currentCwd,
     );
-
     return buildCheckResult(
       surface,
       values,
       resultExtras,
-      normalizedToolName,
       toolName,
-      fullRules,
-    );
-  }
-
-  checkPathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    sessionRules?: Ruleset,
-    surface = "path",
-  ): PermissionCheckResult {
-    const { composedRules } = this.resolvePermissions(agentName);
-    const fullRules: Ruleset = sessionRules?.length
-      ? [...composedRules, ...sessionRules]
-      : composedRules;
-
-    const lookupValues = values.length > 0 ? [...values] : ["*"];
-    return buildCheckResult(
-      surface,
-      lookupValues,
-      {},
-      surface,
-      surface,
+      intent.surface,
       fullRules,
     );
   }
@@ -302,8 +286,8 @@ export class PermissionManager implements ScopedPermissionManager {
  * Evaluate a normalized surface/values triple and shape the result.
  *
  * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
- * aliases); every other surface keeps {@link evaluateFirst}. Shared by
- * `checkPermission` and `checkPathPolicy`.
+ * aliases); every other surface keeps {@link evaluateFirst}. Shared by the
+ * `"tool"` and `"path-values"` branches of {@link PermissionManager.check}.
  */
 function buildCheckResult(
   surface: string,
@@ -357,7 +341,7 @@ function derivePolicyLoaderOptions(
  * Map a matched rule + tool name to the correct PermissionCheckResult.source.
  *
  * Mirrors the source-derivation logic from the former per-branch
- * checkPermission() implementation:
+ * permission-check implementation:
  *
  * - session          → "session" (always, all surfaces)
  * - mcp + default    → "default"

package/src/permission-resolver.ts

@@ -1,34 +1,42 @@
+import type {
+  AccessIntent,
+  ResolvedAccessIntent,
+} from "./access-intent/access-intent";
 import type { ScopedPermissionManager } from "./permission-manager";
 import type { Rule } from "./rule";
 import type { SessionRules } from "./session-rules";
+import type { SkillPermissionChecker } from "./skill-prompt-sanitizer";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
- * Resolves the effective permission for a surface/input, applying the current
- * session rules internally.
+ * Answers an {@link AccessIntent} a gate emits, applying the current session
+ * rules internally.
  *
- * Collapses the `checkPermission` + `getSessionRuleset` relay that every gate
- * previously threaded by hand: the ruleset was only ever fetched to be passed
- * straight back into `checkPermission`, so the two are one operation.
+ * A single `resolve(intent)` entry point means adding a gate cannot widen the
+ * resolver surface, and a test fixture cannot stub one resolution method and
+ * forget another (the #393 false-green class) — #478.
  */
 export interface ScopedPermissionResolver {
-  resolve(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-  ): PermissionCheckResult;
-  /**
-   * Resolve a path-shaped surface against a caller-supplied set of equivalent
-   * policy values, applying the current session rules. Used by the bash path
-   * gate (`path`) and the external-directory gates (`external_directory`),
-   * which compute equivalent path aliases per token. `surface` defaults to
-   * `path`.
-   */
-  resolvePathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    surface?: string,
-  ): PermissionCheckResult;
+  resolve(intent: AccessIntent): PermissionCheckResult;
+}
+
+/**
+ * Reduce a gate-emitted {@link AccessIntent} to the string-based
+ * {@link ResolvedAccessIntent} the manager consumes.
+ *
+ * Tell-Don't-Ask: the resolver asks an `AccessPath` for its `matchValues()`,
+ * so the low-level manager never imports the value object.
+ */
+function toResolvedIntent(intent: AccessIntent): ResolvedAccessIntent {
+  if (intent.kind === "access-path") {
+    return {
+      kind: "path-values",
+      surface: intent.surface,
+      values: intent.path.matchValues(),
+      agentName: intent.agentName,
+    };
+  }
+  return intent;
 }
 
 /**
@@ -41,60 +49,40 @@ export interface ScopedPermissionResolver {
  * - `permissionManager` — the narrow session-scoped permission-checking interface
  * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
  */
-export class PermissionResolver implements ScopedPermissionResolver {
+export class PermissionResolver
+  implements ScopedPermissionResolver, SkillPermissionChecker
+{
   constructor(
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: Pick<SessionRules, "getRuleset">,
   ) {}
 
   /**
-   * Resolve the effective permission for a surface/input, applying the current
-   * session rules. Composes `checkPermission` with `getRuleset()` so callers
-   * never thread the ruleset by hand.
+   * Answer a gate-emitted access intent, composing the current session ruleset
+   * so callers never thread it by hand. Unwraps the `access-path` variant via
+   * `matchValues()` before handing a string-based intent to the manager.
    */
-  resolve(
-    surface: string,
-    input: unknown,
-    agentName?: string,
-  ): PermissionCheckResult {
-    return this.checkPermission(
-      surface,
-      input,
-      agentName,
+  resolve(intent: AccessIntent): PermissionCheckResult {
+    return this.permissionManager.check(
+      toResolvedIntent(intent),
       this.sessionRules.getRuleset(),
     );
   }
 
   /**
-   * Resolve a path-shaped surface (`path` or `external_directory`) for
-   * precomputed policy values, composing the current session ruleset so callers
-   * never thread it by hand. `surface` defaults to `path`; the external-directory
-   * gates pass `external_directory` so a path's typed and symlink-resolved
-   * aliases match against the `external_directory` rules.
+   * Raw permission check without session rules — the no-session-rules path
+   * consumed by `SkillInputGateInputs` / `SkillPermissionChecker`.
+   *
+   * Not on `ScopedPermissionResolver` (ISP: gates do not use this).
    */
-  resolvePathPolicy(
-    values: readonly string[],
-    agentName?: string,
-    surface = "path",
-  ): PermissionCheckResult {
-    return this.permissionManager.checkPathPolicy(
-      values,
-      agentName,
-      this.sessionRules.getRuleset(),
-      surface,
-    );
-  }
-
   checkPermission(
     surface: string,
     input: unknown,
     agentName?: string,
     sessionRules?: Rule[],
   ): PermissionCheckResult {
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
+    return this.permissionManager.check(
+      { kind: "tool", surface, input, agentName },
       sessionRules,
     );
   }

package/src/permissions-service.ts

@@ -32,10 +32,8 @@ export class LocalPermissionsService implements PermissionsService {
     agentName?: string,
   ): ReturnType<PermissionsService["checkPermission"]> {
     const input = buildInputForSurface(surface, value);
-    return this.permissionManager.checkPermission(
-      surface,
-      input,
-      agentName,
+    return this.permissionManager.check(
+      { kind: "tool", surface, input, agentName },
       this.sessionRules.getRuleset(),
     );
   }

package/src/skill-prompt-sanitizer.ts

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

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

@@ -49,10 +49,8 @@ function makeSetup(opts?: {
       opts.toolPermission,
     );
   }
-  // Default checkPermission returns allow (for skill-prompt sanitizer)
-  vi.mocked(permissionManager.checkPermission).mockReturnValue(
-    makeCheckResult(),
-  );
+  // Default check returns allow (for skill-prompt sanitizer via resolver.checkPermission)
+  vi.mocked(permissionManager.check).mockReturnValue(makeCheckResult());
   const toolRegistry = makeToolRegistry(opts?.toolRegistry);
   const handler = new AgentPrepHandler(session, resolver, toolRegistry);
   return {
@@ -195,11 +193,10 @@ describe("AgentPrepHandler.handle", () => {
       "</available_skills>",
     ].join("\n");
     const { handler, permissionManager } = makeSetup();
-    vi.mocked(permissionManager.checkPermission).mockImplementation(
-      (surface) =>
-        surface === "skill"
-          ? makeCheckResult({ state: "deny" })
-          : makeCheckResult(),
+    vi.mocked(permissionManager.check).mockImplementation((intent) =>
+      intent.surface === "skill"
+        ? makeCheckResult({ state: "deny" })
+        : makeCheckResult(),
     );
 
     const first = await handler.handle(makeEvent(systemPrompt), makeCtx());