@gotgenes/pi-permission-system 16.1.0 → 16.2.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.0...pi-permission-system-v16.2.1) (2026-06-27)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** floor opaque bash -c/eval wrappers to ask ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e69493c](https://github.com/gotgenes/pi-packages/commit/e69493c00a04fdcdc1a972ef04ffee5839c93d2a))
+* **pi-permission-system:** strip env-var assignment prefix from bash command units ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1c99fb3](https://github.com/gotgenes/pi-packages/commit/1c99fb3835442dce3cb01b89f26db0a39084b7af))
+
+
+### Documentation
+
+* **pi-permission-system:** document env-prefix stripping and opaque bash-wrapper floor ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([40c0012](https://github.com/gotgenes/pi-packages/commit/40c001270249ace6a9d471c92063f9f09aa67238))
+* **pi-permission-system:** note opaque-wrapper sentinel in README and skill ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e226fe7](https://github.com/gotgenes/pi-packages/commit/e226fe7a49218fac73f2dcb8c84cb13608d48fa0))
+* **pi-permission-system:** note prefix strip and opaque flag in commands() JSDoc ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1892098](https://github.com/gotgenes/pi-packages/commit/18920980e0b17b6dd5e51a75fd103663f9313b32))
+
+## [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/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "16.1.0",
+  "version": "16.2.1",
   "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/access-intent/bash/command-enumeration.ts

@@ -18,6 +18,12 @@ export interface BashCommand {
    * for a current-shell (top-level) command.
    */
   readonly context?: BashCommandContext;
+  /**
+   * True when this is an opaque-payload wrapper (`bash -c`/`eval`) whose inner
+   * program is not re-parsed; its decision is floored to at least `ask` so it
+   * cannot ride a permissive `allow`.
+   */
+  readonly opaque?: boolean;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -75,6 +81,9 @@ const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
  *
  * The enclosing command/subshell is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
+ *
+ * Each emitted command unit has any leading `variable_assignment` prefix
+ * stripped (so an env-var prefix cannot defeat a command-pattern rule).
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
@@ -93,7 +102,9 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(makeUnit(node.text, context));
+    out.push(
+      makeUnit(commandUnitText(node), context, isOpaqueWrapperCommand(node)),
+    );
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectSubstitutionCommands(node, out);
@@ -119,8 +130,74 @@ function collectCommandsInto(
 function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
+  opaque = false,
 ): BashCommand {
-  return context ? { text, context } : { text };
+  const unit: BashCommand = context ? { text, context } : { text };
+  return opaque ? { ...unit, opaque } : unit;
+}
+
+/**
+ * Shell command names whose `-c` flag introduces an opaque inline program.
+ */
+const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
+
+/**
+ * True when a `command` node is an opaque-payload wrapper: a shell
+ * (`bash`/`sh`/`dash`/`zsh`/`ksh`) invoked with a `-c` flag, or `eval`. Its
+ * inner program is a quoted argument the enumerator does not re-parse, so the
+ * wrapper's decision is later floored to at least `ask`.
+ *
+ * The command name is matched on its basename (so `/bin/bash -c …` counts), and
+ * a `-c` flag is recognized within a short-flag cluster (`-c`, `-ec`, `-xc`).
+ * A leading `variable_assignment` prefix is skipped, matching `commandUnitText`.
+ */
+function isOpaqueWrapperCommand(node: TSNode): boolean {
+  let commandName: string | undefined;
+  let sawShortFlagC = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (child.type === "variable_assignment") continue;
+    if (commandName === undefined) {
+      commandName = basename(child.text);
+      continue;
+    }
+    const text = child.text;
+    if (text === "--") break;
+    if (text.startsWith("-") && !text.startsWith("--") && text.includes("c")) {
+      sawShortFlagC = true;
+    }
+  }
+  if (commandName === undefined) return false;
+  if (commandName === "eval") return true;
+  return SHELL_WRAPPER_NAMES.has(commandName) && sawShortFlagC;
+}
+
+/** The final path segment of a command name (`/bin/bash` → `bash`). */
+function basename(name: string): string {
+  const slash = name.lastIndexOf("/");
+  return slash === -1 ? name : name.slice(slash + 1);
+}
+
+/**
+ * The command-pattern text of a `command` node, with any leading
+ * `variable_assignment` prefix stripped.
+ *
+ * An env-var prefix (`AWS_PROFILE=prod aws …`, `PGPASSWORD=…`) is part of the
+ * `command` node's text but must not defeat a rule that gates the underlying
+ * command, so matching targets the text from the first non-assignment child
+ * (the `command_name`) onward, sliced verbatim to preserve spacing. A pure
+ * assignment (`FOO=bar`, no `command_name`) runs no command and is returned
+ * unchanged.
+ */
+function commandUnitText(node: TSNode): string {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.isNamed && child.type !== "variable_assignment") {
+      return node.text.slice(child.startIndex - node.startIndex);
+    }
+  }
+  return node.text;
 }
 
 function descendCommandChildren(

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

@@ -8,6 +8,8 @@ import { memoizeAsyncWithRetry } from "#src/async-cache";
 export interface TSNode {
   readonly type: string;
   readonly text: string;
+  /** Absolute byte offset of this node's start in the parsed source. */
+  readonly startIndex: number;
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;

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

@@ -61,6 +61,9 @@ export class BashProgram {
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
    * are NOT split — a subshell or other compound statement is emitted whole.
+   * Each unit has any leading `variable_assignment` prefix stripped, and an
+   * opaque-payload wrapper (`bash -c`/`eval`) is flagged `opaque` so its decision
+   * is floored to `ask`.
    * May be empty (e.g. an empty command or a comment-only line); callers fall
    * back to the whole command so the surface is never evaluated weaker than
    * before.

package/src/builtin-tool-input-formatters.ts

@@ -5,12 +5,12 @@
  * through exactly the same path a third-party extension would use.
  */
 
-import { toRecord } from "./common";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistry,
 } from "./tool-input-formatter-registry";
 import { truncateInlineText } from "./tool-input-preview";
+import { toRecord } from "./value-guards";
 
 /** Maximum total length of the generated argument summary (before "with " prefix). */
 const MCP_ARGS_SUMMARY_MAX_LENGTH = 160;

package/src/config-loader.ts

@@ -1,12 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-import {
-  isDenyWithReason,
-  isPermissionState,
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./common";
 import {
   getGlobalConfigPath,
   getLegacyExtensionConfigPath,
@@ -16,6 +9,13 @@ import {
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
+import {
+  isDenyWithReason,
+  isPermissionState,
+  normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
+  toRecord,
+} from "./value-guards";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.

package/src/forwarded-permissions/permission-forwarder.ts

@@ -5,7 +5,6 @@ import {
   getActiveAgentNameFromSystemPrompt,
   type SessionEntryView,
 } from "#src/active-agent";
-import { toRecord } from "#src/common";
 import type { ConfigReader } from "#src/config-store";
 import type {
   PermissionDecisionUi,
@@ -31,6 +30,7 @@ import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import { toRecord } from "#src/value-guards";
 import { shouldAutoApprovePermissionState } from "#src/yolo-mode";
 
 import {

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

@@ -19,6 +19,12 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
+ * An opaque-payload wrapper unit (`bash -c`/`eval`, flagged `opaque` by the
+ * enumerator) has its inner program hidden behind a quoted argument, so an
+ * `allow` is floored up to a synthetic `ask` (the `<opaque-bash-wrapper>`
+ * pattern) to keep it from riding a permissive rule; an explicit `deny`/`ask`
+ * on the wrapper is left untouched (`deny > ask > allow`).
+ *
  * When `commands` is empty there are two cases. A trivially-empty command (an
  * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
  * so the whole `command` is resolved as before. A non-empty command that parsed
@@ -38,7 +44,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 +62,30 @@ export function resolveBashCommandCheck(
   }
 
   const results = commands.map((cmd) => {
-    const result = resolver.resolve("bash", { command: cmd.text }, agentName);
+    const base = resolver.resolve({
+      kind: "tool",
+      surface: "bash",
+      input: { command: cmd.text },
+      agentName,
+    });
+    const result =
+      cmd.opaque && base.state === "allow"
+        ? {
+            ...base,
+            state: "ask" as const,
+            matchedPattern: "<opaque-bash-wrapper>",
+          }
+        : base;
     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-external-directory.ts

@@ -1,8 +1,8 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";

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

@@ -1,9 +1,9 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
@@ -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/skill-read.ts

@@ -1,8 +1,8 @@
-import { toRecord } from "#src/common";
 import { normalizePathForComparison } from "#src/path-utils";
 import { formatSkillPathAskPrompt } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
+import { toRecord } from "#src/value-guards";
 import type { GateDescriptor } from "./descriptor";
 import type { ToolCallContext } from "./types";
 

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

@@ -1,5 +1,4 @@
 import { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -8,6 +7,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";
@@ -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/handlers/permission-gate-handler.ts

@@ -2,8 +2,6 @@ import type {
   ExtensionContext,
   InputEventResult,
 } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
@@ -14,6 +12,7 @@ import {
   getToolNameFromValue,
   type ToolRegistry,
 } from "#src/tool-registry";
+import { toRecord } from "#src/value-guards";
 import type { GateRunner } from "./gates/runner";
 import type {
   GateNotifier,

package/src/handlers/tool-call-boundary.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import type { DecisionRecorder } from "#src/decision-audit";
 import type { DecisionReporter } from "#src/decision-reporter";
+import { toRecord } from "#src/value-guards";
 import type { GateOutcome } from "./gates/types";
 
 /** The SDK-facing result shape for a `tool_call` handler. */

package/src/input-normalizer.ts

@@ -1,7 +1,7 @@
 import { stripBashCommentLines } from "./bash-arity";
-import { getNonEmptyString, toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * Construct a surface-appropriate input object from a raw value string.

package/src/mcp-targets.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * An ordered accumulator that owns the uniqueness invariant.

package/src/normalize.ts

@@ -1,6 +1,6 @@
-import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
+import { isDenyWithReason, isPermissionState } from "./value-guards";
 
 /**
  * Convert a flat permission config into a Ruleset.

package/src/path-utils.ts

@@ -8,9 +8,9 @@ import {
 } from "node:path";
 
 import { canonicalizePath } from "./canonicalize-path";
-import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
 import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
+import { getNonEmptyString, toRecord } from "./value-guards";
 import { wildcardMatch } from "./wildcard-matcher";
 
 export function normalizePathForComparison(

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