thincoder 0.12.59 → 0.12.60

package/src/agent-tools/subagent-actions.mjs

@@ -2,11 +2,14 @@
  * subagent-actions.mjs — subagent 动作执行器（§19/§19.5/§19.6——2026-09-05 自
  * subagent-async.mjs 拆分——Module Split Policy §20.9——纯迁移零行为变化）。
  * 内容：executeStatusAction（§19.5 D-M5——非阻塞池查询——touchedSummary/
- * shortTouchedPath/statusFields 摘要助手随行）/ executePanelAction（§19.6——面板镜像
- * view + 门控 freeze——panelFreezeGate/blockKeyIn 随行）/ executeEscalateAction（§19
+ * shortTouchedPath/statusFields 摘要助手随行）/ executeObserveAction + executeSendAction
+ * （SUBAGENT-OBSERVE-SEND——observe 只读/send 控制豁免注入）/ executeEscalateAction（§19
  * D-M4——飞刀——touchedFilesNote 随行）。
- * check/cancel 动作执行器与共享 post-spawn 管线留在 subagent-async.mjs；
+ * §19.8 check 删除后仅 cancel 动作执行器与共享 post-spawn 管线留在 subagent-async.mjs；
  * §20 调度器 + 文件域组在 ./subagent-scheduler.mjs（describeBlockers 由此导入）。
