@maplezzk/pi-interactive-subagents 3.13.1 → 3.15.0

package/README.md

@@ -173,6 +173,8 @@ The persisted Herdr mode, child-spawning policy, and explicit child-extension li
 
 `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. `allowSubagentSpawning` is a global switch for whether child subagents may create or manage other subagents; it defaults to `false`. Set it to `true` to enable the lifecycle tools in child sessions when the corresponding extension is selected. `subagentExtensions` is an optional list of extension paths to load explicitly in child sessions; automatic project/global extension discovery is disabled. Paths may be absolute, start with `~/`, or be relative to `PI_CODING_AGENT_DIR`. `subagent-done.ts` is always loaded. Explicit `deny-tools` restrictions still apply.
 
+You can configure `subagentExtensions` from the input slash-command menu instead of editing JSON: `/config:subagent extensions` discovers project and global Pi extension entrypoints and opens a toggle-style chooser. The built-in `subagent-done.ts` entry is always shown as required and cannot be disabled. Uninstalled extensions are shown as missing and are skipped; saving the chooser removes their stale paths. Choose `Enter extension paths manually` for custom paths. Direct forms remain available: `/config:subagent extensions path-a.ts,path-b.ts` saves paths, and `/config:subagent extensions clear` removes all optional entries. The dedicated `/config:subagent-extensions` command (also `/subagent-extensions`) supports the same behavior. Changes apply to the next child session.
+
 `config.json` is gitignored so local overrides don't get committed.
 
 ---

package/README.zh-CN.md

@@ -62,7 +62,9 @@ zellij --session pi   # 然后运行 pi
 }
 ```
 
-`herdrMode` 支持 `split`（默认，兼容原有 pane 布局）和 `tab`（每个 subagent 独立后台 Tab）。`allowSubagentSpawning` 是全局开关，控制子 agent 是否可以创建或管理其他 subagent，默认值为 `false`；设置为 `true` 后，子 agent 才会获得这些生命周期工具。`subagentExtensions` 是可选扩展路径列表；子 agent 不再自动发现项目级和全局扩展，只加载列表中的扩展，`subagent-done.ts` 始终加载。路径可以是绝对路径、`~/` 路径，或相对于 `PI_CODING_AGENT_DIR` 的路径。`/config:subagent herdr split|tab` 会更新 Herdr 字段。
+`herdrMode` 支持 `split`（默认，兼容原有分屏布局）和 `tab`（每个 subagent 独立后台 Tab）。`allowSubagentSpawning` 是全局开关，控制子 agent 是否可以创建或管理其他 subagent，默认值为 `false`；设置为 `true` 后，子 agent 才会获得这些生命周期工具。`subagentExtensions` 是可选扩展路径列表；子 agent 不再自动发现项目级和全局扩展，只加载列表中的扩展，`subagent-done.ts` 始终加载。路径可以是绝对路径、`~/` 路径，或相对于 `PI_CODING_AGENT_DIR` 的路径。`/config:subagent herdr split|tab` 会更新 Herdr 字段。
+
+现在也可以直接在输入框使用斜杠命令配置扩展：`/config:subagent extensions` 会自动发现项目级和全局 Pi 扩展，并打开可切换的候选列表。内置的 `subagent-done.ts` 会显示为必选项，始终加载且不能取消。已卸载的插件会显示为缺失并被跳过；保存候选列表时会清理这些残留路径。也可以选择“手动输入扩展路径”配置自定义入口。直接配置仍然支持 `/config:subagent extensions path-a.ts,path-b.ts`，清空可使用 `/config:subagent extensions clear`。另提供 `/config:subagent-extensions`（别名 `/subagent-extensions`），用法相同。修改会在下一个子会话启动时生效。
 
 ## 致谢
 

package/SKILL.md

@@ -11,6 +11,8 @@ description: "配置与排查 interactive subagents 的终端复用器、Herdr s
 
 环境变量优先级：`PI_TERMINAL_MUX` > `PI_SUBAGENT_MUX` > 持久化 `mux` > `auto`；`PI_SUBAGENT_HERDR_MODE` > 持久化 `herdrMode` > `split`。
 
