thincoder 0.12.49 → 0.12.51

package/CHANGELOG.md

@@ -1,6 +1,49 @@
-# Changelog
+## [0.12.51] — 2026-08-30
 
-本文件记录 ThinCoder CLI 的发布历史。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，版本遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+### Added
+
+- **折叠系统大修（0.12.7 单框化的终章）**：公共折叠组件 `src/tui/fold-block.mjs`（147→168 行）——所有可折叠区块（思考/工具/子agent/advisor/长消息/连续 dim）统一：折叠态 = 命名头 + tail 3 行；展开态 = 空行 + ▼ 控制行 + 60% 屏幕封顶（触顶时底部第二个 ▼ 控制行必在视口内）。主输出（C.text）**永不折叠**；思考**无条件折叠**（阈值思路三次真机失败后废弃）；工具摘要（C.dim）>12 行折叠。`/fold off` 全关
+- **工具调用单框化**：`_toolBlock` 载体——头 = `❯ name 参数摘要 · running|耗时·摘要`，体 = 参数 pretty JSON + 流式输出 + 结果（dim）。旧四段式（标题/_live 滚动/done 行）废除
+- **会话文件瘦身（deepseek 会诊方案，`slimForDisplay`）**：写入时人读线截断（tool args 300 字符 / tool 结果 500 / 多模态图剥 base64 只留 text part），机读线（contextHistory）一字不动（provider 前缀缓存/配对/多轮看图零风险）；copy-on-write 绝不原地改（两线共享对象引用）；VS Code 端同款
+- **会诊（consult）体验修复**：consult_check/consult_stop 新增递增 `n` 参数（连续调用参数集不同，绕开循环检测器误报）；会诊结束**会话级结算**（finishSubTasksByRole 全量冻结 N 块，单块 finishSubTask 曾留 N-1 个 running 幽灵）；单条回复按 model 精确收尾（尾段归一化——`[model]` 裸名 vs `r.model` provider:model 曾是死代码）；冻结墓碑防 abort 尾部 token 复活块
+- **终端尺寸单源（`dims.mjs`）**：Windows ConPTY 的 columns/rows 不稳定（启动 falsy、输出活动期报 stale 小值）——sample-and-hold 缓存 + 事件驱动采样（启动收敛重试/resize/空闲看门狗/turn-start/turn-finally），渲染路径纯读缓存；非对称接受（变大立即提交、变小需连续两次确认）
+- **主输出呼吸空行**：主输出段前后各空一行（渲染期插入，不写 state.lines）；streaming 与落盘路径一致（首版漏 streaming 分支，用户实测"生成时不空落盘后才空"）
+- **任务面板顶部分隔线** + **子agent 运行区块段首分隔线**（`─` dim，与上方会话区切分；小终端压缩时 task 分隔线先让位）
+- **会诊四轮**：P0（搜索缓存键/中断清扫/tool_call_id 贯穿）、P1（死代码/缓存维度/增量行数/restore 守卫/foldKey 稳定化）、P3（multimodal flag 驱动 offload/日志截断/事件语法单源）——第三轮会诊（ConPTY）与窄屏真根因（组件漏传 cols）分别独立成条
+
+### Fixed
+
+- **流式窄屏真根因**：`renderExpandedBlock`/`renderFoldedHead` 三处调用漏传 `cols` → 组件按默认 80 wrap（280 列终端"生成中左边一小块、落盘后宽"）；全文扫尾 + 组件 cols 纪律入文档
+- **窄屏误诊链清理**：ConPTY 采样不再每帧 refresh（输出活动期 stale 80 污染缓存）；启动收敛跑满窗口（sawValid 曾提前掐断）；turn-start/turn-finally 采样点
+- **会诊残留双根因**：finishSubTask 单块语义（N-1 幽灵 + interrupted 误标）+ 无墓碑（迟到 token 复活块）
+- **subagent/escalate/advisor 成功调用误标 "(interrupted)"**（settleToolBlock 收尾）；Ctrl+I 中断时 tool_calls 悬空（合成占位 tool 结果，strict provider 400）；main 输出空行 streaming 路径缺失
+- **搜索高亮被缓存吃掉**（convCacheKey 补 search 维度）；[model] token 后头部不刷新（subSig 补 model）；并行同名工具输出/耗时错配（toolCallId 贯穿）
+- **generate-title proxy 路径 bug**（动态 import 相对路径从 src/ 解析到仓库根——静默 ERR_MODULE_NOT_FOUND 被 catch 吞，代理用户标题自创建起失效；静态导入 + 测试缝）
+
+### Changed
+
+- **agent.mjs 拆分**：工具结果提交/记账抽 `src/agent/record-results.mjs`（多模态延迟注入、FILE_MUTATORS 失效链、touchedFiles + reindex）；`_maxTurns` 引用 DEFAULT_MAX_TURNS；escalate 删手写 onToken/output（runWithContinue 统一 capture）；AUTO_REMINDER/ensureAutoReminder 单源（helpers）；魔法数字具名（tool-events caps / consult 默认值）；事件语法分支列表单源（EVENT_PHASE/EVENT_TYPE）
+- **行语法统一**：三个行生产者（live flushStream / 恢复 historyToLines / 注入行）统一打 `_kind` 标记（thinking/text/tool），buildConvLines 读标记不再从颜色猜
+- **live/restore 逐行对齐**：同一载体、同一渲染路径；恢复结果守卫与 live 共享（`slimToolResultForDisplay`：read_image base64 剥离 + 400 行封顶）
+- **折叠 key 稳定化**：工具块 fold key 用行级 `_lineId`（loadOlder unshift 不再错绑展开态）
+- **文档同步**：TUI.md / TUI-TOOL-OUTPUT.md / CONSULTATION.md / SESSION.md / AGENT-LOOP.md 与今日全部机制更新对齐
+
+### Tests
+
+- 812 全量（今日新增：折叠组件、dims 单源（sampler 注入 + 守卫 grep 断言）、会诊残留/精确收尾/墓碑、streaming 空行路径、subagent 分隔线、中断配对、工具块 ids、会话瘦身等 30+ 用例）
+- 会诊四轮评审全部落地并回归锁定：P0/P1/P3 + ConPTY 硬度 + ByModel 生产格式（自洽世界假绿被二次会诊实锤后改用生产报文断言）
+
+
+
+### Changed
+
+- **engineering 与 advisor.guard 改为会话级（跨端污染修复）**：旧设计里 engineering 只存 config.json 全局（`agent.engineering`），CLI `/eng` 与 VS Code 面板都写它 → 两端互相翻转对方的工程模式（"VS Code 工程模式下模型仍委托 role='coder'"）。现事实源是当前会话槽位文件（`engineering` 字段 + `advisor.guard`），config.json 降为 CLI 兼容/可见性镜像（双写保留：slot 先、config 后，slot 失败不阻断）。改动：`/eng` toggle 双写 slot（`cmd-eng.mjs` persistEngineering）；`/advisor` guard 切换双写 slot（`cmd-advisor.mjs` persistGuard，model/thinking 仍 config-scoped）；`saveSession`/`applySession` 往返 slot 值（无字段旧槽位回退 config，兼容锁定）；启动恢复链 `bin/thincoder.mjs` applySession 时 slot 覆盖 config 播种值。权威文档：`docs/design/ENGINEERING-MODE.md` §5 重写
+- **METHODOLOGY 三缺口修复**（核对工程模式提示词时发现）：① 需求文档三层结构（总目标/功能用户故事/非功能标准）落地进 METHODOLOGY.md 与 methodology-template.md——engineering.md 的 "three layers per METHODOLOGY" 引用此前悬空；② engineering.md 交付评审补测试文档口径（METHODOLOGY 存在时每条用户故事须有测试用例覆盖正常/边界/异常，无覆盖=评审不通过）——与三文档硬流程对齐；③ METHODOLOGY.md 缺失警告点名后果（引用悬空+硬流程失效+恢复路径），不再静默降级
+- **工程模式 UI/交互决策全链路落档**（用户报告"agent 无视讨论过的 UI 设计"）：设计文档要素扩项——涉及界面时必须收录与用户达成的每条 UI/交互决策（布局/流程/控件行为/状态反馈），未定标 open 不静默发明；eng-coder 任务书必须复述这些决策（或指向设计文档具体章节）——子代理零上下文，留在聊天里的决策永远到不了它；`eng-coder.md` 执行侧闭合——缺失的界面决策停下报告，不自行发明。两端 prompts byte-identical；`ENGINEERING-MODE.md` §7 变更记录
+
+### Tests
+
+- 新增 `test/session-eng-advisor.test.mjs`：/eng 双写断言（slot+config）、applySession slot 恢复（true/false/显式 false 压过 config true）、旧槽位无字段回退 config 锁定、saveSession 每 turn 往返、/advisor guard 双写（model 等仍 config-scoped）
 
 ## [0.12.49] — 2026-08-29
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.49",
+  "version": "0.12.51",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",
@@ -31,9 +31,10 @@
     "url": "git+https://github.com/xinbo-tech/thincoder.git"
   },
   "scripts": {
-    "test": "node --test \"test/*.mjs\"",
+    "test": "node --test \"test/*.test.mjs\"",
     "prepublishOnly": "npm run lint && node --test \"test/*.mjs\"",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "test:full": "node test/run-full.mjs"
   },
   "author": "liwei <liwei@51marine.com> (上海新舶)",
   "license": "MIT",

