@gotgenes/pi-permission-system 7.2.0 → 7.3.1

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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).
 
+## [7.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.0...pi-permission-system-v7.3.1) (2026-05-26)
+
+
+### Bug Fixes
+
+* resolve pre-existing lint errors in pi-autoformat and pi-permission-system ([68fd516](https://github.com/gotgenes/pi-packages/commit/68fd516e33ddbb9a5e37ef19e949ee9ecdc37252))
+
+
+### Documentation
+
+* update subagent integration docs for native permission bridge ([#101](https://github.com/gotgenes/pi-packages/issues/101)) ([0bd456b](https://github.com/gotgenes/pi-packages/commit/0bd456befa8ea6918e74f4393d844868795edc77))
+
+## [7.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.2.0...pi-permission-system-v7.3.0) (2026-05-25)
+
+
+### Features
+
+* **pi-permission-system:** add SubagentSessionRegistry class ([a0ef16b](https://github.com/gotgenes/pi-packages/commit/a0ef16b8302f95b30cc11cb121441dbd164c276c))
+* **pi-permission-system:** detect in-process subagents via session registry ([c90b824](https://github.com/gotgenes/pi-packages/commit/c90b824b4515a1d5ca259348ae0b60c7d70f29d4))
+* **pi-permission-system:** expose registry and getToolPermission on PermissionsService ([984d2bb](https://github.com/gotgenes/pi-packages/commit/984d2bbb76f08cea91b5c0117eb356ae576ad6be))
+* **pi-permission-system:** resolve forwarding target from subagent registry ([5eb15af](https://github.com/gotgenes/pi-packages/commit/5eb15afe680bfd36627c2c21165b59a0ea5e227c))
+
+
+### Documentation
+
+* **pi-permission-system:** document subagent session registry API ([93c5c3e](https://github.com/gotgenes/pi-packages/commit/93c5c3e72b2b757a99eba17d1c6885ea49271403))
+* **pi-permission-system:** update architecture for subagent registry ([7b32e6a](https://github.com/gotgenes/pi-packages/commit/7b32e6a247e789b927e5cb3f19a367db0c110353))
+* plan subagent session registry and tool-level permission query ([#221](https://github.com/gotgenes/pi-packages/issues/221)) ([a11d91a](https://github.com/gotgenes/pi-packages/commit/a11d91aa1e13e846030deb0af37444c44eeda7c8))
+* **retro:** add planning stage notes for issue [#221](https://github.com/gotgenes/pi-packages/issues/221) ([cf434c2](https://github.com/gotgenes/pi-packages/commit/cf434c2f9711f26290a4635aea519f1f56e98cc7))
+* **retro:** add TDD stage notes for issue [#221](https://github.com/gotgenes/pi-packages/issues/221) ([e050898](https://github.com/gotgenes/pi-packages/commit/e05089840ee6bbb07cbeab5c55367e2dcd304866))
+
 ## [7.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.1.4...pi-permission-system-v7.2.0) (2026-05-24)
 
 

package/README.md

@@ -20,6 +20,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **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`
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
+- **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
 
 ## Install
 

package/package.json

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

package/src/extension-config.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 

package/src/forwarded-permissions/polling.ts

@@ -21,6 +21,7 @@ import {
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/permission-forwarding";
 import { isSubagentExecutionContext } from "#src/subagent-context";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
 
 import {
   cleanupPermissionForwardingLocationIfEmpty,
@@ -40,6 +41,8 @@ import {
 export interface PermissionForwardingDeps {
   forwardingDir: string;
   subagentSessionsDir: string;
+  /** In-process subagent session registry for detection and forwarding target resolution. */
+  registry?: SubagentSessionRegistry;
   logger: ForwardedPermissionLogger;
   writeReviewLog: (event: string, details: Record<string, unknown>) => void;
   requestPermissionDecisionFromUi: (
@@ -102,11 +105,18 @@ export async function waitForForwardedPermissionApproval(
   deps: PermissionForwardingDeps,
 ): Promise<PermissionPromptDecision> {
   const requesterSessionId = getSessionId(ctx);
+  const sessionDir = ctx.sessionManager.getSessionDir();
   const targetSessionId = resolvePermissionForwardingTargetSessionId({
     hasUI: ctx.hasUI,
-    isSubagent: isSubagentExecutionContext(ctx, deps.subagentSessionsDir),
+    isSubagent: isSubagentExecutionContext(
+      ctx,
+      deps.subagentSessionsDir,
+      deps.registry,
+    ),
     currentSessionId: requesterSessionId,
     env: process.env,
+    sessionDir,
+    registry: deps.registry,
   });
 
   if (!targetSessionId) {
@@ -360,7 +370,9 @@ export async function confirmPermission(
     );
   }
 
-  if (!isSubagentExecutionContext(ctx, deps.subagentSessionsDir)) {
+  if (
+    !isSubagentExecutionContext(ctx, deps.subagentSessionsDir, deps.registry)
+  ) {
     return { approved: false, state: "denied" };
   }
 

package/src/forwarding-manager.ts

@@ -4,6 +4,7 @@ import type { PermissionForwardingDeps } from "./forwarded-permissions/polling";
 import { processForwardedPermissionRequests } from "./forwarded-permissions/polling";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
 import { isSubagentExecutionContext } from "./subagent-context";
+import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /**
  * Narrow interface for the forwarding lifecycle used by `PermissionSession`.
@@ -30,6 +31,7 @@ export class ForwardingManager {
   constructor(
     private readonly subagentSessionsDir: string,
     private readonly forwardingDeps: PermissionForwardingDeps,
+    private readonly registry?: SubagentSessionRegistry,
   ) {}
 
   /**
@@ -41,7 +43,7 @@ export class ForwardingManager {
   start(ctx: ExtensionContext): void {
     if (
       !ctx.hasUI ||
-      isSubagentExecutionContext(ctx, this.subagentSessionsDir)
+      isSubagentExecutionContext(ctx, this.subagentSessionsDir, this.registry)
     ) {
       this.stop();
       return;

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

@@ -41,6 +41,7 @@ export function shouldExposeTool(
  */
 export class AgentPrepHandler {
   constructor(
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly toolRegistry: ToolRegistry,
   ) {}

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

@@ -48,14 +48,6 @@ function getParser(): Promise<TSParser> {
   return parserPromise;
 }
 
-/**
- * Reset the cached parser promise.  Only used by tests to avoid
- * cross-test pollution or to inject a mock parser.
- */
-function resetParserForTesting(): void {
-  parserPromise = null;
-}
-
 // ── AST walker ─────────────────────────────────────────────────────────────
 
 /**

package/src/handlers/lifecycle.ts

@@ -22,6 +22,7 @@ interface ResourcesDiscoverPayload {
  */
 export class SessionLifecycleHandler {
   constructor(
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly cleanupRpc: () => void,
   ) {}

package/src/handlers/permission-gate-handler.ts

@@ -47,6 +47,7 @@ interface InputPayload {
  */
 export class PermissionGateHandler {
   constructor(
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly events: PermissionEventBus,
     private readonly toolRegistry: ToolRegistry,

package/src/index.ts

@@ -27,6 +27,7 @@ import {
 } from "./service";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
+import { SubagentSessionRegistry } from "./subagent-registry";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -34,18 +35,21 @@ import {
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const runtime = createExtensionRuntime();
+  const subagentRegistry = new SubagentSessionRegistry();
 
   const prompter = new PermissionPrompter({
     getConfig: () => runtime.config,
     writeReviewLog: runtime.writeReviewLog.bind(runtime),
     subagentSessionsDir: runtime.subagentSessionsDir,
     forwardingDir: runtime.forwardingDir,
+    registry: subagentRegistry,
     requestPermissionDecisionFromUi,
   });
 
   const forwardingDeps: PermissionForwardingDeps = {
     forwardingDir: runtime.forwardingDir,
     subagentSessionsDir: runtime.subagentSessionsDir,
+    registry: subagentRegistry,
     logger: {
       writeReviewLog: runtime.writeReviewLog.bind(runtime),
       writeDebugLog: runtime.writeDebugLog.bind(runtime),
@@ -61,7 +65,11 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const session = new PermissionSession(
     runtime,
     createSessionLogger(runtime),
-    new ForwardingManager(runtime.subagentSessionsDir, forwardingDeps),
+    new ForwardingManager(
+      runtime.subagentSessionsDir,
+      forwardingDeps,
+      subagentRegistry,
+    ),
     {
       refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
       logResolvedConfigPaths: () => logResolvedConfigPaths(runtime),
@@ -73,6 +81,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
           isSubagent: isSubagentExecutionContext(
             ctx,
             runtime.subagentSessionsDir,
+            subagentRegistry,
           ),
         }),
       promptPermission: (ctx, details) => prompter.prompt(ctx, details),
@@ -108,6 +117,15 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         sessionRules,
       );
     },
+    registerSubagentSession(sessionKey, info) {
+      subagentRegistry.register(sessionKey, info);
+    },
+    unregisterSubagentSession(sessionKey) {
+      subagentRegistry.unregister(sessionKey);
+    },
+    getToolPermission(toolName, agentName) {
+      return runtime.permissionManager.getToolPermission(toolName, agentName);
+    },
   };
   publishPermissionsService(permissionsService);
 

package/src/permission-dialog.ts

@@ -25,12 +25,6 @@ const APPROVE_OPTION = "Yes";
 const APPROVE_FOR_SESSION_OPTION = "Yes, for this session";
 const DENY_OPTION = "No";
 const DENY_WITH_REASON_OPTION = "No, provide reason";
-const PERMISSION_DECISION_OPTIONS = [
-  APPROVE_OPTION,
-  APPROVE_FOR_SESSION_OPTION,
-  DENY_OPTION,
-  DENY_WITH_REASON_OPTION,
-] as const;
 
 export function normalizePermissionDenialReason(
   value: unknown,

package/src/permission-forwarding.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 
 import type { PermissionDecisionState } from "./permission-dialog";
+import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
 export const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
@@ -118,6 +119,10 @@ export function resolvePermissionForwardingTargetSessionId(options: {
   isSubagent: boolean;
   currentSessionId?: string | null;
   env?: NodeJS.ProcessEnv;
+  /** Session directory key for registry lookup. */
+  sessionDir?: string;
+  /** In-process subagent session registry (checked before env vars). */
+  registry?: SubagentSessionRegistry;
 }): string | null {
   if (options.hasUI) {
     return normalizePermissionForwardingSessionId(options.currentSessionId);
@@ -127,6 +132,16 @@ export function resolvePermissionForwardingTargetSessionId(options: {
     return null;
   }
 
+  // 1. Registry — in-process subagents register parentSessionId explicitly.
+  if (options.registry && options.sessionDir) {
+    const entry = options.registry.get(options.sessionDir);
+    const resolved = normalizePermissionForwardingSessionId(
+      entry?.parentSessionId,
+    );
+    if (resolved) return resolved;
+  }
+
+  // 2. Env vars — process-based subagent extensions.
   const env = options.env ?? process.env;
   for (const key of SUBAGENT_PARENT_SESSION_ENV_CANDIDATES) {
     const resolved = normalizePermissionForwardingSessionId(env[key]);

package/src/permission-manager.ts

@@ -120,7 +120,7 @@ export class PermissionManager {
           // existing patterns from lower scopes keep their earlier origin.
           if (!origins.has(surface)) origins.set(surface, new Map());
           for (const pattern of Object.keys(value)) {
-            origins.get(surface)!.set(pattern, scopeName);
+            origins.get(surface)?.set(pattern, scopeName);
           }
         } else {
           // Full replacement: this scope takes over the entire surface entry.

package/src/permission-merge.ts

@@ -1,4 +1,4 @@
-import type { FlatPermissionConfig, PermissionState } from "./types";
+import type { FlatPermissionConfig } from "./types";
 
 /**
  * Deep-shallow merge two flat permission configs.

package/src/permission-prompter.ts

@@ -9,6 +9,7 @@ import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "./permission-dialog";
+import type { SubagentSessionRegistry } from "./subagent-registry";
 import { shouldAutoApprovePermissionState } from "./yolo-mode";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
@@ -54,6 +55,8 @@ export interface PermissionPrompterDeps {
   subagentSessionsDir: string;
   /** Directory used for file-based permission forwarding requests/responses. */
   forwardingDir: string;
+  /** In-process subagent session registry for detection and forwarding target resolution. */
+  registry?: SubagentSessionRegistry;
   /** Show the interactive permission dialog in the UI. */
   requestPermissionDecisionFromUi(
     ui: ExtensionContext["ui"],
@@ -155,6 +158,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
     return {
       forwardingDir: deps.forwardingDir,
       subagentSessionsDir: deps.subagentSessionsDir,
+      registry: deps.registry,
       logger,
       // eslint-disable-next-line @typescript-eslint/unbound-method -- logger methods are plain function closures; no this-binding issue
       writeReviewLog: deps.writeReviewLog,

package/src/service.ts

@@ -11,9 +11,10 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
+import type { SubagentSessionInfo } from "./subagent-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
-export type { PermissionCheckResult, PermissionState };
+export type { PermissionCheckResult, PermissionState, SubagentSessionInfo };
 
 /** Process-global key for the service slot. */
 const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
@@ -42,6 +43,40 @@ export interface PermissionsService {
     value?: string,
     agentName?: string,
   ): PermissionCheckResult;
+
+  /**
+   * Register an in-process subagent session.
+   *
+   * Call this before `bindExtensions()` so that `isSubagentExecutionContext()`
+   * and permission-forwarding target resolution can detect the child session.
+   * Always pair with `unregisterSubagentSession()` in a `finally` block.
+   *
+   * @param sessionKey - Unique session identifier (use the session directory path).
+   * @param info       - Agent name and optional parent session ID.
+   */
+  registerSubagentSession(sessionKey: string, info: SubagentSessionInfo): void;
+
+  /**
+   * Remove a previously registered in-process subagent session.
+   *
+   * Safe to call even if `registerSubagentSession` was never called for this key.
+   *
+   * @param sessionKey - The same key passed to `registerSubagentSession`.
+   */
+  unregisterSubagentSession(sessionKey: string): void;
+
+  /**
+   * Query the tool-level permission state for pre-filtering tools before
+   * creating a child session.
+   *
+   * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
+   * Does not consider command-level rules (e.g. per-bash-command patterns) —
+   * use `checkPermission` for runtime invocation gates.
+   *
+   * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   */
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
 }
 
 /**

package/src/skill-prompt-sanitizer.ts

@@ -92,33 +92,6 @@ function parseSkillEntries(sectionBody: string): ParsedSkillPromptEntry[] {
   return entries;
 }
 
-function parseSkillPromptSection(prompt: string): SkillPromptSection | null {
-  const start = prompt.indexOf(AVAILABLE_SKILLS_OPEN_TAG);
-  if (start === -1) {
-    return null;
-  }
-
-  const closeStart = prompt.indexOf(
-    AVAILABLE_SKILLS_CLOSE_TAG,
-    start + AVAILABLE_SKILLS_OPEN_TAG.length,
-  );
-  if (closeStart === -1) {
-    return null;
-  }
-
-  const end = closeStart + AVAILABLE_SKILLS_CLOSE_TAG.length;
-  const sectionBody = prompt.slice(
-    start + AVAILABLE_SKILLS_OPEN_TAG.length,
-    closeStart,
-  );
-
-  return {
-    start,
-    end,
-    entries: parseSkillEntries(sectionBody),
-  };
-}
-
 export function parseAllSkillPromptSections(
   prompt: string,
 ): SkillPromptSection[] {

package/src/subagent-context.ts

@@ -2,6 +2,7 @@ import { normalize } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
+import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export function normalizeFilesystemPath(pathValue: string): string {
   const normalizedPath = normalize(pathValue);
@@ -30,7 +31,18 @@ function isPathWithinDirectoryForSubagent(
 export function isSubagentExecutionContext(
   ctx: ExtensionContext,
   subagentSessionsDir: string,
+  registry?: SubagentSessionRegistry,
 ): boolean {
+  const sessionDir = ctx.sessionManager.getSessionDir();
+
+  // 1. Explicit registry — in-process subagent extensions register before
+  //    bindExtensions(); checked first so it takes priority over heuristics.
+  if (registry && sessionDir && registry.has(sessionDir)) {
+    return true;
+  }
+
+  // 2. Env vars — process-based subagent extensions (nicobailon/pi-subagents,
+  //    HazAT/pi-interactive-subagents, pi-agent-router, etc.).
   for (const key of SUBAGENT_ENV_HINT_KEYS) {
     const value = process.env[key];
     if (typeof value === "string" && value.trim()) {
@@ -38,7 +50,8 @@ export function isSubagentExecutionContext(
     }
   }
 
-  const sessionDir = ctx.sessionManager.getSessionDir();
+  // 3. Filesystem path — fallback heuristic for extensions that store sessions
+  //    under a known subagent root directory.
   if (!sessionDir) {
     return false;
   }

package/src/subagent-registry.ts

@@ -0,0 +1,60 @@
+/**
+ * subagent-registry.ts — In-process subagent session registry.
+ *
+ * In-process subagent extensions (e.g. `@gotgenes/pi-subagents`) register
+ * each child session here before calling `bindExtensions()` so that
+ * `isSubagentExecutionContext()` and permission-forwarding target resolution
+ * can detect them without relying on environment variables or filesystem
+ * heuristics.
+ *
+ * The registry is keyed by session directory path, which is unique per
+ * session and available to both producer and consumer via
+ * `ctx.sessionManager.getSessionDir()`.
+ */
+
+/** Signal stored per registered in-process subagent session. */
+export interface SubagentSessionInfo {
+  /** Parent session ID for permission forwarding. Omit when unknown. */
+  parentSessionId?: string;
+  /** Agent name for per-agent policy resolution. */
+  agentName: string;
+}
+
+/**
+ * Registry of active in-process subagent sessions.
+ *
+ * Owned by `ExtensionRuntime`; exposed to external callers through the
+ * `PermissionsService` interface (`registerSubagentSession` /
+ * `unregisterSubagentSession`).
+ *
+ * Concurrent background agents are safe because each session has a unique
+ * directory path as its key — no scalar global flag is needed.
+ */
+export class SubagentSessionRegistry {
+  private readonly sessions = new Map<string, SubagentSessionInfo>();
+
+  /**
+   * Register an in-process subagent session.
+   *
+   * If a previous entry exists for `sessionKey`, it is overwritten
+   * (last-write-wins; single-writer expected per key).
+   */
+  register(sessionKey: string, info: SubagentSessionInfo): void {
+    this.sessions.set(sessionKey, info);
+  }
+
+  /** Remove a previously registered session. No-op if the key is absent. */
+  unregister(sessionKey: string): void {
+    this.sessions.delete(sessionKey);
+  }
+
+  /** Return the registered info for `sessionKey`, or `undefined` if absent. */
+  get(sessionKey: string): SubagentSessionInfo | undefined {
+    return this.sessions.get(sessionKey);
+  }
+
+  /** Return `true` when `sessionKey` has a registered entry. */
+  has(sessionKey: string): boolean {
+    return this.sessions.has(sessionKey);
+  }
+}

package/src/types.ts

@@ -14,17 +14,6 @@ export type FlatPermissionConfig = Record<
   PermissionState | Record<string, PermissionState>
 >;
 
-type BuiltInToolName =
-  | "bash"
-  | "read"
-  | "write"
-  | "edit"
-  | "grep"
-  | "find"
-  | "ls";
-
-type SpecialPermissionName = "external_directory";
-
 /**
  * Per-scope permission config shape after loading and validation.
  * Holds only the flat permission map — all policy is expressed there.

package/test/forwarding-manager.test.ts

@@ -205,6 +205,7 @@ describe("ForwardingManager", () => {
       expect(mockIsSubagentExecutionContext).toHaveBeenCalledWith(
         ctx,
         "/custom/subagent-dir",
+        undefined,
       );
     });
   });

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

@@ -7,7 +7,6 @@ import {
 } from "#src/handlers/before-agent-start";
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionState } from "#src/types";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
 vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {

package/test/handlers/gates/bash-external-directory.test.ts

@@ -101,12 +101,15 @@ describe("describeBashExternalDirectoryGate", () => {
   it("uses config-level checkPermission for the policy state", async () => {
     const checkPermission = vi
       .fn()
-      .mockImplementation((surface: string, input: Record<string, unknown>) => {
-        // Path-specific check returns session for coverage filtering
-        if (input.path) return makeCheckResult("allow", { source: "special" });
-        // Config-level check (no path) returns deny
-        return makeCheckResult("deny");
-      });
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          // Path-specific check returns session for coverage filtering
+          if (input.path)
+            return makeCheckResult("allow", { source: "special" });
+          // Config-level check (no path) returns deny
+          return makeCheckResult("deny");
+        },
+      );
     const result = await describeBashExternalDirectoryGate(
       makeTcc(),
       checkPermission,
@@ -172,12 +175,14 @@ describe("describeBashExternalDirectoryGate", () => {
   it("only includes uncovered paths when some are session-covered", async () => {
     const checkPermission = vi
       .fn()
-      .mockImplementation((surface: string, input: Record<string, unknown>) => {
-        if (input.path === "/outside/a.ts") {
-          return makeCheckResult("allow", { source: "session" });
-        }
-        return makeCheckResult("ask");
-      });
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path === "/outside/a.ts") {
+            return makeCheckResult("allow", { source: "session" });
+          }
+          return makeCheckResult("ask");
+        },
+      );
     const result = await describeBashExternalDirectoryGate(
       makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
       checkPermission,

package/test/handlers/gates/skill-read.test.ts

@@ -1,6 +1,4 @@
 import { describe, expect, it, vi } from "vitest";
-
-import type { GateDescriptor } from "#src/handlers/gates/descriptor";
 import { describeSkillReadGate } from "#src/handlers/gates/skill-read";
 import type { ToolCallContext } from "#src/handlers/gates/types";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";

package/test/handlers/input-events.test.ts

@@ -9,7 +9,6 @@ import type { PermissionDecisionEvent } from "#src/permission-events";
 import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionState } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 

package/test/handlers/input.test.ts

@@ -7,7 +7,6 @@ import {
 } from "#src/handlers/permission-gate-handler";
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionState } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 

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

@@ -10,7 +10,7 @@ import type { PermissionDecisionEvent } from "#src/permission-events";
 import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionCheckResult, PermissionState } from "#src/types";
+import type { PermissionCheckResult } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 

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

@@ -7,7 +7,7 @@ import {
 } from "#src/handlers/permission-gate-handler";
 import type { PermissionSession } from "#src/permission-session";
 import type { ToolRegistry } from "#src/tool-registry";
-import type { PermissionCheckResult, PermissionState } from "#src/types";
+import type { PermissionCheckResult } from "#src/types";
 
 // ── SDK stubs ──────────────────────────────────────────────────────────────
 vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => {

package/test/permission-events.test.ts

@@ -264,7 +264,7 @@ describe("piPermissionSystemExtension ready event wiring", () => {
     mkdirSync(join(baseDir, "agents"), { recursive: true });
     writeFileSync(
       globalConfigPath,
-      JSON.stringify({ permission: { "*": "ask" } }) + "\n",
+      `${JSON.stringify({ permission: { "*": "ask" } })}\n`,
       "utf8",
     );
     process.env.PI_CODING_AGENT_DIR = baseDir;

package/test/permission-forwarding.test.ts

@@ -4,6 +4,7 @@ import {
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
   SUBAGENT_PARENT_SESSION_ENV_KEY,
 } from "#src/permission-forwarding";
+import { SubagentSessionRegistry } from "#src/subagent-registry";
 
 afterEach(() => {
   vi.unstubAllEnvs();
@@ -146,3 +147,99 @@ describe("resolvePermissionForwardingTargetSessionId", () => {
     ).toBe("env-session-abc");
   });
 });
+
+describe("resolvePermissionForwardingTargetSessionId — registry resolution", () => {
+  const sessionDir =
+    "/home/user/projects/.pi/sessions/parent/tasks/session-abc";
+
+  test("returns parentSessionId from registry when env vars are absent", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(sessionDir, {
+      agentName: "Explore",
+      parentSessionId: "parent-from-registry",
+    });
+
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        registry,
+        env: {},
+      }),
+    ).toBe("parent-from-registry");
+  });
+
+  test("registry takes priority over env vars", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(sessionDir, {
+      agentName: "Explore",
+      parentSessionId: "parent-from-registry",
+    });
+
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        registry,
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
+      }),
+    ).toBe("parent-from-registry");
+  });
+
+  test("falls through to env vars when registry entry has no parentSessionId", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(sessionDir, { agentName: "Explore" }); // no parentSessionId
+
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        registry,
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
+      }),
+    ).toBe("parent-from-env");
+  });
+
+  test("falls through to env vars when sessionDir is not in registry", () => {
+    const registry = new SubagentSessionRegistry(); // empty
+
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        registry,
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
+      }),
+    ).toBe("parent-from-env");
+  });
+
+  test("returns null when registry entry has no parentSessionId and no env vars set", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(sessionDir, { agentName: "Explore" }); // no parentSessionId
+
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        registry,
+        env: {},
+      }),
+    ).toBeNull();
+  });
+
+  test("omitting registry preserves existing behaviour", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        sessionDir,
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
+      }),
+    ).toBe("parent-from-env");
+  });
+});

package/test/permission-session.test.ts

@@ -38,7 +38,6 @@ import {
 } from "#src/permission-session";
 import type { SessionLogger } from "#src/session-logger";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
-import type { PermissionCheckResult } from "#src/types";
 
 function makeSkillEntry(
   name: string,

package/test/service.test.ts

@@ -6,6 +6,7 @@ import {
   publishPermissionsService,
   unpublishPermissionsService,
 } from "#src/service";
+import { SubagentSessionRegistry } from "#src/subagent-registry";
 import type { PermissionCheckResult } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -15,6 +16,9 @@ function makeService(
 ): PermissionsService {
   return {
     checkPermission: vi.fn(),
+    registerSubagentSession: vi.fn(),
+    unregisterSubagentSession: vi.fn(),
+    getToolPermission: vi.fn(),
     ...overrides,
   };
 }
@@ -85,12 +89,12 @@ describe("service adapter delegation", () => {
     ];
 
     // Build the adapter the same way index.ts will
-    const service: PermissionsService = {
+    const service = makeService({
       checkPermission(surface, value, agentName) {
         const input = buildInputForSurface(surface, value);
         return checkPermission(surface, input, agentName, sessionRules);
       },
-    };
+    });
 
     publishPermissionsService(service);
     const retrieved = getPermissionsService()!;
@@ -108,12 +112,12 @@ describe("service adapter delegation", () => {
   it("checkPermission passes agentName through", () => {
     const checkPermission = vi.fn().mockReturnValue(fakeResult);
 
-    const service: PermissionsService = {
+    const service = makeService({
       checkPermission(surface, value, agentName) {
         const input = buildInputForSurface(surface, value);
         return checkPermission(surface, input, agentName, []);
       },
-    };
+    });
 
     publishPermissionsService(service);
     getPermissionsService()!.checkPermission("skill", "my-skill", "Explore");
@@ -126,15 +130,105 @@ describe("service adapter delegation", () => {
     );
   });
 
+  it("registerSubagentSession delegates to the registry", () => {
+    const registry = new SubagentSessionRegistry();
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      registerSubagentSession(key, info) {
+        registry.register(key, info);
+      },
+      unregisterSubagentSession(key) {
+        registry.unregister(key);
+      },
+      getToolPermission: vi.fn((): "allow" => "allow"),
+    };
+
+    publishPermissionsService(service);
+    getPermissionsService()!.registerSubagentSession("/sessions/task-1", {
+      agentName: "Explore",
+      parentSessionId: "parent-abc",
+    });
+
+    expect(registry.has("/sessions/task-1")).toBe(true);
+    expect(registry.get("/sessions/task-1")).toEqual({
+      agentName: "Explore",
+      parentSessionId: "parent-abc",
+    });
+  });
+
+  it("unregisterSubagentSession delegates to the registry", () => {
+    const registry = new SubagentSessionRegistry();
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      registerSubagentSession(key, info) {
+        registry.register(key, info);
+      },
+      unregisterSubagentSession(key) {
+        registry.unregister(key);
+      },
+      getToolPermission: vi.fn((): "allow" => "allow"),
+    };
+
+    publishPermissionsService(service);
+    const svc = getPermissionsService()!;
+    svc.registerSubagentSession("/sessions/task-1", { agentName: "Explore" });
+    svc.unregisterSubagentSession("/sessions/task-1");
+
+    expect(registry.has("/sessions/task-1")).toBe(false);
+  });
+
+  it("getToolPermission delegates to the permission manager", () => {
+    const getToolPermissionFn = vi.fn(
+      (_t: string, _a?: string): "deny" => "deny",
+    );
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      registerSubagentSession: vi.fn(),
+      unregisterSubagentSession: vi.fn(),
+      getToolPermission(toolName, agentName) {
+        return getToolPermissionFn(toolName, agentName);
+      },
+    };
+
+    publishPermissionsService(service);
+    const result = getPermissionsService()!.getToolPermission(
+      "bash",
+      "Explore",
+    );
+
+    expect(result).toBe("deny");
+    expect(getToolPermissionFn).toHaveBeenCalledWith("bash", "Explore");
+  });
+
+  it("getToolPermission works without agentName", () => {
+    const getToolPermissionFn = vi.fn(
+      (_t: string, _a?: string): "ask" => "ask",
+    );
+    const service: PermissionsService = {
+      checkPermission: vi.fn(),
+      registerSubagentSession: vi.fn(),
+      unregisterSubagentSession: vi.fn(),
+      getToolPermission(toolName, agentName) {
+        return getToolPermissionFn(toolName, agentName);
+      },
+    };
+
+    publishPermissionsService(service);
+    const result = getPermissionsService()!.getToolPermission("write");
+
+    expect(result).toBe("ask");
+    expect(getToolPermissionFn).toHaveBeenCalledWith("write", undefined);
+  });
+
   it("checkPermission uses empty object for unknown surfaces", () => {
     const checkPermission = vi.fn().mockReturnValue(fakeResult);
 
-    const service: PermissionsService = {
+    const service = makeService({
       checkPermission(surface, value, agentName) {
         const input = buildInputForSurface(surface, value);
         return checkPermission(surface, input, agentName, []);
       },
-    };
+    });
 
     publishPermissionsService(service);
     getPermissionsService()!.checkPermission("read", "/tmp/file");

package/test/subagent-context.test.ts

@@ -5,6 +5,7 @@ import {
   isSubagentExecutionContext,
   normalizeFilesystemPath,
 } from "#src/subagent-context";
+import { SubagentSessionRegistry } from "#src/subagent-registry";
 
 afterEach(() => {
   vi.unstubAllEnvs();
@@ -197,3 +198,67 @@ describe("isSubagentExecutionContext — session dir detection", () => {
     expect(isSubagentExecutionContext(makeCtx(""), subagentRoot)).toBe(false);
   });
 });
+
+describe("isSubagentExecutionContext — registry detection", () => {
+  const subagentRoot = "/home/user/.pi/agent/sessions/subagents";
+  const outsideDir =
+    "/home/user/projects/my-app/.pi/agent/sessions/parent/tasks";
+
+  test("returns true when session dir is registered (no env vars, outside filesystem root)", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(outsideDir, { agentName: "Explore" });
+    expect(
+      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+    ).toBe(true);
+  });
+
+  test("returns true when registered session has a parentSessionId", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(outsideDir, {
+      agentName: "Plan",
+      parentSessionId: "parent-123",
+    });
+    expect(
+      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+    ).toBe(true);
+  });
+
+  test("returns false when registry is provided but session dir is not registered", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(
+      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+    ).toBe(false);
+  });
+
+  test("returns false when session dir is null and registry has no matching entry", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(
+      isSubagentExecutionContext(makeCtx(null), subagentRoot, registry),
+    ).toBe(false);
+  });
+
+  test("registry check takes priority over env var detection", () => {
+    // Registry says registered; env var not set — should still return true.
+    const registry = new SubagentSessionRegistry();
+    registry.register(outsideDir, { agentName: "Explore" });
+    // Confirm no env var is set
+    expect(process.env.PI_IS_SUBAGENT).toBeUndefined();
+    expect(
+      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+    ).toBe(true);
+  });
+
+  test("unregistered session falls through to env var detection", () => {
+    vi.stubEnv("PI_IS_SUBAGENT", "true");
+    const registry = new SubagentSessionRegistry(); // empty — outsideDir not registered
+    // Env var present → still true even without registry entry
+    expect(
+      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+    ).toBe(true);
+  });
+
+  test("no registry passed — existing behaviour unchanged", () => {
+    // Ensure the parameter is truly optional (no registry arg)
+    expect(isSubagentExecutionContext(makeCtx(null), subagentRoot)).toBe(false);
+  });
+});

package/test/subagent-registry.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "vitest";
+import {
+  type SubagentSessionInfo,
+  SubagentSessionRegistry,
+} from "#src/subagent-registry";
+
+function makeInfo(
+  overrides: Partial<SubagentSessionInfo> = {},
+): SubagentSessionInfo {
+  return {
+    agentName: "Explore",
+    ...overrides,
+  };
+}
+
+describe("SubagentSessionRegistry", () => {
+  test("has() returns false for an unregistered key", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(registry.has("/sessions/task-abc")).toBe(false);
+  });
+
+  test("get() returns undefined for an unregistered key", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(registry.get("/sessions/task-abc")).toBeUndefined();
+  });
+
+  test("has() returns true after register()", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("/sessions/task-abc", makeInfo());
+    expect(registry.has("/sessions/task-abc")).toBe(true);
+  });
+
+  test("get() returns the registered info after register()", () => {
+    const registry = new SubagentSessionRegistry();
+    const info = makeInfo({ parentSessionId: "parent-123" });
+    registry.register("/sessions/task-abc", info);
+    expect(registry.get("/sessions/task-abc")).toEqual(info);
+  });
+
+  test("register() stores agentName without parentSessionId", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("/sessions/task-abc", makeInfo());
+    expect(registry.get("/sessions/task-abc")).toEqual({
+      agentName: "Explore",
+    });
+  });
+
+  test("has() returns false after unregister()", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("/sessions/task-abc", makeInfo());
+    registry.unregister("/sessions/task-abc");
+    expect(registry.has("/sessions/task-abc")).toBe(false);
+  });
+
+  test("get() returns undefined after unregister()", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("/sessions/task-abc", makeInfo());
+    registry.unregister("/sessions/task-abc");
+    expect(registry.get("/sessions/task-abc")).toBeUndefined();
+  });
+
+  test("unregister() is a no-op for an unknown key", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(() => registry.unregister("/sessions/nonexistent")).not.toThrow();
+  });
+
+  test("register() overwrites a previous entry for the same key", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(
+      "/sessions/task-abc",
+      makeInfo({ parentSessionId: "parent-1" }),
+    );
+    registry.register(
+      "/sessions/task-abc",
+      makeInfo({ parentSessionId: "parent-2" }),
+    );
+    expect(registry.get("/sessions/task-abc")?.parentSessionId).toBe(
+      "parent-2",
+    );
+  });
+
+  test("multiple keys are independent", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("/sessions/task-1", makeInfo({ agentName: "Explore" }));
+    registry.register("/sessions/task-2", makeInfo({ agentName: "Plan" }));
+
+    expect(registry.get("/sessions/task-1")?.agentName).toBe("Explore");
+    expect(registry.get("/sessions/task-2")?.agentName).toBe("Plan");
+
+    registry.unregister("/sessions/task-1");
+    expect(registry.has("/sessions/task-1")).toBe(false);
+    expect(registry.has("/sessions/task-2")).toBe(true);
+  });
+});