@ian-pascoe/pi-minimal-subagents 0.8.0 → 0.10.0

package/README.md

@@ -156,9 +156,8 @@ spawn attempts; the root retains recursive hierarchy management.
 
 ## Toolsets
 
-Configure ordinary tools using case-sensitive minimatch patterns, with the same
-syntax as CodeMode Exposure Patterns. These are lists of pattern strings, not
-CodeMode exposure-rule objects. For example:
+Configure ordinary tools using case-sensitive minimatch pattern strings. For
+example:
 
 ```json
 {
@@ -183,14 +182,15 @@ Tool Presets are cumulative:
 - `tools: "none"` or `tools: []`: Base Toolset only.
 - `tools: ["read"]`: Base Toolset + exactly `read`; arrays do not expand patterns
   or presets.
-- Omitted `tools`: Base Toolset + the caller's inherited ordinary tools.
+- Omitted `tools`: Base Toolset + the caller's Reachable Tools: the Root Agent's
+  active tools plus tools scripts can call without declaring them (`codemode` or
+  `deferred` exposure, such as MCP tools), or a Child Agent caller's own grant.
 
 Patterns select from permitted ordinary tool names, including inactive tools
 registered at the root. Their matches are unioned in pattern order, retaining
 registry order within each pattern and removing duplicates at first occurrence.
 Each pattern is independent: a negated minimatch pattern matches its complement;
-it does not subtract earlier matches or implement CodeMode's last-rule-wins
-exposure policy. Coordinator Tools remain separately controlled by delegation.
+it does not subtract earlier matches. Coordinator Tools remain separately controlled by delegation.
 
 Invalid configuration entries and patterns matching no permitted ordinary tools
 warn and are skipped. Configured tools unavailable in child resources are also
@@ -206,11 +206,15 @@ still apply; the saved grant is not silently rewritten. Toolsets configure names
 not tool operations: granting `lsp`, `dap`, or another multifunction tool grants
 that tool's available operations, regardless of preset name.
 
-CodeMode still controls whether a granted tool is direct, CodeMode-only, or both.
-If a child needs CodeMode-only tools, also grant `codemode_*` in its toolsets so
-it has the tools needed to discover and call them. This does not bypass CodeMode's
-own restrictions on nested calls. Exposure rules also apply to injected
-Coordinator Tools; delegation still determines which Coordinator Tools are granted.
+Child Agents load Pi's built-in `codemode`, `tool-search`, and `mcp` extensions
+unless settings disable them (`-builtin:<name>`); each child connects its own MCP
+servers. A tool's exposure still decides whether it is declared or reachable only
+through `codemode` or `tool_search`. Granted `codemode`- or `deferred`-exposed
+tools are callable but not declared, so a child that needs them also needs
+`codemode` or `tool_search` in its grant. Ungranted tools are unreachable in the
+child. MCP tools are checked at launch only by name, because children register
+them after connecting; a tool whose server disappeared fails when called. Closing
+a child runtime shuts its extensions down, closing its MCP connections.
 
 ## Capabilities and persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,11 +31,8 @@
     "provenance": true
   },
   "dependencies": {
-    "minimatch": "^10.2.6",
-    "proper-lockfile": "^4.1.2"
-  },
-  "devDependencies": {
-    "@types/proper-lockfile": "^4.1.4"
+    "@ian-pascoe/pi-utils": "^0.3.0",
+    "minimatch": "^10.2.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",

package/src/minimal-subagents-child-resources.ts

@@ -1,4 +1,5 @@
 import { dirname } from "node:path";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { canonicalPath } from "./minimal-subagents-paths.js";
 import type { ProjectContextMode } from "./minimal-subagents-types.js";
@@ -12,6 +13,25 @@ export interface ChildResourceLoaderOptions {
   settingsManager?: SettingsManager;
 }
 
+type InlineExtension = NonNullable<
+  ConstructorParameters<typeof DefaultResourceLoader>[0]["extensionFactories"]
+>[number];
+
+/** Pi's exported built-in extensions (Pi 0.99+); older hosts have none, so neither do children. */
+export function childBuiltinExtensions(): InlineExtension[] {
+  // SAFETY: Older Pi hosts lack these exports; the namespace yields undefined rather than failing.
+  const sdk = piCodingAgent as Partial<typeof piCodingAgent>;
+  return (
+    [
+      ["codemode", sdk.createCodemodeExtension],
+      ["tool-search", sdk.createToolSearchExtension],
+      ["mcp", sdk.createMcpExtension],
+    ] as const
+  ).flatMap(([name, create]) =>
+    create ? [{ name, factory: create(), builtin: true, replaceable: true }] : [],
+  );
+}
+
 function createDefaultChildResourceLoaderOptions(
   input: ChildResourceLoaderOptions,
 ): ConstructorParameters<typeof DefaultResourceLoader>[0] {
@@ -24,6 +44,7 @@ function createDefaultChildResourceLoaderOptions(
     noContextFiles: false,
     noSkills: false,
     noPromptTemplates: false,
+    extensionFactories: childBuiltinExtensions(),
     extensionsOverride: (base) => ({
       ...base,
       extensions: base.extensions.filter(

package/src/minimal-subagents-coordinator.ts

@@ -570,7 +570,7 @@ export class MinimalSubagentsCoordinator {
       const runtime = this.runtimes.get(agent.agent_id);
       try {
         if (agent.active_turn_id) await this.cancelActiveTurn(agent);
-        runtime?.dispose();
+        await runtime?.dispose();
         this.runtimes.delete(agent.agent_id);
         if (agent.session_file) {
           await this.dependencies.sessions.trashSession(agent);
@@ -622,7 +622,7 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(
       abandonedRuntimes.map((runtime) => (runtime.isRunning ? runtime.abort() : Promise.resolve())),
     );
-    for (const runtime of abandonedRuntimes) runtime.dispose();
+    for (const runtime of abandonedRuntimes) await runtime.dispose();
     this.runtimes.clear();
     this.runtimeInitializations.clear();
     this.pendingAgentIds.clear();
@@ -892,7 +892,7 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(this.runtimeInitializations.values());
     await Promise.allSettled(this.backgroundOperations);
     await Promise.allSettled(this.recipientQueues.values());
-    for (const runtime of this.runtimes.values()) runtime.dispose();
+    for (const runtime of this.runtimes.values()) await runtime.dispose();
     this.runtimes.clear();
   }
 
@@ -910,7 +910,7 @@ export class MinimalSubagentsCoordinator {
       const runtime = await this.ensureRuntime(agent);
       if (this.agents.get(agentId) !== agent || agent.active_turn_id !== turnId) {
         if (!this.agents.has(agentId) || !this.acceptingOperations) {
-          runtime.dispose();
+          await runtime.dispose();
           this.runtimes.delete(agentId);
         }
         return;
@@ -943,13 +943,13 @@ export class MinimalSubagentsCoordinator {
     const openingForTurn = agent.active_turn_id !== undefined;
     const initialization = this.dependencies.sessions
       .openRuntime(agent)
-      .then((runtime) => {
+      .then(async (runtime) => {
         if (this.agents.get(agent.agent_id) !== agent) {
-          runtime.dispose();
+          await runtime.dispose();
           throw new Error(`Minimal subagents runtime replaced while opening ${agent.agent_id}`);
         }
         if (!runtime.sessionLeafId) {
-          runtime.dispose();
+          await runtime.dispose();
           throw new Error(
             `Minimal subagents session restoration: no selected session leaf for ${agent.agent_id}`,
           );

package/src/minimal-subagents-extension.ts

@@ -63,7 +63,7 @@ import {
   unavailableAgent,
 } from "./minimal-subagents-sessions.js";
 import { shutdownMinimalSubagentsSession } from "./minimal-subagents-shutdown.js";
-import { MinimalSubagentsSettingsWriter } from "./minimal-subagents-settings-writer.js";
+import { writeMinimalSubagentsEnabled } from "./minimal-subagents-settings-writer.js";
 import {
   MinimalSubagentsStatusPanelController,
   type MinimalSubagentsStatusAccess,
@@ -80,6 +80,7 @@ import { MinimalSubagentsUiController } from "./minimal-subagents-ui.js";
 import type {
   AgentSessionFactory,
   CallerSnapshot,
+  ChildSessionObserver,
   CoordinatorNotification,
   ForkSnapshot,
   PersistedAgent,
@@ -137,16 +138,39 @@ function currentConversationMessages(context: ExtensionContext): AgentMessage[]
   return snapshotCommittedContext(messages, !context.isIdle());
 }
 
+export function availableToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] {
+  return excludeCoordinatorTools(
+    pi
+      .getAllTools()
+      .filter((tool) => tool.exposure !== "hidden")
+      .map((tool) => tool.name),
+  );
+}
+
+/** Reachable Tools: active tools plus tools scripts can call without declaring them. */
+export function reachableToolNames(
+  pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
+): string[] {
+  const active = new Set(pi.getActiveTools());
+  return excludeCoordinatorTools(
+    pi
+      .getAllTools()
+      .filter(
+        (tool) =>
+          active.has(tool.name) || tool.exposure === "codemode" || tool.exposure === "deferred",
+      )
+      .map((tool) => tool.name),
+  );
+}
+
 function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): CallerSnapshot {
   if (!context.model) throw new Error("Minimal subagents spawn: root has no effective model");
-  const activeTools = excludeCoordinatorTools(pi.getActiveTools());
-  const availableTools = excludeCoordinatorTools(pi.getAllTools().map((tool) => tool.name));
   return {
     messages: currentConversationMessages(context),
     model: `${context.model.provider}/${context.model.id}`,
     thinkingLevel: context.thinkingLevel ?? pi.getThinkingLevel(),
-    ordinaryTools: activeTools,
-    capabilityCeiling: availableTools,
+    ordinaryTools: reachableToolNames(pi),
+    capabilityCeiling: availableToolNames(pi),
     spawnEntryId: context.sessionManager.getLeafId() ?? "root",
   };
 }
@@ -560,9 +584,6 @@ export class MinimalSubagentsLifecycleController {
     ) {
       models.push(context.model);
     }
-    const availableToolNames = excludeCoordinatorTools(
-      this.pi.getAllTools().map((tool) => tool.name),
-    );
     const schemas = createCoordinatorToolSchemas(eligibleModelIds);
     let activeCoordinator: MinimalSubagentsCoordinator | undefined;
     const requireActiveCoordinator = (): MinimalSubagentsCoordinator => {
@@ -580,11 +601,24 @@ export class MinimalSubagentsLifecycleController {
       models,
       eligibleModelIds,
       modelScopeRestricted: enabledModelPatterns !== undefined,
-      availableToolNames,
+      availableToolNames: availableToolNames(this.pi),
       getRuntimeToolAdapters: () => codexConversionRuntimeToolAdapters(this.pi),
       projectTrusted: context.isProjectTrusted(),
       maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
       onChildSessionActivity: () => activeCoordinator?.scheduleDeliveryReconciliation(),
+      observeSession: (session, agentId, resourceInputs) => {
+        let observer: ChildSessionObserver | undefined;
+        this.pi.events.emit("pi-minimal-subagents:observe-session", {
+          rootSessionId,
+          agentId,
+          session,
+          resourceInputs,
+          attach: (attached: ChildSessionObserver) => {
+            observer = attached;
+          },
+        });
+        return observer;
+      },
       getCoordinatorTools: (callerId) => {
         const coordinator = requireActiveCoordinator();
         return createCoordinatorToolDefinitions({
@@ -802,15 +836,15 @@ export class MinimalSubagentsLifecycleController {
 
     let persistedScope: "global" | "project" | undefined;
     if (command.scope !== "session") {
-      const writeResult = await new MinimalSubagentsSettingsWriter(
-        context,
-        () => accessSession.agentDir,
-      ).writeMinimalSubagentsEnabled(
-        command.scope,
-        command.action === "reset" ? undefined : command.action === "enable",
-      );
-      if (!writeResult.ok) {
-        context.ui.notify(writeResult.error.message, "error");
+      try {
+        await writeMinimalSubagentsEnabled(
+          context,
+          accessSession.agentDir,
+          command.scope,
+          command.action === "reset" ? undefined : command.action === "enable",
+        );
+      } catch (error) {
+        context.ui.notify(error instanceof Error ? error.message : String(error), "error");
         return;
       }
       persistedScope = command.scope;

package/src/minimal-subagents-sessions.ts

@@ -17,6 +17,7 @@ import {
   SettingsManager,
   sessionEntryToContextMessages,
   type AgentSessionEvent,
+  type Extension,
   type SessionEntry,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
@@ -53,6 +54,7 @@ import { addMinimalSubagentsUsage } from "./minimal-subagents-usage.js";
 import type {
   AgentSessionFactory,
   ChildAgentRuntime,
+  ChildSessionObserver,
   ChildAgentTranscriptSnapshot,
   CoordinatorMessage,
   PersistedAgent,
@@ -96,6 +98,18 @@ export interface RuntimeToolAdapter {
   readonly replacements: readonly RuntimeToolReplacement[];
 }
 
+const MCP_RESOURCE_TOOL_NAMES = new Set([
+  "list_mcp_resources",
+  "list_mcp_resource_templates",
+  "read_mcp_resource",
+]);
+
+// ponytail: Pi's built-in MCP registers tools only after connecting, so launch checks accept its
+// tool names unverified; a vanished server's tools fail when called instead of at launch.
+function isMcpToolName(toolName: string): boolean {
+  return toolName.startsWith("mcp__") || MCP_RESOURCE_TOOL_NAMES.has(toolName);
+}
+
 /** Resolve the exact active tools permitted by one Child Agent Launch Contract. */
 export function resolveChildActiveToolNames(
   allowedToolNames: readonly string[],
@@ -130,24 +144,24 @@ function installChildToolCapabilityPolicy(
   session: AgentSession,
   allowedToolNames: readonly string[],
   runtimeToolAdapters: readonly RuntimeToolAdapter[],
-  preserveGrantedTools = true,
 ): void {
+  const isScriptOnly = (name: string) => {
+    const exposure = session.getAllTools().find((tool) => tool.name === name)?.exposure;
+    return exposure === "codemode" || exposure === "deferred";
+  };
   const applyActiveTools = session.setActiveToolsByName.bind(session);
   session.setActiveToolsByName = (requestedToolNames) => {
-    const permitted = resolveChildActiveToolNames(
-      allowedToolNames,
-      requestedToolNames,
-      runtimeToolAdapters,
-    );
-    // Inside an exposure wrapper, ordinary tools may intentionally be hidden. The
-    // outer policy restores grants before that wrapper applies its own selection.
+    const requested = new Set(requestedToolNames);
+    // Granted declared tools stay active; `codemode` and `deferred` grants stay
+    // callable without being declared unless an extension activates them.
     applyActiveTools(
-      preserveGrantedTools
-        ? permitted
-        : permitted.filter((name) => requestedToolNames.includes(name)),
+      resolveChildActiveToolNames(allowedToolNames, requestedToolNames, runtimeToolAdapters).filter(
+        (name) => requested.has(name) || !isScriptOnly(name),
+      ),
     );
   };
-  session.setActiveToolsByName(session.getActiveToolNames());
+  // Pi's `tools` option also activates script-only grants; drop them before extensions bind.
+  session.setActiveToolsByName(session.getActiveToolNames().filter((name) => !isScriptOnly(name)));
 }
 
 /** Moves one verified child session file to trash and reports command unavailability. */
@@ -180,6 +194,15 @@ export interface PiAgentSessionFactoryOptions {
   sessionFileTrash?: SessionFileTrashCapability;
   getCoordinatorTools: (callerId: string) => ToolDefinition[];
   onChildSessionActivity?: () => void;
+  observeSession?: (
+    session: AgentSession,
+    agentId: string,
+    resourceInputs: {
+      agentDir: string;
+      extensions: readonly Pick<Extension, "path" | "resolvedPath" | "sourceInfo" | "hidden">[];
+      flagValues: ReadonlyMap<string, boolean | string>;
+    },
+  ) => ChildSessionObserver | undefined;
 }
 
 /** Build one child prompt using the active delegation depth rather than persisted launch state. */
@@ -494,7 +517,7 @@ function collectChildTurnOutcome(
       error: "No terminal assistant response",
     };
   }
-  if (finalAssistant.stopReason === "aborted") {
+  if (aborted || finalAssistant.stopReason === "aborted") {
     return {
       status: "cancelled",
       output: assistantText(finalAssistant),
@@ -554,6 +577,7 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     private readonly modelRuntime: ModelRuntime,
     private readonly modelById: ReadonlyMap<string, Model<any>>,
     onSessionActivity?: () => void,
+    private readonly observer?: ChildSessionObserver,
   ) {
     // Keep this child-only; AgentSession.setSteeringMode would overwrite the user's global setting.
     session.agent.steeringMode = "all";
@@ -613,12 +637,21 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
 
   async abort(): Promise<void> {
     this.aborted = true;
-    await this.session.abort();
+    await Promise.all([this.observer?.abort(), this.session.abort()]);
   }
 
-  dispose(): void {
+  async dispose(): Promise<void> {
     this.unsubscribe();
-    this.session.dispose();
+    try {
+      await this.observer?.dispose();
+      // Let child extensions release services such as MCP server connections.
+      const runner = this.session.extensionRunner;
+      if (runner.hasHandlers("session_shutdown")) {
+        await runner.emit({ type: "session_shutdown", reason: "quit" });
+      }
+    } finally {
+      this.session.dispose();
+    }
   }
 
   getRuntimeProfile(): RuntimeProfile | undefined {
@@ -715,7 +748,20 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
 
   private async captureTurn(operation: () => Promise<void>): Promise<RuntimeTurnOutcome> {
     this.aborted = false;
-    return captureChildTurnOutcome(this.session, operation, () => this.aborted);
+    this.observer?.beginTurn();
+    return captureChildTurnOutcome(
+      this.session,
+      async () => {
+        try {
+          await operation();
+          if (!this.aborted) await this.observer?.finishTurn();
+        } catch (error) {
+          await this.observer?.abort();
+          throw error;
+        }
+      },
+      () => this.aborted,
+    );
   }
 
   private async compactImportedContext(
@@ -1098,6 +1144,11 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       await resourceLoader.reload();
       for (const extension of resourceLoader.getExtensions().extensions) {
         for (const toolName of extension.tools.keys()) names.add(toolName);
+        if (extension.path === "builtin:mcp") {
+          for (const toolName of agent.launch_contract.ordinary_tools) {
+            if (isMcpToolName(toolName)) names.add(toolName);
+          }
+        }
       }
       return names;
     })();
@@ -1145,7 +1196,6 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
     ];
     const runtimeToolAdapters = this.options.getRuntimeToolAdapters?.() ?? [];
     const adapterToolNames = new Set(runtimeToolAdapters.flatMap((adapter) => adapter.toolNames));
-    const adaptRuntimeTools = adapterToolNames.size > 0;
     const { session } = await createAgentSession({
       cwd: this.options.cwd,
       agentDir: this.options.agentDir,
@@ -1158,20 +1208,16 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       settingsManager,
       modelRuntime,
     });
-    if (adaptRuntimeTools) session.setActiveToolsByName(allowedToolNames);
-    const initialActiveNames = new Set(session.getActiveToolNames());
-    const missingTools = allowedToolNames.filter((toolName) => !initialActiveNames.has(toolName));
+    const loadedNames = new Set(session.getAllTools().map((tool) => tool.name));
+    const missingTools = allowedToolNames.filter(
+      (toolName) => !loadedNames.has(toolName) && !isMcpToolName(toolName),
+    );
     if (missingTools.length > 0) {
       session.dispose();
       throw new Error(`Minimal subagents child tool loading failed: ${missingTools.join(", ")}`);
     }
-    // The inner policy bounds extension-selected exposure without restoring hidden ordinary tools.
-    installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters, false);
-    await session.bindExtensions({ mode: "print" });
-    // The outer policy filters names before extension wrappers build their own tool catalogues.
     installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
-    // Exposure policy may route granted Coordinator Tools through another tool;
-    // require their definitions to remain registered, not necessarily direct.
+    await session.bindExtensions({ mode: "print" });
     const registeredNames = new Set(session.getAllTools().map((tool) => tool.name));
     const missingCoordinatorTools = coordinatorTools
       .map((tool) => tool.name)
@@ -1187,6 +1233,18 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       modelRuntime,
       this.modelById,
       this.options.onChildSessionActivity,
+      this.options.observeSession?.(session, agent.agent_id, {
+        agentDir: this.options.agentDir,
+        extensions: resourceLoader
+          .getExtensions()
+          .extensions.map(({ path, resolvedPath, sourceInfo, hidden }) => ({
+            path,
+            resolvedPath,
+            sourceInfo,
+            hidden,
+          })),
+        flagValues: new Map(resourceLoader.getExtensions().runtime.flagValues),
+      }),
     );
   }
 

package/src/minimal-subagents-settings-writer.ts

@@ -1,308 +1,72 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
-import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import lockfile from "proper-lockfile";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { updateFileLocked } from "@ian-pascoe/pi-utils/locked-file-update";
+import { resolve } from "node:path";
 
 /** Identifies the standard Pi settings file changed by a Subagent Access command. */
 export type MinimalSubagentsSettingsScope = "global" | "project";
 
-/** Describes why a scoped minimal subagents settings write could not complete. */
-export type MinimalSubagentsSettingsWriteFailureReason =
-  | "project-untrusted"
-  | "malformed-json"
-  | "incompatible-shape"
-  | "filesystem";
-
-/** Reports an expected scoped settings failure without throwing through the command boundary. */
-export class MinimalSubagentsSettingsWriteError extends Error {
-  readonly _tag = "MinimalSubagentsSettingsWriteError" as const;
-
-  /** Create a settings write failure carrying its exact scope and path. */
-  constructor(
-    readonly scope: MinimalSubagentsSettingsScope,
-    readonly path: string,
-    readonly reason: MinimalSubagentsSettingsWriteFailureReason,
-    message: string,
-    readonly operation?: SettingsFilesystemOperation,
-    cause?: unknown,
-  ) {
-    super(message, cause === undefined ? undefined : { cause });
-  }
-}
-
-/** Returns the path changed by a successful write or a typed expected settings failure. */
-export type MinimalSubagentsSettingsWriteResult =
-  | {
-      readonly ok: true;
-      readonly scope: MinimalSubagentsSettingsScope;
-      readonly path: string;
-    }
-  | {
-      readonly ok: false;
-      readonly error: MinimalSubagentsSettingsWriteError;
-    };
-
 /** Supplies only the Root Agent context needed to select and authorize a settings file. */
 export interface MinimalSubagentsSettingsWriteContext {
   readonly cwd: string;
   isProjectTrusted(): boolean;
 }
 
-type SettingsFilesystemOperation = "prepare" | "lock" | "read" | "write" | "release";
 type SettingsJsonObject = Record<string, JsonValue>;
 
-type ParsedSettingsDocument =
-  | { readonly ok: true; readonly settings: SettingsJsonObject }
-  | { readonly ok: false; readonly error: MinimalSubagentsSettingsWriteError };
-
-interface ExistingSettingsDocument {
-  readonly settings: SettingsJsonObject;
-  readonly mode: number;
-}
-
 function isSettingsJsonObject(value: JsonValue | undefined): value is SettingsJsonObject {
   // oxlint-disable-next-line anti-slop/no-runtime-typeof -- JSON.parse already established JSON data; distinguish object roots and settings blocks from primitives and arrays.
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-const SETTINGS_LOCK_RETRY_DELAY_MS = 20;
-const SETTINGS_LOCK_RETRIES = 100;
-const NEW_SETTINGS_FILE_MODE = 0o600;
-
-function stripUtf8Bom(content: string): string {
-  return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
-}
 
-function settingsContractError(
-  scope: MinimalSubagentsSettingsScope,
-  path: string,
-  detail: string,
-): MinimalSubagentsSettingsWriteError {
-  return new MinimalSubagentsSettingsWriteError(
-    scope,
-    path,
-    "incompatible-shape",
-    `Minimal subagents settings shape is incompatible for ${scope} settings at ${path}: ${detail}`,
-  );
-}
-
-function parseSettingsDocument(
-  content: string,
-  scope: MinimalSubagentsSettingsScope,
-  path: string,
-): ParsedSettingsDocument {
+function parseSettings(content: string | undefined, path: string): SettingsJsonObject {
+  if (content === undefined) return {};
   // JSON.parse is the provenance for this JSON type; the object shape is checked below.
   let parsed: JsonValue;
   try {
-    parsed = JSON.parse(stripUtf8Bom(content));
+    parsed = JSON.parse(content.charCodeAt(0) === 0xfeff ? content.slice(1) : content);
   } catch (cause) {
-    return {
-      ok: false,
-      error: new MinimalSubagentsSettingsWriteError(
-        scope,
-        path,
-        "malformed-json",
-        `Minimal subagents settings JSON is malformed for ${scope} settings at ${path}`,
-        "read",
-        cause,
-      ),
-    };
+    throw new Error(`Minimal subagents settings JSON is malformed at ${path}`, { cause });
   }
-
   if (!isSettingsJsonObject(parsed)) {
-    return { ok: false, error: settingsContractError(scope, path, "expected an object root") };
-  }
-  const minimalSubagents = parsed.minimalSubagents;
-  if (minimalSubagents !== undefined && !isSettingsJsonObject(minimalSubagents)) {
-    return {
-      ok: false,
-      error: settingsContractError(
-        scope,
-        path,
-        "expected minimalSubagents to be an object or absent",
-      ),
-    };
-  }
-  return { ok: true, settings: parsed };
-}
-
-function mutateMinimalSubagentsEnabled(
-  settings: SettingsJsonObject,
-  enabled: boolean | undefined,
-): void {
-  const currentMinimalSubagents = settings.minimalSubagents;
-  const minimalSubagents = isSettingsJsonObject(currentMinimalSubagents)
-    ? currentMinimalSubagents
-    : {};
-
-  if (enabled === undefined) {
-    delete minimalSubagents.enabled;
-  } else {
-    minimalSubagents.enabled = enabled;
+    throw new Error(`Minimal subagents settings at ${path} must have an object root`);
   }
-
-  if (Object.keys(minimalSubagents).length === 0) {
-    delete settings.minimalSubagents;
-  } else {
-    settings.minimalSubagents = minimalSubagents;
-  }
-}
-
-function filesystemWriteError(
-  scope: MinimalSubagentsSettingsScope,
-  path: string,
-  operation: SettingsFilesystemOperation,
-  cause: unknown,
-): MinimalSubagentsSettingsWriteError {
-  return new MinimalSubagentsSettingsWriteError(
-    scope,
-    path,
-    "filesystem",
-    `Minimal subagents settings ${operation} failed for ${scope} settings at ${path}`,
-    operation,
-    cause,
-  );
-}
-
-async function readSettingsDocumentUnderLock(
-  scope: MinimalSubagentsSettingsScope,
-  path: string,
-): Promise<ExistingSettingsDocument | MinimalSubagentsSettingsWriteError> {
-  let fileMode = NEW_SETTINGS_FILE_MODE;
-  let content: string;
-  try {
-    const fileStat = await stat(path);
-    fileMode = fileStat.mode & 0o7777;
-    content = await readFile(path, "utf8");
-  } catch (cause) {
-    if (isNodeErrorWithCode(cause, "ENOENT")) return { settings: {}, mode: fileMode };
-    return filesystemWriteError(scope, path, "read", cause);
-  }
-
-  const parsed = parseSettingsDocument(content, scope, path);
-  return parsed.ok ? { settings: parsed.settings, mode: fileMode } : parsed.error;
-}
-
-function isNodeErrorWithCode(cause: unknown, code: string): boolean {
-  return cause instanceof Error && "code" in cause && cause.code === code;
-}
-
-async function replaceSettingsFileAtomically(
-  path: string,
-  settings: SettingsJsonObject,
-  mode: number,
-  temporaryId: string,
-): Promise<void> {
-  const temporaryPath = join(dirname(path), `.${basename(path)}.${process.pid}.${temporaryId}.tmp`);
-  let temporaryFile: Awaited<ReturnType<typeof open>> | undefined;
-  try {
-    temporaryFile = await open(temporaryPath, "wx", mode);
-    await temporaryFile.chmod(mode);
-    await temporaryFile.writeFile(`${JSON.stringify(settings, undefined, 2)}\n`, "utf8");
-    await temporaryFile.sync();
-    await temporaryFile.close();
-    temporaryFile = undefined;
-    await rename(temporaryPath, path);
-  } catch (cause) {
-    if (temporaryFile !== undefined) await temporaryFile.close().catch(() => undefined);
-    await rm(temporaryPath, { force: true }).catch(() => undefined);
-    throw cause;
+  if (parsed.minimalSubagents !== undefined && !isSettingsJsonObject(parsed.minimalSubagents)) {
+    throw new Error(`Minimal subagents settings at ${path} must have an object minimalSubagents`);
   }
+  return parsed;
 }
 
 /**
- * Mutates only `minimalSubagents.enabled` in global or trusted-project Pi settings.
- * Calls targeting the same file are serialized in process and re-read while holding Pi's lock.
+ * Set or remove `minimalSubagents.enabled` in global or trusted-project Pi settings,
+ * preserving every unrelated setting. Writes re-read the file under Pi's settings lock.
+ * @returns The changed settings path.
  */
-export class MinimalSubagentsSettingsWriter {
-  private readonly globalSettingsPath: string;
-  private readonly projectSettingsPath: string;
-
-  /** Bind settings paths to one Root Agent context; the directory supplier exists for isolated tests. */
-  constructor(
-    private readonly context: MinimalSubagentsSettingsWriteContext,
-    getAgentDirectory: () => string = getAgentDir,
-    private readonly createTemporaryId: () => string = randomUUID,
-  ) {
-    this.globalSettingsPath = resolve(getAgentDirectory(), "settings.json");
-    this.projectSettingsPath = resolve(context.cwd, CONFIG_DIR_NAME, "settings.json");
-  }
-
-  /** Set or remove one authored Subagent Access default, preserving every unrelated setting. */
-  async writeMinimalSubagentsEnabled(
-    scope: MinimalSubagentsSettingsScope,
-    enabled: boolean | undefined,
-  ): Promise<MinimalSubagentsSettingsWriteResult> {
-    const path = scope === "global" ? this.globalSettingsPath : this.projectSettingsPath;
-    if (scope === "project" && !this.context.isProjectTrusted()) {
-      return {
-        ok: false,
-        error: new MinimalSubagentsSettingsWriteError(
-          scope,
-          path,
-          "project-untrusted",
-          `Minimal subagents project settings write refused because the project is not trusted: ${path}`,
-        ),
-      };
-    }
-
-    return this.writeEnabledUnderLock(scope, path, enabled);
+export async function writeMinimalSubagentsEnabled(
+  context: MinimalSubagentsSettingsWriteContext,
+  agentDirectory: string,
+  scope: MinimalSubagentsSettingsScope,
+  enabled: boolean | undefined,
+): Promise<string> {
+  const path =
+    scope === "global"
+      ? resolve(agentDirectory, "settings.json")
+      : resolve(context.cwd, CONFIG_DIR_NAME, "settings.json");
+  if (scope === "project" && !context.isProjectTrusted()) {
+    throw new Error(
+      `Minimal subagents project settings write refused because the project is not trusted: ${path}`,
+    );
   }
 
-  private async writeEnabledUnderLock(
-    scope: MinimalSubagentsSettingsScope,
-    path: string,
-    enabled: boolean | undefined,
-  ): Promise<MinimalSubagentsSettingsWriteResult> {
-    try {
-      await mkdir(dirname(path), { recursive: true });
-    } catch (cause) {
-      return { ok: false, error: filesystemWriteError(scope, path, "prepare", cause) };
-    }
-
-    let release: (() => Promise<void>) | undefined;
-    try {
-      release = await lockfile.lock(path, {
-        realpath: false,
-        retries: {
-          retries: SETTINGS_LOCK_RETRIES,
-          factor: 1,
-          minTimeout: SETTINGS_LOCK_RETRY_DELAY_MS,
-          maxTimeout: SETTINGS_LOCK_RETRY_DELAY_MS,
-          randomize: false,
-        },
-      });
-    } catch (cause) {
-      return { ok: false, error: filesystemWriteError(scope, path, "lock", cause) };
-    }
-
-    let result: MinimalSubagentsSettingsWriteResult;
-    try {
-      const existing = await readSettingsDocumentUnderLock(scope, path);
-      if (existing instanceof MinimalSubagentsSettingsWriteError) {
-        result = { ok: false, error: existing };
-      } else {
-        try {
-          mutateMinimalSubagentsEnabled(existing.settings, enabled);
-          await replaceSettingsFileAtomically(
-            path,
-            existing.settings,
-            existing.mode,
-            this.createTemporaryId(),
-          );
-          result = { ok: true, scope, path };
-        } catch (cause) {
-          result = { ok: false, error: filesystemWriteError(scope, path, "write", cause) };
-        }
-      }
-    } finally {
-      try {
-        await release();
-      } catch (cause) {
-        result = { ok: false, error: filesystemWriteError(scope, path, "release", cause) };
-      }
-    }
-    return result;
-  }
+  await updateFileLocked(path, (content) => {
+    const settings = parseSettings(content, path);
+    const current = settings.minimalSubagents;
+    const minimalSubagents = isSettingsJsonObject(current) ? { ...current } : {};
+    if (enabled === undefined) delete minimalSubagents.enabled;
+    else minimalSubagents.enabled = enabled;
+    if (Object.keys(minimalSubagents).length === 0) delete settings.minimalSubagents;
+    else settings.minimalSubagents = minimalSubagents;
+    return `${JSON.stringify(settings, undefined, 2)}\n`;
+  });
+  return path;
 }

package/src/minimal-subagents-tools.ts

@@ -125,6 +125,7 @@ function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   return {
     content: [{ type: "text" as const, text: truncated.content }],
     details: result,
+    structuredContent: JSON.parse(json),
   };
 }
 
@@ -235,13 +236,15 @@ export function createCoordinatorToolDefinitions(
             signal,
             parameters.turn_id,
           );
+          const details = {
+            ...result,
+            source_agent_id: result.agent_id,
+            source_turn_id: result.turn_id,
+          };
           return {
             ...structuredToolResult(result),
-            details: {
-              ...result,
-              source_agent_id: result.agent_id,
-              source_turn_id: result.turn_id,
-            },
+            details,
+            structuredContent: JSON.parse(JSON.stringify(details)),
           };
         });
       } finally {

package/src/minimal-subagents-types.ts

@@ -224,6 +224,14 @@ export interface CoordinatorMessage {
   };
 }
 
+/** Optional review work attached by the root and awaited by the existing child owner. */
+export interface ChildSessionObserver {
+  beginTurn(): void;
+  finishTurn(): Promise<void>;
+  abort(): Promise<void>;
+  dispose(): Promise<void>;
+}
+
 /** Process-local adapter around one SDK-created Pi child session. */
 export interface ChildAgentRuntime {
   readonly sessionLeafId: string | undefined;
@@ -238,7 +246,7 @@ export interface ChildAgentRuntime {
   /** Queue one typed coordinator message into the child session. */
   queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
   abort(): Promise<void>;
-  dispose(): void;
+  dispose(): void | Promise<void>;
   /** Return the live Runtime Profile, or undefined when the SDK session has no model. */
   getRuntimeProfile(): RuntimeProfile | undefined;
   /** Return the effective ordinary tools after child extensions apply runtime adapters. */