package/src/acp/bridge.mjs

@@ -70,6 +70,10 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
       // Strip the subagent `[model]` metadata token (role#id/[model]<name>) — it's a
       // TUI/webview display signal, not conversation content, and must not reach ACP clients.
       if (/^[\w-]+#\d+\/\[model\]/.test(text)) return
+      // D7 (AGENT-LOOP.md §7.2): strip ⟦ev⟧ event tokens (bare or prefixed variants) —
+      // they carry RS control characters and are a TUI display signal; structured ACP
+      // mapping (tool_call_update) is tracked separately in docs/TODO.md.
+      if (/^(?:[\w-]+#\d+\/)?⟦ev⟧(?:turn|approval)\x1e/.test(text)) return
       update("agent_message_chunk", { content: { type: "text", text } })
     },
     onReasoning: (text) => update("agent_thought_chunk", { content: { type: "text", text } }),

package/src/agent/dispatch.mjs

@@ -27,7 +27,7 @@ function logToolError(toolName, args, error) {
     const entry = [
       `time: ${now.toISOString()}`,
       `tool: ${toolName}`,
-      `args: ${JSON.stringify(args, null, 2)}`,
+      `args: ${JSON.stringify(args, null, 2).slice(0, 2000)}${JSON.stringify(args, null, 2).length > 2000 ? "… (truncated)" : ""}`,
       `error: ${error?.message ?? String(error)}`,
       error?.stack ? `stack:\n${error.stack}` : "",
     ].filter(Boolean).join("\n") + "\n"
@@ -111,7 +111,16 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       const allowed = agent.autoApprove
         ? true
         : callbacks.onPermissionRequest
-          ? await callbacks.onPermissionRequest(toolCall.name, args)
+          ? await (async () => {
+              // D2 (AGENT-LOOP.md §7.2): announce the wait BEFORE prompting — the TUI
+              // subagent block header flips to "等待审批" so a waiting child is visibly
+              // different from a stalled one. Depth>0 only (the parent TUI shows its own
+              // permission panel). turn n/max = the child's live turn counters.
+              if (depth > 0) {
+                callbacks.onToken?.(`⟦ev⟧approval\x1e${agent._currentTurn ?? 0}\x1e${agent._maxTurns ?? 0}\x1eapproval\x1e${String(toolCall.name).slice(0, 40)}`)
+              }
+              return await callbacks.onPermissionRequest(toolCall.name, args)
+            })()
           : false
       if (!allowed) {
         prepared.push({ toolCall, tool, denied: true, reason: callbacks.onPermissionRequest ? "denied by user" : "no permission handler" })
@@ -127,7 +136,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
 
     // Panel area abolished — all tools now stream inline via onToolOutput.
 
-    callbacks.onToolCall?.(toolCall.name, args)
+    callbacks.onToolCall?.(toolCall.name, args, toolCall.id)
 
     prepared.push({ toolCall, tool, args })
   }
@@ -157,7 +166,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       if (callbacks.toolRouter) {
         const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
         if (routed?.handled) {
-          callbacks.onToolResult?.(item.toolCall.name, routed.result)
+          callbacks.onToolResult?.(item.toolCall.name, routed.result, item.toolCall.id)
           return { ...item, result: routed.result, ok: true }
         }
       }
@@ -167,14 +176,17 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         depth,
         signal,
         callbacks,
-        onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk),
+        onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk, item.toolCall.id),
         onQuestion: callbacks.onQuestion,
         onPermissionRequest: callbacks.onPermissionRequest,
       })
       if (rawResult === undefined) throw new Error(`Tool "${item.toolCall.name}" returned undefined — all tools must return a string value`)
       const raw = String(rawResult)
