@narumitw/pi-subagents 3.2.1 → 3.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-subagents",
-  "version": "3.2.1",
+  "version": "3.3.2",
   "description": "Subagent jobs with asynchronous main-agent messaging for Pi.",
   "type": "module",
   "license": "MIT",
@@ -39,12 +39,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.2.0",
-    "@earendil-works/pi-coding-agent": "1.2.0",
-    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
-    "typebox": "1.3.37",
+    "typebox": "1.4.2",
     "typescript": "7.0.2"
   },
   "repository": {
@@ -53,6 +53,7 @@
     "directory": "packages/pi-subagents"
   },
   "dependencies": {
-    "ignore": "^7.0.12"
+    "@narumitw/pi-tui-kit": "^0.66.0",
+    "ignore": "^7.0.13"
   }
 }

package/src/display-text.ts

@@ -0,0 +1,14 @@
+import { sanitizeTerminalText } from "./message-broker.js";
+
+/** Single-line terminal display only; keep raw tasks, paths, and identifiers unchanged. */
+export function sanitizeSubagentDisplayText(value: string): string {
+  // Bound sequence bodies at another control introducer to keep malformed input linear.
+  const text = value.replace(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Strip untrusted terminal sequences before display.
+    /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]|(?:\u001b[\]PX^_]|[\u0090\u0098\u009d-\u009f])[^\u0007\u001b\u0080-\u009f]*(?:\u0007|\u001b\\|\u009c)|\u001b[ -/]*[0-~]/gu,
+    "",
+  );
+  return sanitizeTerminalText(text.replace(/\p{Bidi_Control}/gu, ""))
+    .replace(/\s+/gu, " ")
+    .trim();
+}

package/src/menu.ts

