@ian-pascoe/pi-minimal-subagents 0.5.0 → 0.6.1

package/src/minimal-subagents-sessions.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, writeFileSync } from "node:fs";
 import { unlink } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
@@ -8,7 +8,6 @@ import { clampThinkingLevel } from "@earendil-works/pi-ai/compat";
 import {
   AgentSession,
   createAgentSession,
-  DefaultResourceLoader,
   estimateTokens,
   findCutPoint,
   generateSummaryWithUsage,
@@ -24,18 +23,22 @@ import type { Static, TSchema } from "typebox";
 import { Value } from "typebox/value";
 import {
   buildSubagentSystemPrompt,
+  selectChildAgentTranscript,
   snapshotCommittedContext,
 } from "./minimal-subagents-context.js";
 import {
   canAgentContractSpawn,
+  COORDINATOR_TOOL_NAMES,
   DEFAULT_MAX_SUBAGENT_DEPTH,
   getSubagentDepth,
 } from "./minimal-subagents-capabilities.js";
+import { createChildResourceLoader } from "./minimal-subagents-child-resources.js";
 import {
   CHILD_IDENTITY_ENTRY_TYPE,
   FORK_CLONE_ENTRY_TYPE,
   FORK_OWNERSHIP_ENTRY_TYPE,
 } from "./minimal-subagents-registry.js";
+import { canonicalPath } from "./minimal-subagents-paths.js";
 import {
   ChildSessionIdentityRecordSchema,
   DeliveryEvidenceDetailsSchema,
@@ -49,10 +52,10 @@ import { addMinimalSubagentsUsage } from "./minimal-subagents-usage.js";
 import type {
   AgentSessionFactory,
   ChildAgentRuntime,
+  ChildAgentTranscriptSnapshot,
   CoordinatorMessage,
   PersistedAgent,
   PersistedSessionIdentity,
-  ProjectContextMode,
   RuntimeProfile,
   RuntimeTurnOutcome,
 } from "./minimal-subagents-types.js";
@@ -75,14 +78,64 @@ interface PersistentIdentityOptions {
   rootSessionId: string;
 }
 
-interface ChildResourceLoaderOptionsInput {
-  cwd: string;
-  agentDir: string;
-  projectContext: ProjectContextMode;
-  extensionEntrypoint: string;
-  systemPromptBlock: string;
-  ordinaryToolNames?: readonly string[];
-  settingsManager?: SettingsManager;
+/** Replaces the complete source group only while every runtime tool is active. */
+export interface RuntimeToolReplacement {
+  /** Launch Contract tools required to authorize this replacement. */
+  readonly sourceToolNames: readonly string[];
+  /** Adapter tools that jointly replace the source group. */
+  readonly runtimeToolNames: readonly string[];
+}
+
+/** Identifies one configured extension allowed to replace Child Agent runtime tools. */
+export interface RuntimeToolAdapter {
+  /** Every tool registered by the adapter, used to defer initial tool selection until it loads. */
+  readonly toolNames: readonly string[];
+  /** Capability-preserving replacements recognized for this adapter. */
+  readonly replacements: readonly RuntimeToolReplacement[];
+}
+
+/** Resolve the exact active tools permitted by one Child Agent Launch Contract. */
+export function resolveChildActiveToolNames(
+  allowedToolNames: readonly string[],
+  requestedToolNames: readonly string[],
+  runtimeToolAdapters: readonly RuntimeToolAdapter[],
+): string[] {
+  const allowedNames = new Set(allowedToolNames);
+  const requestedNames = new Set(requestedToolNames);
+  const activeReplacements = runtimeToolAdapters
+    .flatMap((adapter) => adapter.replacements)
+    .filter((replacement) =>
+      replacement.sourceToolNames.every((toolName) => allowedNames.has(toolName)),
+    )
+    .filter((replacement) =>
+      replacement.runtimeToolNames.every((toolName) => requestedNames.has(toolName)),
+    );
+  const replacedSourceNames = new Set(
+    activeReplacements.flatMap((replacement) => replacement.sourceToolNames),
+  );
+  const activeRuntimeNames = new Set(
+    activeReplacements.flatMap((replacement) => replacement.runtimeToolNames),
+  );
+  return [
+    ...new Set([
+      ...allowedToolNames.filter((toolName) => !replacedSourceNames.has(toolName)),
+      ...requestedToolNames.filter((toolName) => activeRuntimeNames.has(toolName)),
+    ]),
+  ];
+}
+
+function installChildToolCapabilityPolicy(
+  session: AgentSession,
+  allowedToolNames: readonly string[],
+  runtimeToolAdapters: readonly RuntimeToolAdapter[],
+): void {
+  const applyActiveTools = session.setActiveToolsByName.bind(session);
+  session.setActiveToolsByName = (requestedToolNames) => {
+    applyActiveTools(
+      resolveChildActiveToolNames(allowedToolNames, requestedToolNames, runtimeToolAdapters),
+    );
+  };
+  session.setActiveToolsByName(session.getActiveToolNames());
 }
 
 /** Moves one verified child session file to trash and reports command unavailability. */
@@ -109,6 +162,7 @@ export interface PiAgentSessionFactoryOptions {
   eligibleModelIds: readonly string[];
   modelScopeRestricted: boolean;
   availableToolNames: readonly string[];
+  getRuntimeToolAdapters?: () => readonly RuntimeToolAdapter[];
   projectTrusted: boolean;
   maxSubagentDepth?: number;
   sessionFileTrash?: SessionFileTrashCapability;
@@ -131,12 +185,6 @@ export function buildDepthBoundSubagentPrompt(
   });
 }
 
-/** Canonicalize one path, resolving symlinks only when the target exists. */
-export function canonicalPath(path: string): string {
-  const absolutePath = resolve(path);
-  return existsSync(absolutePath) ? realpathSync(absolutePath) : absolutePath;
-}
-
 /** Build the shared unavailable-agent projection used by fork recovery and ownership binding. */
 export function unavailableAgent(
   agent: PersistedAgent,
@@ -358,48 +406,6 @@ export function verifyChildSessionIdentity(
   }
 }
 
-/** Build child resources while filtering recursive coordinator loading and honoring project-context omission. */
-export function createChildResourceLoaderOptions(
-  input: ChildResourceLoaderOptionsInput,
-): ConstructorParameters<typeof DefaultResourceLoader>[0] {
-  const extensionEntrypoint = canonicalPath(input.extensionEntrypoint);
-  const omitProjectContext = input.projectContext === "omit";
-  const ordinaryToolNames = new Set(input.ordinaryToolNames ?? []);
-  const loadOrdinaryToolExtensions = [...ordinaryToolNames].some(
-    (toolName) => !PI_BUILTIN_ORDINARY_TOOL_NAMES.has(toolName),
-  );
-  return {
-    cwd: input.cwd,
-    agentDir: input.agentDir,
-    settingsManager: input.settingsManager,
-    noExtensions: !loadOrdinaryToolExtensions,
-    noContextFiles: omitProjectContext,
-    noSkills: omitProjectContext,
-    noPromptTemplates: omitProjectContext,
-    extensionsOverride: loadOrdinaryToolExtensions
-      ? (base) => ({
-          ...base,
-          extensions: base.extensions.filter(
-            (extension) =>
-              canonicalPath(extension.resolvedPath) !== extensionEntrypoint &&
-              [...extension.tools.keys()].some((toolName) => ordinaryToolNames.has(toolName)),
-          ),
-          errors: base.errors.filter((error) => canonicalPath(error.path) !== extensionEntrypoint),
-        })
-      : undefined,
-    agentsFilesOverride: omitProjectContext ? () => ({ agentsFiles: [] }) : undefined,
-    skillsOverride: omitProjectContext
-      ? (base) => ({ skills: [], diagnostics: base.diagnostics })
-      : undefined,
-    promptsOverride: omitProjectContext
-      ? (base) => ({ prompts: [], diagnostics: base.diagnostics })
-      : undefined,
-    systemPromptOverride: omitProjectContext ? () => undefined : undefined,
-    appendSystemPromptOverride: (base) =>
-      omitProjectContext ? [input.systemPromptBlock] : [...base, input.systemPromptBlock],
-  };
-}
-
 /** Find durable keyed evidence for exactly-once wait or custom-result delivery. */
 export function findDeliveryEvidence(
   entries: readonly SessionEntry[],
@@ -579,15 +585,14 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
   }
 
   async queueCoordinatorMessage(message: CoordinatorMessage): Promise<void> {
-    await this.session.sendCustomMessage(
-      {
-        customType: message.customType,
-        content: message.content,
-        display: true,
-        details: message.details,
-      },
-      { triggerTurn: true, deliverAs: "steer" },
-    );
+    this.session.agent.steer({
+      role: "custom",
+      customType: message.customType,
+      content: message.content,
+      display: true,
+      details: message.details,
+      timestamp: Date.now(),
+    });
   }
 
   async abort(): Promise<void> {
@@ -609,6 +614,11 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     };
   }
 
+  getActiveToolNames(): string[] {
+    const coordinatorTools = new Set<string>(COORDINATOR_TOOL_NAMES);
+    return this.session.getActiveToolNames().filter((toolName) => !coordinatorTools.has(toolName));
+  }
+
   snapshotCommittedMessages(): AgentMessage[] {
     return snapshotCommittedContext(this.session.messages, this.session.isStreaming);
   }
@@ -618,6 +628,26 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     return [...this.session.messages, ...(streamingMessage ? [streamingMessage] : [])];
   }
 