-      const result = item.toolCall.name === "read_image" ? raw : await offloadToolResult(raw, item.toolCall.id)
-      callbacks.onToolResult?.(item.toolCall.name, result)
+      // Multimodal tools keep the raw result (base64 images ride the multimodal
+    // channel); everything else offloads oversized text to disk. Flag-driven, not
+    // name-driven (consult P3, 2026-08-30).
+    const result = item.tool?.multimodal ? raw : await offloadToolResult(raw, item.toolCall.id)
+      callbacks.onToolResult?.(item.toolCall.name, result, item.toolCall.id)
       // PostToolUse hooks: fire-and-forget (result not awaited on hook failure)
       runHooks("PostToolUse", { agent, toolName: item.toolCall.name, toolArgs: item.args, result: raw }).catch(() => {})
       return { ...item, result, ok: true }

package/src/agent/helpers.mjs

@@ -8,6 +8,18 @@ import { writeFile, mkdir, readdir, stat, unlink } from "node:fs/promises"
 import { join } from "node:path"
 import { execSync } from "node:child_process"
 
+/** Single source for the AUTO-mode reminder (was duplicated in agent.mjs +
+ *  setup.mjs — consult P2, 2026-08-30). */
+export const AUTO_REMINDER = "[System reminder: AUTO mode is active — all tool calls are automatically approved without asking.]"
+
+/** Inject the AUTO reminder once per history (both call sites used the same
+ *  literal + guard — consolidated here). */
+export function ensureAutoReminder(agent) {
+  if (agent.autoApprove && !agent.history.some((m) => m.content === AUTO_REMINDER)) {
+    agent.history.push({ role: "user", content: AUTO_REMINDER })
+  }
+}
+
 export const DEFAULT_MAX_TURNS = 200
 export const DEFAULT_SUBAGENT_TURNS = 100
 export const DEFAULT_GOAL_TURNS = 200