@@ -0,0 +1,188 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runConfirmation, runMenu, runTask, sanitizeTerminalText } from "@narumitw/pi-tui-kit";
+import type { SubagentSettings } from "./settings.js";
+import { JOB_STATES, type JobSummary } from "./types.js";
+
+interface SubagentsMenuState {
+  settings: SubagentSettings;
+  settingsPath: string;
+  jobs: JobSummary[];
+  omitted: number;
+}
+
+interface SubagentsMenuOptions {
+  signal: AbortSignal;
+  isCurrent(): boolean;
+  getState(): SubagentsMenuState;
+  cancelJob(jobId: string, signal: AbortSignal): Promise<void>;
+  showSettings(signal: AbortSignal): Promise<"back" | "close" | "stale">;
+}
+
+export async function showSubagentsMenu(ctx: ExtensionCommandContext, options: SubagentsMenuOptions): Promise<void> {
+  if (options.signal.aborted || !options.isCurrent()) return;
+  let selectedJobId: string | undefined;
+  const current = (signal: AbortSignal) => !signal.aborted && options.isCurrent();
+  const menu = defineMenu<
+    SubagentsMenuState,
+    "main" | "jobs" | "job" | "status" | "help",
+    "selectJob" | "cancelJob" | "settings"
+  >({
+    start: "main",
+    screens: {
+      main: ({ state }) => ({
+        kind: "actions",
+        title: "Subagents",
+        lines: [jobCounts(state)],
+        items: [
+          { id: "jobs", label: "Jobs", to: "jobs" },
+          { id: "settings", label: "Settings", action: "settings" },
+          { id: "status", label: "Status", to: "status" },
+          { id: "help", label: "Help", to: "help" },
+          { id: "close", label: "Close", close: true },
+        ],
+        hint: "close",
+      }),
+      jobs: ({ state }) => ({
+        kind: "choice",
+        title: "Subagent Jobs",
+        lines: [jobCounts(state), ...(state.jobs.length === 0 ? ["No jobs in this session."] : [])],
+        items: state.jobs.map((job) => ({
+          id: job.jobId,
+          label: sanitizeTerminalText(job.jobId),
+          description: sanitizeTerminalText(job.state),
+        })),
+        action: "selectJob",
+        hint: "back",
+      }),
+      job: ({ state }) => {
+        const job = state.jobs.find((candidate) => candidate.jobId === selectedJobId);
+        return {
+          kind: "actions",
+          title: "Subagent Job",
+          lines: job ? jobLines(job) : ["This job is no longer available."],
+          items: job && isActive(job) ? [{ id: "cancel", label: "Cancel job…", action: "cancelJob" }] : [],
+          hint: "back",
+        };
+      },
+      status: ({ state }) => ({
+        kind: "detail",
+        title: "Subagents Status",
+        lines: [
+          "Runtime: active for this session",
+          `Retained jobs: ${state.jobs.length}`,
+          `Active jobs: ${state.jobs.filter(isActive).length}`,
+          `Omitted jobs: ${state.omitted}`,
+          ...JOB_STATES.map((status) => `${status}: ${state.jobs.filter((job) => job.state === status).length}`),
+          `Show widget: ${state.settings.showWidget}`,
+          `Show job ID: ${state.settings.showJobId}`,
+          `Show tools: ${state.settings.showTools}`,
+          `Show timing: ${state.settings.showTiming}`,
+          `User settings: ${sanitizeTerminalText(state.settingsPath)}`,
+        ],
+        hint: "back",
+      }),
+      help: () => ({
+        kind: "detail",
+        title: "Subagents Help",
+        lines: [
+          "/subagents opens the job manager.",
+          "/subagents settings opens the same settings screen directly.",
+          "Jobs shows this session's job summaries. Only queued or running jobs can be cancelled, after confirmation.",
+          "The model uses subagent_spawn to start jobs, subagent_inspect to check them, and subagent_wait to wait for results.",
+          "subagent_send sends a message; subagent_cancel cancels a job.",
+          "Jobs are session-only. The runtime retains up to 32 terminal jobs for up to 24 hours.",
+          "Settings changes display preferences only. All four settings default to true.",
+          "Successful saves apply immediately. Use /reload after manual settings edits.",
+          "In RPC mode, Settings reports the user settings file path.",
+        ],
+        hint: "back",
+      }),
+    },
+    actions: {
+      selectJob: ({ itemId, signal }) => {
+        if (!current(signal)) return { kind: "close" };
+        if (!options.getState().jobs.some((job) => job.jobId === itemId)) return { kind: "stay" };
+        selectedJobId = itemId;
+        return { kind: "to", screen: "job" };
+      },
+      settings: async ({ signal }) => {
+        if (!current(signal)) return { kind: "close" };
+        const reason = await options.showSettings(signal);
+        return { kind: current(signal) && reason === "back" ? "stay" : "close" };
+      },
+      cancelJob: async ({ signal }) => {
+        if (!current(signal)) return { kind: "close" };
+        const jobId = selectedJobId;
+        const job = options.getState().jobs.find((candidate) => candidate.jobId === jobId);
+        if (!job || !isActive(job)) return { kind: "stay" };
+        const confirmation = await runConfirmation(ctx, {
+          title: "Cancel subagent job?",
+          message: `Cancel job ${sanitizeTerminalText(job.jobId)} (${sanitizeTerminalText(job.state)})?`,
+          confirmLabel: "Cancel job",
+          cancelLabel: "Keep job",
+          signal,
+          isCurrent: options.isCurrent,
+          onError: () => undefined,
+        });
+        if (!current(signal)) return { kind: "close" };
+        if (confirmation.kind === "closed") {
+          return { kind: confirmation.reason === "close" ? "close" : "stay" };
+        }
+        if (confirmation.kind === "error") throw confirmation.error;
+        if (confirmation.kind !== "confirmed") return { kind: "close" };
+        // The runtime can finish or remove a job while its confirmation is open.
+        const latest = options.getState().jobs.find((candidate) => candidate.jobId === jobId);
+        if (selectedJobId !== jobId || !latest || !isActive(latest)) return { kind: "stay" };
+        const result = await runTask(ctx, {
+          label: "Cancelling subagent job…",
+          signal,
+          isCurrent: options.isCurrent,
+          task: ({ signal: taskSignal }) => options.cancelJob(latest.jobId, taskSignal),
+          onError: () => undefined,
+        });
+        if (!current(signal)) return { kind: "close" };
+        if (result.kind === "error") throw result.error;
+        if (result.kind === "stale") return { kind: "close" };
+        if (result.kind === "cancelled") return { kind: "close" };
+        return { kind: "stay" };
+      },
+    },
+  });
+  await runMenu(ctx, menu, {
+    signal: options.signal,
+    isCurrent: options.isCurrent,
+    getState: options.getState,
+    onError: (_ctx, error) => {
+      if (!options.signal.aborted && options.isCurrent() && ctx.hasUI) {
+        ctx.ui.notify(
+          sanitizeTerminalText(`Subagents menu failed: ${error instanceof Error ? error.message : String(error)}`),
+          "error",
+        );
+      }
+    },
+  });
+}
+
+function isActive(job: JobSummary): boolean {
+  return job.state === "queued" || job.state === "running";
+}
+
+function jobCounts(state: SubagentsMenuState): string {
+  return `Jobs: ${state.jobs.length} shown, ${state.jobs.filter(isActive).length} active, ${state.omitted} omitted`;
+}
+
+function jobLines(job: JobSummary): string[] {
+  return [
+    `Job ID: ${sanitizeTerminalText(job.jobId)}`,
+    `State: ${sanitizeTerminalText(job.state)}`,
+    `Created: ${timestamp(job.createdAt)}`,
+    ...(job.startedAt === undefined ? [] : [`Started: ${timestamp(job.startedAt)}`]),
+    ...(job.finishedAt === undefined ? [] : [`Finished: ${timestamp(job.finishedAt)}`]),
+    ...(job.timeout === undefined ? [] : [`Timeout: ${job.timeout} seconds`]),
+  ];
+}
+
+function timestamp(value: number): string {
+  const date = new Date(value);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : "unknown";
+}