+  snapshotActivityTranscript(): ChildAgentTranscriptSnapshot {
+    const snapshot = selectChildAgentTranscript(
+      this.session.messages,
+      this.session.state.streamingMessage,
+    );
+    const toolNames = new Set<string>();
+    for (const message of snapshot.messages) {
+      if (message.role !== "assistant") continue;
+      for (const content of message.content) {
+        if (content.type === "toolCall") toolNames.add(content.name);
+      }
+    }
+    return {
+      ...snapshot,
+      toolDefinitions: [...toolNames]
+        .map((toolName) => this.session.getToolDefinition(toolName))
+        .filter((definition) => definition !== undefined),
+    };
+  }
+
   hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean {
     return findDeliveryEvidence(
       this.session.sessionManager.getBranch(),
@@ -933,11 +963,7 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
   }
 
   private discoverChildToolNames(agent: PersistedAgent): Promise<Set<string>> {
-    const cacheKey = `${agent.launch_contract.project_context}:${[
-      ...agent.launch_contract.ordinary_tools,
-    ]
-      .sort()
-      .join(",")}`;
+    const cacheKey = [...agent.launch_contract.ordinary_tools].sort().join(",");
     const cached = this.discoveredToolNames.get(cacheKey);
     if (cached) return cached;
     const discovery = (async () => {
@@ -948,20 +974,15 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
         (name) => !PI_BUILTIN_ORDINARY_TOOL_NAMES.has(name),
       );
       if (!requiresCustomToolDiscovery) return names;
-      const settingsManager = SettingsManager.create(this.options.cwd, this.options.agentDir, {
-        projectTrusted: this.options.projectTrusted,
+      const settingsManager = this.createChildSettingsManager();
+      const resourceLoader = createChildResourceLoader({
+        cwd: this.options.cwd,
+        agentDir: this.options.agentDir,
+        projectContext: agent.launch_contract.project_context,
+        extensionEntrypoint: this.options.extensionEntrypoint,
+        systemPromptBlock: this.buildChildSystemPrompt(agent),
+        settingsManager,
       });
-      const resourceLoader = new DefaultResourceLoader(
-        createChildResourceLoaderOptions({
-          cwd: this.options.cwd,
-          agentDir: this.options.agentDir,
-          projectContext: agent.launch_contract.project_context,
-          extensionEntrypoint: this.options.extensionEntrypoint,
-          systemPromptBlock: this.buildChildSystemPrompt(agent),
-          ordinaryToolNames: agent.launch_contract.ordinary_tools,
-          settingsManager,
-        }),
-      );
       await resourceLoader.reload();
       for (const extension of resourceLoader.getExtensions().extensions) {
         for (const toolName of extension.tools.keys()) names.add(toolName);
@@ -981,23 +1002,18 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       throw new Error(
         `Minimal subagents restore: model unavailable: ${agent.launch_contract.model}`,
       );
-    const settingsManager = SettingsManager.create(this.options.cwd, this.options.agentDir, {
-      projectTrusted: this.options.projectTrusted,
-    });
+    const settingsManager = this.createChildSettingsManager();
     settingsManager.applyOverrides({
       retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
     });
-    const resourceLoader = new DefaultResourceLoader(
-      createChildResourceLoaderOptions({
-        cwd: this.options.cwd,
-        agentDir: this.options.agentDir,
-        projectContext: agent.launch_contract.project_context,
-        extensionEntrypoint: this.options.extensionEntrypoint,
-        systemPromptBlock: this.buildChildSystemPrompt(agent),
-        ordinaryToolNames: agent.launch_contract.ordinary_tools,
-        settingsManager,
-      }),
-    );
+    const resourceLoader = createChildResourceLoader({
+      cwd: this.options.cwd,
+      agentDir: this.options.agentDir,
+      projectContext: agent.launch_contract.project_context,
+      extensionEntrypoint: this.options.extensionEntrypoint,
+      systemPromptBlock: this.buildChildSystemPrompt(agent),
+      settingsManager,
+    });
     await resourceLoader.reload();
     const modelRuntime = await ModelRuntime.create({
       authPath: resolve(this.options.agentDir, "auth.json"),
@@ -1015,25 +1031,43 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       ...agent.launch_contract.ordinary_tools,
       ...coordinatorTools.map((tool) => tool.name),
     ];
+    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,
       model,
       thinkingLevel: agent.launch_contract.thinking_level,
-      tools: allowedToolNames,
+      tools: adaptRuntimeTools ? undefined : allowedToolNames,
       customTools: coordinatorTools,
       resourceLoader,
       sessionManager,
       settingsManager,
       modelRuntime,
     });
-    await session.bindExtensions({ mode: "print" });
-    const activeNames = new Set(session.getActiveToolNames());
-    const missingTools = allowedToolNames.filter((toolName) => !activeNames.has(toolName));
+    if (adaptRuntimeTools) session.setActiveToolsByName(allowedToolNames);
+    const initialActiveNames = new Set(session.getActiveToolNames());
+    const missingTools = allowedToolNames.filter((toolName) => !initialActiveNames.has(toolName));
     if (missingTools.length > 0) {
       session.dispose();
       throw new Error(`Minimal subagents child tool loading failed: ${missingTools.join(", ")}`);
     }
+    // The inner policy filters names added by extension wrappers such as Pi CodeMode.
+    installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
+    await session.bindExtensions({ mode: "print" });
+    // The outer policy filters names before extension wrappers build their own tool catalogues.
+    installChildToolCapabilityPolicy(session, allowedToolNames, runtimeToolAdapters);
+    const activeNames = new Set(session.getActiveToolNames());
+    const missingCoordinatorTools = coordinatorTools
+      .map((tool) => tool.name)
+      .filter((toolName) => !activeNames.has(toolName));
+    if (missingCoordinatorTools.length > 0) {
+      session.dispose();
+      throw new Error(
+        `Minimal subagents child coordinator tool loading failed: ${missingCoordinatorTools.join(", ")}`,
+      );
+    }
     return new PiChildAgentRuntime(
       session,
       modelRuntime,
@@ -1041,4 +1075,10 @@ export class PiAgentSessionFactory implements AgentSessionFactory {
       this.options.onChildSessionActivity,
     );
   }
+
+  private createChildSettingsManager(): SettingsManager {
+    return SettingsManager.create(this.options.cwd, this.options.agentDir, {
+      projectTrusted: this.options.projectTrusted,
+    });
+  }
 }

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

@@ -0,0 +1,307 @@
+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 { Type } from "typebox";
+import { Value } from "typebox/value";
+
+/** 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;
+}
+
+const JsonValueSchema = Type.Unsafe<JsonValue>({});
+const SettingsJsonObjectSchema = Type.Record(Type.String(), JsonValueSchema);
+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 {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripUtf8Bom(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,
+      ),
+    };
+  }
+
+  if (!Value.Check(SettingsJsonObjectSchema, parsed)) {
+    return { ok: false, error: settingsContractError(scope, path, "expected an object root") };
+  }
+  const minimalSubagents = parsed.minimalSubagents;
+  if (minimalSubagents !== undefined && !Value.Check(SettingsJsonObjectSchema, 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 = Value.Check(SettingsJsonObjectSchema, currentMinimalSubagents)
+    ? currentMinimalSubagents
+    : {};
+
+  if (enabled === undefined) {
+    delete minimalSubagents.enabled;
+  } else {
+    minimalSubagents.enabled = enabled;
+  }
+
+  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;
+  }
+}
+
+/**
+ * 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.
+ */
+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);
+  }
+
+  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;
+  }
+}