@gotgenes/pi-permission-system 16.1.0 → 16.2.1

package/src/permission-manager.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { isPermissionState } from "./common";
+import type { ResolvedAccessIntent } from "./access-intent/access-intent";
 import {
   getGlobalConfigPath,
   getProjectAgentsDir,
@@ -27,6 +27,7 @@ import type {
   PermissionCheckResult,
   PermissionState,
 } from "./types";
+import { isPermissionState } from "./value-guards";
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "bash",
@@ -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-prompts.ts

@@ -1,8 +1,8 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { matchQualifier } from "./denial-messages";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 // NOTE: formatDenyReason, formatUserDeniedReason, and
 // formatPermissionHardStopHint have been moved to denial-messages.ts.

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/policy-loader.ts

@@ -1,8 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-import { extractFrontmatter, parseSimpleYamlMap, toRecord } from "./common";
 import {
   loadUnifiedConfig,
   normalizeUnifiedConfig,
@@ -10,6 +8,8 @@ import {
 } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
 import type { ScopeConfig } from "./types";
+import { toRecord } from "./value-guards";
+import { extractFrontmatter, parseSimpleYamlMap } from "./yaml-frontmatter";
 
 // ---------------------------------------------------------------------------
 // File-stamp helper

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/src/tool-input-prompt-formatters.ts

@@ -1,5 +1,5 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { countTextLines, formatCount } from "./tool-input-preview";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export function getPromptPath(input: Record<string, unknown>): string | null {
   return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);

package/src/tool-preview-formatter.ts

@@ -1,4 +1,3 @@
-import { getNonEmptyString, toRecord } from "./common";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
@@ -15,6 +14,7 @@ import {
   getPromptPath,
 } from "./tool-input-prompt-formatters";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export interface ToolPreviewFormatterOptions {
   toolInputPreviewMaxLength: number;

package/src/tool-registry.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /** Narrow interface for the Pi tool API subset used by handler classes. */
 export interface ToolRegistry {

package/src/{common.ts → value-guards.ts}

@@ -53,69 +53,3 @@ export function isDenyWithReason(value: unknown): value is DenyWithReason {
     (record.reason === undefined || typeof record.reason === "string")
   );
 }
-
-type StackNode = { indent: number; target: Record<string, unknown> };
-
-export function parseSimpleYamlMap(input: string): Record<string, unknown> {
-  const root: Record<string, unknown> = {};
-  const stack: StackNode[] = [{ indent: -1, target: root }];
-
-  const lines = input.split(/\r?\n/);
-  for (const rawLine of lines) {
-    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
-      continue;
-    }
-
-    const indent = rawLine.length - rawLine.trimStart().length;
-    const line = rawLine.trim();
-    const separatorIndex = line.indexOf(":");
-    if (separatorIndex <= 0) {
-      continue;
-    }
-
-    const key = line
-      .slice(0, separatorIndex)
-      .trim()
-      .replace(/^['"]|['"]$/g, "");
-    const rawValue = line.slice(separatorIndex + 1).trim();
-
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-
-    const current = stack[stack.length - 1].target;
-
-    if (!rawValue) {
-      const child: Record<string, unknown> = {};
-      current[key] = child;
-      stack.push({ indent, target: child });
-      continue;
-    }
-
-    let scalar = rawValue;
-    if (
-      (scalar.startsWith('"') && scalar.endsWith('"')) ||
-      (scalar.startsWith("'") && scalar.endsWith("'"))
-    ) {
-      scalar = scalar.slice(1, -1);
-    }
-
-    current[key] = scalar;
-  }
-
-  return root;
-}
-
-export function extractFrontmatter(markdown: string): string {
-  const normalized = markdown.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) {
-    return "";
-  }
-
-  const end = normalized.indexOf("\n---", 4);
-  if (end === -1) {
-    return "";
-  }
-
-  return normalized.slice(4, end);
-}

package/src/yaml-frontmatter.ts

@@ -0,0 +1,65 @@
+type StackNode = { indent: number; target: Record<string, unknown> };
+
+export function parseSimpleYamlMap(input: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: StackNode[] = [{ indent: -1, target: root }];
+
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line
+      .slice(0, separatorIndex)
+      .trim()
+      .replace(/^['"]|['"]$/g, "");
+    const rawValue = line.slice(separatorIndex + 1).trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1].target;
+
+    if (!rawValue) {
+      const child: Record<string, unknown> = {};
+      current[key] = child;
+      stack.push({ indent, target: child });
+      continue;
+    }
+
+    let scalar = rawValue;
+    if (
+      (scalar.startsWith('"') && scalar.endsWith('"')) ||
+      (scalar.startsWith("'") && scalar.endsWith("'"))
+    ) {
+      scalar = scalar.slice(1, -1);
+    }
+
+    current[key] = scalar;
+  }
+
+  return root;
+}
+
+export function extractFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return "";
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return "";
+  }
+
+  return normalized.slice(4, end);
+}

package/test/access-intent/bash/node-text.test.ts

@@ -10,6 +10,7 @@ function makeNode(type: string, text: string, children: TSNode[] = []): TSNode {
   return {
     type,
     text,
+    startIndex: 0,
     childCount: children.length,
     isNamed: true,
     child: (i) => children[i] ?? null,

package/test/access-intent/bash/program.test.ts

@@ -435,6 +435,73 @@ describe("BashProgram", () => {
       expect((await BashProgram.parse("", cwd)).commands()).toEqual([]);
       expect((await BashProgram.parse("   ", cwd)).commands()).toEqual([]);
     });
+
+    it("strips a leading env-var assignment prefix", async () => {
+      const program = await BashProgram.parse(
+        "AWS_PROFILE=prod aws ec2 terminate-instances --instance-ids i-1",
+        cwd,
+      );
+      expect(program.commands()).toEqual([
+        { text: "aws ec2 terminate-instances --instance-ids i-1" },
+      ]);
+    });
+
+    it("strips multiple leading env-var assignments", async () => {
+      const program = await BashProgram.parse("A=1 B=2 aws s3 ls", cwd);
+      expect(program.commands()).toEqual([{ text: "aws s3 ls" }]);
+    });
+
+    it("strips the env-var prefix of each command in a chain", async () => {
+      const program = await BashProgram.parse(
+        "X=1 aws sts get-caller-identity && ls",
+        cwd,
+      );
+      expect(program.commands()).toEqual([
+        { text: "aws sts get-caller-identity" },
+        { text: "ls" },
+      ]);
+    });
+
+    it("keeps a pure assignment with no command unchanged", async () => {
+      const program = await BashProgram.parse("FOO=bar", cwd);
+      expect(program.commands()).toEqual([{ text: "FOO=bar" }]);
+    });
+
+    describe("opaque-payload wrappers", () => {
+      it.each([
+        ['bash -c "rm -rf /"', 'bash -c "rm -rf /"'],
+        ['sh -c "rm -rf /"', 'sh -c "rm -rf /"'],
+        ['dash -c "rm -rf /"', 'dash -c "rm -rf /"'],
+        ['zsh -c "rm -rf /"', 'zsh -c "rm -rf /"'],
+        ['ksh -c "rm -rf /"', 'ksh -c "rm -rf /"'],
+        ['eval "rm -rf /"', 'eval "rm -rf /"'],
+        ['/bin/bash -c "rm -rf /"', '/bin/bash -c "rm -rf /"'],
+        ['bash -ec "rm -rf /"', 'bash -ec "rm -rf /"'],
+      ])("flags %s as opaque", async (command, text) => {
+        const program = await BashProgram.parse(command, cwd);
+        expect(program.commands()).toEqual([{ text, opaque: true }]);
+      });
+
+      it("flags an env-prefixed wrapper as opaque after stripping the prefix", async () => {
+        const program = await BashProgram.parse(
+          'AWS_PROFILE=prod bash -c "rm -rf /"',
+          cwd,
+        );
+        expect(program.commands()).toEqual([
+          { text: 'bash -c "rm -rf /"', opaque: true },
+        ]);
+      });
+
+      it.each([
+        "bash script.sh",
+        "bash",
+        "ls -la",
+        "grep -c foo file",
+      ])("does not flag %s as opaque", async (command) => {
+        const program = await BashProgram.parse(command, cwd);
+        expect(program.commands()).toEqual([{ text: command }]);
+      });
+    });
   });
 
   it("derives both slices from a single parse", async () => {

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());