@gotgenes/pi-permission-system 20.3.0 → 20.4.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [20.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.3.0...pi-permission-system-v20.4.0) (2026-07-12)
+
+
+### Features
+
+* **pi-permission-system:** add bash advisory decompose-or-fallback resolver ([e0637f1](https://github.com/gotgenes/pi-packages/commit/e0637f150d5ae0dcb16b92ccaa8520367636cc3c))
+* **pi-permission-system:** add warm tree-sitter parser and sync bash-command parse ([66470f0](https://github.com/gotgenes/pi-packages/commit/66470f084e639e4c7282d4a8e49b3fd6937bcb9e))
+* **pi-permission-system:** decompose advisory bash checkPermission at gate parity ([d8d7ef0](https://github.com/gotgenes/pi-packages/commit/d8d7ef010263b831e512dc26e97dde5bb93c5337))
+* **pi-permission-system:** warm bash parser on before_agent_start ([509c597](https://github.com/gotgenes/pi-packages/commit/509c597ffcf24bb9ef8af64ba91b7ae849ad02a8))
+
+
+### Documentation
+
+* **pi-permission-system:** document advisory bash decomposition and complete roadmap step 4 ([aeb8633](https://github.com/gotgenes/pi-packages/commit/aeb86330f0f7b179796879f3fe4abc1a3642a57d))
+
 ## [20.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.2.0...pi-permission-system-v20.3.0) (2026-07-09)
 
 

package/docs/cross-extension-api.md

@@ -90,6 +90,10 @@ Returns `PermissionCheckResult` with fields `state`, `matchedPattern`, `source`,
 
 For a path-shaped surface (`path`, `external_directory`, or a path-bearing tool — `read`/`write`/`edit`/`grep`/`find`/`ls`), the supplied `value` is matched against both the path as given and its canonical (symlink-resolved) form, at parity with the gates — so a query for a symlinked path matches a rule on its real target.
 
+For the `bash` surface, a `value` containing a chained or nested command (joined by `&&`, `||`, `;`, `|`, `&`, or newlines, or nested in a command substitution/subshell) is decomposed into its command-pattern units and resolved most-restrictive (`deny` > `ask` > `allow`), at parity with the enforcement gate — so `cd /repo && npm install x` returns the decision of the `npm install x` unit, not the leading `cd`.
+A previously chained command that returned `allow` (riding an allowed leading command) may therefore now return `deny`/`ask`.
+Decomposition needs the tree-sitter parser, which is warmed at `before_agent_start` (before any tool call); a bash query in the brief pre-warm window falls back to a whole-string match, so the answer is never weaker than the gate — only strengthened once warm.
+
 #### `getToolPermission`
 
 Returns `"allow"` | `"deny"` | `"ask"` for a tool name without considering command-level rules.

package/docs/subagent-integration.md

@@ -3,11 +3,11 @@
 ## Native integration with `@gotgenes/pi-subagents`
 
 [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) is the only subagent extension with native permission-system integration.
-It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
+It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
 Because the event bus dispatches synchronously, the synchronous registration completes before binding proceeds.
 This inverts the former dependency direction: the core no longer looks up this package's service ([ADR-0002] / pi-subagents [#261]).
 
-The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/subagent-registry.ts`.
+The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/authority/subagent-registry.ts`.
 This is necessary because each session's `ResourceLoader` creates its own `pi.events` bus: the parent emits `subagents:child:session-created` on the parent's bus, and only the parent's permission-system instance receives it.
 The child's jiti instance runs on a separate bus and never receives the event — but because both instances call `getSubagentSessionRegistry()`, they share the same store, so the parent's registration is visible to the child.
 

package/package.json

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

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

@@ -1,3 +1,5 @@
+import type { PathFlavor } from "#src/path/path-flavor";
+
 import {
   canonicalNormalizePathForComparison,
   getPathPolicyValues,
@@ -103,13 +105,13 @@ export class AccessPath {
    */
   static forPath(
     pathValue: string,
-    options: { cwd: string; resolveBase?: string; platform: NodeJS.Platform },
+    options: { cwd: string; resolveBase?: string; flavor: PathFlavor },
   ): AccessPath {
-    const { cwd, resolveBase = cwd, platform } = options;
+    const { cwd, resolveBase = cwd, flavor } = options;
     return new AccessPath(
-      normalizePathForComparison(pathValue, resolveBase, platform),
-      getPathPolicyValues(pathValue, { cwd, resolveBase }, platform),
-      canonicalNormalizePathForComparison(pathValue, resolveBase, platform),
+      normalizePathForComparison(pathValue, resolveBase, flavor),
+      getPathPolicyValues(pathValue, { cwd, resolveBase }, flavor),
+      canonicalNormalizePathForComparison(pathValue, resolveBase, flavor),
     );
   }
 

package/src/access-intent/bash/bash-path-resolver.ts

@@ -440,11 +440,10 @@ export class BashPathResolver {
   ): BashPathRuleCandidate[] {
     const seen = new Set<string>();
     const result: BashPathRuleCandidate[] = [];
-    const windowsSeparators = this.normalizer.usesWindowsSeparators();
 
     for (const { token, base } of candidates) {
       const candidate =
-        classifyTokenAsRuleCandidate(token, { windowsSeparators }) ??
+        classifyTokenAsRuleCandidate(token, this.normalizer.flavor) ??
         classifyPromotedRuleCandidate(token, this.isPromotablePathToken);
       if (!candidate) continue;
 

package/src/access-intent/bash/msys-bash-tokens.ts

@@ -22,7 +22,7 @@ import { isSafeSystemPath } from "#src/safe-system-paths";
  * - `plain` — everything else (relative tokens, `~/…`, native Windows drive
  *   paths); handled by ordinary win32 resolution.
  */
-export type Win32BashTokenKind =
+export type BashTokenShape =
   | { kind: "device" }
   | { kind: "drive-mount"; windowsPath: string }
   | { kind: "posix-absolute" }
@@ -36,7 +36,7 @@ export type Win32BashTokenKind =
  */
 const MSYS_DRIVE_MOUNT_PATTERN = /^\/([a-zA-Z])(\/.*)?$/;
 
-export function classifyWin32BashToken(token: string): Win32BashTokenKind {
+export function classifyWin32BashToken(token: string): BashTokenShape {
   if (isSafeSystemPath(token)) return { kind: "device" };
 
   const driveMatch = MSYS_DRIVE_MOUNT_PATTERN.exec(token);

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

@@ -42,3 +42,42 @@ async function initParser(): Promise<TSParser> {
 // (e.g. a slow WASM load) is retried on the next tool call instead of poisoning
 // the parser for the process lifetime.
 export const getParser = memoizeAsyncWithRetry(initParser);
+
+// Resolved parser cached for synchronous access after warm-up. The tree-sitter
+// parser is stateless (parse is a pure function of its input), so caching it at
+// module scope is safe even though module state now persists across same-cwd
+// session switches.
+let warmedParser: TSParser | null = null;
+
+/**
+ * Warm the tree-sitter parser so {@link getWarmBashParser} can hand it out
+ * synchronously. Triggered at `before_agent_start` (which precedes any tool
+ * call) so the synchronous advisory bash path can decompose at gate parity
+ * (#309).
+ *
+ * Best-effort and idempotent: it swallows a WASM init failure (the sync
+ * accessor stays cold and callers fall back to whole-string matching), and it
+ * returns immediately once warm, so calling it every turn is free.
+ */
+export async function warmBashParser(): Promise<void> {
+  if (warmedParser) return;
+  try {
+    warmedParser = await getParser();
+  } catch {
+    // Leave cold → advisory bash queries fall back to whole-string matching.
+    // getParser's own retry memoization re-attempts init on the next call.
+  }
+}
+
+/**
+ * The warmed parser for synchronous use, or `null` when it has not been warmed
+ * yet (the pre-warm window). Callers that get `null` must degrade gracefully.
+ */
+export function getWarmBashParser(): TSParser | null {
+  return warmedParser;
+}
+
+/** Test-only: clear the warmed-parser cache so cold/warm cases are isolatable. */
+export function resetWarmBashParser(): void {
+  warmedParser = null;
+}

package/src/access-intent/bash/sync-commands.ts

@@ -0,0 +1,31 @@
+import {
+  type BashCommand,
+  collectCommands,
+} from "#src/access-intent/bash/command-enumeration";
+import { getWarmBashParser } from "#src/access-intent/bash/parser";
+
+/**
+ * Synchronously enumerate the command-pattern units of a bash command using the
+ * warmed tree-sitter parser.
+ *
+ * Returns `null` when the parser has not been warmed yet (the pre-warm window),
+ * so the caller can fall back to whole-string matching rather than block. Once
+ * warm it mirrors the enumeration the gate performs (`BashProgram.commands()`):
+ * chains split, nested substitutions/subshells descend, opaque wrappers flagged
+ * (#306). Only the command-pattern surface is produced — no path slices, so no
+ * `PathNormalizer` is needed.
+ *
+ * An unparseable command yields an empty array (the caller's decompose path
+ * fails it closed via `resolveBashCommandCheck`, #452).
+ */
+export function parseBashCommandsSync(command: string): BashCommand[] | null {
+  const parser = getWarmBashParser();
+  if (!parser) return null;
+  const tree = parser.parse(command);
+  if (!tree) return [];
+  try {
+    return collectCommands(tree.rootNode);
+  } finally {
+    tree.delete();
+  }
+}

package/src/access-intent/bash/token-classification.ts

@@ -19,14 +19,15 @@
  * the absolute-path branch. Shape recognition is platform-independent string
  * matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
  *
- * `classifyTokenAsRuleCandidate` also accepts a `RuleCandidateOptions.windowsSeparators`
- * flag: when `true`, a backslash-relative token (`dir\file`, no leading `.`, no
- * `/`, no `..`, not a drive-letter absolute) is accepted as path-shaped (#520).
- * This is the one genuinely platform-sensitive shape rule the classifier owns —
- * on POSIX `\` is a legal filename character, so the caller (`BashPathResolver`)
- * derives the flag from `PathNormalizer.usesWindowsSeparators()` rather than the
- * classifier reading `process.platform` itself.
+ * `classifyTokenAsRuleCandidate` takes the resolved {@link PathFlavor}: a
+ * backslash-relative token (`dir\file`, no leading `.`, no `/`, no `..`, not a
+ * drive-letter absolute) is accepted as path-shaped only under the win32 flavor,
+ * whose `hasPathSeparator` counts `\` as a separator (#520). This is the one
+ * genuinely platform-sensitive shape rule the classifier owns — on POSIX `\` is
+ * a legal filename character — and the flavor owns the bit, so the classifier
+ * never reads `process.platform` itself.
  */
+import type { PathFlavor } from "#src/path/path-flavor";
 import type { PathRuleTokenMatcher } from "#src/types";
 
 // ── Public classifiers ─────────────────────────────────────────────────────
@@ -53,36 +54,22 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
   return null;
 }
 
-/**
- * Platform-sensitive options for {@link classifyTokenAsRuleCandidate}.
- */
-export interface RuleCandidateOptions {
-  /**
-   * True when the host platform treats `\` as a path separator (win32), so a
-   * backslash-relative token (`dir\file`) is accepted as path-shaped (#520).
-   * On POSIX `\` is a legal filename character, so omit this (or pass
-   * `false`) to keep such a token bare.
-   */
-  readonly windowsSeparators?: boolean;
-}
-
 /**
  * Broader token classifier for cross-cutting `path` permission rules.
  *
  * Accepts the same shapes as `classifyTokenAsPathCandidate`, plus:
  * - Dot-files and `./`-relative paths (starting with `.`)
- * - Any relative path containing `/` (e.g. `src/foo.ts`)
+ * - Any token carrying a path separator under `flavor` (`src/foo.ts`, and on
+ *   win32 the backslash-relative `dir\file`, #520) — `flavor.hasPathSeparator`
+ *   owns the platform bit (POSIX: `/` only; win32: `/` or `\`), so this
+ *   classifier never reads `process.platform`.
  * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
- * - A backslash-relative token (`dir\file`) when `options.windowsSeparators`
- *   is `true` (#520) — the caller (`BashPathResolver`) derives this from
- *   `PathNormalizer.usesWindowsSeparators()` so the platform bit has a single
- *   home; this classifier never reads `process.platform`.
  *
- * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
- * The forward-slash drive form (`C:/…`) is also caught by `includes("/")`, but the
+ * The `~/foo` case is covered by `hasPathSeparator` — no separate `~/` branch needed.
+ * The forward-slash drive form (`C:/…`) is also caught by `hasPathSeparator`, but the
  * explicit `WINDOWS_DRIVE_PATH_PATTERN` branch makes both separator forms first-class
- * and order-independent, and covers the backslash-only form (`D:\…`) which `includes("/")`
- * cannot reach.
+ * and order-independent, and covers the backslash-only form (`D:\…`) which the POSIX
+ * flavor's `hasPathSeparator` cannot reach.
  *
  * Does NOT require the strict "must start with `/` or `~/` or contain `..`"
  * gate that the external-directory classifier uses.
@@ -91,15 +78,14 @@ export interface RuleCandidateOptions {
  */
 export function classifyTokenAsRuleCandidate(
   token: string,
-  options?: RuleCandidateOptions,
+  flavor: PathFlavor,
 ): string | null {
   if (rejectNonPathToken(token)) return null;
 
   if (token.startsWith(".")) return token;
-  if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
+  if (flavor.hasPathSeparator(token)) return token; // ~/ paths, relative paths with /, and win32 dir\file
   if (token.includes("..")) return token; // bare ".." (no slash)
   if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token; // backslash-only drive form
-  if (options?.windowsSeparators && token.includes("\\")) return token;
 
   return null;
 }

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

@@ -1,35 +1,21 @@
-import { posix as posixPath, win32 as winPath } from "node:path";
-
-import { canonicalizePath } from "#src/canonicalize-path";
 import { expandHomePath } from "#src/expand-home";
-import { isPathWithinDirectory } from "#src/path-containment";
+import { canonicalizePath } from "#src/path/canonicalize-path";
+import type { PathFlavor } from "#src/path/path-flavor";
 
 /**
  * Representation derivation backing {@link AccessPath}: turn an accessed path
  * into the lexical / canonical / policy-value forms the resolver matches
  * against rules. Pure (no filesystem access except `canonicalizePath`'s
- * best-effort symlink resolution); the `platform` is injected, never read
- * ambiently.
+ * best-effort symlink resolution); the platform's path semantics arrive as an
+ * injected {@link PathFlavor}, never read ambiently.
  */
 export function normalizePathForComparison(
   pathValue: string,
-  cwd: string,
-  platform: NodeJS.Platform,
+  base: string,
+  flavor: PathFlavor,
 ): string {
-  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) {
-    return "";
-  }
-
-  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
-  normalizedPath = expandHomePath(normalizedPath);
-
-  const impl = platform === "win32" ? winPath : posixPath;
-  const absolutePath = impl.resolve(cwd, normalizedPath);
-  const normalizedAbsolutePath = impl.normalize(absolutePath);
-  return platform === "win32"
-    ? normalizedAbsolutePath.toLowerCase()
-    : normalizedAbsolutePath;
+  const cleaned = normalizePathPolicyLiteral(pathValue);
+  return cleaned ? flavor.comparable(cleaned, base) : "";
 }
 
 export interface PathPolicyValueOptions {
@@ -49,9 +35,9 @@ export interface PathPolicyValueOptions {
  * Normalize a single path-like lookup value without resolving it against CWD.
  *
  * Preserves compatibility with existing relative path rules (`src/*`, `*.env`)
- * while applying the same lexical cleanup as
- * {@link normalizePathForComparison}: trim, strip simple wrapping quotes,
- * strip the OpenCode-style leading `@`, and expand `~` / `$HOME`.
+ * while applying the lexical cleanup {@link normalizePathForComparison} shares:
+ * trim, strip simple wrapping quotes, strip the OpenCode-style leading `@`, and
+ * expand `~` / `$HOME`.
  */
 export function normalizePathPolicyLiteral(pathValue: string): string {
   const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
@@ -70,7 +56,7 @@ export function normalizePathPolicyLiteral(pathValue: string): string {
 export function getPathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   const literal = normalizePathPolicyLiteral(pathValue);
   if (!literal) return [];
@@ -78,7 +64,7 @@ export function getPathPolicyValues(
 
   return [
     ...new Set([
-      ...getAbsolutePathPolicyValues(pathValue, options, platform),
+      ...getAbsolutePathPolicyValues(pathValue, options, flavor),
       literal,
     ]),
   ];
@@ -87,38 +73,34 @@ export function getPathPolicyValues(
 function getAbsolutePathPolicyValues(
   pathValue: string,
   options: PathPolicyValueOptions,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   const resolveBase = options.resolveBase ?? options.cwd;
   if (!resolveBase) return [];
 
-  const absolute = normalizePathForComparison(pathValue, resolveBase, platform);
+  const absolute = normalizePathForComparison(pathValue, resolveBase, flavor);
   if (!absolute) return [];
 
   return [
     absolute,
-    ...getCwdRelativePathPolicyValues(absolute, options.cwd, platform),
+    ...getCwdRelativePathPolicyValues(absolute, options.cwd, flavor),
   ];
 }
 
 function getCwdRelativePathPolicyValues(
   absolute: string,
   cwd: string | undefined,
-  platform: NodeJS.Platform,
+  flavor: PathFlavor,
 ): string[] {
   if (!cwd) return [];
 
-  const normalizedCwd = normalizePathForComparison(cwd, cwd, platform);
+  const normalizedCwd = normalizePathForComparison(cwd, cwd, flavor);
   if (!normalizedCwd) return [];
-  if (
-    absolute !== normalizedCwd &&
-    !isPathWithinDirectory(absolute, normalizedCwd, platform)
-  ) {
+  if (absolute !== normalizedCwd && !flavor.isWithin(absolute, normalizedCwd)) {
     return [];
   }
 
-  const impl = platform === "win32" ? winPath : posixPath;
-  const relativeValue = impl.relative(normalizedCwd, absolute);
+  const relativeValue = flavor.impl.relative(normalizedCwd, absolute);
   return relativeValue ? [relativeValue] : [];
 }
 
@@ -129,11 +111,10 @@ function getCwdRelativePathPolicyValues(
  */
 export function canonicalNormalizePathForComparison(
   pathValue: string,
-  cwd: string,
-  platform: NodeJS.Platform,
+  base: string,
+  flavor: PathFlavor,
 ): string {
-  const lexical = normalizePathForComparison(pathValue, cwd, platform);
+  const lexical = normalizePathForComparison(pathValue, base, flavor);
   if (!lexical) return "";
-  const canonical = canonicalizePath(lexical, platform);
-  return platform === "win32" ? canonical.toLowerCase() : canonical;
+  return flavor.fold(canonicalizePath(lexical, flavor));
 }

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

@@ -0,0 +1,57 @@
+import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
+
+/**
+ * What a tool invocation accesses — decided once from the tool name at the
+ * point an invocation enters the system.
+ *
+ * This is the single dispatch point that replaces the scattered
+ * `toolName === "bash"`/`"mcp"` re-derivation across the extraction consumers
+ * (`input-normalizer`, `tool-input-path`, the tool-call gate pipeline, and
+ * `permission-manager`'s source derivation) and the presentation consumers
+ * (`tool-preview-formatter`, `permission-prompts`, `denial-messages`, and
+ * `deriveDecisionValue`), which dispatch on {@link classifyToolKind} or
+ * {@link isMcpCheck}. Adding a tool kind means editing {@link classifyToolKind}
+ * plus the exhaustive switches the compiler flags — an OCP win over silent
+ * `===` comparisons a new variant sails past (#561).
+ *
+ * The value is plain data (a string union): `tool-kind.ts` imports no
+ * `AccessPath`, so `permission-manager.ts` may consume it without breaching the
+ * string boundary formalized in ADR-0002
+ * (`docs/decisions/0002-path-values-string-boundary.md`).
+ *
+ * - `bash` — its own token-based path gates; extraction product is the command.
+ * - `mcp` — extraction product is the qualified target.
+ * - `skill` — a distinct surface `normalizeInput`/`deriveSource` treat specially.
+ * - `path` — a path-bearing built-in (`read`/`write`/`edit`/`grep`/`find`/`ls`);
+ *   extraction product is `input.path`.
+ * - `extension` — every other tool, plus the `external_directory`/`path` special
+ *   surfaces that reach `deriveSource` as normalized names.
+ */
+export type ToolKind = "bash" | "mcp" | "skill" | "path" | "extension";
+
+/** Classify a tool name into its {@link ToolKind}. */
+export function classifyToolKind(toolName: string): ToolKind {
+  const name = toolName.trim();
+  if (name === "bash") return "bash";
+  if (name === "mcp") return "mcp";
+  if (name === "skill") return "skill";
+  if (PATH_BEARING_TOOLS.has(name)) return "path";
+  return "extension";
+}
+
+/** The resolved-check fields that decide MCP-ness. */
+interface McpKindFields {
+  toolName: string;
+  source: string;
+}
+
+/**
+ * True when a resolved check concerns an MCP call — either the invoked tool is
+ * `mcp`, or the winning rule matched on the `mcp` surface (`source`). The
+ * `source` disjunct is why this cannot reduce to `classifyToolKind(toolName)`:
+ * `deriveSource` can set `source` to `mcp` on a result whose `toolName` is a
+ * server-qualified string.
+ */
+export function isMcpCheck(check: McpKindFields): boolean {
+  return check.source === "mcp" || classifyToolKind(check.toolName) === "mcp";
+}

package/src/authority/approval-escalator.ts

@@ -18,7 +18,7 @@ import {
   sleep,
   writeJsonFileAtomic,
 } from "#src/authority/forwarding-io";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPromptDisplay,
@@ -28,10 +28,10 @@ import {
   type PermissionForwardingLocation,
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { toRecord } from "#src/value-guards";
 import type { Authorizer } from "./authorizer";
 import type { PromptPermissionDetails } from "./permission-prompter";

package/src/authority/authorizer-selection.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type Authorizer,
   type AuthorizerSelectionDeps,

package/src/authority/authorizer.ts

@@ -2,10 +2,10 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type {
   PermissionPromptDecision,
   requestPermissionDecisionFromUi,
-} from "#src/permission-dialog";
+} from "#src/authority/permission-dialog";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PermissionEventBus } from "#src/permission-events";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { ParentAuthorizer } from "./approval-escalator";
 import { DenyingAuthorizer } from "./denying-authorizer";
 import { LocalUserAuthorizer } from "./local-user-authorizer";

package/src/authority/denying-authorizer.ts

@@ -1,4 +1,4 @@
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { Authorizer } from "./authorizer";
 
 /**

package/src/authority/forwarded-request-server.ts

@@ -3,17 +3,17 @@ import {
   type ForwarderContext,
   getSessionId,
 } from "#src/authority/forwarder-context";
-import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   isForwardedPermissionRequestForSession,
   type PermissionForwardingLocation,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
-import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import type { PermissionCheckResult } from "#src/types";
 import type { AskEscalator } from "./authorizer-selection";
 import {

package/src/authority/forwarder-context.ts

@@ -1,5 +1,5 @@
 import type { SessionEntryView } from "#src/active-agent";
-import type { PermissionDecisionUi } from "#src/permission-dialog";
+import type { PermissionDecisionUi } from "#src/authority/permission-dialog";
 
 /**
  * Narrow context the forwarding subsystem reads: the UI gate (`hasUI`), the

package/src/authority/forwarding-io.ts

@@ -9,15 +9,15 @@ import {
   writeFileSync,
 } from "node:fs";
 
-import { isPermissionDecisionState } from "#src/permission-dialog";
-import type { PermissionUiPromptSource } from "#src/permission-events";
+import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
   createPermissionForwardingLocation,
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
   type ForwardedSessionApproval,
   type PermissionForwardingLocation,
-} from "#src/permission-forwarding";
+} from "#src/authority/permission-forwarding";
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { DebugReviewLogger } from "#src/session-logger";
 
 /** Valid `permissions:ui_prompt` source values, for tolerant request reads. */

package/src/{forwarding-manager.ts → authority/forwarding-manager.ts}

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { InboxProcessor } from "./authority/forwarded-request-server";
-import type { SubagentDetector } from "./authority/subagent-detection";
+import type { InboxProcessor } from "./forwarded-request-server";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import type { SubagentDetector } from "./subagent-detection";
 
 /**
  * Narrow interface for the forwarding lifecycle used by `PermissionSession`.

package/src/authority/local-user-authorizer.ts

@@ -1,10 +1,10 @@
-import { buildForwardedScopeLabels } from "#src/pattern-suggest";
 import type {
   PermissionDecisionUi,
   PermissionPromptDecision,
   RequestPermissionOptions,
   requestPermissionDecisionFromUi,
-} from "#src/permission-dialog";
+} from "#src/authority/permission-dialog";
+import { buildForwardedScopeLabels } from "#src/pattern-suggest";
 import {
   emitUiPromptEvent,
   type PermissionEventBus,

package/src/{permission-forwarding.ts → authority/permission-forwarding.ts}

@@ -1,7 +1,6 @@
 import { join } from "node:path";
-
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import type { PermissionDecisionState } from "./permission-dialog";
-import type { PermissionUiPromptSource } from "./permission-events";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;

package/src/authority/permission-prompter.ts

@@ -1,5 +1,5 @@
-import type { PermissionPromptDecision } from "#src/permission-dialog";
-import type { ForwardedSessionApproval } from "#src/permission-forwarding";
+import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
+import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 import type { ReviewLogger } from "#src/session-logger";
 import type { Authorizer } from "./authorizer";