@maplezzk/pi-interactive-subagents 3.9.1 → 3.10.1

package/README.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/30adb156-cfb4-4c47-84ca-dd4aa80cba9f
 
 ## How It Works
 
-Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.
+Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it. Completion reminders are injected only after the model stops normally; user aborts and provider errors stay quiet.
 
 ```
 ╭─ Subagents ──────────────────────────── 2 running ─╮
@@ -59,9 +59,9 @@ zellij --session pi   # then run: pi
 # just run pi inside Orca — no wrapper needed
 ```
 
-Optional: set `PI_SUBAGENT_MUX=muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca` to force a specific backend.
+Optional: set `PI_SUBAGENT_MUX=muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca` to force a specific backend. Herdr uses its original split layout by default; set `PI_SUBAGENT_HERDR_MODE=tab` for one background tab per subagent, or `split` to select pane splitting explicitly.
 
-You can also configure it from inside Pi with `/config:subagent`. Run it without arguments for an interactive menu, or use `/config:subagent auto|muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca` for a direct choice. The selection is persisted in Pi's user extension config directory; explicit `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` environment variables take precedence. `/subagent-config` and `/pi-subagent-config` remain available as compatibility aliases.
+You can also configure it from inside Pi with `/config:subagent`. Run it without arguments for an interactive menu, or use `/config:subagent auto|muxy|cmux|tmux|zellij|wezterm|herdr [split|tab]|otty|orca` for a direct choice. For example, `/config:subagent herdr tab` persists both the Herdr backend and tab mode. The selection is persisted in Pi's user extension config directory; explicit `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` and `PI_SUBAGENT_HERDR_MODE` environment variables take precedence. `/subagent-config` and `/pi-subagent-config` remain available as compatibility aliases.
 
 > **Otty notes:**
 > - Otty sets `TERM_PROGRAM=otty` automatically when pi runs inside it; the backend detects this env var.
@@ -159,7 +159,7 @@ These labels are no longer derived from session-file growth. Session JSONL is st
 
 #### Configuration
 
-Status display is controlled by `config.json` in the extension directory. Copy `config.json.example` to get started:
+Subagent settings, including status display and the persisted Herdr mode, are controlled by `config.json` in the extension directory. Copy `config.json.example` to get started:
 
 ```bash
 cp config.json.example config.json
@@ -167,12 +167,15 @@ cp config.json.example config.json
 
 ```json
 {
+  "herdrMode": "split",
   "status": {
     "enabled": true
   }
 }
 ```
 
+`herdrMode` accepts `split` (default, backward-compatible pane layout) or `tab` (one background tab per subagent). The `/config:subagent herdr split|tab` command updates this field.
+
 `config.json` is gitignored so local overrides don't get committed.
 
 ---

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 ## 工作原理
 
-调用 `subagent()` 后**立即返回**，子 agent 在自己的终端分屏中运行。输入框上方的实时 widget 展示所有运行中的 agent 及其状态（`starting`、`active`、`waiting`、`stalled`、`running`）。子 agent 完成后，结果以异步通知形式**回流**到主会话，触发新一轮处理。
+调用 `subagent()` 后**立即返回**，子 agent 在自己的终端分屏中运行。输入框上方的实时 widget 展示所有运行中的 agent 及其状态（`starting`、`active`、`waiting`、`stalled`、`running`）。子 agent 完成后，结果以异步通知形式**回流**到主会话，触发新一轮处理。完成提醒仅在模型正常停止后注入；用户手动终止或提供方异常不会触发。
 
 ```typescript
 subagent({ name: "Scout: Auth", agent: "scout", task: "分析 auth 模块" });
