@ian-pascoe/pi-minimal-subagents 0.9.0 → 0.10.1

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.9.0",
+  "version": "0.10.1",
   "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/skills/pi-minimal-subagents/SKILL.md

@@ -2,6 +2,7 @@
 name: pi-minimal-subagents
 description: Configure or diagnose Pi Minimal Subagents for Subagent Access, missing Coordinator Tools, spawn, capability, delivery, wait, restore, reload, or fork failures.
 license: MIT
+disable-model-invocation: true
 ---
 
 # Pi Minimal Subagents

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

@@ -34,6 +34,7 @@ import {
   type DeliveryLedger,
   type DeliveryLedgerTransition,
 } from "./minimal-subagents-delivery-ledger.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
 import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
@@ -264,7 +265,9 @@ export class MinimalSubagentsCoordinator {
       const requiredMissing = missingDependencies.filter((name) => !optionalMissing.has(name));
       if (requiredMissing.length > 0) {
         throw new Error(
-          `Minimal subagents launch dependencies unavailable: ${requiredMissing.join(", ")}`,
+          withTroubleshootingHint(
+            `Minimal subagents launch dependencies unavailable: ${requiredMissing.join(", ")}`,
+          ),
         );
       }
       if (optionalMissing.size > 0) {
@@ -381,7 +384,7 @@ export class MinimalSubagentsCoordinator {
         agent_id: targetId,
         message_id: messageId,
         disposition: "failed",
-        error: deliveryError,
+        error: withTroubleshootingHint(deliveryError),
       };
     }
   }
@@ -925,7 +928,7 @@ export class MinimalSubagentsCoordinator {
         turn_id: turnId,
         status: "failed",
         output: "",
-        error: error instanceof Error ? error.message : String(error),
+        error: withTroubleshootingHint(error instanceof Error ? error.message : String(error)),
       });
     }
   }
@@ -1366,7 +1369,7 @@ export class MinimalSubagentsCoordinator {
             turn_id: turnId,
             status: "failed",
             output: "",
-            error: cause instanceof Error ? cause.message : String(cause),
+            error: withTroubleshootingHint(cause instanceof Error ? cause.message : String(cause)),
           });
         }
       });
@@ -1634,12 +1637,16 @@ export class MinimalSubagentsCoordinator {
     const agent = this.requireAgent(agentId);
     if (agent.availability === "unavailable") {
       throw new Error(
-        agent.unavailable_reason ?? `Minimal subagents ${operation}: ${agentId} is unavailable`,
+        withTroubleshootingHint(
+          agent.unavailable_reason ?? `Minimal subagents ${operation}: ${agentId} is unavailable`,
+        ),
       );
     }
     if (agent.clone_error || !agent.session_file) {
       throw new Error(
-        `Minimal subagents ${operation}: ${agent.clone_error ?? `${agentId} has no child session`}`,
+        withTroubleshootingHint(
+          `Minimal subagents ${operation}: ${agent.clone_error ?? `${agentId} has no child session`}`,
+        ),
       );
     }
     return agent;

package/src/minimal-subagents-extension.ts

@@ -62,8 +62,9 @@ import {
   type RuntimeToolAdapter,
   unavailableAgent,
 } from "./minimal-subagents-sessions.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.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,
@@ -138,16 +139,42 @@ 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));
+  if (!context.model)
+    throw new Error(
+      withTroubleshootingHint("Minimal subagents spawn: root has no effective model"),
+    );
   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",
   };
 }
@@ -561,9 +588,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 => {
@@ -581,7 +605,7 @@ export class MinimalSubagentsLifecycleController {
       models,
       eligibleModelIds,
       modelScopeRestricted: enabledModelPatterns !== undefined,
-      availableToolNames,
+      availableToolNames: availableToolNames(this.pi),
       getRuntimeToolAdapters: () => codexConversionRuntimeToolAdapters(this.pi),
       projectTrusted: context.isProjectTrusted(),
       maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
@@ -816,15 +840,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

@@ -98,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[],
@@ -132,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. */
@@ -632,6 +644,11 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     this.unsubscribe();
     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();
     }
@@ -1127,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;
     })();
@@ -1174,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,
@@ -1187,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)

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

@@ -10,6 +10,7 @@ import {
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
+import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import {
   renderCoordinatorToolCall,
@@ -125,6 +126,7 @@ function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   return {
     content: [{ type: "text" as const, text: truncated.content }],
     details: result,
+    structuredContent: JSON.parse(json),
   };
 }
 
@@ -134,7 +136,7 @@ function failedStructuredOperation(prefix: string, result: DeleteResult): never
     maxBytes: DEFAULT_MAX_BYTES,
     maxLines: DEFAULT_MAX_LINES,
   });
-  throw new Error(`${prefix}: ${truncated.content}`);
+  throw new Error(withTroubleshootingHint(`${prefix}: ${truncated.content}`));
 }
 
 function callerSourceTurnId(
@@ -235,13 +237,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/troubleshooting-skill.ts

@@ -0,0 +1,14 @@
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of this package's user-invoked troubleshooting Skill. */
+export const TROUBLESHOOTING_SKILL_PATH = fileURLToPath(
+  new URL("../skills/pi-minimal-subagents/SKILL.md", import.meta.url),
+);
+
+/** Model-facing pointer appended to failures this package's Skill diagnoses. */
+export const TROUBLESHOOTING_HINT = `For diagnosis, read the pi-minimal-subagents troubleshooting Skill at ${TROUBLESHOOTING_SKILL_PATH}.`;
+
+/** Append the troubleshooting Skill pointer to a model-facing configuration or runtime failure. */
+export function withTroubleshootingHint(message: string): string {
+  return `${message}\n\n${TROUBLESHOOTING_HINT}`;
+}