+ * 2026-09-08 二次拆分：§19.6 面板段迁至 ./subagent-panel.mjs（601 > 500 硬限跨档——
+ * 尾部 re-export executePanelAction 保 subagent.mjs 既有 import 面）+ ASYNC-RESULT-
+ * CONTAINER.md D1 落地（池访问点改 getAsyncPool accessor）。
  */
 import { isAbsolute, relative } from "node:path"
 import { runAgent, createAgent, CODER_OVERLAY, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
@@ -17,16 +20,20 @@ import {
 import { logEvent, errText } from "../log.mjs"
 import { describeBlockers, detectStall, STALL_NOTE } from "./subagent-scheduler.mjs"
 import { resolveChildProvider, mergeChildMutations } from "./subagent-async.mjs"
+import { launchEscalateAsync } from "./escalate-async.mjs"
+// ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
+import { getAsyncPool } from "./async-settle.mjs"
 
 /**
  * subagent action:"status" (§19 D-M2, new): NON-BLOCKING async-pool query —
- * returns immediately, never consumes a result and never touches the check read
- * counter (T-M10). Source of truth = the pool (_asyncSubagents): entries moved
- * to _pendingAsyncResults during a suspension (§17 D-S3 ② — injected at the next
- * run start) are no longer in the pool and are NOT counted as done-waiting.
+ * returns immediately and never consumes a result (results belong to the auto
+ * channel — §19.8: no check action any more). Source of truth = the pool
+ * (_asyncSubagents): entries moved to _pendingAsyncResults during a suspension
+ * (§17 D-S3 ② — injected at the next run start) are no longer in the pool and
+ * are NOT counted as done-waiting.
  * - id given → { id, role, status, model?, elapsedSec?, turn?, maxTurns?,
  *   touchedFiles?/touchedMore?/touched? ... } for that entry; unknown id → error
- *   (same wording as check — T12 semantics)
+ *   (T12 semantics — unknown async-subagent id error, same wording as the pool).
  * - id omitted → { overview: { running: [{id, role, model, elapsedSec, turn,
  *   maxTurns, touchedFiles?/touched?}], queued: [{id, role, position, touched?}],
  *   done: [{id, role}] } } — live queue positions (index in _asyncQueue + 1).
@@ -34,7 +41,8 @@ import { resolveChildProvider, mergeChildMutations } from "./subagent-async.mjs"
  * 计数——相对查询方 cwd；0 改动 → touched 占位）；queued 条目带 touched 占位
  * "—（未启动）"；done/error/取消条目无 touched 字段（round3 #9）。
  * A settled-but-unconsumed entry (settled during a NORMAL turn) reports done
- * with a "not yet consumed" note — check still retrieves it afterwards.
+ * with a "not yet consumed" note — the auto channel (turn-end collection / the
+ * suspension digest) still delivers it afterwards (§19.8: sole consumption path).
  */
 /** §19.5 D-M5 decision-field assembly (F9): running entries report
  *  {id, role, model, elapsedSec, turn, maxTurns} — the data needed to decide
@@ -86,7 +94,8 @@ function statusFields(entry, cwd) {
 
 export function executeStatusAction(args, ctx) {
   const agent = ctx.agent
-  const map = agent._asyncSubagents ?? new Map()
+  const map = getAsyncPool(agent, "subagent") ?? new Map()
+  const advisors = getAsyncPool(agent, "advisor") ?? new Map()
   const queue = agent._asyncQueue ?? []
   const queuedPosition = (id) => {
     const i = queue.findIndex((e) => String(e.id) === id)
@@ -95,8 +104,13 @@ export function executeStatusAction(args, ctx) {
   const { id } = args ?? {}
   if (id !== undefined && id !== null && String(id) !== "") {
     const key = String(id)
-    const entry = map.get(key)
+    // §24 D-24b: by-id queries fall through to the advisor pool (shared counter —
+    // ids are unique across both pools; role identifies the kind).
+    const entry = map.get(key) ?? advisors.get(key)
     if (!entry) {
+      // Wording kept exact — locked by subagent-async/tool tests (unknown-id error
+      // semantics); an unknown id simply names neither pool (the pools share the
+      // id counter, so the message stays unambiguous).
       return JSON.stringify({ id: key, status: "error", error: `unknown async subagent id: ${key}` })
     }
     const target = statusFields(entry, agent.cwd)
@@ -119,16 +133,17 @@ export function executeStatusAction(args, ctx) {
       }
       return JSON.stringify(out)
     }
-    // done = settled during this turn and not yet consumed — check still retrieves it
-    // (§17.5: at a driven turn end it stays pooled → the suspension digest consumes it).
+    // done = settled during this turn and not yet consumed — the auto channel still
+    // delivers it (§19.8: turn-end collection / the suspension digest — no fetch action).
     target.status = "done"
     target.done = true
     if (entry.error) target.error = entry.error
-    target.note = "settled, not yet consumed — retrieve via check or the suspension digest injects it"
+    target.note = "settled, not yet consumed — delivered by the auto channel (turn-end collection or the suspension digest injects it)"
     return JSON.stringify(target)
   }
   const overview = { running: [], queued: [], done: [] }
-  for (const entry of map.values()) {
+  const mapEntries = [...map.values(), ...advisors.values()]
+  for (const entry of mapEntries) {
     if (entry.status === "running") overview.running.push(statusFields(entry, agent.cwd))
     else if (entry.status === "queued") {
       // §20：queued 条目补 waiting/reason（F-SD4——依赖/冲突原因模型可见）；
@@ -157,145 +172,158 @@ export function executeStatusAction(args, ctx) {
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// §19.6 subagent panel 检查工具（AGENT-LOOP.md §19.6——F-P1..P3/D-P1..P4）
+// SUBAGENT-OBSERVE-SEND（docs/design/SUBAGENT-OBSERVE-SEND.md——CLI 端）
+// observe（D1——readonly 查询）+ send（D2——控制类豁免注入引导）——动作执行器。
+// 目标 = 父自身 spawn 的异步子代理池条目（_asyncSubagents——非 advisor/escalate——
+// 后者共享 id 计数但非"读写子代理"，错误路径明示）。
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** 面板块 key（role#N）在池（Map——条目值）/pending（数组）中的归属判定。 */
-function blockKeyIn(container, key) {
-  const entries = container instanceof Map ? [...container.values()] : (container ?? [])
-  return entries.some((e) => `${e.role}#${e.id}` === key)
+/** D1/N2 摘要形态：从子代理 _fullHistory（real 消息——pushReal 累积）倒序收最近 N 个
+ *  assistant 回合的一行描述（newest-first；assistant 消息 = 一回合——带 tool_calls =
+ *  工具轮、独立 content = 回复首行）。返回纯摘要非全量（N2 隔离——不把子代理噪音灌父）。 */
+function recentTurnLines(child, limit) {
+  const hist = child?._fullHistory
+  if (!Array.isArray(hist)) return []
+  const out = []
+  for (let i = hist.length - 1; i >= 0 && out.length < limit; i--) {
+    const m = hist[i]
+    if (m?.role !== "assistant") continue
+    const tcs = Array.isArray(m.tool_calls)
+      ? m.tool_calls.filter((t) => typeof t?.function?.name === "string")
+      : []
+    if (tcs.length) out.push(`tools: ${tcs.map((t) => t.function.name).join(", ")}`)
+    else if (typeof m.content === "string" && m.content.trim()) {
+      const first = m.content.trim().split(/\r?\n/).find((l) => l.trim())
+      out.push((first ?? m.content.trim()).slice(0, 120))
+    } else out.push("(assistant — no content)")
+  }
+  return out
+}
+
+function queuedPositionOf(agent, key) {
+  const i = (agent?._asyncQueue ?? []).findIndex((e) => String(e.id) === key)
+  return i >= 0 ? i + 1 : undefined
+}
+
+/** recent 参数钳制（默认 ~5 条摘要——可参数；钳到 1..20 防超长 N2 失控）。 */
+function clampRecent(n) {
+  const v = Number.parseInt(n, 10)
+  if (!Number.isFinite(v)) return 5
+  return Math.max(1, Math.min(20, v))
 }
 
 /**
- * §19.6 D-P3 冻结门控（安全）：仅允许冻结 awaitingDigest 且池（_asyncSubagents）
- * 无对应运行条目 + pending（_pendingAsyncResults）无对应条目的块（= 已消化驻留块
- * ——报告已入模型上下文——pending 已消费——状态滞后——补发冻结不破坏任何顺序）。
- * - pending 仍有对应（报告未达模型）→ 拒绝（提前回收破坏消化顺序——T-P3）
- * - 不存在的 key / 仍 running / done 的块 → 拒绝（T-P4——running 块 settle 时自冻）
- * - 无镜像 → 拒绝（headless/VS Code——freeze 不可用——T-P5）
- * 错误信息明确（模型可解释 + 自助修正）。返回 { ok:true } 或 { err }。
+ * subagent action:"observe"（D1——READONLY 查询，父回合内）：按 id 拉运行中异步子代理的
+ * 最近活动快照——从 entry.childAgent（subagent-run.mjs start() 绑定）读**已落回合**摘要
+ * （_fullHistory 最近 N 条）+ _touchedFiles + turn/maxTurns + status + **in-flight 当前
+ * 工具**（评审 #1——从 dispatch runOne 维护的 child._inflightTools 读——非只读已落
+ * history：卡在长工具调用时 history 无新回合、恰是 observe 要检测的卡死态）。返摘要非
+ * 全量（N2）。observe = readonly——running/queued/done 均可查（done 终报 / queued 占位）。
  */
-function panelFreezeGate(agent, key) {
-  const snap = agent._panelSnapshot
-  if (!Array.isArray(snap)) {
-    return { err: "panel unavailable — no CLI TUI panel mirror in this session (headless / VS Code / subagent contexts — freeze unavailable; panel is CLI-TUI-only, AC-P4)" }
+export function executeObserveAction(args, ctx) {
+  if ((ctx.depth ?? 0) > 0) {
+    return JSON.stringify({ status: "error", error: "observe is only available at depth 0 — a child agent has no async pool of its own (AGENT-LOOP.md §7.2)" })
   }
-  const block = snap.find((b) => b.key === key)
-  if (!block) {
-    const live = snap.map((b) => `${b.key}(${b.status})`).join(", ")
-    return { err: `unknown panel block key: ${key} — the live panel holds: ${live || "(no blocks)"}` }
+  const agent = ctx.agent
+  const id = args?.id
+  if (id === undefined || id === null || String(id) === "") {
+    return JSON.stringify({ status: "error", error: "observe requires the id of the async subagent to inspect (from the async spawn return) — pass the id; omitting it observes nothing (SUBAGENT-OBSERVE-SEND)" })
   }
-  if (block.status !== "awaitingDigest") {
-    if (block.status === "done") {
-      return { err: `block ${key} is already done — nothing to freeze; it was (or is about to be) reclaimed into the conversation by the freeze sweep at the turn end / settle (only digested-stuck awaitingDigest blocks need a manual freeze)` }
+  const key = String(id)
+  const entry = getAsyncPool(agent, "subagent")?.get(key)
+  if (!entry) {
+    if (getAsyncPool(agent, "advisor")?.has(key)) {
+      return JSON.stringify({ status: "error", error: `id ${key} is an async ADVISOR review — observe is for async subagents (read/edit children); track an advisor with action:'status' or wait for its auto-delivered report` })
     }
-    if (block.status === "running") {
-      return { err: `block ${key} is still running — freeze only reclaims awaitingDigest blocks whose report is already digested; a running block freezes on its own settle (or stop it with action:'cancel' if it is a background async child)` }
-    }
-    return { err: `block ${key} is in state ${block.status} — freeze only reclaims awaitingDigest blocks whose report is already digested` }
-  }
-  if (blockKeyIn(agent._asyncSubagents, key)) {
-    return { err: `block ${key} still has a live pool entry — it is NOT a digested-stuck block (freeze refused; status action shows the pool)` }
+    return JSON.stringify({ status: "error", error: `unknown async subagent id: ${key}` })
   }
-  if (blockKeyIn(agent._pendingAsyncResults, key)) {
-    return { err: `block ${key} is still genuinely awaiting digestion — its report is still in _pendingAsyncResults and has NOT reached the model yet; freezing now would break the digestion order (wait for the digest run, which reclaims it automatically — §17.5.5)` }
+  const child = entry.childAgent
+  const out = { id: key, role: entry.role, status: entry.status }
+  if (entry.status === "running") {
+    out.turn = entry.turn ?? 0
+    out.maxTurns = entry.maxTurns ?? 0
+    Object.assign(out, touchedSummary(entry, agent.cwd))
+    // in-flight 当前工具（评审 #1）：child._inflightTools Set——dispatch runOne 在工具
+    // 执行前后维护——LLM 生成/工具间空隙为空；子代理 await 长工具调用时父回合可见它。
+    const inflight = child?._inflightTools
+    if (inflight instanceof Set && inflight.size > 0) out.currentTool = [...inflight]
+    const n = clampRecent(args?.recent)
+    out.recentTurns = recentTurnLines(child, n)
+    out.note = `observing running ${entry.role}#${key} — recentTurns newest-first (cap ${n}); currentTool shown only while a tool is executing (stuck detection); sent directions consume at the next turn boundary`
+  } else if (entry.status === "queued") {
+    out.position = queuedPositionOf(agent, key) ?? entry.position ?? null
+    out.note = "queued — not started yet; no activity to observe (starts when the slot frees / dependencies clear; action:'send' targets running only)"
+  } else {
+    // done = settled this turn, not yet consumed — final report rides the auto channel.
+    out.done = true
+    out.turn = entry.turn ?? 0
+    out.maxTurns = entry.maxTurns ?? 0
+    out.recentTurns = child ? recentTurnLines(child, clampRecent(args?.recent)) : []
+    out.note = "settled — the final report is delivered by the auto channel (turn-end collection or the suspension digest); observe returns the activity summary, not the full report (N2)"
   }
-  return { ok: true }
+  return JSON.stringify(out)
 }
 
 /**
- * §19.6 subagent action:"panel"（D-P2——readonly 视图面 + 门控干预面——单动作双参，
- * freeze 优先）：
- * - view（缺省——返回镜像区块列表）：agent._panelSnapshot = TUI 面板镜像（块级
- *   状态变更点由 subagent-blocks syncPanelSnapshot 同步刷新——与用户所见一致——
- *   index.mjs 装配 state._agent）。awaitingDigest 条目**读时交叉**
- *   _pendingAsyncResults/_asyncSubagents 标注 digested（round1 #3——digested:true
- *   = 报告已消化但块仍驻留——异常块——freeze 候选；模型可定位解释 UI 怪相）。
- * - freeze:key（D-P3 门控通过 → 发 key + "/" + ⟦ev⟧done 哨兵字面 token——
- *   onToken——TUI routeSubToken 冻结回收——落位复用 sub._freezeAt settle 锚点
- *   splice，无锚点尾推兜底——§17.5.5 同口径——round1 #2）。
- * 无镜像（headless/VS Code——D-P2 round1 #1：webview 无 state.subTasks 对应物——
- * 7.2.3.2 #8 先例）→ view 恒降级池视图（_asyncSubagents + _pendingAsyncResults
- * 合成）+ no panel 注；freeze 报不可用。CLI-only 完整能力（AC-P4）。
+ * subagent action:"send"（D2——控制类豁免，同 cancel/panel-freeze——父回合内显式调用即
+ * 授权）：按 id 向运行中异步子代理注入一条引导消息——push 进 entry._injected（仅 running
+ * 异步可 send）；子回合边界经 consumeInjected 回调消费 → pushReal 成 user 回合进子历史
+ * → 当作普通指令处理（注入不等同偏离豁免——子收敛/审计纪律不变）。settle/cancel/unknown
+ * /queued → 明确错误。send→settle 竞态：入队后子未及下回合边界即 settle → 消息未投递
+ * → settle 收尾附报告提示（不在此报错——send 返回时无法预知）。
  */
-export function executePanelAction(args, ctx) {
+export function executeSendAction(args, ctx) {
+  if ((ctx.depth ?? 0) > 0) {
+    return JSON.stringify({ status: "error", error: "send is only available at depth 0 — a child agent has no async pool of its own (AGENT-LOOP.md §7.2)" })
+  }
   const agent = ctx.agent
-  const freezeKey = (args?.freeze !== undefined && args?.freeze !== null && String(args.freeze) !== "")
-    ? String(args.freeze)
-    : null
-  // ── freeze 面（优先——D-P2 单动作双参互斥）──
-  if (freezeKey) {
-    if ((ctx.depth ?? 0) > 0) {
-      return JSON.stringify({ status: "error", error: "panel freeze is only available at depth 0 — a child agent has no panel of its own (AGENT-LOOP.md §19.6 D-P2)" })
-    }
-    const gate = panelFreezeGate(agent, freezeKey)
-    if (gate.err) return JSON.stringify({ status: "error", error: gate.err })
-    if (!ctx.callbacks?.onToken) {
-      return JSON.stringify({ status: "error", error: `panel mirror present but no token relay in this context — the freeze of ${freezeKey} cannot reach the TUI` })
-    }
-    // 门控通过 → 发 done 冻结事件（settle 同机制字面格式——TUI routeSubToken done
-    // 分支冻结回收——落位 _freezeAt settle 锚点 splice；无锚点（旧会话残留）时
-    // freezeSubTaskLines 尾推兜底——注明两种落位，模型不被误导（advisor 🟡1）。
-    ctx.callbacks.onToken(`${freezeKey}/⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
-    return JSON.stringify({
-      key: freezeKey,
-      status: "frozen",
-      note: "done freeze event issued — the TUI reclaimed the block into the conversation (spliced at its settle anchor when one is recorded, else appended at the current stream end — §17.5.5 same-rule position)",
-    })
+  const id = args?.id
+  if (id === undefined || id === null || String(id) === "") {
+    return JSON.stringify({ status: "error", error: "send requires the id of the running async subagent to direct (from the async spawn return) — omitting it means an unspecified target (SUBAGENT-OBSERVE-SEND)" })
   }
-  // ── view 面（缺省——readonly）──
-  // 双参互斥（D-P2）：freeze 优先；显式 view:false 且无 freeze = 无请求可执行——报错。
-  if (args?.view === false) {
-    return JSON.stringify({ status: "error", error: "panel has nothing to do — view:false with no freeze key; pass freeze:'role#N' to reclaim a digested-stuck block, or omit view (defaults to true)" })
+  const message = args?.message
+  if (typeof message !== "string" || !message.trim()) {
+    return JSON.stringify({ status: "error", error: "send requires the message to inject — the direction the running subagent should treat as an ordinary user instruction at its next turn boundary" })
   }
-  const snap = agent._panelSnapshot
-  if (!Array.isArray(snap)) {
-    // F-P3 降级：无镜像（headless/VS Code/子代理上下文——CLI TUI-only 完整能力）→
-    // 池视图（_asyncSubagents 运行/排队条目 + _pendingAsyncResults 待消化条目）
-    const blocks = []
-    const queue = agent._asyncQueue ?? []
-    for (const e of [...(agent._asyncSubagents?.values() ?? [])]) {
-      const b = { key: `${e.role}#${e.id}`, role: e.role }
-      if (e.status === "running") {
-        b.status = "running"
-        b.elapsedSec = e.startedAt ? Math.max(0, Math.floor((Date.now() - e.startedAt) / 1000)) : 0
-      } else if (e.status === "queued") {
-        b.status = "queued"
-        const qi = queue.indexOf(e)
-        b.position = qi >= 0 ? qi + 1 : (e.position ?? null)
-      } else {
-        b.status = "done" // 回合内 settle 未取——status action 可查/check 可取回
-      }
-      blocks.push(b)
+  const key = String(id)
+  const entry = getAsyncPool(agent, "subagent")?.get(key)
+  if (!entry) {
+    if (getAsyncPool(agent, "advisor")?.has(key)) {
+      return JSON.stringify({ status: "error", error: `id ${key} is an async ADVISOR review — send is for async subagents; you cannot inject direction into a running review (AGENT-LOOP.md §7.2)` })
     }
-    for (const e of agent._pendingAsyncResults ?? []) {
-      blocks.push({ key: `${e.role}#${e.id}`, role: e.role, status: "awaitingDigest", note: "report pending — injected at the next run start (§17)" })
-    }
-    return JSON.stringify({
-      degraded: true,
-      note: "no panel — this session has no CLI TUI panel mirror (headless / VS Code / subagent context — panel view is CLI-TUI-only, AC-P4); pool-derived view below; action:'status' shows the full pool",
-      panel: blocks,
-    })
+    return JSON.stringify({ status: "error", error: `unknown async subagent id: ${key}` })
   }
-  const panel = snap.map((b) => {
-    const out = { key: b.key, role: b.role, status: b.status }
-    if (b.status === "running") {
-      out.elapsedSec = b.startedAt ? Math.max(0, Math.floor((Date.now() - b.startedAt) / 1000)) : 0
-    } else if (b.status === "awaitingDigest") {
-      // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（注入即从两者移除）——
-      // 块驻留 = 状态滞后——digested:true（freeze 候选——模型可定位异常块）。
-      out.digested = !blockKeyIn(agent._pendingAsyncResults, b.key) && !blockKeyIn(agent._asyncSubagents, b.key)
-    }
-    return out
+  if (entry.done || entry.cancelled) {
+    return JSON.stringify({ status: "error", error: `async subagent #${key} has ${entry.cancelled ? "been cancelled" : "already settled"} — nothing to send (you cannot inject into a finished subagent; re-spawn with the direction instead)` })
+  }
+  if (entry.status !== "running") {
+    return JSON.stringify({ status: "error", error: `async subagent #${key} is ${entry.status} (not running) — send only targets a RUNNING async subagent; a queued one has not started its turn loop yet` })
+  }
+  entry._injected ??= []
+  entry._injected.push(String(message).trim())
+  return JSON.stringify({
+    id: key,
+    status: "delivered",
+    queued: entry._injected.length,
+    note: `message queued for ${entry.role}#${key} — consumed as an ordinary user instruction at its next turn boundary (after its current tool finishes — non-interrupting). If it settles first, its report carries an "undelivered" note.`,
   })
-  return JSON.stringify({ panel })
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// §19.6 subagent panel 检查工具（AGENT-LOOP.md §19.6——F-P1..P3/D-P1..P4）
+// ═══════════════════════════════════════════════════════════════════════════
+// 2026-09-08 拆分（Module Split Policy——601 > 500 硬限跨档）：§19.6 面板段迁至
+// ./subagent-panel.mjs（executePanelAction/panelFreezeGate/blockKeyIn——verbatim +
+// ASYNC-RESULT-CONTAINER D1/D2 落地）；本面保留 re-export 保 subagent.mjs 既有
+// import 面（subagent-async 尾部 re-export 先例）。
+export { executePanelAction } from "./subagent-panel.mjs"
+
 /**
- * subagent action:"escalate"（§19 D-M4——退役 escalate 工具语义原样，ESCALATE.md）：
- * 飞刀——交给 consultModels 池里更强模型（WRITE + 术后报告）。约束全保留：depth-0
- * only / 工程模式拒 / consultModels 空拒 / relay 前缀 `escalate#N/`（与既有前缀同名
- * ——TUI 路由零改动）/ 无 permQueue（continue 直达用户）/ mutations merge 回父。
+ * subagent action:"escalate"（§19 D-M4——退役 escalate 工具语义原样，ESCALATE.md；
+ * §25 D-R17b——R17：缺省 async——后台飞刀 + settle 三分类 digest——async:false 保
+ * 同步旧路径）。飞刀——交给 consultModels 池里更强模型（WRITE + 术后报告）。约束全
+ * 保留：depth-0 only / 工程模式拒 / consultModels 空拒 / relay 前缀 `escalate#N/`
+ * （与既有前缀同名——TUI 路由零改动）/ mutations merge 回父（async 路径在 settle 分类）。
  */
 export async function executeEscalateAction(args, ctx) {
   const parent = ctx.agent
@@ -334,6 +362,16 @@ export async function executeEscalateAction(args, ctx) {
   }
 
   const tag = label(pick)
+
+  // §25 D-R17b (R17 — 决策点 ③): escalate 缺省 async — the launch returns an ack
+  // {id, role:"escalate", status:"running"|"queued"} and the flight runs in the
+  // background (shared other pool; settle 三分类 → pending 单容器 digest——
+  // ASYNC-RESULT-CONTAINER.md D2)。
+  // `async: false` keeps the legacy synchronous flight below (backward compat).
+  if (args?.async !== false) {
+    return launchEscalateAsync(parent, ctx, { task: String(task), provider, tag, effortNote })
+  }
+
   const relayPrefix = makeRelay(parent, "escalate", ctx.callbacks?.onToken, provider.model ?? tag)
 
   // 无墙钟 watchdog——turn cap 即成本预算（2026-08-16 rationale：固定墙钟会误杀正常慢速