+`/config:subagent extensions` 或 `/config:subagent-extensions` 可直接配置 `subagentExtensions`：命令会发现项目级和全局扩展并提供候选列表，`subagent-done.ts` 始终加载且不能移除；已卸载的扩展会被检测并跳过。也可以手动输入路径，命令参数用逗号分隔，输入 `clear` 清空可选扩展。
+
 ## 修改
 
 优先运行：

package/locales/index.json

@@ -46,5 +46,69 @@
   "muxInteractiveOnly": {
     "zh-CN": "请在支持 UI 的 Pi 会话中运行 /config:subagent。",
     "en-US": "Run /config:subagent in a Pi session with UI support."
+  },
+  "extensionCommandDescription": {
+    "zh-CN": "配置子 agent 显式加载的扩展",
+    "en-US": "Configure extensions explicitly loaded by child subagents"
+  },
+  "extensionConfigTitle": {
+    "zh-CN": "配置子 agent 扩展（每行一个路径；命令参数用逗号分隔）",
+    "en-US": "Configure subagent extensions (one path per line; comma-separated in commands)"
+  },
+  "extensionSaved": {
+    "zh-CN": "子 agent 扩展已设置为：{value}",
+    "en-US": "Subagent extensions set to: {value}"
+  },
+  "extensionInvalid": {
+    "zh-CN": "扩展配置无效：{value}。编辑器中每行输入一个路径；命令参数请使用逗号分隔，或输入 clear 清空。",
+    "en-US": "Invalid extension configuration: {value}. Use one path per line in the editor, comma-separated paths in commands, or clear to remove them."
+  },
+  "extensionInteractiveOnly": {
+    "zh-CN": "请在支持 UI 的 Pi 会话中配置子 agent 扩展。",
+    "en-US": "Configure subagent extensions in a Pi session with UI support."
+  },
+  "extensionNone": {
+    "zh-CN": "未配置",
+    "en-US": "none"
+  },
+  "extensionClearDescription": {
+    "zh-CN": "清空子 agent 扩展列表",
+    "en-US": "Clear the child-session extension list"
+  },
+  "extensionConfiguredDescription": {
+    "zh-CN": "当前配置的扩展路径",
+    "en-US": "Currently configured extension path"
+  },
+  "extensionChooserTitle": {
+    "zh-CN": "选择要加载到 subagent 的扩展",
+    "en-US": "Choose extensions to load in subagents"
+  },
+  "extensionChooserDone": {
+    "zh-CN": "完成并保存",
+    "en-US": "Done and save"
+  },
+  "extensionChooserManual": {
+    "zh-CN": "手动输入扩展路径",
+    "en-US": "Enter extension paths manually"
+  },
+  "extensionCandidateProject": {
+    "zh-CN": "项目扩展",
+    "en-US": "project extension"
+  },
+  "extensionCandidateGlobal": {
+    "zh-CN": "全局扩展",
+    "en-US": "global extension"
+  },
+  "extensionCandidateConfigured": {
+    "zh-CN": "已配置扩展",
+    "en-US": "configured extension"
+  },
+  "extensionCandidateRequired": {
+    "zh-CN": "始终加载，不可移除",
+    "en-US": "always loaded and cannot be removed"
+  },
+  "extensionCandidateMissing": {
+    "zh-CN": "插件未安装，已跳过（完成保存后会移除）",
+    "en-US": "plugin is not installed and will be skipped (removed when saved)"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/pi-interactive-subagents",
-  "version": "3.13.1",
+  "version": "3.15.0",
   "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",
@@ -62,17 +62,17 @@
   ],
   "dependencies": {
     "ajv": "^8.20.0",
-    "pi-extensions-i18n": "^0.4.0",
-    "pi-terminal-mux": "^0.5.1"
+    "pi-extensions-i18n": "^0.5.0",
+    "pi-terminal-mux": "^0.6.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
-    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@earendil-works/pi-tui": ">=0.80.0",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.10",
-    "@earendil-works/pi-tui": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@sinclair/typebox": "^0.34.49",
     "@types/node": "24.12.4",
     "tsx": "4.23.1",

package/pi-extension/subagents/index.ts

@@ -2,12 +2,13 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@sinclair/typebox";
 import { Box, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { dirname, isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+import { createTranslator, loadCatalog, notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
 import {
   readdirSync,
   readFileSync,
+  type Dirent,
   writeFileSync,
   existsSync,
   mkdirSync,
@@ -51,6 +52,7 @@ import {
   loadSubagentSpawningConfig,
   saveHerdrMode,
   saveMuxPreference,
+  saveSubagentExtensions,
   SUBAGENT_MUX_BACKENDS,
   type HerdrSurfaceMode,
   type SubagentMuxPreference,
@@ -85,6 +87,21 @@ import {
 
 const i18n = createTranslator(loadCatalog(new URL("../../locales/index.json", import.meta.url)));
 
+/** 本扩展的提示标签；短且唯一，便于在会话里定位来源。 */
+const NOTICE_TAG = "subagents";
+/** 提示标签颜色；与其它扩展错开，避免看起来像同一条消息。 */
+const NOTICE_COLOR: NoticeColor = "toolTitle";
+/** 本扩展的提示来源。 */
+const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
+
+/**
+ * 统一的用户可见提示出口：加来源标签后交给 Pi 的 notify。
+ * 包内所有 notify 都走这里，避免遗漏标签或颜色。
+ */
+function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error"): void {
+  notifyWithSource({ ctx, source: NOTICE_SOURCE, level, message });
+}
+
 /** Absolute path to `pi-extension/subagents`. https://github.com/nodejs/node/issues/37845 */
 const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -275,17 +292,167 @@ function getBundledAgentsDir(): string {
 }
 
 const HOME_PREFIX = "~/";
+const PROJECT_EXTENSIONS_DIR = [".pi", "extensions"] as const;
+const GLOBAL_EXTENSIONS_DIR = "extensions";
+const EXTENSION_ENTRY_SUFFIXES = [".ts", ".js", ".mjs", ".cjs"] as const;
+const EXTENSION_DECLARATION_SUFFIX = ".d.ts";
+const EXTENSION_INDEX_FILE_NAMES = ["index.ts", "index.js", "index.mjs", "index.cjs"] as const;
+
+const EXTENSION_SOURCE_PROJECT = "project" as const;
+const EXTENSION_SOURCE_GLOBAL = "global" as const;
+const EXTENSION_SOURCE_CONFIGURED = "configured" as const;
+
+type SubagentExtensionCandidateSource =
+  | typeof EXTENSION_SOURCE_PROJECT
+  | typeof EXTENSION_SOURCE_GLOBAL
+  | typeof EXTENSION_SOURCE_CONFIGURED;
+
+export interface SubagentExtensionCandidate {
+  path: string;
+  label: string;
+  source: SubagentExtensionCandidateSource;
+  missing?: boolean;
+  required?: boolean;
+}
+
+/** Narrow unknown manifest values to object records before reading fields. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Check whether a file can be loaded as an extension entrypoint, excluding declarations. */
+function isExtensionEntry(fileName: string): boolean {
+  return EXTENSION_ENTRY_SUFFIXES.some((suffix) => fileName.endsWith(suffix)) && !fileName.endsWith(EXTENSION_DECLARATION_SUFFIX);
+}
 
 /** Resolve an extension path from the user config against the Pi agent directory. */
-function resolveSubagentExtensionPath(extensionPath: string): string {
+function resolveSubagentExtensionPath(extensionPath: string, agentDir = getAgentConfigDir()): string {
   if (extensionPath === "~") return homedir();
   if (extensionPath.startsWith(HOME_PREFIX)) return join(homedir(), extensionPath.slice(HOME_PREFIX.length));
-  return isAbsolute(extensionPath) ? extensionPath : join(getAgentConfigDir(), extensionPath);
+  return isAbsolute(extensionPath) ? extensionPath : join(agentDir, extensionPath);
 }
 
-/** Load and resolve explicitly configured child-session extension paths. */
+/** Read the Pi extension manifest fields needed to discover an installed entrypoint. */
+function readExtensionManifest(extensionDir: string): { name?: string; extensions: string[] } | null {
+  try {
+    const parsed = JSON.parse(readFileSync(join(extensionDir, "package.json"), "utf8")) as unknown;
+    if (!isRecord(parsed)) return null;
+
+    const packageName = typeof parsed.name === "string" ? parsed.name : undefined;
+    const pi = isRecord(parsed.pi) ? parsed.pi : undefined;
+    const configured = pi?.extensions;
+    const extensions = Array.isArray(configured)
+      ? configured.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "")
+      : typeof configured === "string" && configured.trim() !== ""
+        ? [configured]
+        : [];
+    return { name: packageName, extensions };
+  } catch {
+    return null;
+  }
+}
+
+/** Discover extension entrypoints in one Pi extension root without throwing on stale installs. */
+function discoverExtensionRoot(
+  root: string,
+  source: Exclude<SubagentExtensionCandidateSource, "configured">,
+): SubagentExtensionCandidate[] {
+  if (!existsSync(root)) return [];
+
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates: SubagentExtensionCandidate[] = [];
+  const seen = new Set<string>();
+
+  /** Add an existing extension candidate once, using its normalized path as the key. */
+  const add = (path: string, label: string) => {
+    const normalizedPath = resolve(path);
+    if (!existsSync(path) || seen.has(normalizedPath)) return;
+    seen.add(normalizedPath);
+    candidates.push({ path: normalizedPath, label, source });
+  };
+
+  for (const entry of entries) {
+    const entryPath = join(root, entry.name);
+    if (entry.isFile()) {
+      if (isExtensionEntry(entry.name)) add(entryPath, entry.name);
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+
+    const manifest = readExtensionManifest(entryPath);
+    const manifestEntries = manifest?.extensions ?? [];
+    if (manifestEntries.length > 0) {
+      for (const extension of manifestEntries) {
+        const extensionPath = isAbsolute(extension) ? extension : resolve(entryPath, extension);
+        add(extensionPath, manifest?.name ?? entry.name);
+      }
+      continue;
+    }
+
+    const indexPath = EXTENSION_INDEX_FILE_NAMES
+      .map((fileName) => join(entryPath, fileName))
+      .find((path) => existsSync(path));
+    if (indexPath) {
+      add(indexPath, manifest?.name ?? entry.name);
+      continue;
+    }
+
+    try {
+      for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+        if (child.isFile() && isExtensionEntry(child.name)) {
+          add(join(entryPath, child.name), `${manifest?.name ?? entry.name}/${child.name}`);
+        }
+      }
+    } catch {
+      // An extension can disappear while the chooser is open; skip that entry.
+    }
+  }
+
+  return candidates;
+}
+
+/** Discover project/global extension candidates and retain stale configured paths for cleanup. */
+export function discoverSubagentExtensionCandidates(params: {
+  cwd?: string;
+  agentDir?: string;
+  configured?: readonly string[];
+} = {}): SubagentExtensionCandidate[] {
+  const cwd = params.cwd ?? process.cwd();
+  const agentDir = params.agentDir ?? getAgentConfigDir();
+  const candidates = [
+    ...discoverExtensionRoot(join(cwd, ...PROJECT_EXTENSIONS_DIR), EXTENSION_SOURCE_PROJECT),
+    ...discoverExtensionRoot(join(agentDir, GLOBAL_EXTENSIONS_DIR), EXTENSION_SOURCE_GLOBAL),
+  ];
+  const known = new Set(candidates.map((candidate) => resolve(candidate.path)));
+  const configured = params.configured ?? loadSubagentExtensionsConfig().extensions;
+
+  for (const configuredPath of configured) {
+    const resolvedPath = resolveSubagentExtensionPath(configuredPath, agentDir);
+    const key = resolve(resolvedPath);
+    if (known.has(key)) continue;
+    candidates.push({
+      path: key,
+      label: basename(key),
+      source: EXTENSION_SOURCE_CONFIGURED,
+      missing: !existsSync(key),
+    });
+    known.add(key);
+  }
+
+  return candidates;
+}
+
+/** Load and resolve explicitly configured child-session extension paths that still exist. */
 function getConfiguredSubagentExtensions(): string[] {
-  return loadSubagentExtensionsConfig().extensions.map(resolveSubagentExtensionPath);
+  return loadSubagentExtensionsConfig().extensions
+    .map((extensionPath) => resolveSubagentExtensionPath(extensionPath))
+    .filter((extensionPath) => existsSync(extensionPath));
 }
 
 /** Build the no-discovery flag and explicit extensions for a child Pi command. */
@@ -1037,7 +1204,227 @@ function parseMuxConfigRequest(requested: string): MuxConfigSelection | null {
   return { preference, herdrMode: requestedMode as HerdrSurfaceMode };
 }
 
-/** 保存 mux 选择，并在 Herdr 选项携带模式时一并持久化。 */
+const SUBAGENT_EXTENSIONS_COMMAND = "extensions";
+const SUBAGENT_EXTENSIONS_CLEAR = "clear";
+const SUBAGENT_EXTENSIONS_COMMAND_NAMES = [
+  "config:subagent-extensions",
+  "subagent-extensions",
+] as const;
+
+/** Parse comma-separated extension paths from a slash-command argument. */
+function parseSubagentExtensionPaths(value: string): string[] | null {
+  const parts = value.split(",").map((part) => part.trim());
+  if (parts.length === 0 || parts.some((part) => !part)) return null;
+  return [...new Set(parts)];
+}
+
+/** Format the configured child-session extension paths for user-facing messages. */
+function formatSubagentExtensions(extensions: readonly string[]): string {
+  return extensions.length > 0 ? extensions.join(", ") : i18n.t("extensionNone");
+}
+
+/** Complete the shared subagent configuration command's first argument. */
+function getSubagentConfigArgumentCompletions(argumentPrefix: string) {
+  const trimmedPrefix = argumentPrefix.trimStart();
+  const [firstToken] = trimmedPrefix.split(/\s+/, 1);
+  if (firstToken?.toLowerCase() === SUBAGENT_EXTENSIONS_COMMAND && trimmedPrefix !== firstToken) {
+    return getSubagentExtensionsArgumentCompletions(trimmedPrefix.slice(firstToken.length).trimStart());
+  }
+
+  const prefix = argumentPrefix.trim().toLowerCase();
+  const options = [
+    {
+      value: SUBAGENT_EXTENSIONS_COMMAND,
+      label: SUBAGENT_EXTENSIONS_COMMAND,
+      description: i18n.t("extensionCommandDescription"),
+    },
+    { value: AUTO_MUX_PREFERENCE, label: AUTO_MUX_PREFERENCE, description: i18n.t("muxAuto") },
+    ...SUBAGENT_MUX_BACKENDS.map((backend) => ({
+      value: backend,
+      label: backend,
+      description: i18n.t("muxCommandDescription"),
+    })),
+  ];
+  return options.filter((option) => !prefix || option.value.startsWith(prefix));
+}
+
+/** Complete the dedicated extension command with clear and current paths. */
+function getSubagentExtensionsArgumentCompletions(argumentPrefix: string) {
+  const prefix = argumentPrefix.trim().toLowerCase();
+  const configured = loadSubagentExtensionsConfig().extensions;
+  const options = [
+    {
+      value: SUBAGENT_EXTENSIONS_CLEAR,
+      label: SUBAGENT_EXTENSIONS_CLEAR,
+      description: i18n.t("extensionClearDescription"),
+    },
+    ...configured.map((extension) => ({
+      value: extension,
+      label: extension,
+      description: i18n.t("extensionConfiguredDescription"),
+    })),
+  ];
+  return options.filter((option) => !prefix || option.value.toLowerCase().startsWith(prefix));
+}
+
+/** Return a localized source label for an extension candidate. */
+function extensionCandidateSourceLabel(source: SubagentExtensionCandidateSource): string {
+  if (source === EXTENSION_SOURCE_PROJECT) return i18n.t("extensionCandidateProject");
+  if (source === EXTENSION_SOURCE_GLOBAL) return i18n.t("extensionCandidateGlobal");
+  return i18n.t("extensionCandidateConfigured");
+}
+
+/** Format one candidate for the toggle-style slash-command chooser. */
+function formatExtensionCandidateOption(
+  candidate: SubagentExtensionCandidate,
+  selected: ReadonlySet<string>,
+): string {
+  if (candidate.required) {
+    return `● ${candidate.label} — ${i18n.t("extensionCandidateRequired")}`;
+  }
+  if (candidate.missing) {
+    return `⚠ ${candidate.label} — ${i18n.t("extensionCandidateMissing")}`;
+  }
+  const marker = selected.has(resolve(candidate.path)) ? "●" : "○";
+  return `${marker} ${candidate.label} — ${candidate.path} (${extensionCandidateSourceLabel(candidate.source)})`;
+}
+
+/** Edit explicit paths manually and return the entered values without persisting them. */
+async function editSubagentExtensionsManually(
+  ctx: ExtensionContext,
+  initial: readonly string[],
+): Promise<string[] | undefined> {
+  if (!ctx.hasUI) {
+    notify(ctx, i18n.t("extensionInteractiveOnly"), "warning");
+    return undefined;
+  }
+
+  const value = await ctx.ui.editor(i18n.t("extensionConfigTitle"), initial.join("\n"));
+  if (value === null || value === undefined) return undefined;
+  return value
+    .split(/\r?\n/)
+    .map((extension) => extension.trim())
+    .filter(Boolean);
+}
+
+/** Save a selected extension list and report the effective configuration. */
+function saveSelectedSubagentExtensions(ctx: ExtensionContext, extensions: readonly string[]): void {
+  const saved = saveSubagentExtensions(extensions);
+  notify(ctx,
+    i18n.t("extensionSaved", { value: formatSubagentExtensions(saved.extensions) }),
+    "info",
+  );
+}
+
+/** Let the user toggle discovered extensions while keeping the built-in done hook fixed. */
+async function chooseSubagentExtensions(ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI) {
+    notify(ctx, i18n.t("extensionInteractiveOnly"), "warning");
+    return;
+  }
+
+  const configured = loadSubagentExtensionsConfig().extensions;
+  const configuredResolved = configured.map((extension) => resolveSubagentExtensionPath(extension));
+  const requiredPath = resolve(join(SUBAGENTS_DIR, SUBAGENT_DONE_EXTENSION_FILE));
+  const candidateMap = new Map<string, SubagentExtensionCandidate>();
+  for (const candidate of [
+    {
+      path: requiredPath,
+      label: SUBAGENT_DONE_EXTENSION_FILE,
+      source: EXTENSION_SOURCE_CONFIGURED,
+      required: true,
+    },
+    ...discoverSubagentExtensionCandidates({ configured }),
+  ]) {
+    const key = resolve(candidate.path);
+    if (!candidateMap.has(key)) candidateMap.set(key, candidate);
+  }
+  const candidates = [...candidateMap.values()];
+  const selected = new Set(
+    configuredResolved
+      .filter((extensionPath) => existsSync(extensionPath))
+      .map((extensionPath) => resolve(extensionPath)),
+  );
+
+  const candidateOptions = new Map<string, SubagentExtensionCandidate>();
+  while (true) {
+    candidateOptions.clear();
+    const options = candidates.map((candidate) => {
+      const option = formatExtensionCandidateOption(candidate, selected);
+      candidateOptions.set(option, candidate);
+      return option;
+    });
+    const doneOption = i18n.t("extensionChooserDone");
+    const manualOption = i18n.t("extensionChooserManual");
+    options.push(manualOption, doneOption);
+
+    const choice = await ctx.ui.select(i18n.t("extensionChooserTitle"), options);
+    if (choice === undefined) return;
+    if (choice === doneOption) {
+      saveSelectedSubagentExtensions(ctx, [...selected]);
+      return;
+    }
+    if (choice === manualOption) {
+      const manual = await editSubagentExtensionsManually(ctx, [...selected]);
+      if (manual !== undefined) {
+        selected.clear();
+        for (const extension of manual) selected.add(resolveSubagentExtensionPath(extension));
+      }
+      continue;
+    }
+
+    const candidate = candidateOptions.get(choice);
+    if (!candidate || candidate.required || candidate.missing) continue;
+    const normalizedPath = resolve(candidate.path);
+    if (selected.has(normalizedPath)) selected.delete(normalizedPath);
+    else selected.add(normalizedPath);
+  }
+}
+
+/** Handle `/config:subagent extensions ...` or the dedicated extension command. */
+async function handleSubagentExtensionsCommand(
+  args: string,
+  ctx: ExtensionContext,
+  hasKeyword: boolean,
+): Promise<boolean> {
+  const requested = args.trim();
+  let extensionArgs = requested;
+
+  if (hasKeyword) {
+    const [keyword] = requested.split(/\s+/, 1);
+    if (keyword?.toLowerCase() !== SUBAGENT_EXTENSIONS_COMMAND) return false;
+    extensionArgs = requested.slice(keyword.length).trim();
+  }
+
+  if (!extensionArgs) {
+    await chooseSubagentExtensions(ctx);
+    return true;
+  }
+
+  if (extensionArgs.toLowerCase() === SUBAGENT_EXTENSIONS_CLEAR) {
+    const saved = saveSubagentExtensions([]);
+    notify(ctx,
+      i18n.t("extensionSaved", { value: formatSubagentExtensions(saved.extensions) }),
+      "info",
+    );
+    return true;
+  }
+
+  const extensions = parseSubagentExtensionPaths(extensionArgs);
+  if (!extensions) {
+    notify(ctx, i18n.t("extensionInvalid", { value: requested }), "warning");
+    return true;
+  }
+
+  const saved = saveSubagentExtensions(extensions);
+  notify(ctx,
+    i18n.t("extensionSaved", { value: formatSubagentExtensions(saved.extensions) }),
+    "info",
+  );
+  return true;
+}
+
+/** Save mux selection, and optionally its Herdr surface mode. */
 function saveMuxConfigSelection(selection: MuxConfigSelection): MuxConfigSelection {
   const savedMux = saveMuxPreference(selection.preference);
   const savedMode = selection.herdrMode ? saveHerdrMode(selection.herdrMode).herdrMode : undefined;
@@ -1048,12 +1435,14 @@ function saveMuxConfigSelection(selection: MuxConfigSelection): MuxConfigSelecti
 function registerMuxConfigCommand(pi: ExtensionAPI): void {
   const command = {
     description: i18n.t("muxCommandDescription"),
+    getArgumentCompletions: getSubagentConfigArgumentCompletions,
     handler: async (args, ctx) => {
       const requested = args.trim();
+      if (requested && await handleSubagentExtensionsCommand(requested, ctx, true)) return;
       if (requested) {
         const selection = parseMuxConfigRequest(requested);
         if (!selection) {
-          ctx.ui.notify(i18n.t("muxInvalid", { value: requested }), "warning");
+          notify(ctx, i18n.t("muxInvalid", { value: requested }), "warning");
           return;
         }
         try {
@@ -1061,18 +1450,18 @@ function registerMuxConfigCommand(pi: ExtensionAPI): void {
           const herdrMode = saved.preference === HERDR_MUX_BACKEND
             ? saved.herdrMode ?? loadHerdrModeConfig().herdrMode
             : undefined;
-          ctx.ui.notify(
+          notify(ctx,
             i18n.t("muxSaved", { value: muxPreferenceLabel(saved.preference, herdrMode) }),
             "info",
           );
         } catch (error) {
-          ctx.ui.notify(String(error), "error");
+          notify(ctx, String(error), "error");
         }
         return;
       }
 
       if (!ctx.hasUI) {
-        ctx.ui.notify(i18n.t("muxInteractiveOnly"), "warning");
+        notify(ctx, i18n.t("muxInteractiveOnly"), "warning");
         return;
       }
 
@@ -1117,20 +1506,31 @@ function registerMuxConfigCommand(pi: ExtensionAPI): void {
       if (!selected) return;
       try {
         const saved = saveMuxConfigSelection(selected);
-        ctx.ui.notify(
+        notify(ctx,
           i18n.t("muxSaved", {
             value: muxPreferenceLabel(saved.preference, saved.herdrMode),
           }),
           "info",
         );
       } catch (error) {
-        ctx.ui.notify(String(error), "error");
+        notify(ctx, String(error), "error");
       }
     },
   };
   for (const name of ["config:subagent", "subagent-config", "pi-subagent-config"] as const) {
     pi.registerCommand(name, command);
   }
+
+  const extensionsCommand = {
+    description: i18n.t("extensionCommandDescription"),
+    getArgumentCompletions: getSubagentExtensionsArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionContext) => {
+      await handleSubagentExtensionsCommand(args, ctx, false);
+    },
+  };
+  for (const name of SUBAGENT_EXTENSIONS_COMMAND_NAMES) {
+    pi.registerCommand(name, extensionsCommand);
+  }
 }
 
 /** 每次启动或恢复都用新 surface 重建归属，不能继承父进程的改名范围。 */
@@ -1140,13 +1540,20 @@ function buildTerminalRenameEnvironment(surface: string, backend = getMuxBackend
 }
 
 export const __test__ = {
+  notify,
+  NOTICE_SOURCE,
   buildTerminalRenameEnvironment,
   borderLine,
   parseMuxConfigRequest,
+  parseSubagentExtensionPaths,
+  getSubagentConfigArgumentCompletions,
+  getSubagentExtensionsArgumentCompletions,
   getShellReadyDelayMs,
   renderSubagentWidgetLines,
   loadAgentDefaults,
   discoverAgentDefinitions,
+  discoverSubagentExtensionCandidates,
+  getConfiguredSubagentExtensions,
   resolveEffectiveSessionMode,
   resolveLaunchBehavior,
   resolveEffectiveInteractive,
@@ -2224,7 +2631,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       const trimmed = args.trim();
       if (!trimmed) {
-        ctx.ui.notify("Usage: /subagent <agent> [task]", "warning");
+        notify(ctx, "Usage: /subagent <agent> [task]", "warning");
         return;
       }
 
@@ -2234,7 +2641,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
       const defs = loadAgentDefaults(agentName);
       if (!defs) {
-        ctx.ui.notify(
+        notify(ctx,
           `Agent "${agentName}" not found in ~/.pi/agent/agents/ or .pi/agents/`,
           "error",
         );
@@ -2392,7 +2799,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       const task = args.trim();
       if (!task) {
-        ctx.ui.notify("Usage: /plan <what to build>", "warning");
+        notify(ctx, "Usage: /plan <what to build>", "warning");
         return;
       }
 

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

@@ -146,6 +146,16 @@ export function loadSubagentExtensionsConfig(path = muxConfigPath()): SubagentEx
   return { extensions: [...DEFAULT_SUBAGENT_EXTENSIONS], source: "default" };
 }
 
+/** Persist the explicit extension list for child sessions. */
+export function saveSubagentExtensions(
+  extensions: readonly string[],
+  path = muxConfigPath(),
+): SubagentExtensionsConfig {
+  const normalized = [...new Set(extensions.map((extension) => extension.trim()).filter(Boolean))];
+  writeConfigObject(path, { ...readConfigObject(path), subagentExtensions: normalized });
+  return { extensions: normalized, source: "file" };
+}
+
 /** Apply persisted mux and Herdr mode settings when no explicit environment override exists. */
 export function applyPersistedMuxPreference(path = muxConfigPath()): void {
   if (!environmentPreference()) {