@@ -32,10 +32,10 @@ tmux new -A -s pi 'pi'
 zellij --session pi   # 然后运行 pi
 ```
 
-可选：设置 `PI_SUBAGENT_MUX=muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca` 强制指定后端。
+可选：设置 `PI_SUBAGENT_MUX=muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca` 强制指定后端。Herdr 默认保持原有分屏布局；设置 `PI_SUBAGENT_HERDR_MODE=tab` 后每个 subagent 创建独立后台 Tab，设置为 `split` 可显式选择分屏模式。
 
 也可以在 Pi 内通过 `/config:subagent` 配置：不带参数打开选择菜单，或直接运行
-`/config:subagent auto|muxy|cmux|tmux|zellij|wezterm|herdr|otty|orca`。选择会保存到 Pi 的用户扩展配置目录；显式设置的 `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` 优先级更高。`/subagent-config` 和 `/pi-subagent-config` 仍作为兼容别名保留。
+`/config:subagent auto|muxy|cmux|tmux|zellij|wezterm|herdr [split|tab]|otty|orca`。例如 `/config:subagent herdr tab` 会同时持久化 Herdr 后端与 Tab 模式。选择会保存到 Pi 的用户扩展配置目录；显式设置的 `PI_TERMINAL_MUX` / `PI_SUBAGENT_MUX` 与 `PI_SUBAGENT_HERDR_MODE` 优先级更高。`/subagent-config` 和 `/pi-subagent-config` 仍作为兼容别名保留。
 
 ## 主要能力
 
@@ -50,7 +50,7 @@ zellij --session pi   # 然后运行 pi
 
 ## 配置
 
-状态显示由扩展目录下的 `config.json` 控制。复制 `config.json.example` 开始：
+状态显示与持久化 Herdr 模式由扩展目录下的 `config.json` 控制。复制 `config.json.example` 开始：
 
 ```bash
 cp config.json.example config.json
@@ -58,12 +58,15 @@ cp config.json.example config.json
 
 ```json
 {
+  "herdrMode": "split",
   "status": {
     "enabled": true
   }
 }
 ```
 