package/src/message-renderers.ts

@@ -0,0 +1,60 @@
+import { type ExtensionAPI, getMarkdownTheme, keyText } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { sanitizeTerminalText } from "./message-broker.js";
+
+export const COMPLETION_MESSAGE_TYPE = "pi-subagents-completion";
+export const BROKER_MESSAGE_TYPE = "pi-subagents-message";
+
+function createMessageBox(children: Component[], outputPad: number, background: (text: string) => string): Component {
+  return {
+    render(width) {
+      if (width <= 0) return [];
+      const maxPadding = Math.floor((width - 1) / 2);
+      const box = new Box(Math.min(Math.max(0, outputPad), maxPadding), 1, background);
+      for (const child of children) box.addChild(child);
+      return box.render(width);
+    },
+    invalidate() {
+      for (const child of children) child.invalidate();
+    },
+  };
+}
+
+export function registerMessageRenderers(pi: ExtensionAPI): void {
+  for (const [messageType, summary] of [
+    [COMPLETION_MESSAGE_TYPE, "Subagent job completion"],
+    [BROKER_MESSAGE_TYPE, "Subagent message"],
+  ] as const) {
+    pi.registerMessageRenderer(messageType, (message, options, theme) => {
+      const children: Component[] = [
+        new Text(theme.fg("customMessageLabel", theme.bold(`[${messageType}]`)), 0, 0),
+        new Spacer(1),
+      ];
+      if (!options.expanded) {
+        children.push(
+          new Text(
+            theme.fg("customMessageText", `${summary} (`) +
+              theme.fg("dim", keyText("app.tools.expand")) +
+              theme.fg("customMessageText", " to expand)"),
+            0,
+            0,
+          ),
+        );
+      } else {
+        const content =
+          typeof message.content === "string"
+            ? message.content
+            : message.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("\n");
+        children.push(
+          new Markdown(sanitizeTerminalText(content), 0, 0, getMarkdownTheme(), {
+            color: (text) => theme.fg("customMessageText", text),
+          }),
+        );
+      }
+      return createMessageBox(children, options.outputPad, (text) => theme.bg("customMessageBg", text));
+    });
+  }
+}

