@armadra/agent 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.12.0 (2026-11-02)
+
+### Tools and permissions
+
+- **The `coordinator` preset never blocks**: when `task` / `task_ctl` are exposed, `task` defaults to background (regardless of `-p` and `subagents.background`; an explicit `background` argument and an agent definition's `background:` still win) and `task_ctl wait` is capped at 5 s (the default and larger `timeoutMs` included); the timed-out reply says the wait was capped and that a `<task-notification>` follows. Other presets, tool descriptions and schemas are byte-identical (#242).
+- **`env` / `printenv` are no longer auto-safe**: the bash subprocess inherits the whole process environment (provider API keys included), so in Auto mode a bare `env`, `printenv`, `env FOO=1` or `env | grep …` now goes to the classifier / approval instead of being allowed statically; `env FOO=1 cmd` is still judged as `cmd`. The read-only list for Plan already excluded them, so both lists now agree (#240).
+
+### ACP client
+
+- **Authentication**: `AcpClient.authenticate(methodId)` and `logout()` (`supportsLogout()`), `isAuthRequiredError` for -32000, and the `authTerminal` option that declares `clientCapabilities.auth.terminal`. `authMethods` keeps id, name, description, type and, for terminal methods, `args` / `env`; a known terminal method is refused locally by `authenticate` (-32602) as the spec requires. `isTerminalAuthMethod` and the types `AcpAuthenticateResult`, `AcpLogoutResult`, `AcpTerminalAuthMethod` are exported (#245).
+- **`elicitation/complete` and richer forms**: `onElicitationComplete` handles the notification (declaring `elicitation: { form: {}, url: {} }`) and dismisses a still-pending request with the same `elicitationId`; form fields gain `array` multi-select and titled `oneOf` / `anyOf`, `content` values may be string arrays, and `multiSelectOptions` / `singleSelectOptions` normalize the option lists (#245).
+- **Sessions**: `listSessions` takes a `signal`, `listAllSessions` follows `nextCursor`, `closeSession` takes a `signal` and first answers the session's pending permission and elicitation requests with cancel; `AcpSessionInfo` gains `additionalDirectories` and `_meta`. `AcpClient.features` gains `auth` and `elicitationComplete`. Default wire output is unchanged unless the new options are used (#245).
+
 ## 0.11.0 (2026-10-30)
 
 ### Tools and permissions

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,19 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.12.0（2026-11-02）
+
+### 工具与权限
+
+- **`coordinator` 预设不阻塞**：暴露 `task` / `task_ctl` 时，`task` 缺省后台（不受 `-p` 与 `subagents.background` 影响，调用参数 `background` 与类型定义的 `background:` 仍优先），`task_ctl wait` 的超时封顶 5 秒（含缺省与更大的 `timeoutMs`），超时回复说明被封顶、完成后会有 `<task-notification>`。其它预设、工具描述与 schema 逐字节不变（#242）。
+- **`env` / `printenv` 不再免审批**：bash 子进程继承整个进程环境（含供应商 API key），Auto 模式下裸 `env`、`printenv`、`env FOO=1`、`env | grep …` 现在交给分类器 / 审批，不再静态放行；`env FOO=1 cmd` 仍按 `cmd` 判断。Plan 的只读名单本来就没有它们，两份名单现在一致（#240）。
+
+### ACP 客户端
+
+- **认证**：`AcpClient.authenticate(methodId)` 与 `logout()`（`supportsLogout()`）、判断 -32000 的 `isAuthRequiredError`，以及声明 `clientCapabilities.auth.terminal` 的构造参数 `authTerminal`。`authMethods` 保留 id、name、description、type，terminal 型还有 `args` / `env`；已知是 terminal 型的方法按规范由 `authenticate` 本地拒绝（-32602）。新增导出 `isTerminalAuthMethod` 与类型 `AcpAuthenticateResult`、`AcpLogoutResult`、`AcpTerminalAuthMethod`（#245）。
+- **`elicitation/complete` 与更丰富的表单**：`onElicitationComplete` 接这条通知（声明 `elicitation: { form: {}, url: {} }`），并收掉同 `elicitationId` 还挂着的请求；表单字段新增 `array` 多选与带标题的 `oneOf` / `anyOf`，`content` 的值可以是字符串数组，`multiSelectOptions` / `singleSelectOptions` 把几种写法收成统一的选项列表（#245）。
+- **会话**：`listSessions` 可传 `signal`，新增跟 `nextCursor` 翻页的 `listAllSessions`；`closeSession` 可传 `signal`，并先把该会话挂起的权限与 elicitation 请求答成取消；`AcpSessionInfo` 补 `additionalDirectories`、`_meta`。`AcpClient.features` 增加 `auth` 与 `elicitationComplete`。不用新选项时默认线路输出不变（#245）。
+
 ## 0.11.0（2026-10-30）
 
 ### 工具与权限

package/dist/acp.d.ts

@@ -8,10 +8,10 @@
  */
 export type * from "./drivers/types.js";
 export type * from "./drivers/acp/types.js";
-export { ACP_META_KEY, ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./drivers/acp/types.js";
+export { ACP_META_KEY, isTerminalAuthMethod, multiSelectOptions, singleSelectOptions, ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./drivers/acp/types.js";
 export { WRITE_CHUNK_BYTES, createLineReader, writeChunked, type LineReader, } from "./modes/rpc/jsonl.js";
 export { JsonRpcPeer, RpcError, type IncomingRequestContext, type JsonRpcPeerOptions, type RpcId, } from "./drivers/jsonrpc.js";
-export { AcpClient, unattendedOutcome, type AcpClientHandlers, type AcpClientOptions, } from "./drivers/acp/client.js";
+export { AcpClient, isAuthRequiredError, unattendedOutcome, type AcpClientHandlers, type AcpClientOptions, } from "./drivers/acp/client.js";
 export { AcpDriver } from "./drivers/acp/driver.js";
 export { runFakeAcpAgent, type FakeAcpAgentOptions } from "./drivers/acp/testing/fake-agent.js";
 /** 假 ACP Agent 的可执行入口（`node <path> [--minimal] [--config-options] [--config-only] [--auth-required]`）；只在已编译的包里存在。 */

package/dist/acp.js

@@ -7,10 +7,10 @@
  * - 假 ACP Agent（进程内 `runFakeAcpAgent`，或 `fakeAcpAgentPath()` 起子进程），用于黄金记录。
  */
 import { fileURLToPath } from "node:url";
-export { ACP_META_KEY, ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./drivers/acp/types.js";
+export { ACP_META_KEY, isTerminalAuthMethod, multiSelectOptions, singleSelectOptions, ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./drivers/acp/types.js";
 export { WRITE_CHUNK_BYTES, createLineReader, writeChunked, } from "./modes/rpc/jsonl.js";
 export { JsonRpcPeer, RpcError, } from "./drivers/jsonrpc.js";
-export { AcpClient, unattendedOutcome, } from "./drivers/acp/client.js";
+export { AcpClient, isAuthRequiredError, unattendedOutcome, } from "./drivers/acp/client.js";
 export { AcpDriver } from "./drivers/acp/driver.js";
 export { runFakeAcpAgent } from "./drivers/acp/testing/fake-agent.js";
 /** 假 ACP Agent 的可执行入口（`node <path> [--minimal] [--config-options] [--config-only] [--auth-required]`）；只在已编译的包里存在。 */

package/dist/bundle/ama.cjs

@@ -41,7 +41,7 @@ var AMA_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    AMA_VERSION = true ? "0.11.0" : readPackageVersion();
+    AMA_VERSION = true ? "0.12.0" : readPackageVersion();
   }
 });
 
@@ -15493,6 +15493,9 @@ var init_jsonl = __esm({
 });
 
 // src/drivers/acp/types.ts
+function isTerminalAuthMethod(method) {
+  return method.type === "terminal";
+}
 var ACP_PROTOCOL_VERSION, ACP_METHODS, RPC_ERRORS, ACP_META_KEY;
 var init_types7 = __esm({
   "src/drivers/acp/types.ts"() {
@@ -15500,8 +15503,10 @@ var init_types7 = __esm({
     ACP_PROTOCOL_VERSION = 1;
     ACP_METHODS = {
       initialize: "initialize",
-      /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+      /** 客户端 → Agent：agent 型认证方法经它完成；terminal 型不经它（规范）。 */
       authenticate: "authenticate",
+      /** 客户端 → Agent：登出当前账号（Agent 声明 `agentCapabilities.auth.logout` 才可用）。 */
+      logout: "logout",
       sessionNew: "session/new",
       sessionLoad: "session/load",
       sessionResume: "session/resume",
@@ -15514,6 +15519,8 @@ var init_types7 = __esm({
       sessionUpdate: "session/update",
       requestPermission: "session/request_permission",
       elicitationCreate: "elicitation/create",
+      /** Agent → 客户端通知：URL 型 elicitation 已在带外完成。 */
+      elicitationComplete: "elicitation/complete",
       /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
       cancelRequest: "$/cancel_request"
     };
@@ -19372,6 +19379,9 @@ var init_task_control = __esm({
 });
 
 // src/tools/task-ctl.ts
+function bindTaskCtlWaitCap(tool, capMs) {
+  if (tool !== void 0) waitCaps.set(tool, capMs);
+}
 function fail4(message) {
   return { content: message, isError: true };
 }
@@ -19398,7 +19408,7 @@ async function send(input2, ctx) {
   return { content: result.text, isError: result.isError };
 }
 function createTaskCtlTool() {
-  return {
+  const tool = {
     name: TASK_CTL_TOOL,
     label: "TaskCtl",
     description: "Manage sub-agent tasks started by task: list them, wait for one, stop it, read its output, or send it a follow-up message (runs in background).",
@@ -19449,14 +19459,17 @@ ${body}` };
           };
         }
         case "wait": {
-          const timeout = Math.min(Math.max(input2.timeoutMs ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
+          const cap = Math.min(waitCaps.get(tool) ?? MAX_WAIT_MS, MAX_WAIT_MS);
+          const wanted = Math.min(Math.max(input2.timeoutMs ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
+          const timeout = Math.min(wanted, cap);
           const signal = control.detachSignal(taskId);
           const result = await control.wait(taskId, timeout, { signal });
           if (result === void 0 && signal.aborted) return { content: waitDetachedText(taskId) };
           if (result === void 0) {
             const turns = control.get(taskId)?.turns ?? 0;
+            const capped2 = wanted > timeout ? ` Waits are capped at ${Math.round(timeout / 1e3)}s here; do not block on it: keep working, a <task-notification> follows when it finishes.` : "";
             return {
-              content: `Task ${taskId} is still running (${turns} turns so far). Wait again or stop it.`
+              content: `Task ${taskId} is still running (${turns} turns so far). Wait again or stop it.${capped2}`
             };
           }
           return {
@@ -19470,8 +19483,9 @@ ${result.text}`,
       }
     }
   };
+  return tool;
 }
-var TASK_CTL_TOOL, DEFAULT_WAIT_MS, MAX_WAIT_MS;
+var TASK_CTL_TOOL, DEFAULT_WAIT_MS, MAX_WAIT_MS, COORDINATOR_WAIT_MAX_MS, waitCaps;
 var init_task_ctl = __esm({
   "src/tools/task-ctl.ts"() {
     "use strict";
@@ -19481,6 +19495,8 @@ var init_task_ctl = __esm({
     TASK_CTL_TOOL = "task_ctl";
     DEFAULT_WAIT_MS = 3e4;
     MAX_WAIT_MS = 6e5;
+    COORDINATOR_WAIT_MAX_MS = 5e3;
+    waitCaps = /* @__PURE__ */ new WeakMap();
   }
 });
 
@@ -20364,7 +20380,10 @@ function effectiveCodemodeMode(config, strict) {
   return resolveCodemodeMode(config, strict).mode;
 }
 function codemodeCallableFilter(config) {
-  return canonicalPreset(config.tools?.preset) === "coordinator" ? "active" : void 0;
+  return isCoordinatorPreset(config) ? "active" : void 0;
+}
+function isCoordinatorPreset(config) {
+  return canonicalPreset(config.tools?.preset) === "coordinator";
 }
 function applyToolAdjustments(base4, adjustments) {
   if (adjustments === void 0 || adjustments.length === 0) return [...base4];
@@ -25563,6 +25582,7 @@ function cdTarget(argv, cwd) {
 function parseSegment(segment) {
   const redirects = extractRedirects(segment);
   return {
+    first: shellWords(redirects.rest.replace(/^[({\s]+/, ""))[0],
     argv: commandWords(redirects.rest),
     withSudo: commandWords(redirects.rest, true),
     redirects
@@ -25586,7 +25606,9 @@ function ruleAsk(info2, options) {
 }
 function safeSegment(info2, extra) {
   const argv = info2.withSudo;
-  if (argv.length === 0) return void 0;
+  if (argv.length === 0) {
+    return info2.first === void 0 ? "empty command" : `${base2(info2.first)} is not in the auto safe list`;
+  }
   for (const word of argv) {
     if (word.includes("$")) return `variable expansion in ${word}`;
     if (GLOB.test(word) && /(^|\/)\.[^./]/.test(word)) return `glob over dotfiles (${word})`;
@@ -25663,7 +25685,6 @@ var init_auto_safe = __esm({
         "echo",
         "printf",
         "which",
-        "printenv",
         "true",
         "false",
         "cut",
@@ -35016,6 +35037,7 @@ var init_client = __esm({
           onNotification: (method, params) => {
             if (method === ACP_METHODS.sessionUpdate)
               options.onUpdate?.(params);
+            else if (method === ACP_METHODS.elicitationComplete) this.onElicitationComplete(params);
           },
           onClose: () => {
             for (const set of this.pendingPermissions.values()) for (const c of set) c.abort();
@@ -35031,14 +35053,25 @@ var init_client = __esm({
        * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
        * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
        * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
-       * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
+       * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`；
+       * - `auth`：`authenticate` / `logout`、构造参数 `authTerminal`、`isAuthRequiredError`；
+       * - `elicitationComplete`：构造参数 `onElicitationComplete` 接 `elicitation/complete`，表单字段含多选与 `oneOf`。
        */
-      static features = { mcpServers: true, elicitation: true, configOptions: true, terminal: true };
+      static features = {
+        mcpServers: true,
+        elicitation: true,
+        configOptions: true,
+        terminal: true,
+        auth: true,
+        elicitationComplete: true
+      };
       peer;
       /** sessionId → 挂起权限请求的取消器。 */
       pendingPermissions = /* @__PURE__ */ new Map();
       /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
       pendingElicitations = /* @__PURE__ */ new Map();
+      /** elicitationId → 挂起 elicitation 的取消器（`elicitation/complete` 用）。 */
+      elicitationsById = /* @__PURE__ */ new Map();
       initResult;
       get closed() {
         return this.peer.closed;
@@ -35065,7 +35098,10 @@ var init_client = __esm({
               fs: { readTextFile: false, writeTextFile: false },
               terminal: this.options.onTerminal !== void 0,
               session: { configOptions: {} },
-              ...this.options.onElicitation !== void 0 ? { elicitation: {} } : {}
+              ...this.options.authTerminal === true ? { auth: { terminal: true } } : {},
+              ...this.options.onElicitation !== void 0 || this.options.onElicitationComplete ? {
+                elicitation: this.options.onElicitationComplete !== void 0 ? { form: {}, url: {} } : {}
+              } : {}
             },
             ...this.options.clientInfo !== void 0 ? { clientInfo: this.options.clientInfo } : {}
           },
@@ -35091,9 +35127,30 @@ var init_client = __esm({
       supportsClose() {
         return this.agentCapabilities.sessionCapabilities?.close != null;
       }
+      /** Agent 声明了 `auth.logout`（存在即支持）。 */
+      supportsLogout() {
+        return this.agentCapabilities.auth?.logout != null;
+      }
       supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
       }
+      /**
+       * 用 agent 型认证方法登录（`methodId` 取自 `authMethods`）。terminal 型方法不经 `authenticate`：已知是
+       * terminal 型时抛 -32602，由宿主在终端里跑该方法的 `args` / `env`。失败的错误码原样抛出。
+       */
+      async authenticate(methodId, signal) {
+        const known = this.authMethods.find((method) => method.id === methodId);
+        if (known !== void 0 && isTerminalAuthMethod(known))
+          throw new RpcError(
+            RPC_ERRORS.invalidParams,
+            `auth method ${methodId} is a terminal method: run it in a terminal, not through authenticate`
+          );
+        return this.peer.request(ACP_METHODS.authenticate, { methodId }, signal);
+      }
+      /** 登出当前账号；Agent 没声明 `auth.logout`（见 `supportsLogout`）时会答 method not found。 */
+      logout(signal) {
+        return this.peer.request(ACP_METHODS.logout, {}, signal);
+      }
       newSession(cwd, signal, options) {
         return this.peer.request(
           ACP_METHODS.sessionNew,
@@ -35117,14 +35174,34 @@ var init_client = __esm({
           signal
         );
       }
-      listSessions(cwd, cursor) {
-        return this.peer.request(ACP_METHODS.sessionList, {
-          ...cwd !== void 0 ? { cwd } : {},
-          ...cursor !== void 0 ? { cursor } : {}
-        });
+      /** 一页会话；`cwd` 过滤（绝对路径），`cursor` 取自上一页的 `nextCursor`。 */
+      listSessions(cwd, cursor, signal) {
+        return this.peer.request(
+          ACP_METHODS.sessionList,
+          {
+            ...cwd !== void 0 ? { cwd } : {},
+            ...cursor !== void 0 ? { cursor } : {}
+          },
+          signal
+        );
       }
-      closeSession(sessionId) {
-        return this.peer.request(ACP_METHODS.sessionClose, { sessionId });
+      /** 跟 `nextCursor` 翻页取全（`maxPages` 防对端游标不终止，缺省 100 页）。 */
+      async listAllSessions(cwd, signal, maxPages = 100) {
+        const sessions = [];
+        let cursor;
+        for (let page2 = 0; page2 < maxPages; page2++) {
+          const result = await this.listSessions(cwd, cursor, signal);
+          sessions.push(...result.sessions ?? []);
+          if (typeof result.nextCursor !== "string" || result.nextCursor === "") break;
+          cursor = result.nextCursor;
+        }
+        return sessions;
+      }
+      /** 关闭会话：规范要求 Agent 先取消进行中的工作，所以本端先把该会话挂起的请求收掉。 */
+      closeSession(sessionId, signal) {
+        for (const controller of this.pendingPermissions.get(sessionId) ?? []) controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? []) controller.abort();
+        return this.peer.request(ACP_METHODS.sessionClose, { sessionId }, signal);
       }
       prompt(sessionId, prompt, signal) {
         return this.peer.request(ACP_METHODS.sessionPrompt, { sessionId, prompt }, signal);
@@ -35191,6 +35268,8 @@ var init_client = __esm({
         const set = this.pendingElicitations.get(key) ?? /* @__PURE__ */ new Set();
         set.add(controller);
         this.pendingElicitations.set(key, set);
+        const id = typeof request.elicitationId === "string" ? request.elicitationId : void 0;
+        if (id !== void 0) this.elicitationsById.set(id, controller);
         const signal = AbortSignal.any([controller.signal, connection]);
         try {
           const answer = await Promise.race([
@@ -35205,8 +35284,17 @@ var init_client = __esm({
           return elicitationAnswer(answer);
         } finally {
           set.delete(controller);
+          if (id !== void 0 && this.elicitationsById.get(id) === controller)
+            this.elicitationsById.delete(id);
         }
       }
+      /** 通知没有答复：参数不对就忽略；还挂着的同 id elicitation 先收掉，再交给宿主。 */
+      onElicitationComplete(params) {
+        const id = params?.elicitationId;
+        if (typeof id !== "string") return;
+        this.elicitationsById.get(id)?.abort();
+        this.options.onElicitationComplete?.(params);
+      }
     };
   }
 });
@@ -38784,6 +38872,7 @@ function subagentEnvironment(deps, catalog) {
   if (retain !== void 0) env.retain = retain;
   const sub = config.subagents;
   env.background = resolveTaskBackground(sub?.background, deps.assembly.unattended === true);
+  if (isCoordinatorPreset(config)) env.background = true;
   const after = sub?.autoBackgroundAfterMs;
   if (typeof after === "number" && after > 0) env.autoBackgroundAfterMs = after;
   return env;
@@ -38836,6 +38925,8 @@ function createSubagentsFactory(deps) {
   bindTaskAgents(task, catalog);
   const env = subagentEnvironment(deps, catalog);
   bindTaskBackground(task, env.background === true);
+  if (isCoordinatorPreset(deps.assembly.config))
+    bindTaskCtlWaitCap(deps.assembly.tools.get("task_ctl"), COORDINATOR_WAIT_MAX_MS);
   return ({ core }) => core.depth > 0 ? void 0 : createSubagentExtension(core, env, wiring);
 }
 var warned;
@@ -38847,6 +38938,8 @@ var init_compose_agents = __esm({
     init_discover();
     init_external();
     init_api_impl();
+    init_presets2();
+    init_task_ctl();
     init_task();
     init_subagent_background();
     init_i18n();
@@ -65827,6 +65920,7 @@ function runInteractiveMode(runtime, context, options = {}) {
   tui.addChild(status);
   tui.addChild(area.quota);
   let finished = false;
+  const hintTimers = options.hintTimers ?? realHintTimers;
   let hintTimer;
   let resolveExit = () => void 0;
   const render = () => tui.requestRender();
@@ -65836,14 +65930,13 @@ function runInteractiveMode(runtime, context, options = {}) {
   };
   const showHint = (text, ms = HINT_MS) => {
     hint.setText(text === "" ? "" : theme.fg("dim", text));
-    if (hintTimer !== void 0) clearTimeout(hintTimer);
+    if (hintTimer !== void 0) hintTimers.clear(hintTimer);
     hintTimer = void 0;
     if (text !== "") {
-      hintTimer = setTimeout(() => {
+      hintTimer = hintTimers.set(() => {
         hint.setText("");
         render();
       }, ms);
-      hintTimer.unref?.();
     }
     render();
   };
@@ -66096,7 +66189,7 @@ function runInteractiveMode(runtime, context, options = {}) {
     if (finished) return;
     finished = true;
     logoAnimation?.finish();
-    if (hintTimer !== void 0) clearTimeout(hintTimer);
+    if (hintTimer !== void 0) hintTimers.clear(hintTimer);
     loader.stop();
     area.dispose();
     osc7501.exit();
@@ -66162,7 +66255,7 @@ function runInteractiveMode(runtime, context, options = {}) {
     }
   });
 }
-var import_node_path101, HINT_MS;
+var import_node_path101, HINT_MS, realHintTimers;
 var init_interactive_mode = __esm({
   "src/modes/interactive/interactive-mode.ts"() {
     "use strict";
@@ -66201,6 +66294,14 @@ var init_interactive_mode = __esm({
     init_tool_view();
     init_task_background();
     HINT_MS = 2500;
+    realHintTimers = {
+      set: (fn, ms) => {
+        const handle = setTimeout(fn, ms);
+        handle.unref?.();
+        return handle;
+      },
+      clear: (handle) => clearTimeout(handle)
+    };
   }
 });
 

package/dist/cli/compose-agents.js

@@ -18,6 +18,8 @@ import { AgentCatalog } from "../agents/catalog.js";
 import { agentSources, discoverAgents } from "../agents/discover.js";
 import { NO_AGENT_PROBE_ENV, SessionExternalAgents, registerExternalAgents, } from "../agents/external.js";
 import { hostRunnersOf } from "../host/api-impl.js";
+import { isCoordinatorPreset } from "../tools/presets.js";
+import { COORDINATOR_WAIT_MAX_MS, bindTaskCtlWaitCap } from "../tools/task-ctl.js";
 import { bindTaskAgents, bindTaskBackground } from "../tools/task.js";
 import { resolveTaskBackground } from "../agent/subagent-background.js";
 import { msg } from "../i18n/index.js";
@@ -62,6 +64,9 @@ export function subagentEnvironment(deps, catalog) {
     // [W7-B1] 缺省后台与自动转后台（配置键 W7-B2 登记于 config/types-w5.ts）
     const sub = config.subagents;
     env.background = resolveTaskBackground(sub?.background, deps.assembly.unattended === true);
+    // [#242] 协调者不阻塞：缺省后台，不受 subagents.background / -p 影响（调用参数与类型定义仍优先）
+    if (isCoordinatorPreset(config))
+        env.background = true;
     const after = sub?.autoBackgroundAfterMs;
     if (typeof after === "number" && after > 0)
         env.autoBackgroundAfterMs = after;
@@ -120,5 +125,8 @@ export function createSubagentsFactory(deps) {
     bindTaskAgents(task, catalog);
     const env = subagentEnvironment(deps, catalog);
     bindTaskBackground(task, env.background === true);
+    // [#242] 协调者预设：task_ctl wait 超时封顶（task 与 task_ctl 同进退）
+    if (isCoordinatorPreset(deps.assembly.config))
+        bindTaskCtlWaitCap(deps.assembly.tools.get("task_ctl"), COORDINATOR_WAIT_MAX_MS);
     return ({ core }) => (core.depth > 0 ? undefined : createSubagentExtension(core, env, wiring));
 }

package/dist/drivers/acp/client.d.ts

@@ -14,13 +14,29 @@
  * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
  *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
  *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `elicitation/complete`（Agent → 客户端通知，URL 型 elicitation 在带外完成）交给 `onElicitationComplete`；给了它
+ *   `initialize` 声明 `elicitation: { form: {}, url: {} }`（只给 `onElicitation` 时仍是 `{}`，与旧版相同）。同一
+ *   `elicitationId` 若还挂着（处理器没答），它的 `signal` 随之 abort、答 `{ action: "cancel" }`，宿主据此收掉卡片。
+ *   表单字段含字符串多选（`type: "array"`）与带标题的 `oneOf` / `anyOf`，答复 `content` 里多选是字符串数组；
+ *   {@link multiSelectOptions} / {@link singleSelectOptions} 把两种写法收成统一的 `{ const, title }` 列表。
+ * - 会话管理：`listSessions(cwd?, cursor?, signal?)` 发 `session/list`（要 Agent 声明 `sessionCapabilities.list`，见
+ *   `supportsList`），`listAllSessions` 跟 `nextCursor` 翻页取全；`closeSession(sessionId, signal?)` 发 `session/close`
+ *   （`supportsClose`），按规范等同先取消：该会话挂起的权限请求答 `cancelled`、elicitation 答 `cancel`，再发请求。
+ *   没声明能力的 Agent 会答 -32601，开会话遇 -32000 同样原样抛出（{@link isAuthRequiredError}）。
  * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
  *   原样交回。`initialize` 声明 `clientCapabilities.session.configOptions: {}`（只认 select，不声明 boolean）；
- *   不声明 `auth.terminal`（ama 作客户端没有可借给 Agent 的交互终端）。[ACP-D]
+ *   `auth.terminal` 缺省不声明（ama 作客户端没有可借给 Agent 的交互终端），见下 `authTerminal`。[ACP-D]
+ * - 认证：`authenticate(methodId)` 发 `authenticate`（agent 型方法）、`logout()` 发 `logout`（Agent 声明
+ *   `auth.logout` 才可用，见 `supportsLogout`）；terminal 型方法规范禁止经 `authenticate`，已知是 terminal 型时本地
+ *   拒绝（-32602），宿主自己在终端里跑 `args` / `env`。构造参数 `authTerminal: true` 才在 `initialize` 声明
+ *   `clientCapabilities.auth.terminal`（宿主有交互终端可借；Agent 据此才给 terminal 型方法），缺省线路与旧版相同。
+ *   开会话遇 -32000（auth_required）用 {@link isAuthRequiredError} 判断，`authMethods` 保留 id / name / description / type
+ *   / args / env 原样。
  * - 线路两侧开 `$/cancel_request`：本端请求的 `signal` abort 时通知 Agent；Agent 撤回挂起的
  *   `session/request_permission` / `elicitation/create` 时处理器的 `signal` abort，回 cancelled / cancel。[ACP-D]
  */
-import { type AcpAgentCapabilities, type AcpAuthMethod, type AcpContentBlock, type AcpElicitationParams, type AcpElicitationResult, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions, type AcpSetConfigOptionResult } from "./types.js";
+import { RpcError } from "../jsonrpc.js";
+import { type AcpAgentCapabilities, type AcpAuthMethod, type AcpAuthenticateResult, type AcpLogoutResult, type AcpCompleteElicitationParams, type AcpContentBlock, type AcpElicitationParams, type AcpElicitationResult, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpCloseSessionResult, type AcpSessionInfo, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions, type AcpSetConfigOptionResult } from "./types.js";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
@@ -30,6 +46,11 @@ export interface AcpClientHandlers {
      * `signal`：该会话被 cancel、连接关闭时 abort（此时回 `{ action: "cancel" }`，不必再答）。
      */
     onElicitation?(params: AcpElicitationParams, signal: AbortSignal): Promise<AcpElicitationResult>;
+    /**
+     * `elicitation/complete`：URL 型 elicitation 已在带外完成（`params.elicitationId` 对应此前
+     * `elicitation/create` 的同名字段），宿主据此收掉对应卡片。给了它，`initialize` 才声明 `elicitation.url`。
+     */
+    onElicitationComplete?(params: AcpCompleteElicitationParams): void;
     /**
      * `terminal/*`（create / output / wait_for_exit / kill / release）：宿主替 Agent 起终端。给了它才声明
      * `clientCapabilities.terminal: true` 并把这些请求交给它；`method` 是完整方法名，`params` 原样交回，返回值即
@@ -43,7 +64,14 @@ export interface AcpClientOptions extends AcpClientHandlers {
     input: NodeJS.ReadableStream;
     output: NodeJS.WritableStream;
     clientInfo?: AcpImplementationInfo;
+    /**
+     * 宿主能在交互终端里复现 Agent 的启动命令：声明 `clientCapabilities.auth.terminal`，Agent 才会在
+     * `authMethods` 里给 terminal 型方法。缺省不声明。
+     */
+    authTerminal?: boolean;
 }
+/** 错误是 ACP 的 auth_required（-32000）：开会话或发提示前需要先认证 / 登录。 */
+export declare function isAuthRequiredError(error: unknown): error is RpcError;
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export declare function unattendedOutcome(params: AcpRequestPermissionParams): AcpRequestPermissionResult;
 export declare class AcpClient {
@@ -53,19 +81,25 @@ export declare class AcpClient {
      * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
      * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
      * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`；
-     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`。
+     * - `terminal`：构造参数 `onTerminal` 接 `terminal/*`；
+     * - `auth`：`authenticate` / `logout`、构造参数 `authTerminal`、`isAuthRequiredError`；
+     * - `elicitationComplete`：构造参数 `onElicitationComplete` 接 `elicitation/complete`，表单字段含多选与 `oneOf`。
      */
     static readonly features: {
         readonly mcpServers: true;
         readonly elicitation: true;
         readonly configOptions: true;
         readonly terminal: true;
+        readonly auth: true;
+        readonly elicitationComplete: true;
     };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
     /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
     private readonly pendingElicitations;
+    /** elicitationId → 挂起 elicitation 的取消器（`elicitation/complete` 用）。 */
+    private readonly elicitationsById;
     private initResult;
     constructor(options: AcpClientOptions);
     get closed(): Promise<void>;
@@ -79,14 +113,27 @@ export declare class AcpClient {
     supportsLoad(): boolean;
     supportsList(): boolean;
     supportsClose(): boolean;
+    /** Agent 声明了 `auth.logout`（存在即支持）。 */
+    supportsLogout(): boolean;
     supportsImages(): boolean;
+    /**
+     * 用 agent 型认证方法登录（`methodId` 取自 `authMethods`）。terminal 型方法不经 `authenticate`：已知是
+     * terminal 型时抛 -32602，由宿主在终端里跑该方法的 `args` / `env`。失败的错误码原样抛出。
+     */
+    authenticate(methodId: string, signal?: AbortSignal): Promise<AcpAuthenticateResult>;
+    /** 登出当前账号；Agent 没声明 `auth.logout`（见 `supportsLogout`）时会答 method not found。 */
+    logout(signal?: AbortSignal): Promise<AcpLogoutResult>;
     newSession(cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpNewSessionResult>;
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
     resumeSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     /** 回放历史（以 session/update 通知）。 */
     loadSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
-    listSessions(cwd?: string, cursor?: string): Promise<AcpListSessionsResult>;
-    closeSession(sessionId: string): Promise<unknown>;
+    /** 一页会话；`cwd` 过滤（绝对路径），`cursor` 取自上一页的 `nextCursor`。 */
+    listSessions(cwd?: string, cursor?: string, signal?: AbortSignal): Promise<AcpListSessionsResult>;
+    /** 跟 `nextCursor` 翻页取全（`maxPages` 防对端游标不终止，缺省 100 页）。 */
+    listAllSessions(cwd?: string, signal?: AbortSignal, maxPages?: number): Promise<AcpSessionInfo[]>;
+    /** 关闭会话：规范要求 Agent 先取消进行中的工作，所以本端先把该会话挂起的请求收掉。 */
+    closeSession(sessionId: string, signal?: AbortSignal): Promise<AcpCloseSessionResult>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;
     setMode(sessionId: string, modeId: string): Promise<unknown>;
     /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
@@ -96,4 +143,6 @@ export declare class AcpClient {
     close(): void;
     private onRequest;
     private onElicitation;
+    /** 通知没有答复：参数不对就忽略；还挂着的同 id elicitation 先收掉，再交给宿主。 */
+    private onElicitationComplete;
 }