+`herdrMode` 支持 `split`（默认，兼容原有 pane 布局）和 `tab`（每个 subagent 独立后台 Tab）。`/config:subagent herdr split|tab` 会更新该字段。
+
 ## 致谢
 
 - 原作者 **HazAT** 的设计与实现（[原始仓库](https://github.com/HazAT/pi-interactive-subagents)）

package/config.json.example

@@ -1,4 +1,5 @@
 {
+  "herdrMode": "split",
   "status": {
     "enabled": true
   }

package/locales/index.json

@@ -4,8 +4,8 @@
     "en-US": "[Auto reminder]\n• Done → call subagent_done to finish.\n• Before finishing, self-check: are you spinning in place? If so, converge your result immediately and hand it back to the main agent with caller_ping — don't overthink.\n• Still working → ignore."
   },
   "muxCommandDescription": {
-    "zh-CN": "配置 subagent 使用的终端复用器",
-    "en-US": "Configure the terminal multiplexer used by subagents"
+    "zh-CN": "配置 subagent 使用的终端复用器及 Herdr 布局模式",
+    "en-US": "Configure the subagent multiplexer and Herdr layout mode"
   },
   "muxConfigTitle": {
     "zh-CN": "选择 subagent 终端复用器（当前：{value}）",
@@ -32,8 +32,16 @@
     "en-US": "Subagent multiplexer set to: {value}"
   },
   "muxInvalid": {
-    "zh-CN": "不支持的 mux：{value}。可选：auto、muxy、cmux、tmux、zellij、wezterm、herdr、otty、orca。",
-    "en-US": "Unsupported mux: {value}. Choose auto, muxy, cmux, tmux, zellij, wezterm, herdr, otty, or orca."
+    "zh-CN": "不支持的 mux 配置：{value}。可选：auto、muxy、cmux、tmux、zellij、wezterm、herdr [split|tab]、otty、orca。",
+    "en-US": "Unsupported mux setting: {value}. Choose auto, muxy, cmux, tmux, zellij, wezterm, herdr [split|tab], otty, or orca."
+  },
+  "herdrModeSplit": {
+    "zh-CN": "分屏",
+    "en-US": "split panes"
+  },
+  "herdrModeTab": {
+    "zh-CN": "独立 Tab",
+    "en-US": "separate tabs"
   },
   "muxInteractiveOnly": {
     "zh-CN": "请在支持 UI 的 Pi 会话中运行 /config:subagent。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/pi-interactive-subagents",
-  "version": "3.9.1",
+  "version": "3.10.1",
   "description": "Interactive async subagents for pi — spawn, orchestrate, and manage sub-agent sessions in multiplexer panes. Fork of HazAT/pi-interactive-subagents.",
   "type": "module",
   "main": "./index.ts",
@@ -17,7 +17,7 @@
     "README.zh-CN.md"
   ],
   "scripts": {
-    "test": "tsx --test test/test.ts",
+    "test": "tsx --test test/subagent-done-nudge.test.ts test/test.ts",
     "test:integration": "tsx --test --test-concurrency=1 test/integration/*.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "build": "npm run typecheck",
@@ -59,7 +59,7 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "pi-extensions-i18n": "^0.3.1",
-    "pi-terminal-mux": "^0.3.2"
+    "pi-terminal-mux": "^0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",

package/pi-extension/subagents/index.ts

@@ -44,9 +44,14 @@ import {
 
 import {
   applyPersistedMuxPreference,
+  HERDR_SURFACE_MODE_TAB,
+  HERDR_SURFACE_MODES,
+  loadHerdrModeConfig,
   loadMuxConfig,
+  saveHerdrMode,
   saveMuxPreference,
   SUBAGENT_MUX_BACKENDS,
+  type HerdrSurfaceMode,
   type SubagentMuxPreference,
 } from "./mux-config.ts";
 
@@ -968,26 +973,78 @@ function isMuxBackendAvailable(backend: MuxBackend): boolean {
   }
 }
 
-function muxPreferenceLabel(preference: SubagentMuxPreference): string {
-  return preference === "auto" ? i18n.t("muxAuto") : preference;
+const AUTO_MUX_PREFERENCE: SubagentMuxPreference = "auto";
+const HERDR_MUX_BACKEND: MuxBackend = "herdr";
+const MAX_MUX_CONFIG_TOKENS = 2;
+
+interface MuxConfigSelection {
+  preference: SubagentMuxPreference;
+  herdrMode?: HerdrSurfaceMode;
+}
+
+/** 返回本地化的 Herdr surface 模式名称。 */
+function herdrModeLabel(mode: HerdrSurfaceMode): string {
+  return mode === HERDR_SURFACE_MODE_TAB
+    ? i18n.t("herdrModeTab")
+    : i18n.t("herdrModeSplit");
+}
+
+/** 格式化当前 mux；Herdr 同时展示 split/tab 子模式。 */
+function muxPreferenceLabel(preference: SubagentMuxPreference, herdrMode?: HerdrSurfaceMode): string {
+  if (preference === AUTO_MUX_PREFERENCE) return i18n.t("muxAuto");
+  if (preference === HERDR_MUX_BACKEND && herdrMode) {
+    return `herdr (${herdrModeLabel(herdrMode)})`;
+  }
+  return preference;
+}
+
+/** 解析 `/config:subagent` 直接参数，Herdr 可追加 split/tab。 */
+function parseMuxConfigRequest(requested: string): MuxConfigSelection | null {
+  const tokens = requested.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0 || tokens.length > MAX_MUX_CONFIG_TOKENS) return null;
+
+  const requestedMux = tokens[0];
+  const preference = requestedMux === AUTO_MUX_PREFERENCE || (SUBAGENT_MUX_BACKENDS as readonly string[]).includes(requestedMux)
+    ? requestedMux as SubagentMuxPreference
+    : null;
+  if (!preference) return null;
+
+  const requestedMode = tokens[1];
+  if (!requestedMode) return { preference };
+  if (preference !== HERDR_MUX_BACKEND || !(HERDR_SURFACE_MODES as readonly string[]).includes(requestedMode)) {
+    return null;
+  }
+  return { preference, herdrMode: requestedMode as HerdrSurfaceMode };
 }
 
+/** 保存 mux 选择，并在 Herdr 选项携带模式时一并持久化。 */
+function saveMuxConfigSelection(selection: MuxConfigSelection): MuxConfigSelection {
+  const savedMux = saveMuxPreference(selection.preference);
+  const savedMode = selection.herdrMode ? saveHerdrMode(selection.herdrMode).herdrMode : undefined;
+  return { preference: savedMux.mux, herdrMode: savedMode };
+}
+
+/** 注册 mux 配置命令及其兼容别名，并持久化用户选择。 */
 function registerMuxConfigCommand(pi: ExtensionAPI): void {
   const command = {
     description: i18n.t("muxCommandDescription"),
     handler: async (args, ctx) => {
-      const requested = args.trim().toLowerCase();
+      const requested = args.trim();
       if (requested) {
-        const preference = requested === "auto" || (SUBAGENT_MUX_BACKENDS as readonly string[]).includes(requested)
-          ? requested as SubagentMuxPreference
-          : null;
-        if (!preference) {
+        const selection = parseMuxConfigRequest(requested);
+        if (!selection) {
           ctx.ui.notify(i18n.t("muxInvalid", { value: requested }), "warning");
           return;
         }
         try {
-          const saved = saveMuxPreference(preference);
-          ctx.ui.notify(i18n.t("muxSaved", { value: muxPreferenceLabel(saved.mux) }), "info");
+          const saved = saveMuxConfigSelection(selection);
+          const herdrMode = saved.preference === HERDR_MUX_BACKEND
+            ? saved.herdrMode ?? loadHerdrModeConfig().herdrMode
+            : undefined;
+          ctx.ui.notify(
+            i18n.t("muxSaved", { value: muxPreferenceLabel(saved.preference, herdrMode) }),
+            "info",
+          );
         } catch (error) {
           ctx.ui.notify(String(error), "error");
         }
@@ -1000,20 +1057,38 @@ function registerMuxConfigCommand(pi: ExtensionAPI): void {
       }
 
       const current = loadMuxConfig();
+      const currentHerdrMode = loadHerdrModeConfig().herdrMode;
       const detected = getMuxBackend();
-      const options: Array<{ preference: SubagentMuxPreference; label: string }> = [
+      const options: Array<MuxConfigSelection & { label: string }> = [
         {
-          preference: "auto",
-          label: `${current.mux === "auto" ? "●" : "○"} ${i18n.t("muxAuto")} — ${detected ?? i18n.t("muxUnavailable")}`,
+          preference: AUTO_MUX_PREFERENCE,
+          label: `${current.mux === AUTO_MUX_PREFERENCE ? "●" : "○"} ${i18n.t("muxAuto")} — ${detected ?? i18n.t("muxUnavailable")}`,
         },
-        ...SUBAGENT_MUX_BACKENDS.map((backend) => ({
-          preference: backend,
-          label: `${current.mux === backend ? "●" : "○"} ${backend} — ${isMuxBackendAvailable(backend) ? i18n.t("muxAvailable") : i18n.t("muxUnavailable")}`,
-        })),
       ];
+      for (const backend of SUBAGENT_MUX_BACKENDS) {
+        const available = isMuxBackendAvailable(backend)
+          ? i18n.t("muxAvailable")
+          : i18n.t("muxUnavailable");
+        if (backend === HERDR_MUX_BACKEND) {
+          for (const herdrMode of HERDR_SURFACE_MODES) {
+            const selected = current.mux === backend && currentHerdrMode === herdrMode;
+            options.push({
+              preference: backend,
+              herdrMode,
+              label: `${selected ? "●" : "○"} ${muxPreferenceLabel(backend, herdrMode)} — ${available}`,
+            });
+          }
+          continue;
+        }
+        options.push({
+          preference: backend,
+          label: `${current.mux === backend ? "●" : "○"} ${backend} — ${available}`,
+        });
+      }
+
       const exit = i18n.t("muxExit");
       const choice = await ctx.ui.select(
-        i18n.t("muxConfigTitle", { value: muxPreferenceLabel(current.mux) }),
+        i18n.t("muxConfigTitle", { value: muxPreferenceLabel(current.mux, currentHerdrMode) }),
         [...options.map((option) => option.label), exit],
       );
       if (!choice || choice === exit) return;
@@ -1021,8 +1096,13 @@ function registerMuxConfigCommand(pi: ExtensionAPI): void {
       const selected = options.find((option) => option.label === choice);
       if (!selected) return;
       try {
-        const saved = saveMuxPreference(selected.preference);
-        ctx.ui.notify(i18n.t("muxSaved", { value: muxPreferenceLabel(saved.mux) }), "info");
+        const saved = saveMuxConfigSelection(selected);
+        ctx.ui.notify(
+          i18n.t("muxSaved", {
+            value: muxPreferenceLabel(saved.preference, saved.herdrMode),
+          }),
+          "info",
+        );
       } catch (error) {
         ctx.ui.notify(String(error), "error");
       }
@@ -1035,6 +1115,7 @@ function registerMuxConfigCommand(pi: ExtensionAPI): void {
 
 export const __test__ = {
   borderLine,
+  parseMuxConfigRequest,
   getShellReadyDelayMs,
   renderSubagentWidgetLines,
   loadAgentDefaults,

package/pi-extension/subagents/mux-config.ts

@@ -5,14 +5,25 @@ import type { MuxBackend } from "pi-terminal-mux";
 
 export type SubagentMuxPreference = "auto" | MuxBackend;
 export type SubagentMuxConfigSource = "environment" | "file" | "default";
+export const HERDR_SURFACE_MODE_SPLIT = "split";
+export const HERDR_SURFACE_MODE_TAB = "tab";
+export const HERDR_SURFACE_MODES = [HERDR_SURFACE_MODE_SPLIT, HERDR_SURFACE_MODE_TAB] as const;
+export type HerdrSurfaceMode = (typeof HERDR_SURFACE_MODES)[number];
 
 export interface SubagentMuxConfig {
   mux: SubagentMuxPreference;
   source: SubagentMuxConfigSource;
 }
 
+export interface SubagentHerdrModeConfig {
+  herdrMode: HerdrSurfaceMode;
+  source: SubagentMuxConfigSource;
+}
+
 const BACKENDS: readonly MuxBackend[] = ["muxy", "cmux", "tmux", "zellij", "wezterm", "herdr", "otty", "orca"];
 const CONFIG_FILE = "config.json";
+const HERDR_MODE_ENV = "PI_SUBAGENT_HERDR_MODE";
+const DEFAULT_HERDR_MODE: HerdrSurfaceMode = HERDR_SURFACE_MODE_SPLIT;
 
 function isMuxBackend(value: unknown): value is MuxBackend {
   return typeof value === "string" && (BACKENDS as readonly string[]).includes(value);
@@ -23,26 +34,61 @@ function normalizePreference(value: unknown): SubagentMuxPreference | null {
   return isMuxBackend(value) ? value : null;
 }
 
+/** 将未知配置值收窄为受支持的 Herdr surface 模式。 */
+function normalizeHerdrMode(value: unknown): HerdrSurfaceMode | null {
+  return typeof value === "string" && (HERDR_SURFACE_MODES as readonly string[]).includes(value)
+    ? value as HerdrSurfaceMode
+    : null;
+}
+
 function environmentPreference(): MuxBackend | null {
   const value = (process.env.PI_TERMINAL_MUX ?? process.env.PI_SUBAGENT_MUX ?? "").trim().toLowerCase();
   return isMuxBackend(value) ? value : null;
 }
 
+/** 读取有效的 Herdr 模式环境变量；非法值留给 pi-terminal-mux 显式报错。 */
+function environmentHerdrMode(): HerdrSurfaceMode | null {
+  return normalizeHerdrMode(process.env[HERDR_MODE_ENV]?.trim().toLowerCase());
+}
+
+/** 判断用户是否显式提供了非空 Herdr 模式环境变量，包括待报错的非法值。 */
+function hasHerdrModeEnvironmentOverride(): boolean {
+  return !!process.env[HERDR_MODE_ENV]?.trim();
+}
+
 /** User-level config shared by the subagent extension across Pi sessions. */
 export function muxConfigPath(): string {
   return join(getAgentDir(), "extensions", "pi-interactive-subagents", CONFIG_FILE);
 }
 
-function readStoredPreference(path: string): SubagentMuxPreference | null {
+/** 读取配置对象；不存在、格式错误或非对象时返回空对象。 */
+function readConfigObject(path: string): Record<string, unknown> {
   try {
-    if (!existsSync(path)) return null;
-    const parsed = JSON.parse(readFileSync(path, "utf-8")) as { mux?: unknown };
-    return normalizePreference(parsed.mux);
+    if (!existsSync(path)) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : {};
   } catch {
-    return null;
+    return {};
   }
 }
 
+/** 写入完整配置对象并保留稳定的格式与结尾换行。 */
+function writeConfigObject(path: string, config: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+function readStoredPreference(path: string): SubagentMuxPreference | null {
+  return normalizePreference(readConfigObject(path).mux);
+}
+
+/** 读取持久化 Herdr 模式；旧配置缺少字段时返回 null。 */
+function readStoredHerdrMode(path: string): HerdrSurfaceMode | null {
+  return normalizeHerdrMode(readConfigObject(path).herdrMode);
+}
+
 /** Environment variables override the persisted slash-command setting. */
 export function loadMuxConfig(path = muxConfigPath()): SubagentMuxConfig {
   const env = environmentPreference();
@@ -54,12 +100,30 @@ export function loadMuxConfig(path = muxConfigPath()): SubagentMuxConfig {
   return { mux: "auto", source: "default" };
 }
 
-/** Apply the persisted setting when no explicit environment override exists. */
+/** Herdr mode environment variables override the persisted setting; default stays split. */
+export function loadHerdrModeConfig(path = muxConfigPath()): SubagentHerdrModeConfig {
+  const env = environmentHerdrMode();
+  if (env) return { herdrMode: env, source: "environment" };
+
+  const stored = readStoredHerdrMode(path);
+  if (stored) return { herdrMode: stored, source: "file" };
+
+  return { herdrMode: DEFAULT_HERDR_MODE, source: "default" };
+}
+
+/** Apply persisted mux and Herdr mode settings when no explicit environment override exists. */
 export function applyPersistedMuxPreference(path = muxConfigPath()): void {
-  if (environmentPreference()) return;
-  const preference = readStoredPreference(path);
-  if (!preference || preference === "auto") return;
-  process.env.PI_TERMINAL_MUX = preference;
+  if (!environmentPreference()) {
+    const preference = readStoredPreference(path);
+    if (preference && preference !== "auto") {
+      process.env.PI_TERMINAL_MUX = preference;
+    }
+  }
+
+  if (!hasHerdrModeEnvironmentOverride()) {
+    const herdrMode = readStoredHerdrMode(path);
+    if (herdrMode) process.env[HERDR_MODE_ENV] = herdrMode;
+  }
 }
 
 /** Persist a slash-command selection and make it effective immediately. */
@@ -67,20 +131,7 @@ export function saveMuxPreference(preference: SubagentMuxPreference, path = muxC
   const normalized = normalizePreference(preference);
   if (!normalized) throw new Error(`Unsupported subagent mux preference: ${String(preference)}`);
 
-  let existing: Record<string, unknown> = {};
-  try {
-    if (existsSync(path)) {
-      const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        existing = parsed as Record<string, unknown>;
-      }
-    }
-  } catch {
-    // A malformed file is replaced with a valid config by this explicit save.
-  }
-
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify({ ...existing, mux: normalized }, null, 2)}\n`, "utf-8");
+  writeConfigObject(path, { ...readConfigObject(path), mux: normalized });
 
   if (normalized === "auto") {
     delete process.env.PI_TERMINAL_MUX;
@@ -93,4 +144,14 @@ export function saveMuxPreference(preference: SubagentMuxPreference, path = muxC
   return { mux: normalized, source: "file" };
 }
 
+/** Persist a Herdr split/tab selection and make it effective immediately. */
+export function saveHerdrMode(mode: HerdrSurfaceMode, path = muxConfigPath()): SubagentHerdrModeConfig {
+  const normalized = normalizeHerdrMode(mode);
+  if (!normalized) throw new Error(`Unsupported Herdr surface mode: ${String(mode)}`);
+
+  writeConfigObject(path, { ...readConfigObject(path), herdrMode: normalized });
+  process.env[HERDR_MODE_ENV] = normalized;
+  return { herdrMode: normalized, source: "file" };
+}
+
 export { BACKENDS as SUBAGENT_MUX_BACKENDS };

package/pi-extension/subagents/subagent-done.ts

@@ -13,7 +13,7 @@
  *   现在不论 autoExit env 如何，agent 都必须主动调用 subagent_done 或 caller_ping
  *   才能结束。如果 agent 不调，会被 nudge 提醒。
  */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { writeFileSync } from "node:fs";
@@ -22,23 +22,41 @@ import { createTranslator, loadCatalog } from "pi-extensions-i18n";
 import { createSubagentActivityRecorder } from "./activity.ts";
 
 const i18n = createTranslator(loadCatalog(new URL("../../locales/index.json", import.meta.url)));
+const ASSISTANT_ROLE = "assistant";
+const NORMAL_STOP_REASON = "stop";
+const ABORTED_STOP_REASON = "aborted";
 
+/** Treat input as manual takeover only after the first agent run has started. */
 export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
   return agentStarted;
 }
 
+/** Return true only when the latest assistant message ended by the model stopping normally. */
+export function shouldScheduleAgentEndNudge(
+  messages: readonly { role?: string; stopReason?: string }[] | undefined,
+): boolean {
+  if (!messages) return false;
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role === ASSISTANT_ROLE) {
+      return message.stopReason === NORMAL_STOP_REASON;
+    }
+  }
+
+  return false;
+}
+
+/** Preserve the former auto-exit decision for callers that still use this helper. */
 export function shouldAutoExitOnAgentEnd(
   _userTookOver: boolean,
-  messages: any[] | undefined,
+  messages: readonly { role?: string; stopReason?: string }[] | undefined,
 ): boolean {
-  // Manual input should not strand an auto-exit subagent. If the latest agent
-  // turn completed normally, close the session. Escape/abort still leaves it
-  // open for inspection or another prompt.
   if (messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
-      const msg = messages[i];
-      if (msg?.role === "assistant") {
-        return msg.stopReason !== "aborted";
+      const message = messages[i];
+      if (message?.role === ASSISTANT_ROLE) {
+        return message.stopReason !== ABORTED_STOP_REASON;
       }
     }
   }
@@ -46,6 +64,7 @@ export function shouldAutoExitOnAgentEnd(
   return true;
 }
 
+/** Parse the comma-separated denied-tool setting and discard blank entries. */
 export function parseDeniedTools(rawValue: string | undefined): string[] {
   return (rawValue ?? "")
     .split(",")
@@ -81,6 +100,7 @@ export default function (pi: ExtensionAPI) {
   let userInputAfterAgentEnd = false;
   let nudgeTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Cancel and forget the pending completion reminder, if any. */
   function clearNudgeTimer(): void {
     if (nudgeTimer !== null) {
       clearTimeout(nudgeTimer);
@@ -89,18 +109,17 @@ export default function (pi: ExtensionAPI) {
   }
 
   /**
-   * After a non-auto-exit subagent finishes generating, schedule a nudge
-   * reminding it to call subagent_done if it hasn't already.
+   * After a subagent stops normally, schedule a nudge reminding it to call
+   * subagent_done if it hasn't already. Error and aborted runs are excluded.
    *
    * Each call replaces any pending nudge, so repeated agent_end events
-   * (e.g. during multi-turn tool use) automatically reset the timer.
-   * The nudge only fires if no new agent activity or user input arrives
-   * within NUDGE_DELAY_MS.
+   * automatically reset the timer. The nudge only fires if no new agent
+   * activity or user input arrives within NUDGE_DELAY_MS.
    */
   function scheduleAgentEndNudge(): void {
     clearNudgeTimer();
     // 不论 autoExit 是否启用，都必须 nudge — autoExit 已被移除，
-    // agent 结束 turn 后只能靠主动调用 subagent_done 才能真正退出。
+    // agent 正常结束 turn 后只能靠主动调用 subagent_done 才能真正退出。
     if (NUDGE_DISABLED || doneCalled) return;
 
     nudgeTimer = setTimeout(() => {
@@ -114,10 +133,11 @@ export default function (pi: ExtensionAPI) {
     }, NUDGE_DELAY_MS);
   }
 
-  function renderWidget(ctx: { ui: { setWidget: Function } }, _theme: any) {
+  /** Render the subagent identity and tool availability widget. */
+  function renderWidget(ctx: Pick<ExtensionContext, "ui">): void {
     ctx.ui.setWidget(
       "subagent-tools",
-      (_tui: any, theme: any) => {
+      (_tui, theme) => {
         const box = new Box(1, 0, (text: string) => theme.bg("toolSuccessBg", text));
 
         const label = subagentAgent || subagentName;
@@ -178,7 +198,7 @@ export default function (pi: ExtensionAPI) {
     toolNames = tools.map((t) => t.name).sort();
     denied = parseDeniedTools(deniedToolsValue);
 
-    renderWidget(ctx, null);
+    renderWidget(ctx);
   });
 
   pi.on("input", () => {
@@ -216,10 +236,13 @@ export default function (pi: ExtensionAPI) {
     // subagent_done（或 caller_ping）。如果 agent 不调，下面会有 nudge 提醒。
     recorder.agentEndWaiting();
 
-    // For non-auto-exit agents: schedule a nudge in case the AI forgot to call
-    // subagent_done. This is automatically cleared/reset on any subsequent
-    // agent activity or user input.
-    scheduleAgentEndNudge();
+    // Only a normal model stop means the agent itself chose to finish.
+    // Provider errors and user aborts must stay quiet.
+    if (shouldScheduleAgentEndNudge(event.messages)) {
+      scheduleAgentEndNudge();
+    } else {
+      clearNudgeTimer();
+    }
   });
 
   pi.on("turn_start", (event) => {
@@ -272,7 +295,7 @@ export default function (pi: ExtensionAPI) {
     description: "Toggle subagent tools widget",
     handler: (ctx) => {
       expanded = !expanded;
-      renderWidget(ctx, null);
+      renderWidget(ctx);
     },
   });