@signalridge/pi-subagents 1.10.3 → 1.11.1

package/src/mention-clone.ts

@@ -1,6 +1,6 @@
 /**
- * mention-clone.ts — start a mentioned agent through a clone of this
- * conversation, without putting anything in the chat.
+ * mention-clone.ts — start a mentioned agent through a hidden, mention-only
+ * session without putting anything in the chat.
  *
  * Claude Code routes `@agent-<type>` through the main model: the mention
  * becomes a `<system-reminder>` appended to the prompt and the model makes the
@@ -9,27 +9,13 @@
  * reasoning and its tool block land in the transcript, for a decision the user
  * already made when they typed the handle.
  *
- * So the turn happens somewhere else. The conversation is cloned into a
- * throwaway in-memory session — same messages, same system prompt, same model —
- * and that copy takes the turn off-screen. A literal clone: the session's own
- * entries, projected by pi's own `sessionEntryToContextMessages`, not
- * `inherit_context`'s text rendering of them.
- *
- * Cloned from memory rather than from the session file, which cannot be relied
- * on: `SessionManager._persist` withholds every write until the first assistant
- * message lands, so a fork taken before then reads an empty file and throws.
- * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
- * the leaf path and substitutes the summary for entries folded into it, so a
- * long conversation clones as what the main model is actually working from. A
- * conversation with nothing in it yet clones to nothing in it yet, which is the
- * correct answer rather than a failure.
- *
- * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
- * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
- * arrived in 0.80.5 — where this one has been exported unchanged from before
- * the declared peer floor, and is the same code path (`byId` is only an index
- * cache, so passing it or not cannot change the result). Keeping the floor
- * honest costs nothing here: see the `compat-floor-pi` job.
+ * So the turn happens somewhere else. A throwaway in-memory session takes it
+ * off-screen on the parent's model, but receives only this mention's text.
+ * Pi's public ExtensionContext exposes a pre-hook SessionManager projection,
+ * not the parent's request-local context hooks (including programmatic hooks).
+ * Copying even a compacted or edited branch could send private parent content
+ * to the clone's provider before its redaction runs. The clone must start empty:
+ * no parent branch, system prompt, tool declarations, or summaries.
  *
  * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
  * better. `getSessionContextSettings` starts at "off" and moves only on an
@@ -63,19 +49,28 @@
 
 import type { Model } from "@earendil-works/pi-ai";
 import {
-  buildSessionContext,
   createAgentSession,
+  DefaultResourceLoader,
   type ExtensionContext,
+  getAgentDir,
   SessionManager,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { runInChildSessionContext } from "./child-context.js";
-import { agentMentionReminder } from "./mention.js";
+import { parentModelSessionOptions } from "./model-runtime-bridge.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
+const MENTION_SYSTEM_PROMPT =
+  "You write a task prompt for the Agent tool using only the user's current message. " +
+  "Call Agent once to start the requested task. You have no prior conversation context; " +
+  "do not invent or request inherited context. If details are missing, pass the user's words through.";
+
+/** Internal acknowledgement: the real Agent handler has returned from manager.spawn. */
+export const MENTION_SPAWNED = Symbol("pi-subagents:mention-spawned");
+
 export interface MentionCloneOptions {
-  /** The MAIN session's context — what the spawn is attributed to, and the
-   * source of both the conversation and the live system prompt. */
+  /** The MAIN session's context — what the spawn is attributed to, not a
+   * source of provider history or instructions for the hidden turn. */
   ctx: ExtensionContext;
   /** Agent type the handle resolved to. */
   type: SubagentType;
@@ -83,79 +78,120 @@ export interface MentionCloneOptions {
   message: string;
   /** The registered `Agent` tool, reused so the spawn is an ordinary one. */
   agentTool: ToolDefinition;
+  /** False once the originating session or branch has been replaced. */
+  isOriginCurrent: () => boolean;
 }
 
 export interface MentionCloneResult {
-  /** True once the clone actually called `Agent`. */
+  /** True once the registered Agent handler confirmed a child was started. */
   spawned: boolean;
+  /** The Agent handler ran but refused the spawn; direct fallback must not bypass its policy. */
+  refused?: boolean;
   /** Why not, when it didn't. Absent on success. */
   error?: string;
 }
 
 /**
- * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Let a mention-only throwaway session make the tool call, then discard it.
  * Never rejects: a clone that cannot run is reported so the caller can fall
  * back to starting the agent directly.
  */
 export async function runMentionClone(opts: MentionCloneOptions): Promise<MentionCloneResult> {
-  const { ctx, type, message, agentTool } = opts;
+  const { ctx, type, message, agentTool, isOriginCurrent } = opts;
 
   let spawned = false;
+  let refused = false;
+  let attempted = false;
   const cloneAgentTool: ToolDefinition = {
     ...agentTool,
-    execute: (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
-      // One spawn per mention. The clone has a single tool and every reason to
-      // stop after using it, but a model that decides to "also" launch a second
-      // agent would do it where nobody can see and nobody asked.
-      if (spawned) {
-        return Promise.resolve({
-          content: [{ type: "text" as const, text: "Already started an agent for this mention. Stop here." }],
+    execute: async (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
+      // The model may ask for another type or a schedule, but the user chose
+      // exactly one agent by typing its handle. Never let the hidden turn widen
+      // that decision or attempt another spawn after a failed call.
+      if (attempted) {
+        return {
+          content: [{ type: "text" as const, text: "Already attempted an agent for this mention. Stop here." }],
           details: undefined,
           isError: true,
-        });
+        };
       }
-      spawned = true;
-      // undefined tool-call id + the main ctx: see the header. Background is
-      // forced rather than left to the clone: `run_in_background` defaults to
-      // false, and a foreground agent answers through its TOOL RESULT — which
-      // here is delivered into a session that is disposed moments later, so the
-      // agent would run, appear in the widget and the fleet, and reach nobody.
-      return agentTool.execute(
-        undefined as never,
-        { ...(params as Record<string, unknown>), run_in_background: true } as typeof params,
-        signal,
-        onUpdate,
-        ctx,
-      );
+      attempted = true;
+      if (!isOriginCurrent()) {
+        return {
+          content: [{ type: "text" as const, text: "The original session changed. Do not start this agent." }],
+          details: undefined,
+          isError: true,
+        };
+      }
+      const choice = params as Record<string, unknown>;
+      const selected = {
+        subagent_type: type,
+        prompt: typeof choice.prompt === "string" && choice.prompt.trim() ? choice.prompt : message,
+        ...(typeof choice.description === "string" && { description: choice.description }),
+        run_in_background: true,
+        // The handler acknowledges immediately after manager.spawn returns,
+        // before UI/event side effects can throw. A tool result alone cannot
+        // distinguish a pre-spawn rejection from a post-spawn exception.
+        [MENTION_SPAWNED]: () => { spawned = true; },
+      } as typeof params;
+      // A foreground result would be delivered only into the discarded clone.
+      // Attribute the background spawn to the real session, with no dangling
+      // tool-call id. A plain text rejection is not a successful spawn.
+      // Pi 0.99 tool handlers require a tool context, not the event-handler
+      // context captured from the parent. Keep every session-bound field from
+      // the parent, and supply the real clone call's nested-tool capabilities;
+      // Agent itself does not use those capabilities. Never pretend the parent
+      // has executeTool(), which only exists during an actual tool invocation.
+      const mainToolCtx = { ...ctx, tools: _cloneCtx.tools, executeTool: _cloneCtx.executeTool };
+      const result = await agentTool.execute(undefined as never, selected, signal, onUpdate, mainToolCtx);
+      const details = result.details as { agentId?: unknown; status?: unknown } | undefined;
+      spawned ||= typeof details?.agentId === "string" &&
+        (details.status === "background" || details.status === "queued");
+      refused = !spawned;
+      return result;
     },
   };
 
   let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
   try {
-    // Pi 0.80.8 moved createAgentSession from modelRegistry to modelRuntime;
-    // agent-runner.ts carries the same shim for the same reason — pass both so
-    // the clone keeps the parent's providers across the supported range.
-    const parentModelRuntime = (ctx.modelRegistry as unknown as { runtime?: unknown }).runtime;
-    // The conversation as the main session resolves it: compaction applied,
-    // branch summaries substituted.
-    const conversation = buildSessionContext(
-      ctx.sessionManager.getEntries(),
-      ctx.sessionManager.getLeafId(),
-    );
+    // Refuse before loading or prompting when a modern host cannot bridge the
+    // parent's providers/virtual routes into this throwaway session.
+    // The hidden clone inherits exactly this model; unlike an explicit child
+    // selection, a stale parent model cannot be replaced before its request.
+    const parentModels = parentModelSessionOptions(ctx, ctx.model);
+    // An empty manager works on both old Pi hosts (which read agent state) and
+    // new ones (which project the manager). Never inspect the parent's branch:
+    // its pre-hook content cannot safely seed a separate provider request.
+    const cloneManager = SessionManager.inMemory(ctx.cwd);
     // Pi 0.82.0 added this; below it the field is absent and the clone takes
     // the settings level instead, which is what a session that never ran
     // `/think` is on anyway. Same shim shape as `modelRuntime` below.
     const thinkingLevel = (ctx as { thinkingLevel?: ThinkingLevel }).thinkingLevel;
-    const created = await runInChildSessionContext(() =>
-      createAgentSession({
+    // No project or inline extensions run in the hidden session. The parent's
+    // programmatic context hooks cannot be enumerated from ExtensionContext,
+    // so replaying only file-backed hooks would be an unsafe partial policy.
+    const loader = new DefaultResourceLoader({
+      cwd: ctx.cwd,
+      agentDir: getAgentDir(),
+      noExtensions: true,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: true,
+      systemPromptOverride: () => MENTION_SYSTEM_PROMPT,
+      appendSystemPromptOverride: () => [],
+    });
+    const created = await runInChildSessionContext(async () => {
+      await loader.reload();
+      return createAgentSession({
         cwd: ctx.cwd,
         // Nothing about the copy is worth persisting, and an in-memory manager
         // is also what keeps the real session untouched.
-        sessionManager: SessionManager.inMemory(ctx.cwd),
+        sessionManager: cloneManager,
+        resourceLoader: loader,
         model: ctx.model as Model<never> | undefined,
         ...(thinkingLevel && { thinkingLevel }),
-        modelRegistry: ctx.modelRegistry,
-        ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime as never }),
+        ...parentModels,
         // An allowlist naming exactly the clone's own tool. NOT `noTools:
         // "all"`, whose doc comment ("start with no tools enabled") reads like
         // it spares custom tools and does not: it resolves to an EMPTY
@@ -166,24 +202,32 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
         // agent-runner's `tools: sessionTools` beside its nested `customTools`.
         tools: [cloneAgentTool.name],
         customTools: [cloneAgentTool],
-      } as Parameters<typeof createAgentSession>[0]),
-    );
+      } as Parameters<typeof createAgentSession>[0]);
+    });
     session = created.session;
+    // Loading resources and creating the session both yield. If the parent was
+    // replaced during either step, never make a provider request for a stale
+    // mention. The tool-level check below still fences a switch during streaming.
+    if (!isOriginCurrent()) return { spawned: false, error: "the original session changed" };
 
-    // The clone rebuilds a system prompt from cwd and agentDir, which is close
-    // but not the live one — extensions contribute to it per turn. Copy the
-    // real thing, so the copy reasons under the instructions the user's model
-    // is actually working under.
-    const systemPrompt = ctx.getSystemPrompt?.();
-    if (systemPrompt) session.agent.state.systemPrompt = systemPrompt;
-
-    // The conversation itself. Pushed rather than assigned so the array the
-    // session was built around stays the one it goes on using.
-    session.agent.state.messages.push(...conversation.messages);
-
-    // User text first, reminder after — the order Claude Code's attachment
-    // renderer produces, where the reminder trails the message it is about.
-    await session.prompt(`${message}\n\n${agentMentionReminder(type)}`);
+    // A session switch during a slow provider stream may produce no tool call
+    // for minutes. The tool fence below prevents a stale spawn, but without
+    // cancelling the clone that hidden request keeps running after its parent
+    // is gone. Check while the prompt is pending and abort the throwaway turn.
+    const clone = session;
+    let abortRequested = false;
+    const staleCheck = setInterval(() => {
+      if (abortRequested || isOriginCurrent()) return;
+      abortRequested = true;
+      void clone.abort().catch(() => {});
+    }, 100);
+    try {
+      // Only the current mention text reaches the hidden provider request.
+      // The selected type is enforced by the Agent wrapper, not extra history.
+      await clone.prompt(message);
+    } finally {
+      clearInterval(staleCheck);
+    }
   } catch (err) {
     return { spawned, error: err instanceof Error ? err.message : String(err) };
   } finally {
@@ -192,5 +236,7 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
 
   return spawned
     ? { spawned: true }
-    : { spawned: false, error: "the conversation clone did not start it" };
+    : refused
+      ? { spawned: false, refused: true, error: "the Agent tool refused this mention" }
+      : { spawned: false, error: "the conversation clone did not start it" };
 }

package/src/model-runtime-bridge.ts

@@ -0,0 +1,68 @@
+import type { ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
+
+function isSameModel(candidate: unknown, selected: { provider: string; id: string }): boolean {
+  if (!candidate || typeof candidate !== "object") return false;
+  const model = candidate as { provider?: unknown; id?: unknown };
+  return model.provider === selected.provider && model.id === selected.id;
+}
+
+/**
+ * Pi 0.80.8+ requires the parent's ModelRuntime, not just its public registry
+ * facade. ExtensionContext does not expose that runtime. Keep the one private
+ * compatibility read here until Pi provides a public accessor. Passing no
+ * runtime on a modern host silently creates a fresh one, losing extension
+ * providers, credentials and virtual routes before the first child request.
+ * Without selectedModel, check only the runtime's shape: the parent ctx.model
+ * may be stale while the child explicitly selects a valid physical model.
+ */
+export function parentModelSessionOptions(
+  ctx: ExtensionContext,
+  selectedModel?: { provider: string; id: string },
+): {
+  modelRegistry: ExtensionContext["modelRegistry"];
+  modelRuntime?: ModelRuntime;
+} {
+  const modelRegistry = ctx.modelRegistry;
+  const modernHost = typeof PiCodingAgent.ModelRuntime?.create === "function";
+  let candidate: unknown;
+  try {
+    candidate = (modelRegistry as unknown as { runtime?: unknown }).runtime;
+  } catch {
+    // Treat an inaccessible private bridge exactly like a missing one; never
+    // include accessor errors, which might contain provider configuration.
+  }
+  let compatible = false;
+  try {
+    if (candidate !== null && typeof candidate === "object") {
+      const runtime = candidate as Record<string, unknown>;
+      // Pi 0.84/0.87 already have ModelRuntime.create but no resolveModel;
+      // virtual routing is a 0.99 feature. Check the shared child-session
+      // capabilities available across all supported runtime generations.
+      compatible = typeof runtime.getAuth === "function" && typeof runtime.stream === "function" &&
+        typeof runtime.getModel === "function" && typeof runtime.streamSimple === "function";
+      if (compatible && modernHost && selectedModel) {
+        const model = (runtime.getModel as (provider: string, id: string) => unknown)(selectedModel.provider, selectedModel.id);
+        compatible = isSameModel(model, selectedModel);
+      }
+    }
+  } catch {
+    compatible = false;
+  }
+  if (modernHost && !compatible) {
+    throw new Error(
+      "Cannot start a child session: Pi exposes ModelRuntime.create but the parent's model runtime is unavailable or incompatible. " +
+        "Update Pi to a host that exposes the parent runtime to extensions, or disable subagent/mention dispatch; " +
+        "a fresh runtime would lose custom providers and virtual model routes.",
+    );
+  }
+  return {
+    modelRegistry, // older supported hosts still consume this option
+    ...(compatible ? { modelRuntime: candidate as ModelRuntime } : {}),
+  };
+}
+
+/** Admit a spawn before allocating any identity; final model validation stays in runAgent. */
+export function assertParentModelRuntimeAvailable(ctx: ExtensionContext): void {
+  parentModelSessionOptions(ctx);
+}

package/src/model-scope.ts

@@ -8,6 +8,7 @@
  */
 
 import { isModelInScope, type ModelRegistryRef, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+import type { ProjectTrust } from "./project-trust.js";
 
 /**
  * When enabled, subagent model choices are validated against `enabledModels`
@@ -22,7 +23,7 @@ export function isScopeModelsEnabled(): boolean { return scopeModelsEnabled; }
 export function setScopeModelsEnabled(enabled: boolean): void { scopeModelsEnabled = enabled; }
 
 export type ModelScopeVerdict =
-  /** In scope, or nothing to validate against (feature off / no allowlist). */
+  /** In scope, or nothing to validate against (feature off / no configured allowlist). */
   | { kind: "ok" }
   /** Caller-supplied out-of-scope choice — refuse the spawn with this message. */
   | { kind: "error"; message: string }
@@ -41,6 +42,8 @@ export type ModelScopeVerdict =
 export function checkModelScope(args: {
   model: { provider: string; id: string } | undefined;
   cwd: string;
+  /** Captured config root/trust and retained ancestor denials; omit only for standalone helpers. */
+  authority?: ProjectTrust;
   modelRegistry: ModelRegistryRef;
   /** True when the model came from the tool call rather than frontmatter. */
   callerSupplied: boolean;
@@ -52,7 +55,7 @@ export function checkModelScope(args: {
   const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
   if (!scopeModelsEnabled || !model) return { kind: "ok" };
 
-  const allowed = resolveEnabledModels(readEnabledModels(cwd), modelRegistry, cwd);
+  const allowed = resolveEnabledModels(readEnabledModels(cwd, args.authority), modelRegistry, cwd);
   if (!allowed || isModelInScope(model, allowed)) return { kind: "ok" };
 
   // A tier whose profile says `inherit` names no model of its own, so fall back
@@ -60,7 +63,9 @@ export function checkModelScope(args: {
   // `Model not in scope: "undefined"`, which tells the caller nothing it can act on.
   const modelLabel = modelInput ?? `${model.provider}/${model.id}`;
   if (callerSupplied) {
-    const list = [...allowed].sort().map(m => `  ${m}`).join("\n");
+    const list = allowed.size > 0
+      ? [...allowed].sort().map(m => `  ${m}`).join("\n")
+      : "  (no configured models are currently available or supported)";
     return {
       kind: "error",
       message: `Model not in scope: "${modelLabel}".\n\nAllowed models (from enabledModels):\n${list}`,

package/src/nested-tools.ts

@@ -16,6 +16,7 @@ import {
   resolveEnabledTypeIn,
   resolveTypeIn,
 } from "./agent-types.js";
+import { INHERIT_CONTEXT_UNAVAILABLE } from "./context-boundary.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
@@ -26,6 +27,7 @@ import {
   streamToOutputFile,
   writeInitialEntry,
 } from "./output-file.js";
+import { configurationContext, type ProjectTrust } from "./project-trust.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
 import type {
   AgentConfig,
@@ -103,6 +105,8 @@ export interface NestedToolContext {
   allowedSubagents: "all" | string[];
   /** Root used for agent/config discovery; may differ from the agent's working directory. */
   configCwd: string;
+  /** Immutable configuration authority captured by the runner, including ancestor denials. */
+  projectTrust: ProjectTrust;
 }
 
 function textResult(text: string, isError = false) {
@@ -151,7 +155,9 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
   // Agents resolve from a registry built for THIS branch's config root (under
   // worktree isolation, the copy). Never via registerAgents — that is
   // process-global state shared with the main session and every other agent.
-  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd));
+  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(
+    context.configCwd, false, context.projectTrust.trusted, context.projectTrust.deniedRoots,
+  ));
   const allowedTypesIn = (registry: Map<string, AgentConfig>): Set<string> | undefined =>
     context.allowedSubagents === "all"
       ? undefined
@@ -176,7 +182,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       run_in_background: Type.Optional(Type.Boolean()),
       resume: Type.Optional(Type.String({ description: "Resume a nested agent owned by this parent." })),
       isolated: Type.Optional(Type.Boolean()),
-      inherit_context: Type.Optional(Type.Boolean()),
+      inherit_context: Type.Optional(Type.Boolean({ description: "Unavailable: true is rejected. Put an explicitly sanitized summary in the task prompt instead." })),
       isolation: Type.Optional(Type.Literal("worktree")),
     }),
     execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
@@ -228,6 +234,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         ...params,
         agentTiers: getAgentTiersSettings(),
       });
+      if (invocation.inheritContext) return textResult(INHERIT_CONTEXT_UNAVAILABLE, true);
       // Leave model/thinking unset whenever an Agent tier may apply. runAgent
       // is the sole final resolver; pre-resolving here would let a parent or
       // legacy field bypass the selected profile.
@@ -248,6 +255,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         const scopeVerdict = checkModelScope({
           model,
           cwd: context.configCwd,
+          authority: context.projectTrust,
           modelRegistry: ctx.modelRegistry,
           callerSupplied: invocation.modelFromParams,
           agentLabel: config?.displayName ?? resolvedType,
@@ -337,7 +345,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         }
       };
 
-      // `ctx` is forwarded to the manager unmodified, never captured at tool-build
+      // `ctx` is forwarded with configuration-root provenance, never captured at tool-build
       // time: each AgentSession builds its own ExtensionRunner from that session's
       // cwd/sessionManager/modelRegistry, so this is the CHILD's context. Capturing
       // one earlier would silently give a grandchild the wrong worktree base, the
@@ -348,7 +356,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       // letting it escape into the child's turn.
       try {
         if (invocation.runInBackground) {
-          const id = context.manager.spawn(context.pi, ctx, resolvedType, params.prompt, {
+          const id = context.manager.spawn(context.pi, configurationContext(ctx, context.configCwd, context.projectTrust), resolvedType, params.prompt, {
             ...options,
             isBackground: true,
           });
@@ -360,7 +368,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
 
         const { record } = await context.manager.spawnAndWait(
           context.pi,
-          ctx,
+          configurationContext(ctx, context.configCwd, context.projectTrust),
           resolvedType,
           params.prompt,
           { ...options, signal },

package/src/project-trust.ts

@@ -0,0 +1,146 @@
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import type { ExtensionAPI, ExtensionContext, ExtensionFactory, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// Child contexts report the execution cwd, but their SettingsManager may own
+// a different configuration root. Keep that provenance package-internal when
+// nested tools forward the child's public context to the manager.
+export interface ProjectTrust {
+  readonly cwd: string;
+  readonly trusted: boolean;
+  readonly deniedRoots: readonly string[];
+}
+
+const configurationRoots = new WeakMap<ExtensionContext, {
+  cwd: string;
+  trusted?: boolean;
+  deniedRoots: readonly string[];
+}>();
+
+export function configurationContext(ctx: ExtensionContext, cwd: string, trust?: ProjectTrust): ExtensionContext {
+  const previous = configurationRoots.get(ctx);
+  configurationRoots.set(ctx, {
+    cwd,
+    trusted: trust?.trusted ?? previous?.trusted,
+    deniedRoots: Object.freeze([...new Set([...(previous?.deniedRoots ?? []), ...(trust?.deniedRoots ?? [])])]),
+  });
+  return ctx;
+}
+
+/** A changed configuration root is denied; ancestor denials survive every hop. */
+export function childProjectTrust(parent: ProjectTrust, cwd: string): ProjectTrust {
+  const trusted = parent.trusted && isSameConfiguration(cwd, parent.cwd);
+  return Object.freeze({
+    cwd: canonicalPath(cwd),
+    trusted,
+    deniedRoots: Object.freeze([...new Set([...parent.deniedRoots, ...(trusted ? [] : [canonicalPath(cwd)])])]),
+  });
+}
+
+/** Pi's MCP factory reads config from the session cwd; pin only its bootstrap to the config root. */
+export function configurationMcpFactory(factory: ExtensionFactory, cwd: string, settings: SettingsManager): ExtensionFactory {
+  return (pi) => factory(new Proxy(pi, {
+    get(target, key, receiver) {
+      if (key === "on") return ((event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown) => {
+        if (event === "session_start") {
+          return target.on("session_start", async (event, ctx) => {
+            await handler(event, {
+              ...ctx,
+              cwd,
+              isProjectTrusted: () => settings.isProjectTrusted(),
+            });
+          });
+        }
+        return Reflect.apply(target.on, target, [event, handler]);
+      }) as ExtensionAPI["on"];
+      return Reflect.get(target, key, receiver);
+    },
+  }));
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** Capture before child resolution/async work; missing or failed trust is denial. */
+export function captureProjectTrust(ctx: ExtensionContext): ProjectTrust {
+  const provenance = configurationRoots.get(ctx);
+  const cwd = canonicalPath(provenance?.cwd ?? ctx.cwd);
+  let trusted = false;
+  try {
+    // Validate the public trust API even with retained authority. If present,
+    // prefer the captured configuration trust to a late execution-cwd callback.
+    if (typeof ctx.isProjectTrusted === "function") {
+      const publicTrust = ctx.isProjectTrusted() === true;
+      trusted = provenance?.trusted ?? publicTrust;
+    }
+  } catch {
+    // A context that cannot establish trust must not authorize project code.
+  }
+  return Object.freeze({
+    cwd,
+    trusted,
+    deniedRoots: Object.freeze([...new Set([...(provenance?.deniedRoots ?? []), ...(trusted ? [] : [cwd])])]),
+  });
+}
+
+export function isSameConfiguration(cwd: string, parentCwd: string): boolean {
+  return canonicalPath(cwd) === parentCwd;
+}
+
+/**
+ * Check every traversed prefix, including intermediate symlink targets. A
+ * global alias into denied metadata cannot gain authority by pointing its
+ * descendants back outside. This is provenance admission, not a race-free
+ * filesystem sandbox; an absent leaf still has its existing ancestors checked.
+ */
+export function isProjectResource(path: string, cwd: string): boolean {
+  if (path.startsWith("builtin:")) return false;
+  const roots = [resolve(cwd), canonicalPath(cwd)];
+  const within = (file: string): boolean => roots.some(root => {
+    const rel = relative(root, file);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+  });
+  const visited = new Set<string>();
+  const traverse = (file: string): boolean => {
+    // Normalize separator variants, never dot segments. Both resolve and join
+    // would erase a traversed symlink before a following ".." is inspected.
+    let absolute = sep === "\\" ? file.replaceAll("/", sep) : file;
+    if (!isAbsolute(absolute)) {
+      const root = parse(absolute).root;
+      // Resolve only the base (including Windows drive-relative bases), not
+      // the unexamined components supplied by the caller or readlink.
+      absolute = `${resolve(root || ".")}${sep}${absolute.slice(root.length)}`;
+    }
+    let prefix = parse(absolute).root;
+    if (within(prefix) || within(canonicalPath(prefix))) return true;
+    for (const component of absolute.slice(prefix.length).split(sep)) {
+      if (!component) continue;
+      prefix = `${prefix}${prefix.endsWith(sep) ? "" : sep}${component}`;
+      if (within(prefix) || within(canonicalPath(prefix))) return true;
+      try {
+        if (!lstatSync(prefix).isSymbolicLink()) continue;
+      } catch {
+        // No readable descendant can exist beyond an absent/invalid prefix.
+        return false;
+      }
+      // Unknown/cyclic resolution is not evidence of global authority.
+      if (visited.has(prefix) || visited.size >= 64) return true;
+      visited.add(prefix);
+      try {
+        const target = readlinkSync(prefix);
+        if (traverse(isAbsolute(target) ? target : `${dirname(prefix)}${sep}${target}`)) return true;
+      } catch {
+        return true;
+      } finally {
+        visited.delete(prefix);
+      }
+    }
+    return false;
+  };
+  return traverse(path);
+}