package/src/agent/record-results.mjs

@@ -0,0 +1,130 @@
+/**
+ * record-results.mjs — tool result commit + mutation accounting (split from
+ * agent.mjs 2026-08-30, consult P2: the 100-line loop was pure bookkeeping
+ * mixed into the run loop; it now lives behind one call).
+ *
+ * Contract (moved verbatim from the run loop):
+ *  - Multimodal tool results ({ text, images }) close the tool pairing with a
+ *    tool message, then inject the images as a multimodal user message — but
+ *    NEVER between tool messages of parallel calls (strict providers 400 when
+ *    a tool message does not immediately follow its assistant tool_calls), so
+ *    image injections are DEFERRED until all results are committed.
+ *  - Non-vision models get a text-only System-reminder instead of image parts
+ *    (image parts 400 on every subsequent request — defense-in-depth).
+ *  - FILE_MUTATORS invalidate advisor/verify state (code changed → prior
+ *    review/verify is stale); non-mutating side-effect tools (bash/git)
+ *    invalidate verify only (user decision 2026-08-08: reviews trigger on
+ *    code mutations, not environment changes).
+ *  - advisor calls always advance _advisorRound (convergence budget counts
+ *    attempts, not successes).
+ *  - Mutations feed _touchedFiles and fire-and-forget memory reindex.
+ */
+import { pushReal } from "../context.mjs"
+import { specForModel } from "../config.mjs"
+import { FILE_MUTATORS } from "./helpers.mjs"
+import { join } from "node:path"
+
+let _reindexFile = null
+
+export async function recordToolResults(agent, toolByName, results) {
+  // Multimodal user messages (injected images / not-injected reminders) must NOT be pushed
+  // between tool results of parallel calls — strict providers (DeepSeek) 400 when a tool
+  // message does not immediately follow its assistant tool_calls. Defer to after the loop.
+  // real: image injections are real messages (pushReal → _fullHistory); reminders stay machine-only.
+  const deferredUserMsgs = []
+
+  for (const { toolCall, result, ok } of results) {
+    const tool = toolByName.get(toolCall.name)
+    // Multimodal tools return JSON { text, images } — inject as multimodal user message
+    if (tool?.multimodal && ok) {
+      try {
+        const parsed = JSON.parse(result)
+        if (parsed.images?.length) {
+          // tool message first — closes the tool_call pairing (OpenAI API requires tool result immediately after assistant with tool_calls)
+          pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: parsed.text })
+          if (specForModel(agent.provider.model).multimodal) {
+            // then inject multimodal user message with base64 images for the model to actually "see" them on the next turn
+            deferredUserMsgs.push({
+              real: true,
+              msg: {
+                role: "user",
+                content: [{ type: "text", text: parsed.text }, ...parsed.images],
+              },
+            })
+          } else {
+            // Non-vision model: image parts must never enter history — text-only APIs 400 on them on EVERY
+            // subsequent request, poisoning the conversation. (read_image itself already refuses; this is defense-in-depth.)
+            deferredUserMsgs.push({
+              real: false,
+              msg: {
+                role: "user",
+                content: `[System reminder: the image returned by ${toolCall.name} was NOT injected — model ${agent.provider.model} does not support image input. Do not call ${toolCall.name} again under this provider; verify visual output programmatically instead.]`,
+              },
+            })
+          }
+          continue
+        }
+      } catch { /* Parse failure doesn't affect normal tool messages */ }
+    }
+    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: result })
+    if (tool && ok) {
+      if (FILE_MUTATORS.has(toolCall.name)) {
+        // Direct file edit — code was changed. The prior advisor review and
+        // verify are stale: a review that ran before the edit no longer
+        // covers the current file state.
+        agent._mutatedThisRun = true
+        agent._calledAdvisorThisRun = false
+        agent._verifiedThisRun = false
+        agent._verifyPassed = undefined
+      } else if (!tool.readonly && !tool.sideEffectExempt) {
+        // Non-mutating side-effect tools (bash, git): do NOT invalidate the
+        // advisor review — a review is triggered by CODE MUTATIONS only
+        // (user decision 2026-08-08: the guard rule is "review after code
+        // changes", not "review after any environment change"; bash is
+        // barred from writing files, so it cannot change the reviewed code).
+        // Verify IS invalidated: its state snapshot (git diff, file list)
+        // may be stale after git/shell operations.
+        if (agent._verifiedThisRun) {
+          agent._verifiedThisRun = false
+          agent._verifyPassed = undefined
+        }
+      }
+      if (toolCall.name === "verify") agent._verifiedThisRun = true
+      if (toolCall.name === "advisor") {
+        agent._calledAdvisorThisRun = true
+        // All advisor calls (code and design) share the 5-round convergence
+        // budget — each advances _advisorRound toward MAX_ADVISOR_ROUNDS.
+        // Always advance the round — the convergence protocol cares about
+        // how many reviews have run (round 1→2→3→4→5), not how many succeeded.
+        // A failed/interrupted review is still a review attempt and should use
+        // the next round's prompt on retry.
+        agent._advisorRound++
+      }
+      if (FILE_MUTATORS.has(toolCall.name)) {
+        const args = JSON.parse(toolCall.arguments)
+        const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
+        for (const p of paths) {
+          const abs = join(agent.cwd, p)
+          if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
+          if (agent.memory) {
+            // Fire-and-forget: don't block the agent loop on indexing.
+            // Reuses a single cached import; errors surface as pending reminders on next turn.
+            if (!_reindexFile) {
+              const mod = await import("../memory.mjs")
+              _reindexFile = mod.reindexFile
+            }
+            _reindexFile(agent.memory, agent.cwd, abs).catch((e) => {
+              agent._pendingReminders.push(`[System reminder: background indexing failed for ${toolCall.name} on ${abs}: ${e.message}. This does not affect your work — the code index will catch up on next reindex.]`)
+            })
+          }
+        }
+      }
+    }
+  }
+
+  // All tool results committed — now safe to inject deferred multimodal user messages
+  for (const { real, msg } of deferredUserMsgs) {
+    if (real) pushReal(agent, msg)
+    else agent.history.push(msg)
+  }
+}

package/src/agent/setup.mjs

@@ -13,13 +13,12 @@ import { loadSkills, formatSkillListing } from "../skills.mjs"
 import {
   escapeXml, repairHistory, listWorkDir, readonlyToolNames,
   collectGitContext, loadProjectInstructions, OUTLINE_INJECT_PREFIX,
-  DEFAULT_MAX_TURNS, DEFAULT_SUBAGENT_TURNS,
+  DEFAULT_MAX_TURNS, DEFAULT_SUBAGENT_TURNS, ensureAutoReminder,
 } from "./helpers.mjs"
 import { readFileSync, existsSync } from "node:fs"
 import { resolve, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 
-const AUTO_REMINDER = "[System reminder: AUTO mode is active — all tool calls are automatically approved without asking.]"
 const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
 const DOC_CHUNK_PREVIEW_LEN = 300
@@ -154,7 +153,7 @@ export async function prepareRun(agent, input, callbacks, {
   // Tail position keeps the second-precision content out of any prefix — caches stay hit.
   agent.history.push({
     role: "user",
-    content: `[System reminder: current time is ${timeNowLocal()} (local; timezone ${Intl.DateTimeFormat().resolvedOptions().timeZone || "local"}).`,
+    content: `[System reminder: current time is ${timeNowLocal()} (local; timezone ${Intl.DateTimeFormat().resolvedOptions().timeZone || "local"})].`,
     transient: true,
   })
 
@@ -252,12 +251,12 @@ export async function prepareRun(agent, input, callbacks, {
         warnings.push(`Engineering template (${agent._role === "eng-coder" ? "engineering-sub.md" : "engineering.md"}) not found — using degraded constraints.`)
       }
       if (engResult.methodologyMissing) {
-        warnings.push("METHODOLOGY.md not found — project-specific rules are absent.")
+        warnings.push("METHODOLOGY.md not found in the project root — no project methodology is loaded, so every 'per METHODOLOGY' reference in the engineering prompt is dangling and the three-document hard flow (requirements / design / test doc) is NOT enforced. Ask the user whether to create METHODOLOGY.md (scaffold available as src/prompts/methodology-template.md) before designing.")
       }
       if (warnings.length > 0) {
         agent.history.push({
           role: "user",
-          content: `[System reminder: ENGINEERING MODE is active but ${warnings.join(" ")} Create METHODOLOGY.md and ensure prompt templates exist for full enforcement, or disable engineering mode (/eng).]`,
+          content: `[System reminder: ENGINEERING MODE is active but ${warnings.join(" ")}]`,
         })
       }
     }
@@ -285,9 +284,7 @@ export async function prepareRun(agent, input, callbacks, {
     if (listing) systemPrompt += `\n\n${listing}`
   }
 
-  if (agent.autoApprove && !agent.history.some((m) => m.content === AUTO_REMINDER)) {
-    agent.history.push({ role: "user", content: AUTO_REMINDER })
-  }
+  ensureAutoReminder(agent)
 
   return { maxTurns, threshold, tools, toolSchemas, toolByName, systemPrompt }
 }

package/src/agent/spawn-child.mjs

@@ -0,0 +1,159 @@
+/**
+ * spawn-child.mjs — 生成侧统一子代理管线（AGENT-LOOP.md §7.2 D3）。
+ *
+ * 收编 subagent/escalate/consult 三份机械同构的重复实现：
+ *   - makeRelay:           _subAgentCounter + relayPrefix 生成 + `[model]` 元数据 token 发送
+ *   - wrapChildCallbacks:  onToken/onReasoning/onToolCall/onToolOutput 前缀包装
+ *                          （onToolOutput 复用 dispatch.mjs 的 onOutput 管线，D1；
+ *                          LLM 文本 token strip ⟦ev⟧ 哨兵——防伪造，D7）
+ *   - runWithContinue:     turn-cap ContinueError 循环骨架（askContinue 差异点经参数注入）
+ *   - ensureChildApiKey:   provider.apiKey trim/检查（apiKey 检查 ×3 合并）
+ *   - clampEffort:         effort 枚举钳制（enum 外丢弃——行为与 escalate/consult 现状逐字一致）
+ *
+ * 不收编（防过度抽象，留在各工具内）：角色过滤/overlay/git 注入、subagent 专属
+ * （报告契约 MIN_REPORT_CHARS、mergeChildMutations）、escalate 专属（touched-files、
+ * effortNote）、consult 专属（session 队列、watchdog、main_history 工具）。
+ */
+import { specForModel } from "../config.mjs"
+import { ContinueError } from "../agent.mjs"
+
+/** 事件 token 哨兵串（D1）——LLM 正常内容混淆概率极低；字段分隔用 RS (\x1e)。 */
+export const EVENT_SENTINEL = "⟦ev⟧"
+const RS = "\x1e"
+
+/** turn-cap 降级文案的公共锚点：subagent/escalate 的 onDeclined 文案必含此子串，
+ *  消费端（TUI tool-events onToolResult）用 includes() 检测"工作可能不完整"语义。
+ *  单源化（2026-08-30 评审）：文案演进只改这里，消除文案与检测正则的漂移面。 */
+export const TURN_CAP_MARK = "stopped: turn cap reached"
+
+/**
+ * 构造 relay 前缀 + 发送 `[model]` 元数据 token（显示层据此更新区块头部，
+ * 不进内容流）。counter 挂在 parent agent 上，多轮/并行子代理互不冲突。
+ * @returns {string} relayPrefix，形如 "coder#3/"
+ */
+export function makeRelay(parent, label, emit, model) {
+  parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
+  const relayPrefix = `${label}#${parent._subAgentCounter}/`
+  emit?.(relayPrefix + "[model]" + (model ?? ""))
+  return relayPrefix
+}
+
+/**
+ * strip ⟦ev⟧ 哨兵序列：子 agent 的 LLM 文本 token 若以事件哨兵开头，剥除之
+ * （模型伪造事件 token 的风险面收窄到"仅生成侧发出口"，D7）。
+ * **良构事件放行**（事件与内容共用 onToken 通道的必然结果）：真正由 runAgent
+ * depth>0 / dispatch 发出的 turn/approval 事件 token（形如
+ * `⟦ev⟧turn\x1e{n}\x1e{max}\x1e{phase}\x1e{detail}`）必须原样通过——只有非良构的
+ * `⟦ev⟧…`（模型伪造）才剥为普通文本。
+ * 已知限制（round2 #7）：单 chunk 匹配，哨兵串切在 chunk 边界（⟦e + v⟧）漏剥——
+ * 残危害由消费端 sanitizeDisplay 兜底，外观级；不引入跨 chunk carry-over 缓冲。
+ */
+// Single source for the event grammar branch lists (consult P3, 2026-08-30):
+// stripEventToken (display) and stripEventTokensForCapture (capture) shared them
+// literally — extending the event set meant touching both regexes.
+const EVENT_PHASE = "turn|approval"
+const EVENT_TYPE = "llm|tool|approval|done"
+const WELL_FORMED_EVENT = new RegExp(`^${EVENT_SENTINEL}(${EVENT_PHASE})${RS}[^${RS}]*${RS}[^${RS}]*${RS}(${EVENT_TYPE})${RS}`)
+export function stripEventToken(text) {
+  if (!text.startsWith(EVENT_SENTINEL)) return text
+  if (WELL_FORMED_EVENT.test(text)) return text // 真事件（生成侧发出），放行
+  return text.slice(EVENT_SENTINEL.length) // 模型伪造的哨兵串 → 剥为普通文本
+}
+
+/**
+ * Review #4: 事件 token 整体剥除——用于捕获进父 LLM 历史的 output（partial
+ * 输出/空报告 fallback）。与 stripEventToken（显示路径，放行真事件供头部消费）
+ * 不同：partial 输出不需要事件语义，RS 控制字符对父 LLM 是纯噪音。
+ * detail 字段可选（turn 事件 detail 为空且带收尾 RS；approval 事件 detail 为
+ * 工具名、无收尾 RS）——round2 复核缺口修复：此前正则要求收尾 RS，approval 的
+ * detail 会作为裸工具名残留在 partial 输出里。
+ */
+export function stripEventTokensForCapture(text) {
+  if (!String(text).includes(EVENT_SENTINEL)) return text
+  return String(text).replace(new RegExp(`${EVENT_SENTINEL}(${EVENT_PHASE})${RS}[^${RS}]*${RS}[^${RS}]*${RS}(${EVENT_TYPE})(?:${RS}[^${RS}]*)?`, "g"), "")
+}
+
+/**
+ * 子 agent 回调前缀包装：`role#id/` 前缀转发给父回调。
+ * - onToken 先剥伪造的 ⟦ev⟧ 哨兵（D7），再带前缀转发。
+ * - onToolOutput 带**已加前缀**的 name 走父 onToolOutput（name 形如
+ *   "coder#1/bash"，消费端剥前缀路由进对应区块；chunk 对象/裸串原样透传）。
+ * 父回调缺省时不包装（headless 嵌入）。
+ */
+export function wrapChildCallbacks(relayPrefix, parentCallbacks = {}) {
+  const wrapped = {
+    onToken: parentCallbacks.onToken
+      ? (t) => parentCallbacks.onToken(relayPrefix + stripEventToken(String(t)))
+      : null,
+    onReasoning: parentCallbacks.onReasoning
+      ? (t) => parentCallbacks.onReasoning(relayPrefix + t)
+      : null,
+    onToolCall: parentCallbacks.onToolCall
+      ? (name, args) => parentCallbacks.onToolCall(relayPrefix + name, args)
+      : null,
+    onToolOutput: parentCallbacks.onToolOutput
+      ? (name, chunk) => parentCallbacks.onToolOutput(relayPrefix + name, chunk)
+      : null,
+  }
+  return wrapped
+}
+
+/**
+ * 子 agent provider API key 检查：trim 后非空才保留；缺失返回 null（调用方
+ * 按各自业务语汇报错——subagent 抛出 / escalate·consult 返回 Error 文本）。
+ */
+export function ensureChildApiKey(provider) {
+  provider.apiKey = provider.apiKey?.trim() || null
+  return provider.apiKey ? provider : null
+}
+
+/**
+ * effort 枚举钳制：pool 配置的 effort 超出模型的 reasoningEffortEnum 时
+ * 丢弃（provider/core.mjs 会在每次 chat 抛错——候选未起飞先坠机）。enum 外
+ * 丢弃即"provider 预设默认也可能是该 override 模型的 enum 外值"的同款防御。
+ * @returns {boolean} true = effort 保留；false = effort 被 clamp 丢弃（调用方决定是否拼 effortNote）
+ */
+export function clampEffort(provider, model, effort) {
+  if (!effort) return true
+  const enumList = specForModel(model).reasoningEffortEnum
+  if (enumList && !enumList.includes(effort)) {
+    delete provider.reasoningEffort
+    return false
+  }
+  provider.reasoningEffort = effort
+  return true
+}
+
+/**
+ * turn-cap continue 循环骨架（TURN-CAP-CONTINUE.md）：ContinueError → 询问
+ * 继续（askContinue 回调，差异点注入）→ resume:true 重跑（保留 history 与
+ * mutation 记账、刷新 turn 预算）；拒绝/headless → 按 onDeclined 降级返回。
+ * 非 ContinueError 错误原样抛出（dispatch.mjs 转 Error 工具结果——行为不变）。
+ *
+ * @param {Function} runner  — async (child, input, callbacks, opts) => result
+ * @param {object}   child   — createAgent 返回的子 agent 对象
+ * @param {string}   input   — 任务文本
+ * @param {object}   callbacks — 子 agent callbacks（含 onPermissionRequest 等）
+ * @param {object}   runOpts — { depth, maxTurns, signal }（resume 由本函数管理）
+ * @param {object}   hooks   — { askContinue(err) => Promise<boolean>（必需）,
+ *                             onDeclined(err, output) => string（拒绝降级）}
+ */
+export async function runWithContinue(runner, child, input, callbacks, runOpts, { askContinue, onDeclined }) {
+  let output = ""
+  // Review #4 fix: strip sentinel/control chars from the capture — `output` feeds
+  // onDeclined's partial-output return, which lands in the PARENT LLM history where
+  // the display-layer sanitizeDisplay backstop does not apply.
+  const capture = callbacks?.onToken
+    ? (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output; callbacks.onToken(t) }
+    : (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output }
+  for (let resume = false; ; resume = true) {
+    try {
+      return await runner(child, input, { ...callbacks, onToken: capture }, { ...runOpts, resume })
+    } catch (e) {
+      if (!(e instanceof ContinueError)) throw e
+      const go = await askContinue(e)
+      if (go) continue
+      return onDeclined(e, output)
+    }
+  }
+}