@armadra/agent 0.11.0 → 0.12.0

package/dist/drivers/acp/client.js

@@ -14,14 +14,33 @@
  * - `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 { JsonRpcPeer, RpcError } from "../jsonrpc.js";
-import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
+import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, isTerminalAuthMethod, } from "./types.js";
+/** 错误是 ACP 的 auth_required（-32000）：开会话或发提示前需要先认证 / 登录。 */
+export function isAuthRequiredError(error) {
+    return error instanceof RpcError && error.code === RPC_ERRORS.authRequired;
+}
 /** 开会话参数里的 `mcpServers`：拷一份，缺省空数组。 */
 function mcpServersOf(options) {
     return [...(options?.mcpServers ?? [])];
@@ -52,14 +71,25 @@ export 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 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 = new Map();
     /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
     pendingElicitations = new Map();
+    /** elicitationId → 挂起 elicitation 的取消器（`elicitation/complete` 用）。 */
+    elicitationsById = new Map();
     initResult;
     constructor(options) {
         this.options = options;
@@ -71,6 +101,8 @@ export class AcpClient {
             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())
@@ -109,7 +141,12 @@ export class AcpClient {
                 fs: { readTextFile: false, writeTextFile: false },
                 terminal: this.options.onTerminal !== undefined,
                 session: { configOptions: {} },
-                ...(this.options.onElicitation !== undefined ? { elicitation: {} } : {}),
+                ...(this.options.authTerminal === true ? { auth: { terminal: true } } : {}),
+                ...(this.options.onElicitation !== undefined || this.options.onElicitationComplete
+                    ? {
+                        elicitation: this.options.onElicitationComplete !== undefined ? { form: {}, url: {} } : {},
+                    }
+                    : {}),
             },
             ...(this.options.clientInfo !== undefined ? { clientInfo: this.options.clientInfo } : {}),
         }, signal);
@@ -130,9 +167,27 @@ export class AcpClient {
     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 !== undefined && 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, { cwd, mcpServers: mcpServersOf(options) }, signal);
     }
@@ -144,14 +199,33 @@ export class AcpClient {
     loadSession(sessionId, cwd, signal, options) {
         return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
-    listSessions(cwd, cursor) {
+    /** 一页会话；`cwd` 过滤（绝对路径），`cursor` 取自上一页的 `nextCursor`。 */
+    listSessions(cwd, cursor, signal) {
         return this.peer.request(ACP_METHODS.sessionList, {
             ...(cwd !== undefined ? { cwd } : {}),
             ...(cursor !== undefined ? { cursor } : {}),
-        });
+        }, signal);
+    }
+    /** 跟 `nextCursor` 翻页取全（`maxPages` 防对端游标不终止，缺省 100 页）。 */
+    async listAllSessions(cwd, signal, maxPages = 100) {
+        const sessions = [];
+        let cursor;
+        for (let page = 0; page < maxPages; page++) {
+            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;
     }
-    closeSession(sessionId) {
-        return this.peer.request(ACP_METHODS.sessionClose, { sessionId });
+    /** 关闭会话：规范要求 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);
@@ -225,6 +299,9 @@ export class AcpClient {
         const set = this.pendingElicitations.get(key) ?? new Set();
         set.add(controller);
         this.pendingElicitations.set(key, set);
+        const id = typeof request.elicitationId === "string" ? request.elicitationId : undefined;
+        if (id !== undefined)
+            this.elicitationsById.set(id, controller);
         const signal = AbortSignal.any([controller.signal, connection]);
         try {
             const answer = await Promise.race([
@@ -243,6 +320,16 @@ export class AcpClient {
         }
         finally {
             set.delete(controller);
+            if (id !== undefined && 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);
+    }
 }

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

@@ -14,8 +14,10 @@ export declare const ACP_PROTOCOL_VERSION: 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export declare const ACP_METHODS: {
     readonly initialize: "initialize";
-    /** ama 不实现（只给 terminal 型认证方法，规范要求这类方法不经 authenticate）。 */
+    /** 客户端 → Agent：agent 型认证方法经它完成；terminal 型不经它（规范）。 */
     readonly authenticate: "authenticate";
+    /** 客户端 → Agent：登出当前账号（Agent 声明 `agentCapabilities.auth.logout` 才可用）。 */
+    readonly logout: "logout";
     readonly sessionNew: "session/new";
     readonly sessionLoad: "session/load";
     readonly sessionResume: "session/resume";
@@ -28,6 +30,8 @@ export declare const ACP_METHODS: {
     readonly sessionUpdate: "session/update";
     readonly requestPermission: "session/request_permission";
     readonly elicitationCreate: "elicitation/create";
+    /** Agent → 客户端通知：URL 型 elicitation 已在带外完成。 */
+    readonly elicitationComplete: "elicitation/complete";
     /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
     readonly cancelRequest: "$/cancel_request";
 };
@@ -93,6 +97,7 @@ export interface AcpClientCapabilities {
         } | null;
     } | null;
     /** `terminal: true`：客户端能替 Agent 起终端跑 terminal 型认证方法。 */
+    /** 能在交互终端里复现 Agent 的启动命令；声明后 Agent 才会给 terminal 型认证方法。 */
     auth?: {
         terminal?: boolean;
     };
@@ -144,6 +149,19 @@ export type AcpAuthMethod = {
 export interface AcpAuthenticateParams {
     methodId: string;
 }
+/** `authenticate` / `logout` 的答复：规范里只有 `_meta`。 */
+export type AcpAuthenticateResult = {
+    _meta?: Record<string, unknown> | null;
+};
+export type AcpLogoutResult = {
+    _meta?: Record<string, unknown> | null;
+};
+/** terminal 型认证方法（客户端在终端里跑 `<agent 命令> <args…>`，带 `env`）。 */
+export type AcpTerminalAuthMethod = Extract<AcpAuthMethod, {
+    type: "terminal";
+}>;
+/** 是 terminal 型认证方法：这类方法不经 `authenticate`。 */
+export declare function isTerminalAuthMethod(method: AcpAuthMethod): method is AcpTerminalAuthMethod;
 export interface AcpInitializeResult {
     protocolVersion: number;
     agentCapabilities?: AcpAgentCapabilities;
@@ -234,14 +252,23 @@ export interface AcpSetConfigOptionParams {
 export interface AcpSetConfigOptionResult {
     configOptions?: AcpSessionConfigOption[] | null;
 }
-/** 表单里的一个字段：扁平的原始类型，规范只允许这几种。 */
+/** 带标题的枚举项（`oneOf` / `anyOf` 里的一项）：`const` 是提交的值，`title` 是显示名。 */
+export interface AcpEnumOption {
+    const: string;
+    title: string;
+}
+/** 表单里的一个字段：扁平的原始类型或字符串多选，规范只允许这几种；未知 `type` 保留原样、不当已知控件渲染。 */
 export type AcpElicitationField = {
     type: "string";
     title?: string;
     description?: string;
+    /** 单选：只有取值。 */
     enum?: string[];
     enumNames?: string[];
+    /** 单选：带标题的取值（`const` / `title`）。 */
+    oneOf?: AcpEnumOption[];
     format?: string;
+    pattern?: string;
     minLength?: number;
     maxLength?: number;
     default?: string;
@@ -257,7 +284,27 @@ export type AcpElicitationField = {
     title?: string;
     description?: string;
     default?: boolean;
+} | {
+    /** 字符串多选：提交值是 `string[]`。 */
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    /** `{ type: "string", enum }`（只有取值）或 `{ anyOf: [{ const, title }] }`（带标题）。 */
+    items: {
+        type?: "string";
+        enum?: string[];
+        anyOf?: AcpEnumOption[];
+    };
+    default?: string[];
 };
+/** 表单字段的提交值：多选是字符串数组。 */
+export type AcpElicitationValue = string | number | boolean | string[];
+/** 多选字段可选的项：带标题的 `anyOf` 或只有取值的 `enum`（标题取值本身）；不是多选字段返回 undefined。 */
+export declare function multiSelectOptions(field: AcpElicitationField): AcpEnumOption[] | undefined;
+/** 单选字符串字段可选的项：`oneOf`（带标题）优先，其次 `enum`（可配 `enumNames`）；没有枚举返回 undefined。 */
+export declare function singleSelectOptions(field: AcpElicitationField): AcpEnumOption[] | undefined;
 export interface AcpElicitationSchema {
     type: "object";
     properties: Record<string, AcpElicitationField>;
@@ -266,6 +313,12 @@ export interface AcpElicitationSchema {
 /** Agent 发来的 `elicitation/create` 参数；未知字段保留。 */
 export interface AcpElicitationParams {
     sessionId?: string;
+    /** 关联的工具调用（会话范围的 elicitation 可带）。 */
+    toolCallId?: string | null;
+    /** 不在会话里时关联的请求 id（请求范围）。 */
+    requestId?: string | number;
+    /** URL 型 elicitation 的 id；之后 Agent 以 `elicitation/complete` 通知它在带外完成。 */
+    elicitationId?: string;
     message: string;
     /** `form`（缺省）或 `url`。 */
     mode?: "form" | "url" | (string & {});
@@ -273,11 +326,16 @@ export interface AcpElicitationParams {
     url?: string;
     [key: string]: unknown;
 }
+/** `elicitation/complete` 通知的参数：URL 型 elicitation 已完成。 */
+export interface AcpCompleteElicitationParams {
+    elicitationId: string;
+    _meta?: Record<string, unknown> | null;
+}
 export type AcpElicitationAction = "accept" | "decline" | "cancel";
 export interface AcpElicitationResult {
     action: AcpElicitationAction;
     /** 只随 `accept`。 */
-    content?: Record<string, string | number | boolean>;
+    content?: Record<string, AcpElicitationValue>;
 }
 export type AcpResumeSessionParams = AcpLoadSessionParams;
 export type AcpResumeSessionResult = AcpLoadSessionResult;
@@ -288,8 +346,12 @@ export interface AcpListSessionsParams {
 export interface AcpSessionInfo {
     sessionId: string;
     cwd: string;
+    /** Agent 报告的额外工作区根（绝对路径）；缺省与空数组等价。 */
+    additionalDirectories?: string[];
     title?: string | null;
+    /** ISO 8601 的最近活动时间。 */
     updatedAt?: string | null;
+    _meta?: Record<string, unknown> | null;
 }
 export interface AcpListSessionsResult {
     sessions: AcpSessionInfo[];
@@ -298,6 +360,10 @@ export interface AcpListSessionsResult {
 export interface AcpCloseSessionParams {
     sessionId: string;
 }
+/** `session/close` 的答复：规范里只有 `_meta`。 */
+export type AcpCloseSessionResult = {
+    _meta?: Record<string, unknown> | null;
+};
 export interface AcpSetModeParams {
     sessionId: string;
     modeId: string;

package/dist/drivers/acp/types.js

@@ -13,8 +13,10 @@ export const ACP_PROTOCOL_VERSION = 1;
 /** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
 export const 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",
@@ -27,6 +29,8 @@ export const ACP_METHODS = {
     sessionUpdate: "session/update",
     requestPermission: "session/request_permission",
     elicitationCreate: "elicitation/create",
+    /** Agent → 客户端通知：URL 型 elicitation 已在带外完成。 */
+    elicitationComplete: "elicitation/complete",
     /** 协议级取消（双向通知，`requestId` 指对端发来的、尚未答复的请求）。 */
     cancelRequest: "$/cancel_request",
 };
@@ -42,5 +46,30 @@ export const RPC_ERRORS = {
     /** 请求被 `$/cancel_request` 撤回。 */
     requestCancelled: -32800,
 };
+/** 是 terminal 型认证方法：这类方法不经 `authenticate`。 */
+export function isTerminalAuthMethod(method) {
+    return method.type === "terminal";
+}
+/** 多选字段可选的项：带标题的 `anyOf` 或只有取值的 `enum`（标题取值本身）；不是多选字段返回 undefined。 */
+export function multiSelectOptions(field) {
+    if (field.type !== "array")
+        return undefined;
+    const items = field.items;
+    if (Array.isArray(items?.anyOf))
+        return items.anyOf.map((o) => ({ const: o.const, title: o.title }));
+    if (Array.isArray(items?.enum))
+        return items.enum.map((value) => ({ const: value, title: value }));
+    return undefined;
+}
+/** 单选字符串字段可选的项：`oneOf`（带标题）优先，其次 `enum`（可配 `enumNames`）；没有枚举返回 undefined。 */
+export function singleSelectOptions(field) {
+    if (field.type !== "string")
+        return undefined;
+    if (Array.isArray(field.oneOf))
+        return field.oneOf.map((o) => ({ const: o.const, title: o.title }));
+    if (Array.isArray(field.enum))
+        return field.enum.map((value, i) => ({ const: value, title: field.enumNames?.[i] ?? value }));
+    return undefined;
+}
 /** ama 自己的 `_meta` 命名空间（客户端不得假设其含义）。 */
 export const ACP_META_KEY = "ama";

package/dist/modes/interactive/interactive-mode.d.ts

@@ -32,6 +32,11 @@ import { StatusArea } from "./status-area.js";
 import type { StatusBar } from "./status-bar.js";
 import { type ProgramStatusOptions } from "./program-status-ui.js";
 import { ToolTracker } from "./tool-view.js";
+/** 底部提示行的清除计时器（测试注入手动时钟，帧黄金不再依赖墙钟）。 */
+export interface HintTimers {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
 export interface InteractiveModeOptions {
     /** 缺省 `ProcessTerminal`（测试注入 MemoryTerminal）。 */
     terminal?: Terminal;
@@ -49,6 +54,8 @@ export interface InteractiveModeOptions {
     onReady?(handle: InteractiveHandle): void;
     /** 剪贴板读取的注入（测试；缺省调系统命令）。 */
     clipboard?: ClipboardDeps;
+    /** 提示行清除计时器的注入（测试；缺省真实 `setTimeout`）。 */
+    hintTimers?: HintTimers;
     /** 终端程序状态 OSC 7501（缺省只在真实终端启用；测试注入终端时给了才启用）。 */
     programStatus?: ProgramStatusOptions;
 }

package/dist/modes/interactive/interactive-mode.js

@@ -56,6 +56,14 @@ import { loadKeys, processTerminal } from "./terminal-setup.js";
 import { ToolTracker } from "./tool-view.js";
 import { backgroundTasks, blockingTasks, keyLabel, runningBackground } from "./task-background.js";
 const HINT_MS = 2500;
+const realHintTimers = {
+    set: (fn, ms) => {
+        const handle = setTimeout(fn, ms);
+        handle.unref?.();
+        return handle;
+    },
+    clear: (handle) => clearTimeout(handle),
+};
 export function runInteractiveMode(runtime, context, options = {}) {
     const terminal = options.terminal ?? processTerminal();
     const ui = runtime.config.ui ?? {};
@@ -142,6 +150,7 @@ export function runInteractiveMode(runtime, context, options = {}) {
     tui.addChild(area.quota);
     // ---- 小工具 ---------------------------------------------------------------
     let finished = false;
+    const hintTimers = options.hintTimers ?? realHintTimers;
     let hintTimer;
     let resolveExit = () => undefined;
     const render = () => tui.requestRender();
@@ -152,14 +161,13 @@ export function runInteractiveMode(runtime, context, options = {}) {
     const showHint = (text, ms = HINT_MS) => {
         hint.setText(text === "" ? "" : theme.fg("dim", text));
         if (hintTimer !== undefined)
-            clearTimeout(hintTimer);
+            hintTimers.clear(hintTimer);
         hintTimer = undefined;
         if (text !== "") {
-            hintTimer = setTimeout(() => {
+            hintTimer = hintTimers.set(() => {
                 hint.setText("");
                 render();
             }, ms);
-            hintTimer.unref?.();
         }
         render();
     };
@@ -423,7 +431,7 @@ export function runInteractiveMode(runtime, context, options = {}) {
         finished = true;
         logoAnimation?.finish();
         if (hintTimer !== undefined)
-            clearTimeout(hintTimer);
+            hintTimers.clear(hintTimer);
         loader.stop();
         area.dispose();
         osc7501.exit();

package/dist/permissions/auto-safe.d.ts

@@ -8,6 +8,9 @@
  * - 写入目标：重定向（`>`、`>>`、`&>`）、tee、cp / mv / mkdir / touch / ln / chmod 等的目标在项目外或受保护；
  * - 参数里出现机密路径（`cat .env`、`< ~/.ssh/id_rsa`、`--env-file=.env`）。
  *
+ * `env` / `printenv` 不在安全名单里：子进程继承整个进程环境（供应商 API key 等），打印出来就会进
+ * tool_result 与会话文件。段里只剩环境赋值或包装命令（`env`、`env FOO=1`）同样不放行。
+ *
  * 静态判定（全部满足即放行）：每一段都命中安全名单（{@link AUTO_SAFE_COMMANDS} + 用户追加），整条命令
  * 没有命令替换、参数没有变量展开 `$X`、没有可能匹配点文件的通配、没有超深嵌套。
  *

package/dist/permissions/auto-safe.js

@@ -8,6 +8,9 @@
  * - 写入目标：重定向（`>`、`>>`、`&>`）、tee、cp / mv / mkdir / touch / ln / chmod 等的目标在项目外或受保护；
  * - 参数里出现机密路径（`cat .env`、`< ~/.ssh/id_rsa`、`--env-file=.env`）。
  *
+ * `env` / `printenv` 不在安全名单里：子进程继承整个进程环境（供应商 API key 等），打印出来就会进
+ * tool_result 与会话文件。段里只剩环境赋值或包装命令（`env`、`env FOO=1`）同样不放行。
+ *
  * 静态判定（全部满足即放行）：每一段都命中安全名单（{@link AUTO_SAFE_COMMANDS} + 用户追加），整条命令
  * 没有命令替换、参数没有变量展开 `$X`、没有可能匹配点文件的通配、没有超深嵌套。
  *
@@ -38,7 +41,6 @@ export const AUTO_SAFE_COMMANDS = [
         "echo",
         "printf",
         "which",
-        "printenv",
         "true",
         "false",
         "cut",
@@ -451,6 +453,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,
@@ -478,8 +481,12 @@ function ruleAsk(info, options) {
 }
 function safeSegment(info, extra) {
     const argv = info.withSudo;
-    if (argv.length === 0)
-        return undefined;
+    // 只剩环境赋值或包装命令：`env` / `env FOO=1` 会打印整个环境（含密钥），不放行。
+    if (argv.length === 0) {
+        return info.first === undefined
+            ? "empty command"
+            : `${base(info.first)} is not in the auto safe list`;
+    }
     for (const word of argv) {
         if (word.includes("$"))
             return `variable expansion in ${word}`;

package/dist/permissions/readonly-bash.d.ts

@@ -3,8 +3,8 @@
  *
  * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
  * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：
- * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器、`printenv`
- *   这类会把环境变量里的密钥打进上下文的命令）；
+ * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器；`env` /
+ *   `printenv` 这类会把环境变量里的密钥打进上下文的命令两边都没有）；
  * - 没有输出重定向（`/dev/null` 等设备除外）；
  * - 没有嵌套 shell（`sh -c`、`eval`、`xargs`、`find -exec`）与进程替换；
  * - 段首没有环境赋值或包装命令（`GIT_EXTERNAL_DIFF=… git diff`、`env …`、`nohup …`）。

package/dist/permissions/readonly-bash.js

@@ -3,8 +3,8 @@
  *
  * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
  * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：
- * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器、`printenv`
- *   这类会把环境变量里的密钥打进上下文的命令）；
+ * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器；`env` /
+ *   `printenv` 这类会把环境变量里的密钥打进上下文的命令两边都没有）；
  * - 没有输出重定向（`/dev/null` 等设备除外）；
  * - 没有嵌套 shell（`sh -c`、`eval`、`xargs`、`find -exec`）与进程替换；
  * - 段首没有环境赋值或包装命令（`GIT_EXTERNAL_DIFF=… git diff`、`env …`、`nohup …`）。

package/dist/tools/presets.d.ts

@@ -23,6 +23,8 @@
  *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
  * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
  *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - （#242）`coordinator` 预设不阻塞：`task` 缺省后台（无视 `subagents.background`，调用参数 `background`
+ *   与类型定义的 `background:` 仍优先）、`task_ctl wait` 的超时封顶 5 秒；其它预设不变。
  * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
  *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
  *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
@@ -56,6 +58,11 @@ export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" |
  * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
  */
 export declare function codemodeCallableFilter(config: Pick<AmaConfig, "tools">): "active" | undefined;
+/**
+ * [#242] 是否 `coordinator` 预设：协调者只分派、不阻塞——`task` 缺省后台、`task_ctl wait` 超时封顶
+ * （组装根据此绑定，见 cli/compose-agents.ts）。其它预设不受影响。
+ */
+export declare function isCoordinatorPreset(config: Pick<AmaConfig, "tools">): boolean;
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
  * 返回去重后的名字（保持首次出现顺序）。

package/dist/tools/presets.js

@@ -23,6 +23,8 @@
  *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
  * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
  *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - （#242）`coordinator` 预设不阻塞：`task` 缺省后台（无视 `subagents.background`，调用参数 `background`
+ *   与类型定义的 `background:` 仍优先）、`task_ctl wait` 的超时封顶 5 秒；其它预设不变。
  * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
  *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
  *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
@@ -72,7 +74,14 @@ export function effectiveCodemodeMode(config, strict) {
  * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
  */
 export function codemodeCallableFilter(config) {
-    return canonicalPreset(config.tools?.preset) === "coordinator" ? "active" : undefined;
+    return isCoordinatorPreset(config) ? "active" : undefined;
+}
+/**
+ * [#242] 是否 `coordinator` 预设：协调者只分派、不阻塞——`task` 缺省后台、`task_ctl wait` 超时封顶
+ * （组装根据此绑定，见 cli/compose-agents.ts）。其它预设不受影响。
+ */
+export function isCoordinatorPreset(config) {
+    return canonicalPreset(config.tools?.preset) === "coordinator";
 }
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。

package/dist/tools/task-ctl.d.ts

@@ -7,6 +7,8 @@
  *   与父一致，运行时拒绝；
  * - `wait` / `output` 是轮询类调用（`annotations.pollable`，重复调用检测豁免）；
  * - `send` = 续聊放后台：等价于 `task{taskId, prompt, background:true}`，完成后同样收到通知。
+ * - [#242] `coordinator` 预设下 `wait` 的超时封顶 `COORDINATOR_WAIT_MAX_MS`（协调者不阻塞，见
+ *   `bindTaskCtlWaitCap`）；其它预设不变。
  * - [W7-B1] `wait` 被转后台（`background()`，TUI `Ctrl+B` / RPC `background_task`）打断时立即返回固定
  *   文案，要求模型不要再等。
  */
@@ -14,6 +16,13 @@ import type { ToolDefinition } from "./types.js";
 export declare const TASK_CTL_TOOL = "task_ctl";
 export declare const DEFAULT_WAIT_MS = 30000;
 export declare const MAX_WAIT_MS = 600000;
+/** [#242] `coordinator` 预设下 `wait` 的超时上限（毫秒）。 */
+export declare const COORDINATOR_WAIT_MAX_MS = 5000;
+/**
+ * [#242] 组装根把 `wait` 的超时上限绑到 `task_ctl` 工具（`coordinator` 预设）；没绑定按 `MAX_WAIT_MS`。
+ * 工具描述与参数 schema 不变（其它预设逐字节不变）；被封顶时在超时回复里说明。
+ */
+export declare function bindTaskCtlWaitCap(tool: ToolDefinition | undefined, capMs: number): void;
 export interface TaskCtlInput {
     action: "list" | "wait" | "stop" | "output" | "send";
     taskId?: string;