@thincoder/core 0.9.4 → 0.10.1

package/agent-tools/subagent-spawn.mjs

@@ -1,7 +1,7 @@
 /**
  * subagent-spawn.mjs — spawn 路径装配（2026-09-05 module-split：subagent.mjs 726
  * > 500 硬限——spawn 前置 helpers（effectiveSubagentModel/resolveDesignSlot——审计块
- * 构造器 2026-09-22 起另立 ./audit-block.mjs）+ §20 调度参数准入（prepareScheduling）+ child 装配
+ * 构造器 2026-09-22 起另立 ./audit-block.mjs）+ AGENT-LOOP-SUBAGENT.md §6.9 调度参数准入（prepareScheduling）+ child 装配
  * （buildSpawnChild）verbatim 迁入（仅闭包变量参数化），语义零变；executeAsyncSpawn
  * 另在 subagent-run.mjs。subagent.mjs execute 经本文件 import 调用。
  * 2026-09-07：executeConsumeDesignAction 消费执行器（token 链终消费制——与 spawn 侧
@@ -11,14 +11,13 @@
  * （`child._spawnSystemBlock` 单点绑定——消费点 = 核 `prepareRun`），`input` 只留任务书。
  */
 
-import { resolve } from "node:path"
-import { existsSync, statSync } from "node:fs"
+import { basename, isAbsolute, relative } from "node:path"
 import {
   createAgent,
-  readonlyToolNames, escapeXml,
+  readonlyToolNames, escapeXml, excludeSubagentTools,
 } from "../agent.mjs"
 import { allocRelay, wrapChildCallbacks, relayPrefixOf } from "../agent/spawn-child.mjs"
-// TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口常量单源（store 零依赖）。
+// TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：子代理人读线窗口常量单源（store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { validateDesignToken } from "./advisor.mjs"
 import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot, persistEngTokens } from "../token-ttl.mjs"
@@ -33,6 +32,37 @@ import { validateTaskBookFields } from "./spawn-gates.mjs"
 // 台账 #23（AGENT-LOOP-SUBAGENT.md §6.26 · D23-3）：审计块构造器外提（`summarizeEngTaskBook`
 // + `buildAuditBlock` 纯函数）——spawn 档只做「收集 + 绑定」；块文本逐字搬移（D23-4）。
 import { buildAuditBlock } from "./audit-block.mjs"
