@thincoder/core 0.9.5 → 0.10.1

package/agent-tools/consult.mjs

@@ -1,7 +1,7 @@
 /**
  * consult.mjs — multi-model consultation ("会诊", docs/design/CONSULTATION.md). CLI port.
  *
- * Two tools (AGENT-LOOP.md §25 D-R17a — R17, 2026-09-06): consult_start
+ * Two tools (CONSULTATION.md §6.3 — R17, 2026-09-06): consult_start
  * (non-blocking spawn) / consult_stop (cancel a running session). consult_check
  * was RETIRED with the digest auto-injection: the mechanism does ZERO judging —
  * when every model of a session settles (pending 0), the session moves to the
@@ -19,8 +19,9 @@
  * prefix `consult#<childRelayN>/` (one per consultant child — the shared subagent
  * relay channel; the child relay number is NOT the session id — sessions key
  * their own `_consultIdCounter`), not onSubagent/onToolPanel.
- * Each child settles its own TUI block with a ⟦ev⟧done event at settle (R17 —
- * the old in-turn check consumption is gone).
+ * Each child settles its own TUI block with a ⟦ev⟧settled event at settle (consult
+ * 同族收齐批 · #748; a cancelled session's children emit ⟦ev⟧stopped — R17: the old
+ * in-turn check consumption is gone; consumed blocks archive at the consumption window).
  */
 import { createAgent, runAgent, readonlyToolNames, excludeSubagentTools } from "../agent.mjs"
 import { resolveChildProvider } from "./subagent.mjs"
@@ -29,11 +30,15 @@ import { offloadToolResult, escapeXml } from "../agent/helpers.mjs"
 import { logEvent, errText } from "../log.mjs"
 import { deathLine } from "../abort-provenance.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
-// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+// TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口常量（单源——store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 // ASYNC-RESULT-CONTAINER.md D2/D3/D6：pending 单容器停靠 + settle 公共收尾 + child signal 单点
 import { bindChildController, buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
-import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs" // B5（群 B 批 §22 D-DG2）：digest 注入预算单源
+import { registerTurnCapCheckpoint } from "./checkpoint.mjs"
+import { drainInjectedQueue } from "./subagent-run.mjs"
+import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs" // B5（群 B 批 AGENT-LOOP.md §6.14 D-DG2）：digest 注入预算单源
+// #15 描述外置：描述文本单点 = tool-docs/{consult_start,consult_stop,main_history}.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 // Named consult defaults (consult P2, 2026-08-30).
 const CONSULT_TIMEOUT_MS = 600_000 // default consult lifecycle timeout
@@ -83,11 +88,7 @@ export function makeMainHistoryTool(parentAgent) {
   return {
     name: "main_history",
     readonly: true,
-    description:
-      "Read the main agent's conversation history — what has been tried, the exact errors, recent context. " +
-      "Use it to ground your analysis in the actual failure trail instead of guessing.\n" +
-      "Parameters:\n" +
-      "- limit: Number of recent messages to return (default 20, max 100)",
+    description: DESC("main_history"),
     parameters: {
       type: "object",
       properties: { limit: { type: "number", description: "Recent messages (default 20, max 100)" } },
@@ -132,7 +133,7 @@ export function makeMainHistoryTool(parentAgent) {
 }
 
 /**
- * Full-session settle routing (R17 — AGENT-LOOP.md §25 D-R17a): a session whose
+ * Full-session settle routing (R17 — CONSULTATION.md §6.2): a session whose
  * pending count reached 0 has no more replies coming — the session leaves
  * `_consultSessions` and, unless it was cancelled (consult_stop / turn-end
  * abort), moves into the pending single container (`_pendingAsyncResults` +role
@@ -144,8 +145,8 @@ export function makeMainHistoryTool(parentAgent) {
  * is woken (settle-event parity with the async pools) so an idle settle still
  * triggers the digestion round (T-R17j).
  * D3：公共收尾统一走 settleAsyncEntry 共享 helper（四族同机制）——consult 族参数：
- * 无池（会话池无条目——settle 即出池）、无 ctx（无 TUI 冻结事件——子块各自 settle 时
- * 已冻结）、无 onAccounting；helper 按 role "consult" 恒停靠 pending（非挂起期也停靠）。
+ * 无池（会话池无条目——settle 即出池）、无 ctx（无 TUI 冻结事件——子块由消费窗三端
+ * 收口——#748）、无 onAccounting；helper 按 role "consult" 恒停靠 pending（非挂起期也停靠）。
  * Cancelled sessions produce no digest (T-R17c).
  */
 function sessionSettled(agent, session) {
@@ -156,6 +157,7 @@ function sessionSettled(agent, session) {
     role: "consult",
     report: composeConsultDigest(session),
     error: null, done: true, status: "done", cancelled: false,
+    childIds: [...(session.childIds ?? [])], // #748：随 settle 携子块映射表（消费窗三端展开同源）
     relayPrefix: null, startedAt: null, _settle: null, _settleSeq: 0,
   }
   settleAsyncEntry(agent, entry, { pool: null, ctx: null })
@@ -183,7 +185,7 @@ export function composeConsultDigest(session) {
  */
 export async function injectConsultResult(agent, entry) {
   const full = String(entry?.report ?? "(no consultation result)")
-  // §22 D-DG3（群 B 批 B5）：计入预算的 raw = 报告正文（标签行不计）——首行标签拆出；超限
+  // §6.14 D-DG3（群 B 批 B5）：计入预算的 raw = 报告正文（标签行不计）——首行标签拆出；超限
   // 路径保留族标签行（与 VSC 镜像同形）；落盘内容 = raw（与其余三族同口径）。
   const at = full.indexOf("\n")
   const label = at === -1 ? "" : full.slice(0, at + 1)
@@ -197,7 +199,11 @@ export async function injectConsultResult(agent, entry) {
   })
 }
 
-function settleChild(agent, session, id, label, ok, payload, emitDone) {
+/** Per-child settle 路由（consult 同族收齐批 · 2026-09-30 · 台账 #748）：settle 一律发
+ *  `⟦ev⟧settled`（区块驻留「done · awaiting digestion」——冻结 ∥ 归档落消费窗，三端补发面同源）；
+ *  取消径（会话 stopped——consult_stop ∥ cleanup）⇒ `⟦ev⟧stopped` 即折（消费永不来——与四族取消面同判）。
+ *  无块子块（relayPrefix 缺省——spawn 前失败，从未开块）零发射；测试缝 = 最小导出接桩（会话桩直调）。 */
+export function settleChild(agent, session, id, label, ok, payload, relayPrefix, emit) {
   if (ok) {
     session.received++
     session.replies.push({ model: label, reply: payload })
@@ -208,7 +214,10 @@ function settleChild(agent, session, id, label, ok, payload, emitDone) {
     session.replies.push({ model: label, reply: `(consultation failed: ${payload})`, failed: true })
   }
   session.pending--
-  emitDone?.() // per-child TUI block freeze at settle (R17 — child's activity card is done)
+  if (relayPrefix) {
+    const kind = session.stopped ? "stopped" : "settled" // 块发射两态（消费面口径 = AGENT-LOOP-ASYNC-POOL.md §6.8）
+    emit?.(`${relayPrefix}⟦ev⟧${kind}\x1e0\x1e0\x1e${kind}\x1e`)
+  }
   if (session.pending === 0) sessionSettled(agent, session)
 }
 
@@ -219,7 +228,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   const armWatchdog = () => {
     const t = setTimeout(() => {
       timedOut = true
-      // §20.3 站点 #12 信号面（第 24 批）：watchdog 中止带 timeout reason
+      // AGENT-LOOP-SUBAGENT.md §6.12 站点 #12 信号面（第 24 批）：watchdog 中止带 timeout reason
       try { ctrl.abort({ abortTrigger: "timeout", abortDetail: "consult-watchdog" }) } catch { /* already settled */ }
     }, timeoutMs)
     t.unref?.()
@@ -243,11 +252,9 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     else logEvent("child:error", { ...base, err: errText(payload, 200) })
   }
   // R17: relay prefix assigned before the child runner arms — the per-child TUI
-  // block freeze emits only when a block actually exists (relay established).
+  // block event emits only when a block actually exists (relay established).
   let relayPrefix = null
-  const settle = (ok, payload) => settleChild(agent, session, id, label, ok, payload, relayPrefix
-    ? () => ctx.callbacks?.onToken?.(`${relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
-    : null)
+  const settle = (ok, payload) => settleChild(agent, session, id, label, ok, payload, relayPrefix, ctx.callbacks?.onToken)
   try {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
@@ -282,16 +289,22 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       // role "consult" (overlay + base would concatenate it twice).
       role: "consult",
     })
-    // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）——consult 会话跨回合驻留，
+    // TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口（四处创建点同置）——consult 会话跨回合驻留，
     // 不置窗则 _fullHistory 仍无界（F-O1 覆盖 depth>0 全部创建点）
     child._historyWindow = RECORD_WINDOW_MESSAGES
+    // SUBAGENT-UPSTREAM-CHANNEL 补赋（TURN-CAP-CONTINUE.md §3.1）：会诊 = 后台族（consult_start
+    // 发后即返）⇒ 父在飞可答——撞帽检查点的上行 ask 与 notify_parent 同源通道。
+    child._upstream = { parent: agent, label, sync: false }
 
-    // Activity relay via the unified spawn-child pipeline (§7.2 D3): `consult#<subId>/`
+    // Activity relay via the unified spawn-child pipeline (docs/cli/design/TUI.md §6.8 D3): `consult#<subId>/`
     // prefix (same channel subagent uses — parallel consultants stay independent) +
     // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
     relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
     // LOGGING：arm（spawn 事件——relay 建立后；子内事件归属 _logId）
     childLogId = relayPrefix.slice(0, -1)
+    // #748：会话自持 `childIds`（= 子块 relay 号——块键形 `consult#<N>` 的 N）；无块子块不入表
+    // （relayPrefix 缺省 = spawn 前失败——从未开块）。消费窗三端按该表逐子块展开（同源）。
+    session.childIds.push(childLogId.slice(childLogId.lastIndexOf("#") + 1))
     child._logId = childLogId
     logT0 = Date.now()
     logArmed = true
@@ -300,24 +313,29 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     let declined = false // review #1: guard against double-settle when onDeclined fired
 
     // Turn-cap continue loop (TURN-CAP-CONTINUE.md) via runWithContinue (§7.2 D3): hitting
-    // the cap asks the user via the SAME y/n panel the main agent uses — unlimited
-    // continues, each with a fresh turn budget AND a re-armed wall-clock watchdog (a
-    // continue is a fresh budget, the clock restarts too). Parallel consultants serialize
-    // their prompts through a session-level queue. Declined / headless → failed reply
-    // (partial diagnosis).
+    // the cap reports to the PARENT agent through the turn-cap checkpoint — the user y/n
+    // card is gone (F8; see the askContinue hook below). Each grant = a fresh turn budget
+    // AND a re-armed wall-clock watchdog (a continue is a fresh budget, the clock restarts
+    // too). Parallel consultants serialize their prompts through a session-level queue.
+    // Declined / headless → failed reply (partial diagnosis).
     const runner = ctx.runAgent ?? runAgent
     try {
       const result = await runWithContinue(
         (childAgent, input, cbs, opts) => runner(childAgent, input, cbs, opts),
         child, "# Problem\n" + problem,
         childCallbacks,
-        { depth: 1, maxTurns: agent?.config?.agent?.consultTurns ?? CONSULT_TURNS, signal: ctrl.signal },
         {
+          depth: 1, maxTurns: agent?.config?.agent?.consultTurns ?? CONSULT_TURNS, signal: ctrl.signal,
+          // send 注入队列回合边界消费（缺口补配——续段文本落 rec.child._injected 后由此消费）。
+          consumeInjected: (ag) => { drainInjectedQueue(child, ag ?? child) },
+        },
+        {
+          // F8（TURN-CAP-CONTINUE.md §1 #7 / #5）：撞帽 ⇒ 报请父代理（检查点）——不再弹
+          // continue 卡；报请串行在会话级 `continueQueue` 上（唯一会话级队列消费者）。
+          // 续期 ⇒ 新段预算 + watchdog 重挂（N3）。headless 亦登记（答复通道 = 父 send，
+          // 非权限 handler——§2.5 用例 13）。
           askContinue: (e) => {
-            if (!ctx.onPermissionRequest) return Promise.resolve(false)
-            // 残环批（2026-09-16）：归属键形态（`consult#<relayN>`——端侧键形解析的输入契约；
-            // 原 label = 显示名不携 id）；relay 未建立（spawn 前失败路径不可达此 ask）时回落 label。
-            const ask = () => ctx.onPermissionRequest("continue", { turns: e.turn, agent: relayPrefix ? relayPrefix.slice(0, -1) : label })
+            const ask = () => registerTurnCapCheckpoint(child, session, { turn: e.turn, signal: ctrl.signal })
             session.continueQueue = (session.continueQueue ?? Promise.resolve()).then(ask, ask)
             return session.continueQueue.then((go) => {
               if (go) {
@@ -381,24 +399,12 @@ export const consultStartTool = {
   name: "consult_start",
   readonly: false,
   sideEffectExempt: true,
-  description:
-    "Start a parallel multi-model consultation (会诊) for a hard problem you are stuck on (repeated failures, no headway). " +
-    "Call it directly when the user asks for 会诊 / consult — an explicit user request applies even if you are not 'stuck'. " +
-    "Several configured models (agent.consultModels) analyze the same problem INDEPENDENTLY and in parallel. " +
-    "Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns. " +
-    "When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system " +
-    "reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion " +
-    "yourself with your own tools (opinions are suggestions, not gates). To stop a session early (user changed their " +
-    "mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.\n" +
-    "Parameters:\n" +
-    "- problem (required): a brief — the symptom, what you already tried (failure trail), and entry-point files. " +
-    "Do NOT paste raw error logs; consultants pull the main session history themselves via their main_history tool.\n" +
-    "- models (optional): subset of agent.consultModels to run — an array of \"provider:model\", bare provider, or bare model names (case-insensitive). Omit to run all.",
+  description: DESC("consult_start"),
   parameters: {
     type: "object",
     properties: {
       problem: { type: "string", description: "Problem brief (symptom + failure trail + entry files)" },
-      models: { type: "array", items: { type: "string" }, description: 'Optional subset of agent.consultModels to run (default: all). Each entry is "provider:model", a bare provider name, or a bare model name (case-insensitive).' },
+      models: { type: "array", items: { type: "string" }, description: 'Optional subset of agent.consultModels to run (default: all) — each entry "provider:model", a bare provider, or a bare model name (case-insensitive).' },
     },
     required: ["problem"],
   },
@@ -419,7 +425,7 @@ export const consultStartTool = {
     agent._consultSessions ??= new Map()
     const id = String((agent._consultIdCounter = (agent._consultIdCounter ?? 0) + 1))
     const session = {
-      id, controllers: [], replies: [], pending: 0,
+      id, controllers: [], replies: [], childIds: [], pending: 0,
       failed: 0, terminated: 0, stopped: false, received: 0, total: run.length,
       models: run.map(consultLabel),
     }
@@ -445,13 +451,7 @@ export const consultStopTool = {
   name: "consult_stop",
   readonly: false,
   sideEffectExempt: true,
-  description:
-    "Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. " +
-    "Aborts every consultant that is still running; a stopped session delivers NO digest (R17 — its already-collected partial replies are dropped). " +
-    "Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.\n" +
-    "Returns JSON {abandoned: <pending count>, cancelled: true} — or {error: \"unknown consult id\"} (already finished/cancelled).\n" +
-    "Parameters:\n" +
-    "- id (required): the consult id from consult_start",
+  description: DESC("consult_stop"),
   parameters: {
     type: "object",
     properties: {
@@ -464,7 +464,7 @@ export const consultStopTool = {
     if (!s) return JSON.stringify({ error: "unknown consult id" })
     const abandoned = s.pending
     s.stopped = true
-    // §20.3 站点 #11（第 24 批）：会话级停 = stop
+    // §6.12 站点 #11（第 24 批）：会话级停 = stop
     for (const c of s.controllers) { try { c.abort({ abortTrigger: "stop", abortDetail: "consult-stop" }) } catch { /* already settled */ } }
     return JSON.stringify({ abandoned, cancelled: true })
   },

package/agent-tools/context.mjs

@@ -1,13 +1,15 @@
 /**
  * agent-tools/context.mjs — `context` 工具（CONTEXT-COMPACTION.md §6.16 · context-tool 批 2026-09-21）。
  * 单一工具三操作（用户定形 F-CC5）：`stats`（感知 F-CC1）· `prune`（噪声清理 F-CC3）· `compact`（主动压缩 F-CC2，携 focus + 自动附任务/目标 + 可回查锚——裁令 A/D）。
- * 内联 description（**不新增 tool-docs 档**——24 档族计数零动）；装配面 = 登记册 `agent-tools.mjs`（#83）+ `agent/family-tools.mjs` 的 depth-0 段（`depthOnly`）——两端自动同表；**depth>0 不给**（§6.16.6）。
+ * 描述外置（tool-docs/context.md——#15 统一面：文本单点 = tool-docs，DESC 加载）；装配面 = 登记册 `agent-tools.mjs`（#83）+ `agent/family-tools.mjs` 的 depth-0 段（`depthOnly`）——两端自动同表；**depth>0 不给**（§6.16.6）。
  * 本档同时是**注记文案 / 轻推行 / 回执文案的单源**（核与 VSC 的 run-stages 消费点经动态 import 取用——零新增静态边）。
  * 机械面：`stats` 不新增第三口径（阈值取本回合判定值；百分比走 `historyPercent` 与状态行同式）；`prune` = 合格集（`token-window.mjs` 单源）+「原位换内容」应用面（`context.mjs`）；`compact` **当次零执行**（只登记 `agent._pendingCompact`，由下一安全点消费——§6.16.2）。
  */
 import { contextUsage, estimateTokens, collectStaleToolOutputs, historyPercent, PRUNE_MIN_TOKENS } from "../token-window.mjs"
 import { pruneStaleToolOutputs, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
 import { slotPath } from "../session-slots.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/context.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 /** 轻推行前缀（单活体去重判据——§6.16.5「同前缀旧行先滤」）。 */
 export const CONTEXT_NUDGE_PREFIX = "[System reminder: task/goal changed —"
@@ -125,25 +127,7 @@ function compactReceipt(agent, focus, replaced) {
 
 export const contextTool = {
   name: "context",
-  description:
-    "Manage your own context window — see how full it is, drop stale tool output, or compact the earlier " +
-    "conversation into a summary at a moment of your own choosing.\n" +
-    "- action='stats': current usage — total vs the compaction threshold, per-segment shares, and how much " +
-    "is prunable / reclaimable.\n" +
-    "- action='prune': drop the CONTENT of stale tool results (older than the protected tail) and replace it " +
-    "with a short stub — tool pairing stays intact, the session record keeps the full text, and the tool can " +
-    "simply be re-run.\n" +
-    "- action='compact': compact the earlier conversation now, with 'focus' — write what the UPCOMING work " +
-    "needs (1–3 sentences: the goal, the files, the constraints that must survive). The summary is written to " +
-    "serve that focus; the current task list and goal are attached automatically. It runs at the next safe " +
-    "point (before the next request — never mid-exchange) through the same machine as the automatic " +
-    "compaction: same summary chain, same panel, same failure chain (3 consecutive failures degrade to a " +
-    "deterministic truncation). The receipt carries this session's record path, so nothing is lost for good.\n" +
-    "Nothing here runs on its own — the automatic threshold compaction stays in place as a fallback; whether " +
-    "to compact is your call. Errors come back as 'Error: ...' and change nothing.\n" +
-    "Parameters:\n" +
-    "- action (required): stats | prune | compact\n" +
-    "- focus (required for compact): what the upcoming work needs — the summary is weighted toward it",
+  description: DESC("context"),
   parameters: {
     type: "object",
     properties: {

package/agent-tools/design-token.mjs

@@ -23,7 +23,7 @@ export function buildApprovedSuffix(designToken, designId, slotCount) {
   return `Approved. Pass this exact token to eng-coder (designToken parameter): ${designToken}\ndesignId: ${designId} (pass as the designId parameter when spawning eng-coder — optional while this session holds a single design; ${slotCount} approved design slot(s) held as of this approval, and the count may have changed since — with several designs the spawn gate refuses a missing designId and lists the held ids)`
 }
 
-/** F2e (§29.1): strip the engine-generated Approved suffix from a report before
+/** F2e: strip the engine-generated Approved suffix from a report before
  *  it becomes a prior — the suffix is deterministic (buildApprovedSuffix), so the
  *  truncation is exact; a text not ending in it passes through untouched. */
 export function stripApprovedSuffix(text, suffix) {
@@ -83,7 +83,7 @@ export function settleDesignReview(agent, run, designToken, rawResult, opts = {}
   if (!designToken || typeof rawResult !== "string") {
     return { passed: false, output: rawResult ?? "" }
   }
-  // A（F11/§14.3 消费点 1）：未完成即不签发——判据与 code 完成守卫同源（单谓词）。
+  // A（F11/ADVISOR-GUARDS.md §1 消费点 1）：未完成即不签发——判据与 code 完成守卫同源（单谓词）。
   const incomplete = opts?.incomplete ?? null
   if (incomplete) {
     const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
@@ -107,7 +107,7 @@ export function settleDesignReview(agent, run, designToken, rawResult, opts = {}
   if (agent._role === "eng-coder") agent._engDesignReviewed = true
   run.open = false // approval closes this doc-set instance — next review is fresh
   const clean = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
-  // F2c (§29.1): id echo + omission guidance + point-in-time slot snapshot — the
+  // F2c: id echo + omission guidance + point-in-time slot snapshot — the
   // same suffix the F2e prior stores strip with (stored for the exact truncation).
   run.approvedSuffix = buildApprovedSuffix(designToken, run.designId, agent._engDesignTokens.size)
   return {

package/agent-tools/digest-budget.mjs

@@ -1,5 +1,5 @@
 /**
- * digest-budget.mjs — digest 注入批量预算单源（群 B 批 B5——AGENT-LOOP.md §22 语义源）。
+ * digest-budget.mjs — digest 注入批量预算单源（群 B 批 B5——AGENT-LOOP.md §6.14 语义源）。
  * 原预算块居 subagent-async.mjs（只覆盖经 injectAsyncResult 的三族：subagent / advisor /
  * escalate），consult 族注入器（injectConsultResult）绕过 ⇒ 多族条目同轮合并注入时可累计
  * 超限（BATCH-3-STRUCTURE F-2 原始事故面 1.3MB 请求体）。本档把常量 / 判超 / 记账 / 落盘

package/agent-tools/eng.mjs

@@ -18,6 +18,8 @@ import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
 import { clearPlanMode } from "./plan.mjs"
 import { purgeExpiredDesignTokens } from "../token-ttl.mjs"
 import { resolveEngineeringManifest } from "../manifest.mjs"
+// 描述面 = `tool-docs/eng.md`（#15 描述外置统一——DESC 单一解析面，与内置工具族同径）
+import { DESC } from "../tools/shared.mjs"
 
 // ─── 持久化镜像 / 面板提示注入缝（#91——「写盘镜像 / 面板提示按端注入」，形态参 §2.13.5 注入缝）──
 /**
@@ -41,9 +43,7 @@ async function mirrorNotice(enabled, ctx) {
 
 export const engTool = {
   name: "eng",
-  description:
-    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. " +
-    "Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).",
+  description: DESC("eng"),
   parameters: {
     type: "object",
     properties: {
@@ -59,7 +59,7 @@ export const engTool = {
       // R16 (F-R16a): OFF 不清 token——有效 token 跨模式存活（设计评审过的产物不因
       // 开关重复烧）。过期清理跑在另外三处（恢复过滤 / 开模式 / spawn 门禁拒）。
       ctx.agent._advisorRound = 0          // reset convergence budget
-      ctx.agent._advisorRuns = new Map()   // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._advisorRuns = new Map()   // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._touchedFiles = []         // clear mutation tracking
       ctx.agent._lastEngState = false
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
@@ -90,7 +90,7 @@ export const engTool = {
       // R16 (F-R16b ②): off→on 不重评——只清过期 token（用户裁定"打开工程模式时
       // 应该清理"），有效 token 原样保留——遍历 Map 删过期，返回文案含清理个数。
       const cleared = purgeExpiredDesignTokens(ctx.agent)
-      ctx.agent._advisorRuns = new Map() // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._advisorRuns = new Map() // §6.10 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._lastEngState = true
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_ON_REMINDER)

package/agent-tools/escalate-async.mjs

@@ -1,5 +1,5 @@
 /**
- * escalate-async.mjs — async 飞刀 runner (AGENT-LOOP.md §25 D-R17b — R17, 2026-09-06).
+ * escalate-async.mjs — async 飞刀 runner (ESCALATE.md §5 — R17, 2026-09-06).
  *
  * The subagent action:"escalate" is DEFAULT-async at depth 0 (decision ③: the
  * depth-0-only escalate flips to async like every other background family;
@@ -27,7 +27,7 @@
 import { relative, isAbsolute } from "node:path"
 import { runAgent, createAgent, DEFAULT_SUBAGENT_TURNS, excludeSubagentTools } from "../agent.mjs"
 import { runWithContinue, TURN_CAP_MARK, wrapChildCallbacks } from "../agent/spawn-child.mjs"
-// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+// TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口常量（单源——store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { logEvent } from "../log.mjs"
 import { deathLine } from "../abort-provenance.mjs"
@@ -38,6 +38,8 @@ import { refreshQueuedTokens, nextSubagentId, consumeSubagentToken, assertPoolKe
 import { mutationSeqOf } from "./advisor-async.mjs"
 // ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
 import { bindChildController, buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+import { registerTurnCapCheckpoint } from "./checkpoint.mjs"
+import { drainInjectedQueue } from "./subagent-run.mjs"
 
 /** Parent-side mutations (absolute paths) committed AFTER the escalate launch —
  *  the overlap scan feeds the settle classification (review #4/round2 #4: the
@@ -90,7 +92,7 @@ function touchedFilesNote(child, cwd) {
 }
 
 /**
- * Async escalate settle — three-way classification (§25 D-R17b review #4):
+ * Async escalate settle — three-way classification (ESCALATE.md §5 D-R17b review #4):
  *  - done: merge ALL mutations (the escalation's changes are the parent's —
  *    verify/advisor guards must see them) + overlap warning into the report
  *    (report-level hint — not a gate — round2 #4);
@@ -104,7 +106,7 @@ function touchedFilesNote(child, cwd) {
  */
 export function classifyEscalateSettle(parent, entry) {
   if (entry.cancelled) return { cancelled: true }
-  // §23.3.1（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
+  // AGENT-LOOP.md §6.15（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
   // merge）与 status/observe 摘要的读取源；**消化注入完成后由 `releaseSettledEntry`
   // （async-settle.mjs）置 null**（池内未消化窗口不释放——表 2 候选 2 否决）。
   const child = entry.childAgent
@@ -148,7 +150,7 @@ export function launchEscalateAsync(parent, ctx, launch) {
   const { task, provider, tag, effortNote } = launch
   parent._asyncSubagents ??= new Map()
   parent._asyncQueue ??= []
-  // Async id allocation (AGENT-LOOP.md §15 D-A1 precedent): reserve the relay
+  // Async id allocation (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1 precedent): reserve the relay
   // counter at launch — the returned id stays stable while the entry sits queued.
   // The [model] token (TUI block creation) is DEFERRED to actual start so queued
   // flights don't paint an empty panel block (subagent-parity).
@@ -161,7 +163,7 @@ export function launchEscalateAsync(parent, ctx, launch) {
   const relayPrefix = `escalate#${id}/`
   const entry = {
     id, role: "escalate", relayPrefix,
-    _pool: poolDomainOf("escalate"), // other — shares the domain with explore/plan/coder (§11.1 D-24a)
+    _pool: poolDomainOf("escalate"), // other — shares the domain with explore/plan/coder (AGENT-LOOP-ASYNC-POOL.md §6.10 D-24a)
     status: "queued",
     position: undefined,
     report: null, error: null, done: false, cancelled: false,
@@ -200,7 +202,7 @@ export function launchEscalateAsync(parent, ctx, launch) {
       role: "coder",
     })
     entry.childAgent = child // settle 分类/status touched 摘要绑定（start 时刻）
-    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）
+    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口（四处创建点同置）
     child._logId = relayPrefix.slice(0, -1)
     // SUBAGENT-UPSTREAM-CHANNEL（§6.27.4 W3——escalate **async**：工具返回注走异步形）。
     child._upstream = { parent, label: relayPrefix.slice(0, -1), sync: false }
@@ -224,6 +226,9 @@ export function launchEscalateAsync(parent, ctx, launch) {
       signal: entry.controller.signal,
       // §2.5 #78 并入：escalate 子代理输出流式（VSC subagent-escalate-async 同款豁免）。
       streamOutput: true,
+      // SUBAGENT-OBSERVE-SEND 缺口补配（TURN-CAP-CONTINUE.md §3.1 :85）：send 注入队列
+      // 回合边界消费（否则续段文本静默丢弃）。空队列 no-op。
+      consumeInjected: (ag) => { drainInjectedQueue(entry, ag ?? child) },
     }
     // 权限按 async 子代理同款装配：AUTO 直放行；手动档经父 _permQueue（并行子代理
     // 审批不叠弹窗）——背景飞行撞门时无 handler → denied 不悬挂（D-S7 同规则）。
@@ -242,9 +247,9 @@ export function launchEscalateAsync(parent, ctx, launch) {
       { ...childCallbacks, onPermissionRequest: childPermission },
       runOpts,
       {
-        // 后台飞行不弹 continue 面板（D-A3 §15 例外同款）：AUTO && engineering 自动
-        // resume——escalate 只在 normal 模式可用（engineering 拒）——恒自动拒 → partial。
-        askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
+        // F8（TURN-CAP-CONTINUE.md §1 #7）：撞帽 ⇒ 父代理检查点（同池、同载具——send 兑现 /
+        // cancel 走既有 abort ⇒ partial + TURN_CAP_MARK）；原 AUTO 自动 resume 由 #7 取代。
+        askContinue: (e) => registerTurnCapCheckpoint(child, entry, { turn: e.turn, signal: entry.controller.signal }),
         onDeclined: (e, output) => `escalate (${tag})${entry.effortNote} ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`,
       },
     )
@@ -265,7 +270,7 @@ export function launchEscalateAsync(parent, ctx, launch) {
         // 运行失败/中止：错误文本落 entry.error（子代理同款——cancel 分支忽略它；
         // Ctrl+I 中止的残条目由收尾消化带错误文本——不落空 "(no report)" digest）。
         const child = entry.childAgent
-        // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+        // AGENT-LOOP-SUBAGENT.md §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
         entry.error = `escalate (${tag}) error: ${deathLine(e, entry.controller?.signal)}\nPartial output: ${(child?._capturedOutput ?? "").slice(0, 2000)}`
       })
       .finally(() => {

package/agent-tools/goal.mjs

@@ -1,21 +1,14 @@
 // F-CC4（CONTEXT-COMPACTION.md §6.16.5）：goal 任一状态变更 ⇒ 方向转换轻推（本档只调用；文案/去重单源 = agent-tools/context.mjs）
 import { pushContextNudge } from "./context.mjs"
+import { DESC } from "../tools/shared.mjs"
 
 /**
  * goal tool: lifecycle management for long-running autonomous goals (completion contract).
- * Three states: active / complete / blocked. Completion must pass a verify evidence threshold;
- * blocked is only accepted after the same condition persists 3 consecutive times.
- * The system injects status + budget progress + audit discipline every turn.
+ * 描述面 = `tool-docs/goal.md`（DESC() 加载）；完成阈 / 阻塞计次 / 每回合注入 = execute 内实现注。
  */
 export const goalTool = {
   name: "goal",
-  description:
-    "Manage a long-running autonomous goal. " +
-    "action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort). " +
-    "action='complete': mark achieved — only after the criterion's check has actually passed. " +
-    "action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts. " +
-    "action='cancel': abandon the goal. " +
-    "Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.",
+  description: DESC("goal"),
   parameters: {
     type: "object",
     properties: {

package/agent-tools/panel-blocks.mjs

@@ -8,14 +8,14 @@
  *
  * 现算面板块列表（state.subTasks 活值纯推导——无时点快照语义）。
  * status 三态映射：done+awaitingDigest → "awaitingDigest"；done → "done"；
- * queued（waiting/等位未启动）→ "queued"；其余 → "running"（§20 D-SD3b queued 态入镜口径保留）。
+ * queued（waiting/等位未启动）→ "queued"；其余 → "running"（AGENT-LOOP-SUBAGENT.md §6.9 D-SD3b queued 态入镜口径保留）。
  */
 export function computePanelBlocks(state) {
   const subs = state?.subTasks
   if (!subs) return null // 未挂载（headless/mock 无 TUI state）——无面板
   const blocks = []
   for (const sub of Object.values(subs)) {
-    // §20 D-SD3b：waiting/等位块（sub.queued——未启动）以 queued 态入镜（视图与面板
+    // AGENT-LOOP-SUBAGENT.md §6.9 D-SD3b：waiting/等位块（sub.queued——未启动）以 queued 态入镜（视图与面板
     // 所见一致——action:'panel' 视图 + freeze 门控读此态）。
     const status = sub.done ? (sub.awaitingDigest ? "awaitingDigest" : "done") : (sub.queued ? "queued" : "running")
     blocks.push({ key: sub.key, role: sub.role ?? null, status, startedAt: sub.started ?? Date.now() })

package/agent-tools/parent-channel.mjs

@@ -43,6 +43,8 @@ import { carrierField, getAsyncPool, tombstoneOf, wakeAsyncWaiters } from "./asy
 import { pushReal } from "../context.mjs"
 import { escapeXml } from "../agent/helpers.mjs"
 import { logEvent } from "../log.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/notify_parent.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 /** message 长度上限（字符——闸三上界）。 */
 export const UPSTREAM_MSG_MAX = 1500
@@ -180,19 +182,7 @@ export function drainChildUpstream(agent) {
  */
 export const parentChannelTool = {
   name: "notify_parent",
-  description:
-    "A one-way channel to your PARENT (the agent that spawned you) — you are a subagent, so there is no user to ask.\n" +
-    "Queue a message on the parent's side; your turn is not interrupted and nothing is consumed from it.\n" +
-    "- kind:'ask' — a question whose answer changes your next step and that you cannot answer from the materials you can read\n" +
-    "  (task book / design doc / repo). The parent replies with subagent action:'send'; you receive it as an ordinary\n" +
-    "  instruction at your next turn boundary. One ask at a time while the previous one is still waiting in the parent's queue.\n" +
-    "- kind:'note' — an FYI that needs no answer (a premise you found broken, a conflict you resolved and want visible early).\n" +
-    "- NON-BLOCKING: the call returns immediately. Keep working on the unaffected parts; keep the affected part pending.\n" +
-    "  There is no fetch and no waiting — if you finish first, report the unanswered part as not done (never idle, never poll).\n" +
-    "- SYNCHRONOUS SPAWN: if the parent is blocked on your run (sync spawn), nothing can be sent back to you — the reply path (`send`) reaches only a RUNNING ASYNC child. The message is read when the parent's call returns (it may re-spawn you with an answer); report the unanswered part as not done.\n" +
-    "- Out of scope: naming / implementation / wording details, anything a read or a command would answer, trade-offs the\n" +
-    "  task book already states. When in doubt use the stop-and-report discipline — this is not an escape from your own judgment.\n" +
-    "- Availability: subagents only (depth > 0). At depth 0 you talk to the user through your normal reply or the question tool.",
+  description: DESC("notify_parent"),
   parameters: {
     type: "object",
     properties: {

package/agent-tools/plan.mjs

@@ -1,12 +1,12 @@
 /**
  * plan tool: enter/exit plan mode.
- * In plan mode only read-only tools are allowed — explore code, design solutions, no code writing.
- * Exit plan mode to present the plan for the user's approval; implement only after they approve.
+ * 描述面 = `tool-docs/plan.md`（DESC() 加载）。
  *
  * Reminder cadence (kimi-code style): while plan mode is active the agent loop
  * re-injects reminders — sparse every 2 turns, full every 5 turns or when the
  * user sends a new message — so the constraint never fades from context.
  */
+import { DESC } from "../tools/shared.mjs"
 
 const PLAN_FULL_REMINDER =
   "[System reminder: plan mode is ON. Workflow: (1) explore/read codebase with read-only tools, " +
@@ -88,8 +88,7 @@ export function planReminderForTurn(agent, userMessageSince) {
 
 export const planTool = {
   name: "plan",
-  description:
-    "Enter or exit plan mode. In plan mode you are restricted to READ-ONLY tools: read files, search code, run read-only shell commands. Use plan mode before complex multi-step tasks — explore the codebase, design the architecture, present a plan to the user. Exit plan mode to present the plan for the user's approval; implement only after they approve. For simple single-file edits, skip plan mode and just make the change.",
+  description: DESC("plan"),
   parameters: {
     type: "object",
     properties: {