@armadra/agent 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.6.8 (2026-10-04)
+
+- **ACP client: elicitation and session config options**: `AcpClient` takes an optional `onElicitation(params, signal)`;
+  when given, `initialize` declares `clientCapabilities.elicitation` and `elicitation/create` goes to it (answers normalized
+  to `accept` / `decline` / `cancel`; pending ones resolve `cancel` on `cancel(sessionId)` or connection close). New
+  `setConfigOption(sessionId, configId, value)` and `configOptions` on session-open results. `AcpClient.features` gains
+  `elicitation` and `configOptions`. Without a handler the wire is unchanged. The fake ACP agent adds `[elicit]`, `[model]`
+  and `[env NAME]` markers and `--config-options`. Docs: docs/acp.md.
+
+## 0.6.7 (2026-10-03)
+
+- **A host runner with id `ama` is used**: when the host registers a runner for `ama` via `HostApi.runners.provide`
+  (for example another ama node on an Armadra canvas), `task(agent="ama")` now goes to it instead of being unknown; without
+  one nothing changes, and the built-in types (`general` / `explore` / `plan`) are always ama sub-sessions. Docs:
+  docs/agents.md.
+
 ## 0.6.6 (2026-10-03)
 
 - **Local search hints**: when both `grep` and `glob` are directly available, the system prompt's rules gain one line

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,20 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.8（2026-10-04）
+
+- **ACP 客户端：elicitation 与会话配置项**：`AcpClient` 可选构造参数 `onElicitation(params, signal)`，给了才在 `initialize`
+  声明 `clientCapabilities.elicitation` 并把 `elicitation/create` 交给它（答复收成 `accept` / `decline` / `cancel`；
+  `cancel(sessionId)` 或连接关闭时挂起的回 `cancel`）。新增 `setConfigOption(sessionId, configId, value)`，开会话答复带
+  `configOptions`。`AcpClient.features` 多 `elicitation` 与 `configOptions`。不给处理器时线路不变。假 ACP Agent 加
+  `[elicit]`、`[model]`、`[env NAME]` 标记与 `--config-options`。文档：docs/acp.md。
+
+## 0.6.7（2026-10-03）
+
+- **宿主注入的 `ama` runner 生效**：宿主经 `HostApi.runners.provide` 注入 id 为 `ama` 的 runner（如 Armadra 画布上另一个
+  ama 节点）时，`task(agent="ama")` 交给它；没注入时行为不变，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
+  文档：docs/agents.md。
+
 ## 0.6.6（2026-10-03）
 
 - **本地检索提示**：`grep` 与 `glob` 都直接可用时，系统提示的规则节多一句「先 grep / glob 定位再 read，不要猜路径」；`grep` /