+// 批次档路径解析单源（BATCH-RECORD.md §4.15 · 台账 #287）：门内解析改经叶档（读面非抛形），
+// 与 append / create 同源——门判据仍「参数在 + 路径可读」，错误文案逐字零变。
+import { resolveBatchReadPath, batchDocBases } from "./batch-paths.mjs"
+// LOGGING（LOGGING.md）：#309 形三观测留痕走同一事件通道。
+import { logEvent } from "../log.mjs"
+
+/** #309 任务书 token 判据（`AGENT-LOOP-SUBAGENT.md` §6.29.3）：`.md` 结尾的连续路径型字面
+ *  （含盘符形态——裸名 `AGENTS.md` 无分隔符且非绝对，见调用点过滤）。 */
+const MD_PATH_TOKEN = /[A-Za-z0-9_@.:\\/-]+\.md\b/g
+
+/** #309 形三·task↔batchDoc 观测留痕（§6.29.3——**不阻断**，spawn 照常放行）：任务书文本提及
+ *  **他批存在档** ⇒ `logEvent` 留痕一条（键面 = 两侧基名，零任务书内容）；只提绑定档 / 无路径型
+ *  `.md` 字面 ⇒ 零事件。token 逐条经 `resolveBatchReadPath` 解析（路径单源），命中 = 可读 ∧
+ *  落基底内 ∧ ≠ 绑定档（同一档多 token 按解析后绝对路径去重）。 */
+function logBatchDocRefs(parent, role, task, boundAbs) {
+  const cwd = parent?.cwd ?? process.cwd()
+  const text = typeof task === "string" ? task : ""
+  const key = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+  const bases = batchDocBases(cwd) // 歧义锚 ⇒ 候选项目基底并集（#828——入基底判据覆盖面随之对齐）
+  const seen = new Set()
+  for (const m of text.matchAll(MD_PATH_TOKEN)) {
+    const token = m[0]
+    if (!/[/\\]/.test(token) && !isAbsolute(token)) continue // 裸名（AGENTS.md 形态）不取
+    const abs = resolveBatchReadPath(cwd, token)
+    if (!abs || key(abs) === key(boundAbs ?? "")) continue // 不可读 / 就是绑定档 ⇒ 零事件
+    const inBase = bases.some((b) => { const r = relative(b, abs); return r && !r.startsWith("..") && !isAbsolute(r) })
+    if (!inBase || seen.has(key(abs))) continue // 他 .md 引用（设计档 / 需求档等）/ 同档重复
+    seen.add(key(abs))
+    logEvent("child:batchdoc-ref", { role, batchDocBase: basename(boundAbs ?? ""), refBase: basename(abs) })
+  }
+}
 
 /**
  * Effective subagent model override for a role (CLI parity shared with VS Code):
@@ -75,7 +105,7 @@ export function resolveDesignSlot(parent, designIdArg) {
     const rec = reconcileEngTokensFromSlot(parent)
     if (rec && rec !== slots) slots = rec
   }
-  // F2d (§29.1): both refusal branches carry the HELD id list — after a
+  // F2d: both refusal branches carry the HELD id list — after a
   // persistence restore the parent has no digest to look the id up in; the error
   // list is the only discovery path (ids are not credentials — the token is).
   const size = slots instanceof Map ? slots.size : 0
@@ -144,14 +174,14 @@ export function executeConsumeDesignAction(args, ctx) {
   return `design slot consumed — designId ${designId ?? "(single-design session)"} is closed out; a further eng-coder spawn for this design is mechanically rejected, and any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
 }
 
-// ── §20 spawn 调度参数准入（AGENT-LOOP.md §20 D-SD1/D-SD3 + 20.4 round2 #5/#7）──
+// ── spawn 调度参数准入（AGENT-LOOP-SUBAGENT.md §6.9 D-SD1/D-SD3）────────────
 // files/dependsOn 声明即契约（v1：不做任务书文本自动解析——不可靠）。缺省（两者皆
 // 缺）= 既有语义零改动（不参与冲突检测/无校验——legacy spawn 零开销直通）。
 // 校验序：参数形态 → 依赖 unknown id（非 consumed 墓碑——T-SD10）→ 依赖环可达
 // （T-SD5——防御断言：自然流程不可达）→ 等待态判定。判定结果：wait/depc 阻塞 →
 // async 入 queued 等位（spawn 返回带 reason——D-SD3b）；**sync spawn（async:false）
 // 命中阻塞 → 明确错误——不队列化 sync——sync 语义零变更（round2 #7——T-SD13）**。
-/** §20 准入（参数化提取——2026-09-05 module-split）：返回归一化 { files, dependsOn }。
+/** 准入（参数化提取——2026-09-05 module-split）：返回归一化 { files, dependsOn }。
  *  filesRaw 目录声明 fail-closed（检测器 throw → 错误即工具结果 JSON）。 */
 export function prepareScheduling(parent, filesRaw, dependsRaw, wantAsync) {
   const files = []
@@ -191,7 +221,7 @@ export function prepareScheduling(parent, filesRaw, dependsRaw, wantAsync) {
 }
 
 /**
- * §20 准入通过后的 child 装配（2026-09-05 module-split——自 execute 参数化提取，
+ * AGENT-LOOP-SUBAGENT.md §6.9 准入通过后的 child 装配（2026-09-05 module-split——自 execute 参数化提取，
  * 原 318-488 段 verbatim——语义零变）。副作用保留：relay 取号（sync 支 allocRelay——
  * `[model]` 出生声明归 SYNC-CANCEL 单点，#133）/ 子代理 _logId / _engTaskInput 携带 /
  * _spawnSystemBlock 绑定（台账 #23——spawn 固块单点）全部在此发生。返回阻塞/异步两路径共用的
@@ -206,20 +236,19 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 批次档路径（需求 §1.11 铁律 #5 随件传递的机械面）。落点 = 本装配点（token 门之前）：
   // sync 与 async 两条 spawn 路径都经过 buildSpawnChild——一处校验双路生效，错误出口与
   // token 门一致（§2.13.1 选型 A）。
-  // 判据只到"参数在 + 路径可读"——**不校验内容/措辞**（不做"已收口"正则、不匹配模板、
-  // 不生成；内容够不够由执行者拒收兜底——需求 §1.14 #9 行为面）。路径语义照
-  // `files` 先例：cwd 相对或绝对均可，`\` 归一为 `/`。错误文案带**实际角色名**（§2.15
-  // 越界文案参数化——designer 撞门时不误导）。
+  // 路径语义照 `files` 先例：cwd 相对或绝对均可，`\` 归一为 `/`；解析序单源 = §4.15（cwd → 项目根 →
+  // 逐基底，读面取首个可读）——cwd 非项目根时根相对串不再必拒（BR-29/BR-33）。错误文案带
+  // **实际角色名**（§2.15 越界文案参数化——designer 撞门时不误导）与逐字不可读后缀。
   let batchDocAbs = null
   if (role === "eng-coder" || role === "eng-designer") {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
     const refusal = (suffix = "") => new Error(
       `batchDoc is required for role='${role}' — pass the batch record path (docs/batches/<batch>-<topic>.md); spawn refused without it.` + suffix)
     if (!given) throw refusal()
-    batchDocAbs = resolve(parent.cwd ?? process.cwd(), given.replace(/\\/g, "/"))
-    let readable = false
-    try { readable = existsSync(batchDocAbs) && statSync(batchDocAbs).isFile() } catch { readable = false }
-    if (!readable) throw refusal(" (given path is not a readable file)")
+    batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
+    if (!batchDocAbs) throw refusal(" (given path is not a readable file)")
+    // #309 形三：任务书中的他批批次档引用观测留痕（不阻断——放行不受影响）。
+    logBatchDocRefs(parent, role, args.task, batchDocAbs)
   }
 
   // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：任务书六强制字段门——
@@ -258,6 +287,9 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   } else {
     tools = parent.tools
   }
+  // Then the depth>0 exclusion (TOOLS.md §6.16): role selection above, exclusion LAST — both
+  // branches converge here (`question` = interactive main-session tool; a child has no user to ask).
+  tools = excludeSubagentTools(tools)
 
   // PROMPT-SYSTEM 施工② G3（2026-09-10）：overlay（人格）装载随装配改造退役——人格槽
   // 由 assemblePrompt 的 D1 场景表按 role 承载（persona-{role}，explore/coder/plan =
@@ -307,19 +339,19 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     overlay,
     role,
   })
-  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口置位（常量单源
+  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：子代理人读线窗口置位（常量单源
   // session-store.mjs）——机制复用主 agent 同路径（context.mjs pushReal 驱逐）；
   // 每个 child 原先各自一份永不压缩的 _fullHistory（勘察 C2 乘数面）。
   child._historyWindow = RECORD_WINDOW_MESSAGES
 
-  // §2.20.2 批次档段写入通道绑定（第 4 批）：工程角色（eng-coder/eng-designer）把批次档
-  // 绝对路径记在 child 上——setup 挂载 batch_segment 时读它。无路径参数的工具靠这条
+  // BATCH-RECORD.md §2 批次档段写入通道绑定（第 4 批）：工程角色（eng-coder/eng-designer）把批次档
+  // 绝对路径记在 child 上——setup 挂载 `batch` 时读它。无路径参数的工具靠这条
   // 绑定决定目标档（spawn 门已保证「参数在 + 路径可读」）。
   if (engineeringRole) child._batchDoc = batchDocAbs
 
   // Token-verified design review → child is authorized to modify files without re-reviewing
   if (role === "eng-coder") child._engDesignReviewed = true
-  // §18 D-E3 task-domain authorization: approved design + spawn task = authorization.
+  // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 task-domain authorization: approved design + spawn task = authorization.
   // The child's OWN tools skip ONLY the onPermissionRequest ask (autoApprove
   // equivalent — dispatch.mjs permission stage); every other gate (JSON parse /
   // unknown tool / planMode / design-token) still applies (T-E14). Non-eng-coder
@@ -334,7 +366,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     child._engDesignId = args.designId ?? null
   }
 
-  // §18.5 子代理零 git（D-AG1——2026-09-04 用户裁定）：explore/plan 一律不注入
+  // §6.7.4 子代理零 git（D-AG1——2026-09-04 用户裁定）：explore/plan 一律不注入
   // git 上下文——子代理证据链 = 任务书 ∪ 磁盘当前状态（read/glob/grep）∪（审计时）
   // _touchedFiles，无一项来自 git；注入的全工作区脏状态快照与任务域无关，会误导
   // 审计/探索（"status 里这个文件算不算超清单？"）。注入分支整体删除（B 方案
@@ -353,7 +385,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 本行让子代理"拿到本档路径"）。行文不含 summarizeEngTaskBook 的三组段 marker
   // （Docs involved / Files list / Acceptance criteria）——段匹配不受影响。仅工程角色注入。
   if (engineeringRole) spawnBlocks.push(`Batch record (batchDoc): ${batchDocAbs}`)
-  // §18 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
+  // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
   // the eng-coder's OWN spawn task — mechanically kept as _engTaskInput by the
   // parent spawn and injected as the D-TS5 A2 mechanical summary (design docs /
   // affected-file list / acceptance criteria verbatim, verbose context dropped)
@@ -370,10 +402,10 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   if (spawnBlocks.length > 0) child._spawnSystemBlock = spawnBlocks.join("\n\n")
 
   // Relay content/reasoning/tool/output to the parent TUI via the unified spawn-child
-  // pipeline (AGENT-LOOP.md §7.2 D3). Prefix includes a unique id: parallel child agents
+  // pipeline (AGENT-LOOP-SUBAGENT.md §6.7.2 D3). Prefix includes a unique id: parallel child agents
   // with the same role stay independent and don't overwrite each other.
   // Format: role#id/  →  onToken("coder#2/writing..."), onToolCall("coder#2/read", args)
-  // Async id allocation (AGENT-LOOP.md §15 D-A1): reserve the relay counter at
+  // Async id allocation (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1): reserve the relay counter at
   // spawn time — the returned id must be stable while the item sits in the queue.
   // The [model] token (TUI block creation) is DEFERRED to actual start so queued
   // children don't paint an empty panel block ("queued 态不显示").

package/agent-tools/subagent.mjs

@@ -6,15 +6,15 @@
  * 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
  *（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
  *（async 分支 + 阻塞路径）原样保留于本文件；导出面由文末 re-export shim 兜住。
- * 2026-09-03 §19 合体轮: subagent_check/escalate 工具退役——status/escalate
+ * 2026-09-03 合体轮（AGENT-LOOP-SUBAGENT.md §6.7）: subagent_check/escalate 工具退役——status/escalate
  * 动作执行器并入 ./subagent-async.mjs，本文件只承载工具面（action schema）与
  * spawn 路径 + 动作分流。
- * 2026-09-06 §19.8 删 check 轮: check 动作删除——工具面五动作（spawn/status/
+ * 2026-09-06 删 check 轮（AGENT-LOOP-SUBAGENT.md §6.7.5）: check 动作删除——工具面五动作（spawn/status/
  * escalate/cancel/panel）——async 结果仅自动通道送达。
  * 2026-09-05 拆分轮: status/escalate/panel 动作执行器 → ./subagent-actions.mjs；§20
  * 调度器全套 → ./subagent-scheduler.mjs——本文件 import 源随之改写。
  * 2026-09-05 模块拆分轮（726 > 500 硬限）: spawn 前置 helpers（summarizeEngTaskBook/
- * effectiveSubagentModel/resolveDesignSlot）+ §20 准入（prepareScheduling）+ child
+ * effectiveSubagentModel/resolveDesignSlot）+ AGENT-LOOP-SUBAGENT.md §6.9 准入（prepareScheduling）+ child
  * 装配（buildSpawnChild）→ ./subagent-spawn.mjs；async 分支（executeAsyncSpawn）
  * → ./subagent-run.mjs——execute 只保留动作分流 + 装配调用 + 阻塞路径。
  */
@@ -33,6 +33,8 @@ import { executeStatusAction, executeEscalateAction, executePanelAction, execute
 import { prepareScheduling, buildSpawnChild, executeConsumeDesignAction } from "./subagent-spawn.mjs"
 import { executeAsyncSpawn } from "./subagent-run.mjs"
 import { ROUND_VALUES } from "./spawn-gates.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/subagent.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 // ─── SYNC-CANCEL 纯函数（可测——无 io）──────────────────────────────────────────
 
@@ -71,7 +73,7 @@ export function classifySyncAbort(ctxSignal, baseSignal, ctrlSignal, err) {
 export function armSyncChildAbort(parent, key, baseSignal, announce = null) {
   const ctrl = new AbortController()
   if (baseSignal) {
-    // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason（下游可判定「谁杀的」）
+    // AGENT-LOOP-SUBAGENT.md §6.12 站点 #10（第 24 批）：hop 逐跳保 reason（下游可判定「谁杀的」）
     if (baseSignal.aborted) ctrl.abort(baseSignal.reason)
     else baseSignal.addEventListener("abort", () => ctrl.abort(baseSignal.reason), { once: true })
   }
@@ -100,15 +102,15 @@ export function buildSyncStoppedReport(role, capturedOutput, designId) {
 }
 
 /**
- * subagent tool — ONE tool, EIGHT actions (AGENT-LOOP.md §19/§19.5/§19.6/§19.8 +
+ * subagent tool — ONE tool, EIGHT actions (AGENT-LOOP-SUBAGENT.md §6.7 +
  * SUBAGENT-OBSERVE-SEND): spawn (default) / status (non-blocking pool query) / observe
- * (inspect a running/queued/done async child's recent activity + current tool — §7.2) /
+ * (inspect a running/queued/done async child's recent activity + current tool — docs/cli/design/TUI.md §6.8) /
  * send (inject a direction into a RUNNING async child — consumed at its next turn
- * boundary as an ordinary instruction — §7.2) / escalate (飞刀 — hand implementation to
- * a stronger model) / cancel (stop ONE background subagent — §19.5) / panel (view + fix
- * the live subagent panel — §19.6) / consume-design (parent-side chain-terminal token
+ * boundary as an ordinary instruction — §6.8) / escalate (飞刀 — hand implementation to
+ * a stronger model) / cancel (stop ONE background subagent — AGENT-LOOP-SUBAGENT.md §6.7.2) / panel (view + fix
+ * the live subagent panel — AGENT-LOOP-SUBAGENT.md §6.7.2) / consume-design (parent-side chain-terminal token
  * consumption — ENGINEERING-MODE.md §2.6, 2026-09-07). The check
- * action was deleted (§19.8): async results reach the model only via the auto channel.
+ * action was deleted (AGENT-LOOP-SUBAGENT.md §6.7.5): async results reach the model only via the auto channel.
  * - action:"spawn" roles: "explore" — read-only tools, search/read/analyze
  *   (suitable for codebase exploration); "coder" — full tool set, self-contained
  *   implementation tasks; "plan" — read-only planning; "eng-coder" —
@@ -117,56 +119,34 @@ export function buildSyncStoppedReport(role, capturedOutput, designId) {
  * - no role specified — invalid by design since the 2026-08-25 fail-closed gate
  *   (role is mandatory; "no role → same tool set as parent" was removed with the
  *   coder-leak fix and the header text above predates it)
- * - non-recursive: child agents do not get the subagent tool (depth > 0 is not injected)
+ * - non-recursive for non-eng children: child agents do not get the subagent tool (depth > 0 is not
+ *   injected); eng-coder / eng-designer children get a spawn-only variant (`agent/family-tools.mjs`)
+ * - 描述文本单点 = `thincoder-core/tool-docs/subagent.md`（模型可见文本不在此复述——本块只留实现注记）
  */
 
 export const subagentTool = {
   name: "subagent",
-  description:
-    "ONE tool, EIGHT actions — pick by what you need:\n" +
-    "- action:'spawn' (DEFAULT): spawn a sub-agent to handle an independent subtask in an isolated context; the sub-agent returns only its final report. Spawn MULTIPLE subagents in the SAME response for parallel work—they run concurrently.\n" +
-    "- action:'status': NON-BLOCKING progress query — returns immediately and consumes nothing. Give the spawn's id for one child ({id, role, status: running|queued|done, model, elapsedSec, turn, maxTurns, position?), or omit it for an overview of the whole pool ({overview: {running: [{id, role, model, elapsedSec, turn, maxTurns}], queued: [{id, role, position}], done: [{id, role}]}}). Touched-files summary: running entries also carry touchedFiles (first 5, relative to your cwd), touchedMore (count beyond 5) and, when nothing was touched yet, the placeholder touched (\"—（尚无改动）\"); queued (not yet started) entries carry the placeholder touched (\"—（未启动）\") — see what a running child has changed BEFORE deciding to cancel it. Use THIS to see progress — it never blocks and never consumes a result (async results are delivered to you automatically). Background advisor reviews share this status surface: pass a review id and it answers in the same shape with role:'advisor' plus reviewType (design|code) / round / elapsedSec — and the overview lists reviews alongside subagents.\n" +
-    "- action:'observe': SEE what a running async subagent is DOING right now (progress vs stuck) — pass the spawn id. Returns {id, role, status, turn, maxTurns, touched…, currentTool? — array of tool name(s) currently executing (read from its dispatch state; omitted when none in flight — present when stuck in a long tool call), recentTurns: [last N one-line turn summaries, newest-first; default 5, parameterizable via recent]}. Readonly — observable on running/queued/done: running shows live activity, queued (not started) returns a placeholder, done (settled, report auto-delivered) returns the activity summary only — NOT the full report (that rides the auto channel; observe stays terse to keep your context lean). Use it to judge whether a long-running child is stuck vs progressing BEFORE deciding to cancel or steer it.\n" +
-    "- action:'send': STEER a running async subagent mid-flight — pass the spawn id + message (a direction like \"check X, don't fixate on Y\"). The message queues and the child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting — its current tool finishes first; its convergence/audit discipline is unchanged — injection is guidance, not a deviation waiver). Returns {id, status:'delivered', queued}. Only a RUNNING async subagent is targetable — sync (you're waiting on it, no relay), queued (not started), settled or unknown ids error clearly. If the child settles before its next turn boundary, its settle report carries an 'undelivered' note so you don't assume the guidance landed.\n" +
-    "- action:'escalate' (飞刀 — a flown-in expert): hand an implementation task to a STRONGER model from your consult models (agent.consultModels). It gets WRITE access and does the work itself — reads, edits, runs tests — then returns a post-op report (what changed, why, verification). Use it when YOU judge the task calls for stronger hands (complex multi-file refactoring, an intractable bug, intricate algorithm work — or work beyond your comfortable ability); escalate EARLY, not after burning attempts. model: pick a candidate as 'provider:model' (default = the first consult model). Not available in engineering mode (implementation goes through eng-coder spawns there). DEFAULT-ASYNC at depth 0: the launch returns an ack {id, role:'escalate', status:'running'} and the flight runs in the background (pooled with the other role-domain spawns) — its post-op report is delivered to you automatically with its mutations merged into your bookkeeping.\n" +
-    "- action:'cancel': STOP one background subagent — pass the id from the async spawn return (REQUIRED — omitting it errors; a blanket cancel is unsupported, Ctrl+C stops everything). Running target aborts immediately ({id, status:'cancelled'}); a queued target is removed from the queue ({id, status:'cancelled', was:'queued'} and later queue positions shift forward). Other children and the session keep running — cancellation is targeted. Use it when a background child is going the wrong way (e.g. burning turns) and you must stop it before its report arrives. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first; prefer scoped recovery (restore a single affected file) over killing the child — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews are cancelable on this same action: pass the review id — its controller aborts, no token is issued for a cancelled review.\n" +
-    "- action:'consume-design' (engineering mode, parent side — chain-terminal token consumption): after the delivery is verified and the chain closes out, consume this design's token slot — pass the designId (optional for a single-design session). The slot is consumed; a further spawn for the same designId is mechanically rejected, and any new work (including deviation fixes) requires a fresh design review and token. Idempotent: an unknown designId / already-consumed slot is a no-op notice, never an error. Do NOT call it while the chain is still open — fix rounds reuse the same slot (same designId + designToken).\n" +
-    "- action:'panel': DIAGNOSE + fix the subagent panel — the collapsible blocks under the conversation the user sees (CLI TUI panel mirror; headless/VS Code degrade to a 'no panel' pool view). view (default — call it with no params or view:true): returns the live panel blocks [{key, role, status: running|done|awaitingDigest} — running entries also carry elapsedSec; awaitingDigest entries whose report is ALREADY digested carry digested:true (stuck blocks — the freezable ones — explain odd panel states here)] exactly as the user sees them. freeze: pass the block key of a digested-stuck block ({action:'panel', freeze:'role#N'}) to reclaim it into the conversation — the freeze ONLY passes for awaitingDigest blocks with no live pool entry and no pending report (gated); freezing a block whose report is still pending would break the digestion order and is refused with a clear error.\n\n" +
-    "Why delegate? A sub-agent runs in its own isolated context — its reads, searches, tool calls and edits never enter your history or pollute your window; only its final report comes back. Delegation keeps your working context lean (you see the whole session, not the child's noise) and the child single-mindedly focused on one task. Parallel children run concurrently, saving wall-clock time. Every coder/eng-coder child carries its own verify + advisor self-review discipline — handed-off work is already verified before you read a word of it.\n\n" +
-    "Available roles (which roles are exposed depends on the active mode — see Mode filtering below):\n" +
-    "- explore — read-only search & analysis. Toolset: the read/search family (grep, read, glob, code_search, doc_search, repo_outline, lsp, tree...). No git context injected—evidence from read/glob/grep and the task book. Its report must list what it searched and what it did NOT find. Fast — specify thoroughness in the task: quick / medium / thorough (default medium).\n" +
-    "- plan — read-only implementation planning. Same read/search toolset; NEVER edits files. Returns a step-by-step plan for the parent to execute.\n" +
-    "- coder — full implementation. The parent's complete read/write/execute toolset plus verify and advisor for self-review. Its final report must include a delivery transparency table with one row per task requirement (Done / Simplified / Not done — no deferred column).\n" +
-    "- eng-coder — engineering-mode coder (available only in engineering mode, replacing coder). Same full toolset as coder plus the design-driven methodology overlay; REQUIRES a valid designToken arg obtained from a passed advisor(type='design') review. The advisor's Approved reply also echoes a designId — pass it as the designId arg: required to pick between designs when several approved reviews are active, optional for a single design. The delivery report echoes the designId back for the audit fix round. ALSO REQUIRES a batchDoc arg — the batch record path (docs/batches/<batch>-<topic>.md), the batch §2 task book this spawn implements: a spawn without it, or with a path that does not resolve to a readable file, is mechanically refused.\n" +
-    "- eng-designer — engineering-mode design writer (available only in engineering mode): the SOLE author of the requirements + design documents and of the batch record §2 (the batch task book) — revisions included. Writes no implementation code, does not edit prompt files, does not fire reviews, and needs NO designToken (its authorization is the confirmed requirements). It surveys on its own, but may only spawn read-only 'explore' children (sync, ≤6 per batch). ALSO REQUIRES a batchDoc arg — the batch record path (docs/batches/<batch>-<topic>.md); the same mechanical gate as eng-coder: a spawn without it, or with a path that does not resolve to a readable file, is mechanically refused.\n" +
-    "Mode filtering: normal mode exposes explore/plan/coder (eng-coder and eng-designer are refused); engineering mode exposes explore/eng-designer/eng-coder (plan and coder are refused — plan is a normal-mode role, coder is replaced by eng-coder). The role enum is filtered per mode at assembly, and the spawn gate refuses out-of-mode roles mechanically.\n\n" +
-    "Async spawn: pass async:true to spawn WITHOUT waiting — returns {id, role, status:\"running\"} immediately so you can keep working in your own turn (read/check files, run other tools) while the child runs in the background. The child's report is delivered to you automatically — there is no fetch action; use action:'status' only to see progress, never to wait for the result. Top-level spawns are ALWAYS async — never pass `async:false` at depth-0 (the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it). Inside subagents (depth>0) spawns are always synchronous (platform rule). Eng-coder's delivery protocol runs fully inside the child (implementation → audit → self-fix → advisor re-review → converged delivery). Async spawns are pooled per role domain: at most 4 concurrent eng-coders and 4 concurrent other-role spawns by default (agent.poolLimits overrides both) — a full domain queues further spawns with a position while the other domain keeps starting (domains never block each other), and top-level only. After an async spawn the turn winds down normally — nothing expects you to wait for it: the child runs in the background and its report is delivered to you automatically — before your next turn, or digested in the suspension session — so end the turn; do not poll or wait for the result.\n\n" +
-    "Task scheduling: declare the scheduling metadata to let the SCHEDULER order your spawns — files: the file paths this task will modify, dependsOn: ids from prior async spawn returns whose outcome this task needs. Overlapping-file tasks are serialized and dependent tasks are started in order automatically: a spawn that would conflict, or whose dependencies have not settled, queues instead of running ({id, status:\"queued\", position, reason} — the waiting task auto-starts when the conflict clears / its dependency settles; cancel a queued task to drop it). A spawn whose dependency was cancelled or failed stays queued and marked \"dependency cancelled\" until you decide (cancel it) — in an AUTO session it starts by itself. Referencing an unknown id errors; an id already consumed (auto-delivered by the auto channel) counts as satisfied. Omit both parameters for the plain immediate spawn (no scheduler involvement).\n\n" +
-    "Writing the prompt:\n" +
-    "- The sub-agent starts with zero context — it has not seen this conversation. Brief it like a colleague who just walked into the room: state the goal, list what you already know, hand over the specifics.\n" +
-    "- Put exact paths and commands in the prompt when you know them. The sub-agent should not search for things you already know.\n" +
-    "- Do not delegate understanding: if the task hinges on a file path or line number, find it yourself first and write it into the prompt.\n" +
-    "- Once a sub-agent is running, leave that scope to it: don't redo its searches in parallel, and don't abandon it midway to finish manually.",
+  description: DESC("subagent"),
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send"], description: "Which subagent-family action — spawn (default), status (non-blocking progress query — never consumes; async results arrive automatically — no fetch action), observe (inspect a running/queued/done async subagent's recent activity — recent turn summaries + current in-flight tool + turn/touched), send (inject a direction into a RUNNING async subagent, consumed at its next turn boundary as an ordinary instruction), escalate (飞刀 — hand implementation to a stronger consult model), cancel (stop ONE background subagent — pass its id; never omit), panel (view the live subagent panel / freeze a digested-stuck block), consume-design (engineering mode, parent side: chain-terminal token consumption — close out a design's token slot after the delivery is verified and the chain closes out, 2026-09-07). See the tool description for the full action matrix." },
-      view: { type: "boolean", description: "action:'panel' only: true (default) = return the live panel blocks (the mirror of what the user sees). false with no freeze = nothing to do — error. Mutually exclusive with freeze (freeze wins)." },
-      freeze: { type: "string", description: "action:'panel' only: block key of a digested-stuck awaitingDigest block (e.g. \"eng-coder#9\") to reclaim into the conversation via the gated done-freeze event. Refused when the block is running/done/unknown or its report is still pending digestion (would break the digestion order). Requires the CLI TUI panel mirror — headless/VS Code report the freeze unavailable." },
-      task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria). Not used by status." },
+      action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design; semantics per action in the tool description." },
+      view: { type: "boolean", description: "action:'panel' only: true (default) = the live panel blocks as the user sees them; false without freeze = error. Mutually exclusive with freeze (freeze wins)." },
+      freeze: { type: "string", description: "action:'panel' only: block key of a digested-stuck block — reclaims it into the conversation; refused for running/done/unknown blocks or a still-pending report; requires the CLI TUI panel mirror." },
+      task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria)." },
       context: { type: "string", description: "Optional background the sub-agent needs (it cannot see this conversation); action:'spawn' only." },
-      role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer"], description: "The sub-agent role — see the tool description for the role capability matrix. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
-      model: { type: "string", description: "action:'spawn': provider/model override for this sub-agent ('provider:model', a provider name, or a model name on the parent's provider — defaults to config.agent.subagentModels[role], then config.agent.subagentModel, then the parent's provider). pass \"default\" to explicitly inherit the default model — equivalent to omitting the parameter. action:'escalate': pick a consult candidate as 'provider:model' (default = the first consult model)." },
-      designToken: { type: "string", description: "Required when role='eng-coder': the token returned by advisor(type='design') after the design review passed. Without a valid token, eng-coder cannot modify files." },
-      designId: { type: "string", description: "Optional when role='eng-coder': the designId echoed with the approved token by advisor(type='design'). Required to pick between designs when several approved reviews are active in the session — each eng-coder carries its own designId+token pair so parallel implementations never overwrite each other. Optional for a single design. action:'consume-design': the design whose slot to close out — optional for a single-design session; required to pick when several approved designs are active (the consume gate refuses to guess)." },
-      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder' and role='eng-designer': the batch record path (docs/batches/<batch>-<topic>.md) — the batch §2 task book this spawn implements (or writes). The spawn is mechanically refused without it, and also when the path does not resolve (cwd-relative or absolute) to a readable file; the CONTENT is never validated (the batch record owns that). explore/plan/coder spawns ignore it." },
-      round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder' and role='eng-designer' (explore/plan/coder exempt — and advisor is review-only, never a spawn write role): the implementation round this spawn is — initial (first implementation round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default: a missing round is a dispatch defect and the spawn is mechanically refused." },
-      async: { type: "boolean", description: "action:'spawn': true = spawn without waiting — returns {id, status:\"running\"} immediately; the report is delivered to you automatically (there is no fetch action). Default: depth-0 → true (async — every role); depth>0 → sync (forced). action:'escalate': same semantics — default async at depth 0; async:false keeps the legacy synchronous flight (mechanism parameter — see the Async spawn section for top-level guidance)." },
-      files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares (cwd-relative or absolute paths). files must be file-level paths (one per file you will modify). Directory declarations are NOT supported — they bypass the conflict detector and are rejected with an error. Tasks with overlapping files are serialized automatically — a conflicting spawn queues ({id, status:\"queued\", position, reason}) instead of running concurrently and starts when the conflict clears. Omit to skip conflict detection (plain immediate spawn)." },
-      dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async spawn returns whose outcome this task needs — the task queues ({id, status:\"queued\", position, reason}) until every dependency settles, then starts automatically. Ids already consumed (auto-delivered to the model) count as satisfied; a dependency cancelled or failed leaves the task queued marked 'dependency cancelled' until you decide (cancel it — AUTO sessions auto-start). Unknown ids error." },
-      id: { type: "string", description: "action:'status'/'observe'/'send'/'cancel': the subagent id from the async spawn return. status: omit = overview of the whole pool; observe/send/cancel: REQUIRED (observe needs the child to inspect; send needs the target; never omit on cancel — a blanket cancel is unsupported)." },
-      message: { type: "string", description: "action:'send' only (REQUIRED there): the direction to inject — the running async subagent consumes it at its next turn boundary as an ordinary user instruction (non-interrupting; its convergence/audit discipline is unchanged — injection is guidance, not a deviation waiver)." },
-      recent: { type: "integer", description: "action:'observe' only (optional, default 5): how many recent-turn summaries to return (clamped 1..20 — N2 keeps observe terse)." },
+      role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer"], description: "The sub-agent role — see the role matrix in the tool description. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
+      model: { type: "string", description: "action:'spawn': provider/model override ('provider:model', a provider, or a model name on the parent's provider) — defaults config.agent.subagentModels[role] → config.agent.subagentModel → the parent's provider; \"default\" inherits. action:'escalate': a consult candidate (default = the first)." },
+      designToken: { type: "string", description: "Required when role='eng-coder': the token from advisor(type='design') after the review passed — without it, eng-coder cannot modify files." },
+      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the slot to close out (required to pick between several; the gate refuses to guess)." },
+      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (docs/batches/<batch>-<topic>.md) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated." },
+      round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder'/'eng-designer': initial (first round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default — missing = refused." },
+      async: { type: "boolean", description: "action:'spawn'/'escalate': default at depth 0 = true (async; the report arrives automatically); depth>0 always sync. async:false forces the blocking flight." },
+      files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares — file-level paths only (cwd-relative or absolute; directories rejected — they bypass the conflict detector). Overlapping-file tasks serialize automatically. Omit = no conflict detection." },
+      dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async returns whose outcome this task needs — queues until every dependency settles, then starts. Consumed ids count as satisfied; a cancelled/failed dependency stays queued marked 'dependency cancelled' until you decide (AUTO sessions auto-start). Unknown ids error." },
+      id: { type: "string", description: "action:'status'/'observe'/'send'/'cancel': the subagent id from the spawn return. status: omit = pool overview; observe/send/cancel: REQUIRED." },
+      message: { type: "string", description: "action:'send' only (REQUIRED there): the direction to inject — consumed by the running child at its next turn boundary as an ordinary instruction (non-interrupting)." },
+      recent: { type: "integer", description: "action:'observe' only (optional, default 5): how many recent-turn summaries (1..20)." },
     },
     required: [],
   },
@@ -174,20 +154,20 @@ export const subagentTool = {
   sideEffectExempt: true, // child agent may write files; parent can't introspect its _mutatedThisRun
   parallel: true,
   async execute(args, ctx) {
-    // §19 action dispatch: default spawn keeps every legacy call unchanged
+    // AGENT-LOOP-SUBAGENT.md §6.7 action dispatch: default spawn keeps every legacy call unchanged
     // (no action parameter → the spawn path below, byte-identical semantics).
     const action = args?.action !== undefined && args?.action !== null && String(args.action) !== ""
       ? String(args.action)
       : "spawn"
     if (action !== "spawn") {
-      // §19 restricted-variant action gate (round2 #3): the engineering-child channel
+      // AGENT-LOOP-SUBAGENT.md §6.7 restricted-variant action gate (round2 #3): the engineering-child channel
       // (depth>0, role eng-coder or eng-designer) is spawn-only — escalate spawns a
       // coder+WRITE child (violates explore-only intent) and status/panel/observe/send
       // have no async pool / panel mirror to query in a child context.
       if ((ctx.depth ?? 0) > 0 && (ctx.agent?._role === "eng-coder" || ctx.agent?._role === "eng-designer")) {
         throw new Error(`only action:'spawn' (sync explore children) is available inside an ${ctx.agent._role} — escalate/status/cancel/panel/consume-design/observe/send are not`)
       }
-      // §17 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn —
+      // AGENT-LOOP-ASYNC-POOL.md §6.8 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn —
       // async OR blocking — the digest must stay organize-only. The escalate
       // action spawns a write child too, so the same mechanical refusal applies
       // (AUTO tier exempt — user authorized unattended continuation).
@@ -196,14 +176,14 @@ export const subagentTool = {
       }
       if (action === "status") return executeStatusAction(args, ctx)
       if (action === "escalate") return await executeEscalateAction(args, ctx)
-      // §19.5 控制类动作：digest 内放行（D-S7 分类——控制/自省；dispatch 控制类
+      // AGENT-LOOP-SUBAGENT.md §6.7.2 控制类动作：digest 内放行（D-S7 分类——控制/自省；dispatch 控制类
       // 豁免同批生效——19.5.2b round2 #4；escalate 的 digest 拒绝在上一分支）
       if (action === "cancel") return executeCancelAction(args, ctx)
       // 2026-09-07 token 链终消费制（ENGINEERING-MODE.md §2.6 F1）：父侧核销消费——
       // 非只读控制动作——depth-0 + 工程模式限定（本分流已过受限变体门；工程模式门在
       // 执行器内）——planMode 拒绝（dispatch 不豁免）——不入批审批分组（dispatch 免审）。
       if (action === "consume-design") return executeConsumeDesignAction(args, ctx)
-      // §19.6 panel 动作：view（readonly 面——digest 内放行——自省类）与 freeze
+      // AGENT-LOOP-SUBAGENT.md §6.7.2 panel 动作：view（readonly 面——digest 内放行——自省类）与 freeze
       // （控制类——同 cancel——digest 内放行）。深度/门控检查在 executePanelAction 内。
       // CLI-ACTIVITY-DEBLOAT F-3（2026-09-10）接线：executePanelAction 经 ctx.state
       // （= agent._tuiState——startTUI 反向挂载）读时现算面板块（computePanelBlocks）——
@@ -239,7 +219,7 @@ export const subagentTool = {
     if (!ROLES.has(role)) {
       throw new Error(`Unknown subagent role: ${JSON.stringify(role)}. Valid roles: explore, plan, coder, eng-coder, eng-designer (exact spelling).`)
     }
-    // §18 D-E3 internal-spawn gate: an eng-coder sub-agent may only spawn sync
+    // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 internal-spawn gate: an eng-coder sub-agent may only spawn sync
     // explore (audit) children — non-explore roles and async are refused here
     // (mechanical), the audit budget is enforced (7th audit spawn refused), and
     // the returned attempt number marks this spawn as an audit for the task-book
@@ -263,7 +243,7 @@ export const subagentTool = {
       throw new Error("Engineering mode is not active — role='eng-designer' is engineering-mode only (it writes the requirements/design documents inside the engineering workflow); use role='explore' or role='plan' for read-only work.")
     }
 
-    // §17 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn — async
+    // AGENT-LOOP-ASYNC-POOL.md §6.8 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn — async
     // OR blocking — the digest must stay organize-only. AUTO tier (autoApprove) is
     // exempt (推进型 — user authorized unattended continuation). Mechanical refusal
     // so the digest never pops a permission panel or chains new background work.
@@ -300,7 +280,7 @@ export const subagentTool = {
         // stopped 折叠语义丢失：无 ⟦ev⟧stopped/无 STOPPED_MARK——块冻结标 done 而非
         // stopped——评审 🟡#2）。stopped 分支改抛 AbortError——runWithContinue 只捕
         // ContinueError——原样上抛 → 阻塞 catch 三分支②折叠（"child 随即在 abort 检出点
-        // 解绕折叠"——AGENT-LOOP §7.2 机制文）。abort 恒已在途（stopped 只由
+        // 解绕折叠"——AGENT-LOOP-SUBAGENT.md §6.7.2 机制文）。abort 恒已在途（stopped 只由
         // cancelSyncChild 与 ctrl.abort 同时置位）——信号语义真实。
         if (parent._syncChildAborts?.get(key)?.stopped) throw abortError(ctrl.signal, "settle", "sync-stopped")
         const go = await ctx.onPermissionRequest("continue", { turns: e.turn, agent: key })
@@ -348,14 +328,14 @@ export const subagentTool = {
       const cls = classifySyncAbort(ctx.signal, baseSignal, ctrl.signal, e)
       if (cls === "base") {
         // ① 整回合停（现状逐字保留——挂起场景 base 命中而 ctx.signal 未 abort——R2）：
-        // §27 R23：外层 abort 传播的中断——内层开块随之外层冻结前先收尾定格
+        // docs/cli/design/TUI.md §6.8.2 R23：外层 abort 传播的中断——内层开块随之外层冻结前先收尾定格
         // （D-R23c1 stopped——T-R23c.2a 生成侧路径；TUI 冻结兜底仍在 freezeSubTaskLines）
         emitNestedChildEvent(ctx, relayPrefix, "stopped")
         throw e // 用户停——不落错误事件
       }
       if (cls === "error") {
         // ③ 其他错误（现状逐字保留——:249-253）：
-        // §27 R23 error-run 映射（实现批补一行）：run 错误（非 abort）→ 同样发 stopped
+        // §6.8.2 R23 error-run 映射（实现批补一行）：run 错误（非 abort）→ 同样发 stopped
         // ——内层子块定格不悬空（T-R23a.3——工具错/运行错误路径）。
         emitNestedChildEvent(ctx, relayPrefix, "stopped")
         logEvent("child:error", { role, id: child._logId, ms: Date.now() - blockT0, err: errText(deathLine(e, ctrl?.signal), 200) })
@@ -370,7 +350,7 @@ export const subagentTool = {
       // 块冻结标 stopped（R6——非 done）：⏹ 定向中止的 TUI 顶层块立即定格 stopped
       // （async settle cancelled 分支同款直发——async-settle.mjs settleAsyncEntry）；
       // 嵌套（eng-coder 内 explore 审计）经 emitNestedChildEvent 定格子块——stopped
-      // 幂等无害（重复/迟到 done 由 §27.1 F2 done 子块定格丢弃兜底）。
+      // 幂等无害（重复/迟到 done 由 docs/cli/design/TUI.md §6.8.2 F2 done 子块定格丢弃兜底）。
       ctx.callbacks?.onToken?.(`${relayPrefix}⟦ev⟧stopped\x1e0\x1e0\x1estopped\x1e`)
       emitNestedChildEvent(ctx, relayPrefix, "stopped")
     } finally {
@@ -378,7 +358,7 @@ export const subagentTool = {
       // 口径 = 成功/折叠/整回合停——错误③ 同样 rethrow 经 finally——同归本注销）
       disarm()
     }
-    // §27 R23 D-R23c1（评审 #1 🅰——生成侧补发射）：sync spawn 同步收尾——若本 spawn
+    // §6.8.2 R23 D-R23c1（评审 #1 🅰——生成侧补发射）：sync spawn 同步收尾——若本 spawn
     // 处于嵌套上下文（ctx.callbacks 已是嵌套 wrapper——eng-coder 内 explore 审计）→
     // 发内层 ⟦ev⟧done（完整嵌套前缀——wrapper 链自动补外层）→ 主 TUI 路由子块定格
     // （T-R23c.1）。非嵌套（depth-0）零变化——冻结仍由 dispatch subKey 精确冻承接。
@@ -386,7 +366,7 @@ export const subagentTool = {
     // 冻结管线复用——迟到 done 对已定格 stopped 块被丢弃——幂等无害）。
     emitNestedChildEvent(ctx, relayPrefix, "done")
     logEvent("child:done", { role, id: child._logId, ms: Date.now() - blockT0, kind: String(pipelineReport).includes(TURN_CAP_MARK) || String(pipelineReport).includes(STOPPED_MARK) ? "partial" : "ok" })
-    // §7.2.3 sync spawn 完成精确冻结（方案 e）：execute 返回前 ctx 留子代理 key
+    // docs/cli/design/TUI.md §6.8 sync spawn 完成精确冻结（方案 e）：execute 返回前 ctx 留子代理 key
     // （relayPrefix 去尾 = `role#N`）——dispatch runOne 读它作 onToolResult 第 4 参 →
     // TUI finishSubTaskKey 按 key 精确冻（async eng-coder 先启动时不再误冻其块——
     // T-F2）。仅成功/折叠路径设置：async 分支不设（round2 #2——ack 带 status:running 由
@@ -397,7 +377,7 @@ export const subagentTool = {
   },
 }
 
-// Re-export shim (2026-09-03 拆分轮 + §19 合体轮 + 2026-09-05 拆分轮): 机械与动作
+// Re-export shim (2026-09-03 拆分轮 + 合体轮 + 2026-09-05 拆分轮): 机械与动作
 // 执行器迁至 ./subagent-async.mjs、./subagent-actions.mjs、./subagent-scheduler.mjs
 // ——本文件保留导出面，消费点（agent.mjs / agent-turn.mjs / consult.mjs / 测试）导入
 // 路径零改动；池逻辑/准入见 subagent-run.mjs（executeAsyncSpawn）与 subagent-scheduler.mjs

package/agent-tools/task.mjs

@@ -1,5 +1,6 @@
 // F-CC4（CONTEXT-COMPACTION.md §6.16.5）：task 列表变更 ⇒ 方向转换轻推（本档只调用；文案/去重单源 = agent-tools/context.mjs）
 import { pushContextNudge } from "./context.mjs"
+import { DESC } from "../tools/shared.mjs"
 
 /** Common synonyms LLMs tend to use — normalize to canonical values */
 const STATUS_ALIASES = {
@@ -26,18 +27,11 @@ function normalizeStatus(raw) {
 
 /**
  * task tool: multi-step task planning and progress tracking (Claude Code's todo mode).
- * Each call replaces the entire list; only modifies agent internal state (no external world), so readonly.
- * Accesses the caller agent via ctx.agent (injected by runAgent).
+ * 描述面 = `tool-docs/task.md`（DESC() 加载）；仅改 agent 内部状态（readonly）；ctx.agent 由 runAgent 注入。
  */
 export const taskTool = {
   name: "task",
-  description:
-    "Plan and track a task list for complex multi-step work. Each call replaces the entire list. " +
-    "Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial. " +
-    "Statuses: pending | in_progress | done — synonyms (completed/finished/complete, todo/open/waiting, active/running/working, …) are accepted and normalized with a warning. " +
-    "IMPORTANT: title is required and must be a non-empty string — items with empty titles are silently dropped. " +
-    "For cross-session / project-level tracking, use `/ledger`. " +
-    "Returns the updated task list (or the new item's ID on add).",
+  description: DESC("task"),
   parameters: {
     type: "object",
     properties: {

package/agent-tools/timer.mjs

@@ -1,18 +1,13 @@
+import { TIMER_MAX_PENDING } from "../agent/timers.mjs"
+import { DESC } from "../tools/shared.mjs"
+
 /**
  * timer tool: set a time budget for thinking before the agent insists on action.
- * Call this when starting to analyze code or debug — it gives a bounded
- * thinking window. When the timer fires, a system reminder is injected
- * suggesting the model try running code, adding logs, or otherwise acting
- * instead of continuing to think.
+ * 描述面 = `tool-docs/timer.md`（DESC() 加载；机制 = AGENT-LOOP-ASYNC-POOL.md §6.30.3 D-TW8）。
  */
 export const timerTool = {
   name: "timer",
-  description:
-    "Set a timer before you start analyzing code. When the timer fires, " +
-    "a system reminder will be injected suggesting you try running code or " +
-    "adding debug logs. Use this to enforce a thinking budget: you get " +
-    "N seconds to reason, then the timer reminds you to act. " +
-    "Returns the set confirmation — the reminder fires at the deadline.",
+  description: DESC("timer"),
   parameters: {
     type: "object",
     properties: {
@@ -38,8 +33,13 @@ export const timerTool = {
     const expiresAt = Date.now() + seconds * 1000
     const message = args.message || `⏰ Time's up (${seconds}s). Have you tried running the code, adding a console.log, or checking the output? Thinking more without data is guessing.`
 
-    ctx.agent._pendingTimers = ctx.agent._pendingTimers ?? []
-    ctx.agent._pendingTimers.push({ id: Date.now(), expiresAt, message })
+    // §6.30.3 门三件②（D-TW6）：在途帽 8——超限显式拒（不静默丢 / 不静默清；形态先例 = 队满
+    // 「拒 + 提示 + 保留」）。拒点时在途表零变动（本次不推入）。
+    const pending = (ctx.agent._pendingTimers = ctx.agent._pendingTimers ?? [])
+    if (pending.length >= TIMER_MAX_PENDING) {
+      throw new Error(`timer: ${pending.length} timers already pending (max ${TIMER_MAX_PENDING}) — wait for one to fire before setting another`)
+    }
+    pending.push({ id: Date.now(), expiresAt, message })
 
     return `Timer set for ${seconds} seconds. A reminder will appear when time is up.`
   },