package/src/runtime.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { COMPLETION_MESSAGE_TYPE } from "./completion-renderer.js";
 import { type BrokerSendAcknowledgement, type MessageBroker, sanitizeTerminalText } from "./message-broker.js";
+import { COMPLETION_MESSAGE_TYPE } from "./message-renderers.js";
 import { modelVisibleJson, requireBoundedModelText } from "./model-output.js";
 import { runChild as defaultRunChild } from "./process.js";
 import type { ExtensionAttachment } from "./resource-attachments.js";
@@ -29,6 +29,7 @@ interface InternalJob extends JobSummary {
   resolveTerminal: () => void;
   task?: Promise<void>;
   taskText: string;
+  thinkingLevel: SubagentThinkingLevel;
   stopRequest?: StopRequest;
   control?: ChildControl;
   controlReady: Promise<ChildControl>;
@@ -51,6 +52,7 @@ export interface ActiveJobDisplay {
   jobId: string;
   task: string;
   state: Extract<SubagentJobState, "queued" | "running">;
+  thinkingLevel: SubagentThinkingLevel;
   elapsedMs: number;
   timeout?: number;
   tools: string[];
@@ -117,6 +119,7 @@ export class SubagentRuntime {
         jobId: job.jobId,
         task: job.taskText,
         state: job.state,
+        thinkingLevel: job.thinkingLevel,
         elapsedMs: Math.max(0, now - (job.startedAt ?? job.createdAt)),
         ...(job.timeout !== undefined ? { timeout: job.timeout } : {}),
         tools: [...job.tools],
@@ -159,6 +162,7 @@ export class SubagentRuntime {
       controller,
       tools: effectiveTools,
       taskText: input.task,
+      thinkingLevel: input.thinkingLevel,
       terminal,
       resolveTerminal,
       controlReady,

package/src/settings-ui.ts

@@ -0,0 +1,204 @@
+import { stripVTControlCharacters } from "node:util";
+import { type ExtensionCommandContext, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type SettingItem, SettingsList, Text, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import {
+  HorizontalRule,
+  renderBoundedFrameLayout,
+  runCustomInteraction,
+  sanitizeTerminalText,
+} from "@narumitw/pi-tui-kit";
+import type { SubagentSettings } from "./settings.js";
+
+interface SubagentSettingsUIOptions {
+  signal: AbortSignal;
+  isCurrent(): boolean;
+  get(): SubagentSettings;
+  save(key: keyof SubagentSettings, value: boolean, signal: AbortSignal): Promise<SubagentSettings>;
+  apply(settings: SubagentSettings): void;
+}
+
+type CloseReason = "back" | "close" | "stale";
+
+const SETTINGS: { key: keyof SubagentSettings; label: string; description: string }[] = [
+  { key: "showWidget", label: "Show widget", description: "Show subagent jobs above the editor." },
+  { key: "showJobId", label: "Show job ID", description: "Show job IDs in the widget." },
+  { key: "showTools", label: "Show tools", description: "Show active tools in the widget." },
+  { key: "showTiming", label: "Show timing", description: "Show job timing in the widget." },
+];
+
+export async function showSubagentSettings(
+  ctx: ExtensionCommandContext,
+  options: SubagentSettingsUIOptions,
+): Promise<CloseReason> {
+  const result = await runCustomInteraction<CloseReason>(ctx, {
+    signal: options.signal,
+    isCurrent: options.isCurrent,
+    // The command owner reports interaction failures and non-TUI settings paths.
+    onError: () => {},
+    create({ tui, theme, signal, complete }) {
+      let queue = Promise.resolve();
+      const current = () => !signal.aborted && options.isCurrent();
+      const revisions = new Map<string, number>();
+      const pending = new Map<string, number>();
+      const mouseRows = new Map<number, number>();
+      let renderedWidth = 0;
+      let contentHeight = 0;
+      let mousePressed = false;
+      const reportFailure = (message: string) => {
+        if (!current()) return;
+        try {
+          ctx.ui.notify(sanitizeTerminalText(`Could not save pi-subagents.json: ${message}`), "error");
+        } catch {
+          // The host can dispose its notifier after the ownership check.
+        }
+      };
+      const rule = new HorizontalRule({ ruleStyle: (text) => theme.fg("border", text) });
+      // Keep native SettingsList semantics, but use this screen's callback theme.
+      const listTheme = {
+        ...getSettingsListTheme(),
+        label: (text: string, selected: boolean) => (selected ? theme.fg("accent", text) : text),
+        value: (text: string, selected: boolean) => theme.fg(selected ? "accent" : "muted", text),
+        description: (text: string) => theme.fg("dim", text),
+        cursor: theme.fg("accent", "→ "),
+        hint: (text: string) => theme.fg("dim", text),
+      };
+      const initial = options.get();
+      const items: SettingItem[] = SETTINGS.map(({ key, label, description }) => ({
+        id: key,
+        label,
+        description,
+        currentValue: String(initial[key]),
+        values: ["true", "false"],
+      }));
+      const list = new SettingsList(
+        items,
+        items.length,
+        listTheme,
+        (id, value) => {
+          if (!current()) return;
+          const key = id as keyof SubagentSettings;
+          const revision = (revisions.get(id) ?? 0) + 1;
+          revisions.set(id, revision);
+          pending.set(id, revision);
+          queue = queue
+            .then(async () => {
+              if (!current()) {
+                complete("stale");
+                return;
+              }
+              const before = { ...options.get() };
+              let effective = before;
+              try {
+                const settings = await options.save(key, value === "true", signal);
+                // A successful rename is durable, even when closing aborted the save signal.
+                if (!options.isCurrent()) {
+                  complete("stale");
+                  return;
+                }
+                options.apply(settings);
+                effective = options.get();
+              } catch (error) {
+                if (!options.isCurrent()) {
+                  complete("stale");
+                  return;
+                }
+                let message = error instanceof Error ? error.message : String(error);
+                try {
+                  options.apply(before);
+                } catch (rollbackError) {
+                  message += `; could not restore effective settings: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`;
+                }
+                reportFailure(message);
+              }
+              if (!current()) return;
+              if (pending.get(id) === revision) pending.delete(id);
+              // Saving rereads the full document, including unrelated manual edits. Keep newer
+              // optimistic choices, but refresh every row with no outstanding user change.
+              for (const { key: settingKey } of SETTINGS) {
+                if (!pending.has(settingKey)) list.updateValue(settingKey, String(effective[settingKey]));
+              }
+              tui.requestRender();
+            })
+            .catch((error: unknown) => {
+              // A failed action must not prevent later requests from entering the queue.
+              reportFailure(error instanceof Error ? error.message : String(error));
+            });
+        },
+        () => complete("back"),
+      );
+      return {
+        render(width: number) {
+          if (!current()) complete("stale");
+          renderedWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : 0;
+          listTheme.cursor = theme.fg("accent", "→ ");
+          // The native footer hardcodes keys. Advertise only the hard-cancel key owned here;
+          // configured native navigation, change, and Back actions remain unchanged.
+          const content = list.render(Math.max(4, renderedWidth)).slice(0, -2);
+          contentHeight = content.length;
+          const focusedRow = content.findIndex((line) => stripVTControlCharacters(line).startsWith("→"));
+          mouseRows.clear();
+
+          const terminalRows = Number.isFinite(tui.terminal.rows) ? Math.floor(tui.terminal.rows) : 24;
+          const frame = renderBoundedFrameLayout({
+            width: renderedWidth,
+            maxRows: Math.max(1, terminalRows - 3),
+            rule: rule.render(renderedWidth)[0] ?? "",
+            title: new Text(theme.fg("accent", theme.bold("Subagents Settings")), 0, 0).render(renderedWidth),
+            context: [theme.fg("muted", "Saved changes apply immediately.")],
+            content,
+            hints: new Text(theme.fg("muted", "Ctrl+C close"), 0, 0).render(renderedWidth),
+            priorityRows: focusedRow < 0 ? [] : [focusedRow],
+            focusedRow,
+          });
+          for (const { frameIndex, contentIndex } of frame.contentRows) mouseRows.set(frameIndex, contentIndex);
+          return frame.lines;
+        },
+        invalidate() {
+          mouseRows.clear();
+          mousePressed = false;
+          list.invalidate();
+        },
+        handleInput(data: string) {
+          if (!current()) return complete("stale");
+          mouseRows.clear();
+          mousePressed = false;
+          if (matchesKey(data, Key.ctrl("c"))) complete("close");
+          else {
+            // SettingsList uses Pi's effective native keybindings for standard actions.
+            list.handleInput(data);
+          }
+          tui.requestRender();
+        },
+        handleMouse(event: TuiMouseEvent) {
+          if (!current()) {
+            complete("stale");
+            return;
+          }
+          const nativeRow = mouseRows.get(event.y);
+          if (nativeRow === undefined || event.x < 0 || event.x >= renderedWidth) {
+            if (event.button === "left" && (event.type === "press" || event.type === "click")) mousePressed = false;
+            return;
+          }
+          const nativeEvent = { ...event, y: nativeRow, width: renderedWidth, height: contentHeight };
+          if (event.type === "click" && event.button === "left" && !mousePressed) {
+            list.handleMouse({ ...nativeEvent, type: "press" });
+          }
+          const result = list.handleMouse(nativeEvent);
+          if (event.type === "press" && event.button === "left") mousePressed = result?.handled === true;
+          if (event.type === "click" || event.type === "wheel") mousePressed = false;
+          if (result?.handled && result.render !== false) tui.requestRender();
+          return result;
+        },
+        waitForPending() {
+          return queue;
+        },
+        dispose() {
+          mouseRows.clear();
+          mousePressed = false;
+        },
+      };
+    },
+  });
+  if (result.kind === "error") throw result.error;
+  return result.kind === "completed" ? result.value : result.kind === "unsupported" ? "back" : "stale";
+}

package/src/settings.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+export interface SubagentSettings {
+  showWidget: boolean;
+  showJobId: boolean;
+  showTools: boolean;
+  showTiming: boolean;
+}
+
+export const DEFAULT_SUBAGENT_SETTINGS: Readonly<SubagentSettings> = Object.freeze({
+  showWidget: true,
+  showJobId: true,
+  showTools: true,
+  showTiming: true,
+});
+
+const SETTINGS_KEYS = Object.keys(DEFAULT_SUBAGENT_SETTINGS) as (keyof SubagentSettings)[];
+
+type SettingsDocument = {
+  document?: Record<string, unknown>;
+  diagnostics: string[];
+};
+
+export function subagentSettingsPath(): string {
+  return join(getAgentDir(), "pi-subagents.json");
+}
+
+/** User-only settings with in-process ordering; this does not lock other Pi processes. */
+export class SubagentSettingsStore {
+  private effective: SubagentSettings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  private tail: Promise<void> = Promise.resolve();
+
+  constructor(readonly userPath: string) {}
+
+  get settings(): SubagentSettings {
+    return { ...this.effective };
+  }
+
+  load(): Promise<{ settings: SubagentSettings; diagnostics: string[] }> {
+    return this.enqueue(async () => {
+      const loaded = await readDocument(this.userPath);
+      const settings = normalizeSettings(loaded.document ?? {}, loaded.diagnostics);
+      this.effective = settings;
+      return { settings: this.settings, diagnostics: loaded.diagnostics };
+    }).catch((error: unknown) => ({
+      settings: this.settings,
+      diagnostics: [readDiagnostic(this.userPath, error)],
+    }));
+  }
+
+  save(key: keyof SubagentSettings, value: boolean, signal: AbortSignal): Promise<SubagentSettings> {
+    return this.enqueue(async () => {
+      signal.throwIfAborted();
+      if (!SETTINGS_KEYS.includes(key) || typeof value !== "boolean") {
+        throw new Error("Invalid subagent settings update");
+      }
+      const loaded = await readDocument(this.userPath);
+      signal.throwIfAborted();
+      if (!loaded.document) {
+        throw new Error(`Cannot save subagent settings: ${loaded.diagnostics.join("; ")}`);
+      }
+      // Read again for each save and patch only the requested key, including after a failed save.
+      const document = { ...loaded.document, [key]: value };
+      const settings = normalizeSettings(document, []);
+      const parent = dirname(this.userPath);
+      await fs.mkdir(parent, { recursive: true });
+      signal.throwIfAborted();
+      const temporary = await fs.mkdtemp(join(parent, ".pi-subagents-"));
+      try {
+        signal.throwIfAborted();
+        const staged = join(temporary, "settings.json");
+        await fs.writeFile(staged, `${JSON.stringify(document, null, 2)}\n`, { flag: "wx", signal });
+        signal.throwIfAborted();
+        await fs.rename(staged, this.userPath);
+        // Rename is the commit point. Cancellation or cleanup must not turn a commit into a failure.
+        this.effective = settings;
+        return this.settings;
+      } finally {
+        await fs.rm(temporary, { recursive: true, force: true }).catch(() => {});
+      }
+    });
+  }
+
+  flush(): Promise<void> {
+    return this.tail;
+  }
+
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const previous = this.tail;
+    // Register immediately so other stores and Pi file operations retain request order too.
+    const result = withFileMutationQueue(this.userPath, async () => {
+      await previous;
+      return operation();
+    });
+    this.tail = result.then(
+      () => {},
+      () => {},
+    );
+    return result;
+  }
+}
+
+async function readDocument(path: string): Promise<SettingsDocument> {
+  let text: string;
+  try {
+    text = await fs.readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return { document: {}, diagnostics: [] };
+    }
+    return { diagnostics: [readDiagnostic(path, error)] };
+  }
+  let document: unknown;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    return { diagnostics: [`Cannot load subagent settings at ${path}: invalid JSON`] };
+  }
+  if (typeof document !== "object" || document === null || Array.isArray(document)) {
+    return { diagnostics: [`Cannot load subagent settings at ${path}: expected a JSON object`] };
+  }
+  return { document: document as Record<string, unknown>, diagnostics: [] };
+}
+
+function normalizeSettings(document: Record<string, unknown>, diagnostics: string[]): SubagentSettings {
+  const settings = { ...DEFAULT_SUBAGENT_SETTINGS };
+  for (const key of SETTINGS_KEYS) {
+    if (!Object.hasOwn(document, key)) continue;
+    if (typeof document[key] === "boolean") {
+      settings[key] = document[key];
+    } else {
+      diagnostics.push(`Ignored invalid subagent setting ${key}: expected a boolean`);
+    }
+  }
+  return settings;
+}
+
+function readDiagnostic(path: string, error: unknown): string {
+  return `Cannot load subagent settings at ${path}: ${error instanceof Error ? error.message : String(error)}`;
+}