package/dist/agents/external.d.ts

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -34,6 +35,11 @@ export declare const externalTesting: {
 export declare function isExternalSpec(name: string): boolean;
 /** 外部 CLI 的类型（`task(agent="claude")`）。 */
 export declare function externalDefinition(spec: string): AgentDefinition;
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export declare const HOST_AMA_RUNNER = "host:ama";
 export declare function hostDefinition(runner: HostRunner): AgentDefinition;
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export declare function externalOnPath(spec: string, env: NodeJS.ProcessEnv): boolean;

package/dist/agents/external.js

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -58,8 +59,17 @@ function definition(name, runner, description, source) {
 export function externalDefinition(spec) {
     return definition(spec, spec, `External ${labelOf(spec)} CLI (its own login, model and permission policy; full instructions in prompt).`, "builtin");
 }
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export const HOST_AMA_RUNNER = "host:ama";
+/** 宿主 runner id → 类型里的 runner 名。 */
+function hostRunnerName(id) {
+    return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 export function hostDefinition(runner) {
-    return definition(runner.id, runner.id, runner.description, "host");
+    return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export function externalOnPath(spec, env) {
@@ -207,8 +217,16 @@ export class SessionExternalAgents {
     runner(agent) {
         if (agent.runner === "ama")
             return undefined;
-        const spec = agent.runner;
+        // 宿主注入的 `ama` 走宿主；宿主已注销时报不可用，不退回自起（驱动表里也有一个 ama）。
+        // 宿主 id 不在 AgentRunnerSpec 的字面量里（见 definition），按字符串比
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec);
+        if (hostAma && host === undefined) {
+            const error = new AmaError("agent_host_only", `"ama" was provided by the host and is no longer available`);
+            return { id: spec, start: () => Promise.reject(error) };
+        }
         let inner;
         try {
             inner = this.agents.resolve(spec);

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.6.6" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.8" : readPackageVersion();
   }
 });
 
@@ -30592,8 +30592,10 @@ var init_types9 = __esm({
       sessionPrompt: "session/prompt",
       sessionCancel: "session/cancel",
       sessionSetMode: "session/set_mode",
+      sessionSetConfigOption: "session/set_config_option",
       sessionUpdate: "session/update",
-      requestPermission: "session/request_permission"
+      requestPermission: "session/request_permission",
+      elicitationCreate: "elicitation/create"
     };
     RPC_ERRORS = {
       parseError: -32700,
@@ -30790,18 +30792,25 @@ var init_jsonrpc = __esm({
 function mcpServersOf(options) {
   return [...options?.mcpServers ?? []];
 }
+function elicitationAnswer(answer) {
+  const action = answer?.action;
+  if (action === void 0 || !ELICITATION_ACTIONS.has(action)) return { action: "cancel" };
+  if (action !== "accept" || answer?.content === void 0) return { action };
+  return { action, content: answer.content };
+}
 function unattendedOutcome(params) {
   const reject2 = params.options.find((o) => o.kind === "reject_once");
   return {
     outcome: reject2 !== void 0 ? { outcome: "selected", optionId: reject2.optionId } : { outcome: "cancelled" }
   };
 }
-var AcpClient;
+var ELICITATION_ACTIONS, AcpClient;
 var init_client = __esm({
   "src/drivers/acp/client.ts"() {
     "use strict";
     init_jsonrpc();
     init_types9();
+    ELICITATION_ACTIONS = /* @__PURE__ */ new Set(["accept", "decline", "cancel"]);
     AcpClient = class {
       constructor(options) {
         this.options = options;
@@ -30815,6 +30824,7 @@ var init_client = __esm({
           },
           onClose: () => {
             for (const set of this.pendingPermissions.values()) for (const c of set) c.abort();
+            for (const set of this.pendingElicitations.values()) for (const c of set) c.abort();
             options.onClose?.();
           },
           ...options.onProtocolError !== void 0 ? { onProtocolError: options.onProtocolError } : {}
@@ -30822,13 +30832,17 @@ var init_client = __esm({
       }
       options;
       /**
-       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+       * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+       * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
        */
-      static features = { mcpServers: true };
+      static features = { mcpServers: true, elicitation: true, configOptions: true };
       peer;
       /** sessionId → 挂起权限请求的取消器。 */
       pendingPermissions = /* @__PURE__ */ new Map();
+      /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+      pendingElicitations = /* @__PURE__ */ new Map();
       initResult;
       get closed() {
         return this.peer.closed;
@@ -30847,7 +30861,11 @@ var init_client = __esm({
           ACP_METHODS.initialize,
           {
             protocolVersion: ACP_PROTOCOL_VERSION,
-            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            clientCapabilities: {
+              fs: { readTextFile: false, writeTextFile: false },
+              terminal: false,
+              ...this.options.onElicitation !== void 0 ? { elicitation: {} } : {}
+            },
             ...this.options.clientInfo !== void 0 ? { clientInfo: this.options.clientInfo } : {}
           },
           signal
@@ -30913,15 +30931,22 @@ var init_client = __esm({
       setMode(sessionId, modeId) {
         return this.peer.request(ACP_METHODS.sessionSetMode, { sessionId, modeId });
       }
-      /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+      /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+      setConfigOption(sessionId, configId, value) {
+        return this.peer.request(ACP_METHODS.sessionSetConfigOption, { sessionId, configId, value });
+      }
+      /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
       async cancel(sessionId) {
         for (const controller of this.pendingPermissions.get(sessionId) ?? []) controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? []) controller.abort();
         await this.peer.notify(ACP_METHODS.sessionCancel, { sessionId });
       }
       close() {
         this.peer.close();
       }
       async onRequest(method, params, connection) {
+        if (method === ACP_METHODS.elicitationCreate && this.options.onElicitation !== void 0)
+          return this.onElicitation(params, connection);
         if (method !== ACP_METHODS.requestPermission)
           throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
         const request = params;
@@ -30953,6 +30978,32 @@ var init_client = __esm({
           set.delete(controller);
         }
       }
+      async onElicitation(params, connection) {
+        const request = params;
+        if (request === null || typeof request !== "object" || typeof request.message !== "string")
+          throw new RpcError(RPC_ERRORS.invalidParams, "invalid elicitation/create params");
+        const handler = this.options.onElicitation;
+        const key = typeof request.sessionId === "string" ? request.sessionId : "";
+        const controller = new AbortController();
+        const set = this.pendingElicitations.get(key) ?? /* @__PURE__ */ new Set();
+        set.add(controller);
+        this.pendingElicitations.set(key, set);
+        const signal = AbortSignal.any([controller.signal, connection]);
+        try {
+          const answer = await Promise.race([
+            handler(request, signal),
+            new Promise((resolve39) => {
+              const cancelled = () => resolve39({ action: "cancel" });
+              if (signal.aborted) cancelled();
+              else signal.addEventListener("abort", cancelled, { once: true });
+            })
+          ]);
+          if (signal.aborted) return { action: "cancel" };
+          return elicitationAnswer(answer);
+        } finally {
+          set.delete(controller);
+        }
+      }
     };
   }
 });
@@ -33541,8 +33592,11 @@ function externalDefinition(spec2) {
     "builtin"
   );
 }
+function hostRunnerName(id) {
+  return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 function hostDefinition(runner) {
-  return definition(runner.id, runner.id, runner.description, "host");
+  return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 function externalOnPath(spec2, env) {
   const found = candidatesFor(spec2);
@@ -33594,7 +33648,7 @@ function mergeAgentInfos(base4, external) {
   }
   return out;
 }
-var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, ExternalTaskHandle, infoCache, SessionExternalAgents;
+var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, HOST_AMA_RUNNER, ExternalTaskHandle, infoCache, SessionExternalAgents;
 var init_external = __esm({
   "src/agents/external.ts"() {
     "use strict";
@@ -33611,6 +33665,7 @@ var init_external = __esm({
     LISTED_EXTERNAL_AGENTS = ["claude", "codex"];
     NO_AGENT_PROBE_ENV = "AMA_NO_AGENT_PROBE";
     externalTesting = {};
+    HOST_AMA_RUNNER = "host:ama";
     ExternalTaskHandle = class {
       constructor(inner, reopen) {
         this.inner = inner;
@@ -33689,8 +33744,17 @@ var init_external = __esm({
       /** 注册表的 `runners(agent)`：ama 子会话类型返回 undefined。 */
       runner(agent) {
         if (agent.runner === "ama") return void 0;
-        const spec2 = agent.runner;
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec2 = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec2);
+        if (hostAma && host === void 0) {
+          const error2 = new AmaError(
+            "agent_host_only",
+            `"ama" was provided by the host and is no longer available`
+          );
+          return { id: spec2, start: () => Promise.reject(error2) };
+        }
         let inner;
         try {
           inner = this.agents.resolve(spec2);

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

@@ -10,12 +10,22 @@
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
  * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
  *   传入，原样转发。
+ * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
+ *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
+ *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
+ *   原样交回。
  */
-import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions } from "./types.js";
+import { type AcpAgentCapabilities, 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";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
     onPermission?(params: AcpRequestPermissionParams, signal: AbortSignal): Promise<AcpRequestPermissionResult>;
+    /**
+     * `elicitation/create`：Agent 向人要结构化输入。给了它才声明 `clientCapabilities.elicitation`。
+     * `signal`：该会话被 cancel、连接关闭时 abort（此时回 `{ action: "cancel" }`，不必再答）。
+     */
+    onElicitation?(params: AcpElicitationParams, signal: AbortSignal): Promise<AcpElicitationResult>;
     onProtocolError?(line: string, reason: string): void;
     onClose?(): void;
 }
@@ -29,15 +39,21 @@ export declare function unattendedOutcome(params: AcpRequestPermissionParams): A
 export declare class AcpClient {
     private readonly options;
     /**
-     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+     * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
      */
     static readonly features: {
         readonly mcpServers: true;
+        readonly elicitation: true;
+        readonly configOptions: true;
     };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
+    /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+    private readonly pendingElicitations;
     private initResult;
     constructor(options: AcpClientOptions);
     get closed(): Promise<void>;
@@ -59,8 +75,11 @@ export declare class AcpClient {
     closeSession(sessionId: string): Promise<unknown>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;
     setMode(sessionId: string, modeId: string): Promise<unknown>;
-    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+    setConfigOption(sessionId: string, configId: string, value: string): Promise<AcpSetConfigOptionResult>;
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
     cancel(sessionId: string): Promise<void>;
     close(): void;
     private onRequest;
+    private onElicitation;
 }

package/dist/drivers/acp/client.js

@@ -10,6 +10,11 @@
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
  * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
  *   传入，原样转发。
+ * - `elicitation/create` 交给 `onElicitation`；给了它 `initialize` 才声明 `clientCapabilities.elicitation`，
+ *   没给时线路与旧版相同（不声明，Agent 发来的请求回 method not found）。`cancel(sessionId)`、连接关闭时
+ *   挂起的 elicitation 一律回 `{ action: "cancel" }`；ama 从不替人填表。
+ * - `setConfigOption(sessionId, configId, value)` 发 `session/set_config_option`；开会话答的 `configOptions`
+ *   原样交回。
  */
 import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
@@ -17,6 +22,16 @@ import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
 function mcpServersOf(options) {
     return [...(options?.mcpServers ?? [])];
 }
+const ELICITATION_ACTIONS = new Set(["accept", "decline", "cancel"]);
+/** 处理器的答复收成规范形状：动作不认识当 cancel，`content` 只随 accept。 */
+function elicitationAnswer(answer) {
+    const action = answer?.action;
+    if (action === undefined || !ELICITATION_ACTIONS.has(action))
+        return { action: "cancel" };
+    if (action !== "accept" || answer?.content === undefined)
+        return { action };
+    return { action, content: answer.content };
+}
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export function unattendedOutcome(params) {
     const reject = params.options.find((o) => o.kind === "reject_once");
@@ -29,13 +44,17 @@ export function unattendedOutcome(params) {
 export class AcpClient {
     options;
     /**
-     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
-     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段，旧一点的只有 `mcpServers`）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器；
+     * - `elicitation`：构造参数 `onElicitation` 接 `elicitation/create`；
+     * - `configOptions`：`setConfigOption` 与开会话答的 `configOptions`。
      */
-    static features = { mcpServers: true };
+    static features = { mcpServers: true, elicitation: true, configOptions: true };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
+    /** sessionId（没给就是空串）→ 挂起 elicitation 的取消器。 */
+    pendingElicitations = new Map();
     initResult;
     constructor(options) {
         this.options = options;
@@ -51,6 +70,9 @@ export class AcpClient {
                 for (const set of this.pendingPermissions.values())
                     for (const c of set)
                         c.abort();
+                for (const set of this.pendingElicitations.values())
+                    for (const c of set)
+                        c.abort();
                 options.onClose?.();
             },
             ...(options.onProtocolError !== undefined
@@ -73,7 +95,11 @@ export class AcpClient {
     async initialize(signal) {
         const result = await this.peer.request(ACP_METHODS.initialize, {
             protocolVersion: ACP_PROTOCOL_VERSION,
-            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            clientCapabilities: {
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false,
+                ...(this.options.onElicitation !== undefined ? { elicitation: {} } : {}),
+            },
             ...(this.options.clientInfo !== undefined ? { clientInfo: this.options.clientInfo } : {}),
         }, signal);
         if (result.protocolVersion !== ACP_PROTOCOL_VERSION)
@@ -122,16 +148,24 @@ export class AcpClient {
     setMode(sessionId, modeId) {
         return this.peer.request(ACP_METHODS.sessionSetMode, { sessionId, modeId });
     }
-    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    /** 改一个会话配置项（如模型）；答复是全部配置项的新状态。 */
+    setConfigOption(sessionId, configId, value) {
+        return this.peer.request(ACP_METHODS.sessionSetConfigOption, { sessionId, configId, value });
+    }
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled、挂起的 elicitation 回 cancel。 */
     async cancel(sessionId) {
         for (const controller of this.pendingPermissions.get(sessionId) ?? [])
             controller.abort();
+        for (const controller of this.pendingElicitations.get(sessionId) ?? [])
+            controller.abort();
         await this.peer.notify(ACP_METHODS.sessionCancel, { sessionId });
     }
     close() {
         this.peer.close();
     }
     async onRequest(method, params, connection) {
+        if (method === ACP_METHODS.elicitationCreate && this.options.onElicitation !== undefined)
+            return this.onElicitation(params, connection);
         if (method !== ACP_METHODS.requestPermission)
             throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
         const request = params;
@@ -168,4 +202,34 @@ export class AcpClient {
             set.delete(controller);
         }
     }
+    async onElicitation(params, connection) {
+        const request = params;
+        if (request === null || typeof request !== "object" || typeof request.message !== "string")
+            throw new RpcError(RPC_ERRORS.invalidParams, "invalid elicitation/create params");
+        const handler = this.options.onElicitation;
+        const key = typeof request.sessionId === "string" ? request.sessionId : "";
+        const controller = new AbortController();
+        const set = this.pendingElicitations.get(key) ?? new Set();
+        set.add(controller);
+        this.pendingElicitations.set(key, set);
+        const signal = AbortSignal.any([controller.signal, connection]);
+        try {
+            const answer = await Promise.race([
+                handler(request, signal),
+                new Promise((resolve) => {
+                    const cancelled = () => resolve({ action: "cancel" });
+                    if (signal.aborted)
+                        cancelled();
+                    else
+                        signal.addEventListener("abort", cancelled, { once: true });
+                }),
+            ]);
+            if (signal.aborted)
+                return { action: "cancel" };
+            return elicitationAnswer(answer);
+        }
+        finally {
+            set.delete(controller);
+        }
+    }
 }

package/dist/drivers/acp/testing/fake-agent-main.d.ts

@@ -1,5 +1,5 @@
 /**
- * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal] [--config-options]`。[W5-E]
  * 行为见 fake-agent.ts；stdin 结束即退出。
  */
 export {};

package/dist/drivers/acp/testing/fake-agent-main.js

@@ -1,7 +1,8 @@
 /**
- * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal] [--config-options]`。[W5-E]
  * 行为见 fake-agent.ts；stdin 结束即退出。
  */
 import { runFakeAcpAgent } from "./fake-agent.js";
 const minimal = process.argv.includes("--minimal");
-void runFakeAcpAgent(process.stdin, process.stdout, { minimal }).then(() => process.exit(0));
+const configOptions = process.argv.includes("--config-options");
+void runFakeAcpAgent(process.stdin, process.stdout, { minimal, configOptions }).then(() => process.exit(0));

package/dist/drivers/acp/testing/fake-agent.d.ts

@@ -13,6 +13,13 @@
  * | `[plan]`         | 先发 `plan`（两条）再回文本                                                      |
  * | `[think]`        | 先发 `agent_thought_chunk`                                                        |
  * | `[refuse]`       | `refusal`                                                                         |
+ * | `[elicit]`       | `elicitation/create`（选颜色的表单）→ 回 `elicit: <action> <content JSON>`；客户端    |
+ * |                  | 没声明 `elicitation` 能力时回 `elicit: unsupported`；`cancel` 时本回合 `cancelled` |
+ * | `[model]`        | 回 `model <当前模型>`（`configOptions` 关着时是 `model none`）                     |
+ * | `[env NAME]`     | 回 `env NAME <值的 sha256 | absent>`（测环境变量到没到，不回显值）                  |
+ *
+ * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（`small`，分组
+ * `big` 里有 `large`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
  *
  * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
  * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
@@ -22,6 +29,8 @@ export interface FakeAcpAgentOptions {
     name?: string;
     /** 不声明 resume / list / close / loadSession（测降级路径）。 */
     minimal?: boolean;
+    /** 开会话答 `configOptions`（一个 `model` 选择项）并接 `session/set_config_option`。 */
+    configOptions?: boolean;
 }
 /** 在给定流上跑假 Agent；输入流结束时 resolve。 */
 export declare function runFakeAcpAgent(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, options?: FakeAcpAgentOptions): Promise<void>;

package/dist/drivers/acp/testing/fake-agent.js

@@ -13,16 +13,38 @@
  * | `[plan]`         | 先发 `plan`（两条）再回文本                                                      |
  * | `[think]`        | 先发 `agent_thought_chunk`                                                        |
  * | `[refuse]`       | `refusal`                                                                         |
+ * | `[elicit]`       | `elicitation/create`（选颜色的表单）→ 回 `elicit: <action> <content JSON>`；客户端    |
+ * |                  | 没声明 `elicitation` 能力时回 `elicit: unsupported`；`cancel` 时本回合 `cancelled` |
+ * | `[model]`        | 回 `model <当前模型>`（`configOptions` 关着时是 `model none`）                     |
+ * | `[env NAME]`     | 回 `env NAME <值的 sha256 | absent>`（测环境变量到没到，不回显值）                  |
+ *
+ * `configOptions: true`（可执行入口 `--config-options`）：开会话答一个 `model` 配置项（`small`，分组
+ * `big` 里有 `large`），`session/set_config_option` 可改；缺省不答，线路与之前相同。
  *
  * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
  * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
  */
+import { createHash } from "node:crypto";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS } from "../types.js";
 import { JsonRpcPeer, RpcError } from "../../jsonrpc.js";
 const MODES = [
     { id: "default", name: "Default" },
     { id: "plan", name: "Plan" },
 ];
+const MODELS = [
+    { value: "small", name: "Small" },
+    { group: "big", name: "Big", options: [{ value: "large", name: "Large", description: "slow" }] },
+];
+const MODEL_VALUES = ["small", "large"];
+/** 一个表单：必填的颜色（枚举）与可选的数量。 */
+const ELICIT_SCHEMA = {
+    type: "object",
+    properties: {
+        color: { type: "string", enum: ["red", "blue"] },
+        count: { type: "integer", minimum: 1 },
+    },
+    required: ["color"],
+};
 function textOf(blocks) {
     return blocks.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("");
 }
@@ -37,6 +59,20 @@ function waitAbort(signal) {
 export function runFakeAcpAgent(input, output, options = {}) {
     const sessions = new Map();
     let counter = 0;
+    /** 客户端在 initialize 里声明了 elicitation。 */
+    let canElicit = false;
+    const configOf = (s) => [
+        {
+            id: "model",
+            name: "Model",
+            category: "model",
+            type: "select",
+            currentValue: s.model,
+            options: MODELS,
+        },
+    ];
+    /** 开会话答复里的 `configOptions`（关着时不加这个键）。 */
+    const config = (s) => options.configOptions === true ? { configOptions: configOf(s) } : {};
     const update = (sessionId, value) => peer.notify(ACP_METHODS.sessionUpdate, { sessionId, update: value });
     const session = (id) => {
         const found = typeof id === "string" ? sessions.get(id) : undefined;
@@ -45,7 +81,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
         return found;
     };
     const open = (id, cwd) => {
-        const created = { id, cwd, mode: "default", turns: 0 };
+        const created = { id, cwd, mode: "default", model: "small", turns: 0 };
         sessions.set(id, created);
         return created;
     };
@@ -75,6 +111,37 @@ export function runFakeAcpAgent(input, output, options = {}) {
             });
         if (text.includes("[refuse]"))
             return done("refusal");
+        const say = (line) => update(s.id, { sessionUpdate: "agent_message_chunk", content: { type: "text", text: line } });
+        if (text.includes("[elicit]")) {
+            if (!canElicit) {
+                await say("elicit: unsupported");
+                return done("end_turn");
+            }
+            let answer;
+            try {
+                answer = await peer.request(ACP_METHODS.elicitationCreate, {
+                    sessionId: s.id,
+                    message: "Pick a color",
+                    requestedSchema: ELICIT_SCHEMA,
+                });
+            }
+            catch {
+                return done("cancelled");
+            }
+            await say(`elicit: ${answer.action} ${JSON.stringify(answer.content ?? null)}`);
+            return done(answer.action === "cancel" ? "cancelled" : "end_turn");
+        }
+        if (text.includes("[model]")) {
+            await say(`model ${options.configOptions === true ? s.model : "none"}`);
+            return done("end_turn");
+        }
+        const env = /\[env ([A-Z0-9_]+)\]/.exec(text);
+        if (env !== null) {
+            const value = process.env[env[1]];
+            const digest = value === undefined ? "absent" : createHash("sha256").update(value).digest("hex");
+            await say(`env ${env[1]} ${digest}`);
+            return done("end_turn");
+        }
         if (text.includes("[slow]")) {
             await waitAbort(turn.signal);
             return done("cancelled");
@@ -141,7 +208,9 @@ export function runFakeAcpAgent(input, output, options = {}) {
         async onRequest(method, raw) {
             const params = (raw ?? {});
             switch (method) {
-                case ACP_METHODS.initialize:
+                case ACP_METHODS.initialize: {
+                    const capabilities = params["clientCapabilities"];
+                    canElicit = capabilities?.["elicitation"] != null;
                     return {
                         protocolVersion: ACP_PROTOCOL_VERSION,
                         agentCapabilities: options.minimal
@@ -154,12 +223,17 @@ export function runFakeAcpAgent(input, output, options = {}) {
                         authMethods: [],
                         agentInfo: { name: options.name ?? "fake-acp-agent", version: "1.0.0" },
                     };
+                }
                 case ACP_METHODS.sessionNew: {
                     counter += 1;
                     const s = open(`fake-${counter}`, String(params["cwd"] ?? ""));
                     if (options.minimal)
-                        return { sessionId: s.id };
-                    return { sessionId: s.id, modes: { currentModeId: s.mode, availableModes: MODES } };
+                        return { sessionId: s.id, ...config(s) };
+                    return {
+                        sessionId: s.id,
+                        modes: { currentModeId: s.mode, availableModes: MODES },
+                        ...config(s),
+                    };
                 }
                 case ACP_METHODS.sessionResume:
                 case ACP_METHODS.sessionLoad: {
@@ -177,7 +251,7 @@ export function runFakeAcpAgent(input, output, options = {}) {
                             content: { type: "text", text: "echo: earlier" },
                         });
                     }
-                    return { modes: { currentModeId: s.mode, availableModes: MODES } };
+                    return { modes: { currentModeId: s.mode, availableModes: MODES }, ...config(s) };
                 }
                 case ACP_METHODS.sessionList:
                     return {
@@ -193,6 +267,18 @@ export function runFakeAcpAgent(input, output, options = {}) {
                     await update(s.id, { sessionUpdate: "current_mode_update", currentModeId: s.mode });
                     return {};
                 }
+                case ACP_METHODS.sessionSetConfigOption: {
+                    if (options.configOptions !== true)
+                        throw new RpcError(RPC_ERRORS.methodNotFound, `method not found: ${method}`);
+                    const s = session(params["sessionId"]);
+                    if (params["configId"] !== "model")
+                        throw new RpcError(RPC_ERRORS.invalidParams, `unknown config: ${String(params["configId"])}`);
+                    const value = String(params["value"]);
+                    if (!MODEL_VALUES.includes(value))
+                        throw new RpcError(RPC_ERRORS.invalidParams, `unknown model: ${value}`);
+                    s.model = value;
+                    return { configOptions: configOf(s) };
+                }
                 case ACP_METHODS.sessionPrompt:
                     return prompt(raw);
                 default:

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

@@ -2,8 +2,8 @@
  * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
- * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
  * 未知字段一律保留不报错；`_meta` 不解释。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
@@ -22,8 +22,10 @@ export declare const ACP_METHODS: {
     readonly sessionPrompt: "session/prompt";
     readonly sessionCancel: "session/cancel";
     readonly sessionSetMode: "session/set_mode";
+    readonly sessionSetConfigOption: "session/set_config_option";
     readonly sessionUpdate: "session/update";
     readonly requestPermission: "session/request_permission";
+    readonly elicitationCreate: "elicitation/create";
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export declare const RPC_ERRORS: {
@@ -76,6 +78,8 @@ export interface AcpClientCapabilities {
         writeTextFile?: boolean;
     };
     terminal?: boolean;
+    /** 能接 `elicitation/create`（存在即支持）。 */
+    elicitation?: Record<string, unknown>;
 }
 export interface AcpInitializeParams {
     protocolVersion: number;
@@ -149,6 +153,7 @@ export interface AcpNewSessionParams {
 export interface AcpNewSessionResult {
     sessionId: string;
     modes?: AcpSessionModeState | null;
+    configOptions?: AcpSessionConfigOption[] | null;
 }
 export interface AcpLoadSessionParams {
     sessionId: string;
@@ -157,6 +162,84 @@ export interface AcpLoadSessionParams {
 }
 export interface AcpLoadSessionResult {
     modes?: AcpSessionModeState | null;
+    configOptions?: AcpSessionConfigOption[] | null;
+}
+/** 配置项里一个可选值。 */
+export interface AcpConfigSelectOption {
+    value: string;
+    name: string;
+    description?: string | null;
+}
+/** 规范允许把可选值分组。 */
+export interface AcpConfigSelectGroup {
+    group: string;
+    name: string;
+    options: AcpConfigSelectOption[];
+}
+/** `session/new|load|resume` 答的 `configOptions[]` 的一项（目前规范只有 `select`）。 */
+export interface AcpSessionConfigOption {
+    id: string;
+    name: string;
+    description?: string | null;
+    /** `mode` / `model` / `thought_level`，或 Agent 自己的。 */
+    category?: string | null;
+    type: "select" | (string & {});
+    currentValue: string;
+    options: (AcpConfigSelectOption | AcpConfigSelectGroup)[];
+}
+export interface AcpSetConfigOptionParams {
+    sessionId: string;
+    configId: string;
+    value: string;
+}
+/** 答复带全部配置项的新状态（改一项可能连带别的）。 */
+export interface AcpSetConfigOptionResult {
+    configOptions?: AcpSessionConfigOption[] | null;
+}
+/** 表单里的一个字段：扁平的原始类型，规范只允许这几种。 */
+export type AcpElicitationField = {
+    type: "string";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    enumNames?: string[];
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    default?: string;
+} | {
+    type: "number" | "integer";
+    title?: string;
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+} | {
+    type: "boolean";
+    title?: string;
+    description?: string;
+    default?: boolean;
+};
+export interface AcpElicitationSchema {
+    type: "object";
+    properties: Record<string, AcpElicitationField>;
+    required?: string[];
+}
+/** Agent 发来的 `elicitation/create` 参数；未知字段保留。 */
+export interface AcpElicitationParams {
+    sessionId?: string;
+    message: string;
+    /** `form`（缺省）或 `url`。 */
+    mode?: "form" | "url" | (string & {});
+    requestedSchema?: AcpElicitationSchema;
+    url?: string;
+    [key: string]: unknown;
+}
+export type AcpElicitationAction = "accept" | "decline" | "cancel";
+export interface AcpElicitationResult {
+    action: AcpElicitationAction;
+    /** 只随 `accept`。 */
+    content?: Record<string, string | number | boolean>;
 }
 export type AcpResumeSessionParams = AcpLoadSessionParams;
 export type AcpResumeSessionResult = AcpLoadSessionResult;

package/dist/drivers/acp/types.js

@@ -2,8 +2,8 @@
  * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
  *
  * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
- * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
- * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode|set_config_option`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`、`elicitation/create`。字段名与规范一致（camelCase），
  * 未知字段一律保留不报错；`_meta` 不解释。
  *
  * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
@@ -21,8 +21,10 @@ export const ACP_METHODS = {
     sessionPrompt: "session/prompt",
     sessionCancel: "session/cancel",
     sessionSetMode: "session/set_mode",
+    sessionSetConfigOption: "session/set_config_option",
     sessionUpdate: "session/update",
     requestPermission: "session/request_permission",
+    elicitationCreate: "elicitation/create",
 };
 /** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
 export const RPC_ERRORS = {

package/docs/acp.md

@@ -67,12 +67,19 @@ stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM
 - 开会话（`newSession` / `resumeSession` / `loadSession`）的 `mcpServers` 缺省为空数组；宿主可传第三个参数
   `{ mcpServers }`（如 stdio 的 `{ name, command, args, env: [{ name, value }] }`），原样转发给 Agent。
   `AcpClient.features.mcpServers === true` 表示支持（旧版没有 `features`）。ama 自己作客户端时仍不传。
+- `elicitation/create`（Agent 向人要结构化输入）：构造参数给了 `onElicitation(params, signal)` 才在 `initialize` 声明
+  `clientCapabilities.elicitation` 并接这个请求；没给时不声明、请求回 method not found（与旧版相同）。答复收成
+  `{ action: "accept" | "decline" | "cancel", content? }`（`content` 只随 accept，不认识的动作当 cancel）；`cancel(sessionId)`
+  与连接关闭时挂起的一律回 `{ action: "cancel" }`。ama 自己作客户端时不给处理器，从不替人填表。
+- 会话配置项：开会话（new / load / resume）答的 `configOptions` 原样交回；`setConfigOption(sessionId, configId, value)` 发
+  `session/set_config_option`，答复是全部配置项的新状态。
+- `AcpClient.features`：`{ mcpServers, elicitation, configOptions }`，宿主据此做特性检测。
 
 `AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
 
 ## 测试替身
 
-`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。
+`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。另有 `[elicit]`（发 `elicitation/create`，客户端没声明能力时回 `elicit: unsupported`）、`[model]`、`[env NAME]`（只回值的 sha256）三个标记；`--config-options`（进程内 `{ configOptions: true }`）让开会话答一个 `model` 配置项并接 `session/set_config_option`。
 
 黄金记录在 `test/fixtures/acp/`：`driver-{allow,reject,cancel}.jsonl`（ama 驱动假 Agent 的三条路径）与 `mode-prompt.jsonl`（`ama --mode acp` 一轮往返）。`UPDATE_GOLDEN=1` 重写。
 

package/docs/agents.md

@@ -259,7 +259,7 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 
 ### 嵌入宿主
 
-有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。
+有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。宿主注入的 runner id 也可以是 `ama`（例如画布上另一个 ama 节点）：`task(agent="ama")` 交给宿主，不起子会话；没注入时 `ama` 照旧不是可用类型，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
 
 **在 Armadra 画布终端里直接运行 ama（没有 `--host`）**：此时 ama 按独立模式工作，自己启动的外部 Agent 是这个终端节点里的子进程，不会出现在画布上，也不经连线授权；需要让多个 Agent 在画布上协同，就在画布上连线 Agent 节点，或以宿主模式嵌入 ama。终端带着该节点的身份变量（`ARMADRA_NODE_ID`、`ARMADRA_SESSION_ID`、Hook 端点、`ARMADRA_CANVAS_CONTROL` 等），ama 起子进程时一律剥离（askpass 除外），否则 Armadra 装在 Claude / Codex 上的 Hook 会把子 Agent 的事件记到这个节点名下。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [