@thincoder/core 0.9.5 → 0.10.2

package/advisor.mjs

@@ -127,7 +127,7 @@ export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
  * @param {Object} agent — the parent agent (history used for the response table)
  * @param {Object|null} prior — prior issue table (extracted from history when null)
  * @param {string[]|null} [scopeFiles] — review surface for the no-response fallback (cwd-relative)
- * @param {Object|null} [object] — review-object declaration (§18.8): mechanically
+ * @param {Object|null} [object] — review-object declaration (AGENT-LOOP-ASYNC-POOL.md §6.18): mechanically
  *   prepended to the round-2+ follow-up so every round stays anchored (T-OA2).
  * @returns {string} the follow-up user message — or a plain "System reminder: …"
  *   fresh-review fallback (NO brackets — some OpenAI-compatible servers parse
@@ -183,10 +183,10 @@ export { escapeLiteralEscapes }
  * @param {string|null} [designToken] — design-review approval token (design only)
  * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review (passed through to buildAdvisorUserMessage)
  * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review
- * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1): passed through
+ * @param {Object|null} [object] — review-object declaration (AGENT-LOOP-ASYNC-POOL.md §6.18 D-OA1): passed through
  *   to the user-message builders; mechanically injected at the start of every review
  *   round (round 1 design/code + round 2+ follow-up). Absent → legacy behavior.
- * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ * @param {string|null} [designId] — F2a: injected next to the design token in
  *   the Approval Signal (round 1 + round 2+ — both values, verbatim anchor).
  */
 export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null, designId = null) {
@@ -258,7 +258,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   // review surface.
   const scopeFiles = resolveScopeFiles(agent, paths)
   const followUp = buildAdvisorFollowUp(agent, prior, scopeFiles, object)
-  // §11.2 D-24b (design round 2+ — async fix-round continuations must be able to
+  // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b (design round 2+ — async fix-round continuations must be able to
   // re-approve): re-anchor the review scope (the convergence follow-up carries no
   // document list) and inject the round's design token with the approval signal.
   if (reviewType === "design") {

package/agent/assemble.mjs

@@ -0,0 +1,111 @@
+/**
+ * agent/assemble.mjs — 会话装配序**核单源**：配置 → 代理注入 → 记忆（+embedder）→ 文件规则 →
+ * 记忆层（项目 → 团队）→ 工具 →〔工具终形缝〕→ 代理 + 三字段（providers ∕ activeProvider ∕ activeModel）。
+ * 来源（纯搬 —— 端壳零副本）：desk `src/main/agent-assemble.mjs`（其前身 = `agent-host.mjs` 装配段逐字搬运）
+ * ∕ CLI `src/cli/make-agent.mjs` 装配段——两造 1–8 步逐段对齐（同序同义），本档为其唯一实现。
+ * 本档出 `assembleAgent` + 装配缺省面 `DEFAULT_DEPS`（逐项可注入 —— 装配序可机验 U79）+ 团队层取值
+ * `teamConfig` + 装配作者 `gitAuthor` + 装配后唯一校验点 `validateProvider`。
+ * 端壳留面（各端 adapter，非本档）：desk = cwd 注入（`projects.currentCwd()`）· `_slot` · 校验调用 ·
+ * `installExecRunSeams()` 尾；CLI = cwd = `process.cwd()` · MCP 合入（入 `toolsFinalize`）· `_mcpWarnings` ·
+ * `applyToolExclusions` · `attachManifest` · 校验调用。
+ * 零宿主依赖：核函数全部经 `deps` 取值（缺省 = 本档单源）⇒ 平 node 直测。
+ */
+import { execSync } from "node:child_process"
+import { isAbsolute, join } from "node:path"
+import { createAgent } from "../agent.mjs"
+import { configDir, loadConfig } from "../config.mjs"
+import { createMemory, syncDir } from "../memory.mjs"
+import { discoverRules, mergeFileRules } from "../rules.mjs"
+import { assembleBuiltinTools } from "../tools/index.mjs"
+
+/** 装配缺省面（逐项可注入 —— 断言装配调用序用假 deps；缺省 = 本档单源）。 */
+export const DEFAULT_DEPS = Object.freeze({
+  loadConfig, createMemory, createAgent, assembleBuiltinTools, discoverRules, syncDir,
+  team: teamConfig, author: gitAuthor,
+})
+
+/** 团队层配置（核 `config.memory.team` 有 repo 才成层）——原两造逐字同构，归一至此；
+ *  未配置 ⇒ null（装配跳过团队层）。缺省 name = `"default"`；`dir` 缺省 = `<configDir>/teams/<name>`。 */
+export function teamConfig(config) {
+  const team = config?.memory?.team
+  if (!team?.repo) return null
+  const name = team.name ?? "default"
+  return { name, repo: team.repo, dir: team.dir ?? join(configDir, "teams", name) }
+}
+
+/** 装配作者：git `user.name`，缺 ⇒ `"unknown"`（注入缝 = `DEFAULT_DEPS.author`）。 */
+export function gitAuthor() {
+  try { return execSync("git config user.name", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || "unknown" } catch { return "unknown" }
+}
+
+/** 装配后唯一校验点（判据 = `name && model && baseURL`）：**不抛** —— 无效 ⇒ 记 `_providerInvalid`
+ *  由回合驱动消费（`{ok:false,reason:"provider-invalid"}`，零假回合）；有效 ⇒ 清两标（幂等，复验径复用）。
+ *  reason = `config?.providerInvalidReason ?? 三档文案`（provider 不存在 ∕ model 缺失 ∕ 缺少 baseURL）。
+ *  返回 agent 便于链式调用。 */
+export function validateProvider(agent, config) {
+  const p = agent?.provider
+  if (p?.name && p?.model && p?.baseURL) {
+    delete agent._providerInvalid
+    delete agent._providerInvalidReason
+    return agent
+  }
+  agent._providerInvalid = true
+  agent._providerInvalidReason = config?.providerInvalidReason
+    ?? (!p?.name ? "provider 不存在" : !p.model ? "model 缺失" : "缺少 baseURL")
+  return agent
+}
+
+/** 装配一份会话代理（序见档头；`cwd` = 项目根，由各端 adapter 注入）。
+ *  `deps` 逐项可注入（缺省 = 本档单源）：装配序可机验（U79）；`deps.injectProxy` 可选（缺省 = 动态
+ *  import `../proxy.mjs`）。
+ *  `toolsFinalize(baseTools, { config, cwd, provider }) → tools ∕ Promise<tools>`：工具终形缝
+ *  （缺省 = 恒等）——位次 = 工具装配后、`createAgent` 前；核体 `await`（同步返回值与 Promise 同判）。 */
+export async function assembleAgent({ cwd, deps = {}, toolsFinalize = null }) {
+  const D = { ...DEFAULT_DEPS, ...deps }
+  const config = D.loadConfig()
+  const provider = config.provider
+  const providers = config.providersList
+  // 代理注入（double opt-in: provider.proxy + config.proxy.model）；config.provider 是 loadConfig 里的
+  // 独立拷贝 —— 同步注入结果（proxyUri）。
+  const injectProxy = D.injectProxy ?? (await import("../proxy.mjs")).injectProxy
+  injectProxy(providers, config)
+  if (provider?.name) provider.proxyUri = providers.find((p) => p.name === provider.name)?.proxyUri
+
+  const memory = D.createMemory({ dbPath: config.memory.dbPath })
+  // Vector retrieval: enabled if embedding is configured (lazy vector generation, computed on first search)
+  if (config.embedding?.apiKey) {
+    const { createEmbedder } = await import("../embedding.mjs")
+    memory.embedder = createEmbedder(config.embedding)
+  }
+  // 项目级规则（.thincoder/rules/*.md）并入 config：文件规则在前（优先），config.json 规则按 pattern 去重在后。
+  // 合并体单源 = `../rules.mjs` `mergeFileRules`（B7 3a 自本处内联块抽取；`discover` 走 `D.` 注入缝）。
+  config.agent.streamRules = mergeFileRules(config.agent?.streamRules, cwd, D.discoverRules)
+  // code/doc 索引按 origin（项目根目录）隔离：检索只落本项目范围。
+  memory.codeOrigin = cwd
+  // 项目层：启动时把 `.thincoder/memory/` 目录同步进索引（有则同步、无则跳过）。
+  if (config.memory.projectDir) {
+    memory.projectOrigin = isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(cwd, config.memory.projectDir)
+    await D.syncDir(memory, { layer: "project", dir: memory.projectOrigin })
+  }
+  // 团队层（可选）：首用自动 clone；启动只索引本地目录，远端拉取走显式 sync 命令。
+  const team = D.team(config)
+  if (team) {
+    const { ensureClone } = await import("../git/gitmem.mjs")
+    await ensureClone(team)
+    await D.syncDir(memory, { layer: "team", dir: team.dir })
+  }
+  // #70（CORE-UNIFICATION TOOLS）：注册表与消费侧拼装面归位核内——单源 `assembleBuiltinTools`
+  // （静态表 ∪ memory / code_search / doc_search / repo_outline / settings / peer_instances 六面 ∪
+  // 门控 read_image）。传 `model` 必需：漏传 ⇒ `read_image` 对所有模型静默消失
+  // （门判据 = specForModel(model)?.multimodal）。
+  const baseTools = await D.assembleBuiltinTools({
+    memory, cwd, projectDir: config.memory.projectDir, author: D.author(), team,
+    model: provider?.model ?? null,
+  })
+  const tools = toolsFinalize ? await toolsFinalize(baseTools, { config, cwd, provider }) : baseTools
+  const agent = D.createAgent({ provider, tools, config, cwd, memory })
+  agent.providers = providers
+  agent.activeProvider = provider?.name ?? ""
+  agent.activeModel = provider?.model ?? null
+  return agent
+}

package/agent/chat-call.mjs

@@ -0,0 +1,68 @@
+/**
+ * agent/chat-call.mjs — 单回合模型调用（2026-09-29 P2 三拆：agent.mjs runAgent 段 4 逐字迁入 +
+ * `streamOutputAllowed` 定义随迁——agent.mjs re-export 保 import 面）。
+ * 接口 = callModelTurn(agent, ctx) → response；错误走原样：AbortError-中断臂处理完照旧 `throw e`，
+ * 由 runAgent 的 catch/finally 收束。
+ */
+import { chat } from "../provider/index.mjs"
+
+/** 流式输出门（§2.5 #78 并入——VSC 三态门，纯函数可直驱测试）：depth 0 恒通；
+ *  consult 子代理豁免（其输出进会诊面板）；其余经 `streamOutput` 显式选择进入。 */
+export function streamOutputAllowed(depth, role, streamOutput = false) {
+  return depth === 0 || role === "consult" || streamOutput === true
+}
+
+export async function callModelTurn(agent, {
+  systemPrompt, toolSchemas, streamOutput, callbacks, signal, streamRuleFired, autoTurn, depth, turn,
+}) {
+  const messages = [{ role: "system", content: systemPrompt }, ...agent.history]
+  let response
+
+  // Auto-think: classify difficulty and set reasoning effort on turn 0; silent on failure.
+  if (agent.config?.agent?.autoThink && turn === 0) {
+    const { classifyAndApply } = await import("../auto-think.mjs")
+    await classifyAndApply(agent, turn).catch(() => {})
+  }
+
+  try {      response = await chat(agent.provider, {
+      messages, tools: toolSchemas,
+      // §2.5 #78 并入（VSC onToken 三态门）：depth 0 恒通；consult 子代理豁免（其输出进
+      // 会诊面板）；escalate 等经 opts.streamOutput 显式选择进入；其余子代理不流式。
+      onToken: streamOutputAllowed(depth, agent._role, streamOutput) ? callbacks.onToken : null,
+      onReasoning: callbacks.onReasoning,
+      onWait: callbacks.onWait,
+      signal,
+      streamRules: agent.config.agent?.streamRules ?? [],
+      firedPatterns: streamRuleFired,
+      // LOGGING（LOGGING.md）：llm:* 事件的语义上下文（stage=turn 主循环回合——含
+      // digest 消化轮 auto=true；child=子代理 id（spawn 时 stamp 于 child._logId））
+      // TRACES.md §6.1 D-TR4：轨迹元数据增补（role/depth/kind/session/cwd——trace-store 只读
+      // logCtx，签名不变）；kind：depth>0 = subagent（consult 孩子 = consult）——子代理
+      // 对回靠 role+depth+child id（children 无 _sessionStart——不经 depth-0 设置——
+      // session 字段对子代理轨迹为 null——见 trace-store/agent.mjs 注释）。
+      logCtx: {
+        stage: "turn", turn: turn + 1, auto: autoTurn, child: agent._logId,
+        role: agent._role ?? null,
+        depth,
+        kind: depth > 0 ? (agent._role === "consult" ? "consult" : "subagent") : "turn",
+        session: agent._sessionStart ?? null,
+        cwd: agent.cwd,
+        traces: agent.config?.traces?.enabled !== false,
+      },
+    })
+  } catch (e) {
+    // User interrupt (Ctrl+I): controller.abort({ interrupt: true, message }).
+    // Inject into history; the outer loop recreates the controller and resumes.
+    if (e.name === "AbortError" && signal?.reason?.interrupt) {
+      const msg = `[User interrupt: ${signal.reason.message}]`
+      // Dedup: if already handled during tool execution (interrupt branch below),
+      // don't push a duplicate — the outer loop still recreates the controller.
+      if (agent.history.at(-1)?.content !== msg) {
+        agent.history.push({ role: "user", content: msg })
+      }
+    }
+    throw e
+  }
+
+  return response
+}

package/agent/child-marks.mjs

@@ -3,8 +3,8 @@
  *
  * 收编自 `spawn-child.mjs`（2026-09-20 端差·显示面消差批 §2.2 X6 实现轮）：端壳侧需**静态**
  * 导入锚点做块头注记判定，而 `spawn-child.mjs` 静态链经核 agent 栈可达 `node:sqlite`
- * ⇒ 端壳静态闭包禁达（W8 契约②；`thincoder-vscode/test/engine-floor-guard.test.mjs`
- * fail-closed 红）⇒ 锚点下沉**零依赖叶**（先例 = `relay-prefix.mjs` 同因下沉）。`spawn-child.mjs`
+ * ⇒ 端壳静态闭包禁达（W8 契约②判据（现载体 = 批件 `docs/batches/2026-09-29-residuals-round2.test.mjs`；
+ * 单测树重建时回迁端侧单测档）：fail-closed 红）⇒ 锚点下沉**零依赖叶**（先例 = `relay-prefix.mjs` 同因下沉）。`spawn-child.mjs`
  * 原样再导出 ⇒ 既有 import 面（核 agent-tools 族 / CLI `tool-events.mjs`）零改。
  *
  * 语义：消费端用 `includes()` 检出锚点 ⇒ 合成块头注记（"work may be partial"）——两端各一处：

package/agent/completion.mjs

@@ -3,6 +3,7 @@
  *
  * Checks: pending tasks, verify guard, advisor guard.
  * Returns { action: 'continue' | 'done', content?, guardPushbacks, honestReminderInjected, advisorPushbacks }
+ * 子回合边界（#628）：六推回点各触 `callbacks.onSubTurnBreak?.()` —— 零参可选（缺省 no-op）；`onTurnEnd` 超集语义零改。
  */
 import { hasCodeMutations } from "../advisor/repos.mjs"
 import { pushReal } from "../context.mjs"
@@ -24,7 +25,7 @@ const MAX_EMPTY_RETRIES = 2
  * @param {number} guardPushbacks - verify guard pushback count (mutated)
  * @param {boolean} honestReminderInjected - whether exhausted-verify reminder was already sent (mutated)
  * @param {number} advisorPushbacks - advisor guard pushback count (mutated)
- * @param {object} callbacks - { onTurnEnd }
+ * @param {object} callbacks - { onTurnEnd, onSubTurnBreak }
  */
 export function handleCompletion(agent, response, depth, turn, guardPushbacks, honestReminderInjected, advisorPushbacks, callbacks) {
   if (!response.content) {
@@ -38,6 +39,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
         role: "user",
         content: "[System reminder: your last response was empty — the provider returned no content (likely reasoning was exhausted or output was truncated). Respond again, continuing your work from where you left off.]",
       })
+      callbacks.onSubTurnBreak?.()
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
@@ -63,6 +65,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
       role: "user",
       content: `[System reminder: you still have pending tasks: ${pending}. Update their status with the task tool before finishing — if they're done, mark them done; if they're not applicable, remove them. (This is your only reminder — if you choose not to, finish anyway.)]`,
     })
+    callbacks.onSubTurnBreak?.()
     callbacks.onTurnEnd?.(agent, turn)
     return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
   }
@@ -81,6 +84,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
         role: "user",
         content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: run the project's verification yourself (per its AGENTS.md test method), then call verify declaring the outcome via verification.status. verify mechanically gates on your declaration. If verification is genuinely impossible here, say so explicitly in your reply.]",
       })
+      callbacks.onSubTurnBreak?.()
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
@@ -94,6 +98,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
         role: "user",
         content: `[System reminder: (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}) verify was not passed — either your verification declared failed, was skipped without a reason, or was not declared. Fix or complete your verification, then call verify again declaring the outcome. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
       })
+      callbacks.onSubTurnBreak?.()
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
@@ -109,6 +114,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
         role: "user",
         content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted. You have not passed verification. Either state explicitly that your verification could not be completed, or run verify again once it is. If your verification could not be completed, say so explicitly in your reply to the user — state what you tried and what you believe is blocking you, and do not present the work as complete; the user needs to know it is unfinished.]`,
       })
+      callbacks.onSubTurnBreak?.()
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
@@ -121,7 +127,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   const cfg = agent.config?.advisor
   const advisorReview = cfg?.guard === true
   if (depth === 0 && advisorReview && !agent.config?.agent?.engineering) {
-    // §11.2 D-24b (T-24b4 — guard timing): an async review that is still in flight
+    // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b (T-24b4 — guard timing): an async review that is still in flight
     // (or queued in the advisor pool) means the review was launched — the guard
     // does NOT push back while it is pending (未决不算未评审); once it settles
     // non-stale it marks _calledAdvisorThisRun, and a STALE settle leaves the
@@ -137,6 +143,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
         role: "user",
         content: `[System reminder: you changed code in this run and MUST get an advisor review before finishing (round ${rounds + 1}). Call the \`advisor\` tool now. This is required, not optional — do not skip it even if you believe the changes are trivial — the review will be quick either way. After the review, produce a response table for every issue found (see discipline rules for format).]`,
       })
+      callbacks.onSubTurnBreak?.()
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }

package/agent/continue-decision.mjs

@@ -0,0 +1,25 @@
+/**
+ * continue-decision.mjs — 续跑判定（核单源 · #677 · I10）。
+ * 同形重复族 #127 ④（续跑循环双写——CLI `thincoder-cli/src/tui/agent-turn.mjs` ∥ VSC
+ * `thincoder-vscode/src/extension/panel-turn-loop.mjs`）收口：端壳循环只接线本函数，
+ * 零第二分支；判定口径改一处 ⇒ 两端同轮生效（原双改纪律退役）。
+ * 三格判定（口径 = TURN-CAP-CONTINUE.md D-TC15 ∕ F8）：
+ *   ① ContinueError（撞帽）——无人值守档（autoTurn）⇒ "cap-stop"（不静默自续）；
+ *      人工档 ⇒ "ask"（续期恒须人答——AUTO 亦不自动批准）。
+ *   ② 中止（AbortError ∥ reason 在场）——带注入消息的 interrupt（Ctrl+I）⇒ "resume"；其余 ⇒ "stop"。
+ *   ③ 其余错误 ⇒ "error"；无错误（正常完成）⇒ "done"。
+ * `reason` = 调用方解析后的中止 reason（两端同式 = 回合 controller `signal.reason` 单源——#677 修正轮对齐；
+ * 核不臆测宿主 signal 源）。
+ * `autoApprove` = 接口承载（#127 形）；现语义下不改判定（F8 ∕ D-TC15）。
+ */
+import { ContinueError } from "./helpers.mjs"
+
+/** @returns {"done"|"cap-stop"|"ask"|"resume"|"stop"|"error"} */
+export function continueDecision(error, { autoTurn = false, autoApprove = false, reason = null } = {}) {
+  if (error == null) return "done"
+  if (error instanceof ContinueError) return autoTurn ? "cap-stop" : "ask"
+  if (error.name === "AbortError" || reason != null) {
+    return reason?.interrupt && reason?.message ? "resume" : "stop"
+  }
+  return "error"
+}

package/agent/dispatch-gates.mjs

@@ -0,0 +1,140 @@
+/**
+ * agent/dispatch-gates.mjs — dispatch 门面谓词与记账（2026-09-28 拆分批 · R3——自
+ * `agent/dispatch.mjs`（498/499 贴 500 硬限）外提：动作级分类四谓词（readonly ∕ control ∕
+ * consume-design ∕ escalate）+ 工具错误落盘 `logToolError` + 执行即刻 mutation 记账
+ * `noteExecutedMutation`；**逐字迁移**、零行为改）。
+ * `executeToolCalls` 仍住 `dispatch.mjs`（对外缝零改——签名与调用点零改）；单条执行体住
+ * `./dispatch-run.mjs`（其 import 本档的 `logToolError` ∕ `noteExecutedMutation`）——本档
+ * 零回引，为两者之叶。ERRORS_DIR = ~/.thincoder/tool-errors。
+ */
+import { writeFileSync, mkdirSync, existsSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { homedir } from "node:os"
+import { toolTouchPaths } from "./helpers.mjs"
+// fix A（2026-09-07）：FILE_MUTATORS 的 mutation-seq 记账从
+// 批后提交（record-results noteMutations）移到执行成功即刻——唯一记账点（取代批后段
+// + agent.mjs 中断分支记账——不双计）——同消息 [写 + async advisor launch] 时 launch 前
+// 完成的写在 launchSeq 之前落地 → settle 不再误判 stale（fix A 症状根因）。
+import { noteMutations } from "../agent-tools/advisor-async.mjs"
+
+const ERRORS_DIR = join(homedir(), ".thincoder", "tool-errors")
+
+/**
+ * Persist a tool error to ~/.thincoder/tool-errors/YYYY-MM-DD/HHmmss-toolName.log
+ * Only called for actual execution failures and malformed invocations.
+ * Skipped for intentional denials (plan mode, user reject).
+ */
+export function logToolError(toolName, args, error) {
+  try {
+    const now = new Date()
+    const ymd = now.toISOString().slice(0, 10)
+    const ts = now.toISOString().replace(/:/g, "").replace(/\..+/, "").replace("T", "-")
+    const dir = join(ERRORS_DIR, ymd)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${ts}-${toolName.replace(/[/\\]/g, "_")}.log`)
+    const entry = [
+      `time: ${now.toISOString()}`,
+      `tool: ${toolName}`,
+      `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"
+    writeFileSync(file, entry, "utf8")
+  } catch {
+    // Log failure itself must not crash the agent
+  }
+}
+
+/**
+ * action-level classification (AGENT-LOOP-SUBAGENT.md §6.7 D-M1): the merged subagent
+ * tool expresses spawn (side effect) and status (read-only query) through
+ * its `action` parameter — the tool-level readonly flag can no longer express both.
+ * dispatch Phase-1/Phase-2 classifies per action: status behaves as readonly
+ * (planMode pass / no permission ask / batchable), spawn keeps its non-readonly
+ * gates, escalate runs non-readonly AND serially (the retired escalate tool had no
+ * parallel flag — zero behavior change under the merged surface).
+ * AGENT-LOOP-SUBAGENT.md §6.7.2 cancel (19.5.2b round2 #4): CONTROL-class exemption — cancel only
+ * stops, never starts. isSubagentControlAction feeds the SAME two gate sites as
+ * readonly (planMode pass / no permission ask — never joins a batch approval
+ * group / no handler → not denied — digest 内 cancel 放行).
+ * AGENT-LOOP-SUBAGENT.md §6.7.2 panel (round1 #5): view 面归只读类（同 status——planMode 放行、免
+ * 审批、可批并行）；freeze 面归控制类（同 cancel——planMode 放行、免权限审批、
+ * 批审批不入组、digest 内放行）。freeze 存在（非空 key）即控制类——否则只读类。
+ */
+export function isSubagentReadonlyAction(toolName, args) {
+  // §6 memory 工具面重构（MEMORY.md §6 D-M5）：memory search/list 是只读动作——与
+  // subagent status 同分类（planMode 放行/免审批——Phase-2 批并行只认工具级
+  // readonly/parallel，memory 无 parallel → 按非只读串行，见 MEMORY.md §6.4 实现注）。
+  // 动作级判定——不能按工具名（同一 memory 工具的 put/delete/clear 保持侧效门）。
+  if (toolName === "memory") {
+    const action = args?.action
+    return action === "search" || action === "list"
+  }
+  // SETTINGS-TOOL.md（2026-09-05）：settings list/get 是只读动作（memory search/list 同分类——
+  // planMode 放行/免审批）；set 保持侧效门。
+  if (toolName === "settings") {
+    const action = args?.action
+    return action === "list" || action === "get"
+  }
+  // #9（TOOLS.md §6.19）：process 动作分级——list 保持只读分类（planMode 放行/免审批/可批并行）；
+  // kill 是破坏性动作（审批门 + planMode 拒）。
+  if (toolName === "process") return args?.action !== "kill"
+  if (toolName !== "subagent" || !args || typeof args !== "object") return false
+  const action = args.action
+  // AGENT-LOOP-SUBAGENT.md §6.7.5: check 动作已删除——只读面仅剩 status（planMode 放行/免权限审批/可批并行）
+  if (action === "status") return true
+  // SUBAGENT-OBSERVE-SEND：observe = readonly 查询（同 status——digest/planMode 放行）
+  if (action === "observe") return true
+  // AGENT-LOOP-SUBAGENT.md §6.7.2 panel view 面（freeze 缺省/空 = 视图请求——readonly；非空 freeze 归控制类）
+  if (action === "panel" && (args.freeze === undefined || args.freeze === null || String(args.freeze) === "")) return true
+  return false
+}
+export function isSubagentControlAction(toolName, args) {
+  if (toolName !== "subagent") return false
+  if (args?.action === "cancel") return true
+  // SUBAGENT-OBSERVE-SEND：send = 控制类豁免（同 cancel——父回合内显式调用即授权——
+  // 写子输入队列属父对子轻量引导，非产品代码写——免审批、planMode 放行、digest 内放行）
+  if (args?.action === "send") return true
+  // AGENT-LOOP-SUBAGENT.md §6.7.2 panel freeze 面（D-P3 门控在 executor——只读/控制分类在此）
+  if (args?.action === "panel" && args.freeze !== undefined && args.freeze !== null && String(args.freeze) !== "") return true
+  return false
+}
+/**
+ * §2.6 token 链终消费制（2026-09-07——评审 #7d dispatch 分类）：consume-design =
+ * 非只读控制动作——planMode 拒绝（不入 readonly/control 豁免——与其他非只读动作同门）、
+ * 免权限审批、不入批审批分组（无文件写——控制类直行——只停既有状态不起新副作用）。
+ * 与 cancel 的不同：cancel 是控制类豁免（planMode 放行），consume-design 按设计
+ * planMode 拒绝——故不并入 isSubagentControlAction，单独谓词只接权限豁免位。
+ */
+export function isSubagentConsumeDesignAction(toolName, args) {
+  return toolName === "subagent" && args?.action === "consume-design"
+}
+export function isSubagentEscalateAction(toolName, args) {
+  return toolName === "subagent" && args?.action === "escalate"
+}
+
+/** E1（parity-b1 §2.5——动作谓词采纳）：工具面动作谓词钩子**优先**、缺省回落核名面谓词（`??` 同式）。
+ *  端壳装饰体携钩子（`gitTool.isReadonlyAction` ∕ `memoryTool.isReadonlyAction` ∕ 子代 `vscSubagentFace`
+ *  的 `isReadonlyAction/isControlAction`）——取核 dispatch 后其动作级分类（planMode 放行 ∕ 免审批）
+ *  由此保形；核内工具零钩子 ⇒ CLI ∕ desktop 逐字零变（`undefined ?? 核谓词`）。
+ *  两谓词 = 上列两门禁位（planMode ∕ 权限短路）的公共输入（同址同用，防两处漂移）。 */
+export function readonlyActionOf(tool, toolName, args) {
+  return tool?.isReadonlyAction?.(args) ?? isSubagentReadonlyAction(toolName, args)
+}
+export function controlActionOf(tool, toolName, args) {
+  return tool?.isControlAction?.(args) ?? isSubagentControlAction(toolName, args)
+}
+
+/**
+ * fix A — 唯一记账点：FILE_MUTATORS 工具执行成功即刻记 mutation seq（abs 路径）。
+ * 取代 record-results 批后段 + agent.mjs 中断分支的 noteMutations（不双计——中断+同批
+ * launch 场景 seq 单计，T-A1i）。调用时机 = 写执行成功（非 Error 前缀
+ * 结果——recordPeerWrites 同款门）；routed（M2 ACP 客户端执行）成功同样记账。
+ */
+export function noteExecutedMutation(agent, tool, args) {
+  // #327（TOOLS.md §6.17）：单源谓词恒数组 · 恒零抛——原 try/catch 外壳退休。
+  const abs = toolTouchPaths(tool, args)
+    .filter((p) => typeof p === "string" && p)
+    .map((p) => resolve(agent.cwd, p))
+  if (abs.length > 0) noteMutations(agent, abs)
+}

package/agent/dispatch-run.mjs

@@ -0,0 +1,167 @@
+/**
+ * agent/dispatch-run.mjs — 单条 prepared 项的执行体（2026-09-28 拆分批 · R3——自
+ * `agent/dispatch.mjs`（498/499 贴 500 硬限）外提：原 `executeToolCalls` 内闭包 `runOne`
+ * 提升为模块级 `runPreparedItem`（**函数体逐字搬运**——闭包自由变量经形参代入，缩进回归
+ * 一级）；`executeToolCalls` 两处调用点同批改指（批并行 ∕ escalate 串行分支）。
+ * 依赖方向：本档 → `./dispatch-gates.mjs`（logToolError ∕ noteExecutedMutation）；主档 → 本档
+ * ——零环。
+ */
+import { logEvent, errText, headText } from "../log.mjs"
+import { offloadToolResult, FILE_MUTATORS } from "./helpers.mjs"
+import { runHooks } from "../hooks.mjs"
+import { snapshotForUndo } from "../undo-stack.mjs"
+import { PEER_WRITE_TOOLS, peerCollabNote, recordPeerWrites, markClaimNoted } from "../peer-domains.mjs"
+import { logToolError, noteExecutedMutation } from "./dispatch-gates.mjs"
+
+/** 单条 prepared 项的执行（Phase 2 体——原 `dispatch.mjs` runOne 闭包；自由变量 agent ∕ depth ∕
+ *  signal ∕ callbacks 经形参代入，语义逐字保持：console 捕获 ∕ routed 短路 ∕ mutation 记账 ∕
+ *  错误收口零改）。 */
+export async function runPreparedItem(item, agent, depth, signal, callbacks) {
+  if (item.error) return { ...item, result: `Error: ${item.error}`, ok: false }
+  if (item.denied) {
+    const reason = item.reason === "plan mode"
+      ? "Error: plan mode is active — only read-only tools are allowed. Exit plan mode first."
+      : item.reason === "engineering design gate"
+        ? `Error: design review required before any file modification. ${item.hint}`
+        : item.reason === "d5 freeze window" || item.reason === "cross-batch record write"
+        ? `Error: ${item.hint}`
+        : item.reason === "denied by user"
+        ? "Error: permission denied by user"
+        : item.reason === "blocked by PreToolUse hook"
+          ? "Error: blocked by PreToolUse hook"
+          : "Error: no permission handler configured — this tool requires user approval but the current context doesn't support interaction (e.g. subagent or non-TUI mode)"
+    return { ...item, result: reason, ok: false }
+  }
+  // 2026-08-31 工具顺手度（用户批准"做吧"）：dispatch 拦截工具执行期间的
+  // console.log/console.error——工具的探查/调试输出（原本只到终端、模型看不到）
+  // 收集后附在工具结果后回显给模型。bash 工具的输出走子进程回显（onOutput），
+  // 不走 dispatch console——拦截安全。嵌套 dispatch（subagent）各自拦截/恢复，
+  // 捕获分离（父恢复原始后子的拦截期间父捕获停止、子恢复后父继续）——正确。
+  // 声明在 try 之外：catch 块（异常路径）也要访问（报错前的探查输出回显）。
+  const capturedConsole = []
+  // LOGGING（LOGGING.md）：tool:* 事件——仅真实执行（pre-gate 拦截项在下方早退分支不入事件）。
+  // 参数值永不落盘（NF-L3——工具事件不记 args）；child=子代理 id（agent._logId，spawn 时 stamp）。
+  const toolT0 = Date.now()
+  const toolName = item.toolCall.name
+  logEvent("tool:call", { tool: toolName, child: agent?._logId })
+  try {
+    // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b / §4.4.4)：结构化写工具执行前查冲突与认领
+    // 命中（软提示——决策⑥ A 不阻止；一次目录 stat——N3 度量）；足迹累积（D-L3a——"检测+
+    // 记录一次完成"）与认领登记延后到执行成功（实际写过的文件）。
+    const isPeerWriteTool = PEER_WRITE_TOOLS.has(toolName)
+    const peerNote = isPeerWriteTool ? peerCollabNote(agent, item.tool, item.args) : null
+    // Snapshot for undo before side-effect tools (setupOutputPanel already fired in Phase 1)
+    if (!item.tool?.readonly && item.args) {
+      snapshotForUndo(agent, item.toolCall.name, item.args, agent.cwd)
+    }
+    // M2 ACP: route fs tools through the client (IDE buffer / diff review).
+    // toolRouter returns { handled: true, result } to short-circuit execution.
+    if (callbacks.toolRouter) {
+      const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
+      if (routed?.handled) {
+        const routedOk = !String(routed.result).startsWith("Error:")
+        const routedResult = peerNote && routedOk ? `${routed.result}\n${peerNote.text}` : routed.result
+        if (peerNote && routedOk) markClaimNoted(agent, peerNote.keys) // 提示已附加 ⇒ 落去重标记
+        if (isPeerWriteTool && routedOk) recordPeerWrites(agent, item.tool, item.args)
+        // fix A：routed 写成功（客户端执行）同样执行期即刻记账（唯一记账点）
+        if (routedOk && FILE_MUTATORS.has(toolName)) noteExecutedMutation(agent, item.tool, item.args)
+        callbacks.onToolResult?.(item.toolCall.name, routedResult, item.toolCall.id)
+        logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(routedResult, 200), child: agent?._logId })
+        return { ...item, result: routedResult, ok: true }
+      }
+    }
+    const origConsoleLog = console.log
+    const origConsoleErr = console.error
+    console.log = (...a) => capturedConsole.push(a.map(String).join(" "))
+    console.error = (...a) => capturedConsole.push("[err] " + a.map(String).join(" "))
+    let rawResult
+    // ctx 对象提升为变量（docs/cli/design/TUI.md §6.8）：subagent 阻塞 execute 返回前在 ctx 上留
+    // _subagentKey（relayPrefix 去尾）——runOne 在 execute 返回后读它作 onToolResult
+    // 第 4 参（普通工具/错误路径无此字段——undefined 兼容既有签名）。每次工具调用
+    // 独立 ctx——并行同名工具（批并行 runOne）各自带自己的 key，互不串扰。
+    const toolCtx = {
+      cwd: agent.cwd,
+      agent,
+      depth,
+      signal,
+      callbacks,
+      // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: per-call id — the advisor tool marker-keys its launch so
+      // recordToolResults can split async-ack accounting from sync settles.
+      _toolCallId: item.toolCall.id,
+      onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk, item.toolCall.id),
+      onQuestion: callbacks.onQuestion,
+      onPermissionRequest: callbacks.onPermissionRequest,
+    }
+    try {
+      // SUBAGENT-OBSERVE-SEND D1（评审 #1）：in-flight 当前工具记账——工具执行期间在
+      // agent 上留 _inflightTools Set（子代理 observe 从 dispatch 状态读——卡在长工具
+      // 调用时 history 无新回合、恰需此信号）；finally 清除。批并行工具同入 Set（observe
+      // 如实返回多个在跑工具）。主会话同样记账——无害（无人读）。
+      const inflight = agent._inflightTools ?? (agent._inflightTools = new Set())
+      inflight.add(toolName)
+      try {
+        rawResult = await item.tool.execute(item.args, toolCtx)
+      } finally {
+        inflight.delete(toolName)
+      }
+    } finally {
+      console.log = origConsoleLog
+      console.error = origConsoleErr
+    }
+    if (rawResult === undefined) throw new Error(`Tool "${item.toolCall.name}" returned undefined — all tools must return a string value`)
+    const raw = String(rawResult)
+    // 写成功（非 "Error:" 字符串结果）→ 足迹计入本回合集合（flush 在 finalizeAgentTurn）
+    if (isPeerWriteTool && !raw.startsWith("Error:")) {
+      recordPeerWrites(agent, item.tool, item.args)
+    }
+    // fix A：FILE_MUTATORS 执行成功即刻记账（唯一记账点——取代 record-results 批后
+    // 段 + agent.mjs 中断分支——不双计）——同批 launch 前的写在 launchSeq 之前落地 →
+    // async advisor settle 不误判 stale（同批 launch 后写仍保守 stale——T-A2/T-24b9）。
+    if (FILE_MUTATORS.has(toolName) && !raw.startsWith("Error:")) {
+      noteExecutedMutation(agent, item.tool, item.args)
+    }
+    // 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)
+    // 2026-08-31：工具执行期间捕获的 console 输出附在结果后回显（模型视野）
+    const resultWithConsole = capturedConsole.length > 0
+      ? `${result}\n[console during ${item.toolCall.name}]\n${capturedConsole.join("\n")}`
+      : result
+    // R10 L3：冲突 / 认领软提示附在工具结果末尾（模型可见——不阻止写；提示附加成功才落去重标记）
+    const notedOk = Boolean(peerNote) && !raw.startsWith("Error:")
+    if (notedOk) markClaimNoted(agent, peerNote.keys)
+    const resultForModel = notedOk
+      ? `${resultWithConsole}\n${peerNote.text}`
+      : resultWithConsole
+    callbacks.onToolResult?.(item.toolCall.name, resultForModel, item.toolCall.id, toolCtx._subagentKey)
+    // PostToolUse hooks: fire-and-forget (result not awaited on hook failure)
+    runHooks("PostToolUse", { agent, toolName: item.toolCall.name, toolArgs: item.args, result: raw }).catch(() => {})
+    logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(resultForModel, 200), child: agent?._logId })
+    return { ...item, result: resultForModel, ok: true }
+  } catch (error) {
+    // Persist to ~/.thincoder/tool-errors/ for post-mortem; only pass message to the model (stack traces confuse LLMs and may leak paths)
+    logToolError(item.toolCall.name, item.args, error)
+    // User interrupt (Ctrl+C / Ctrl+I) must propagate, not become a tool error:
+    // swallowing it here would make the parent keep looping while the user
+    // asked to stop — worst case with subagents, where the child runs its
+    // whole turn budget and the interrupt appears to do nothing.
+    if (signal?.aborted) throw error
+    // LOGGING（2026-09-03 code review #4）：中止先于事件——用户停不落 tool:error
+    //（vscode execute-tools parity；阻塞子代理 child:error 同款抑制）
+    logEvent("tool:error", { tool: toolName, ms: Date.now() - toolT0, err: errText(error, 200), child: agent?._logId })
+    runHooks("PostToolUseFailure", { agent, toolName: item.toolCall.name, toolArgs: item.args, error }).catch(() => {})
+    // Build contextual error: tool name + key args — #327 same family: no raw args deref (`arguments:"null"` reachable)
+    const a = item.args ?? {}
+    const ctxParts = []
+    if (a.path) ctxParts.push(`path=${a.path}`)
+    if (a.pattern) ctxParts.push(`pattern=${a.pattern}`)
+    if (a.command) ctxParts.push(`cmd=${String(a.command).slice(0, 80)}`)
+    const ctx = ctxParts.length > 0 ? ` [${ctxParts.join(", ")}]` : ""
+    // 2026-08-31：异常路径同样回显捕获的 console（工具报错前的探查输出最有价值）
+    const consolePart = capturedConsole.length > 0
+      ? `\n[console during ${item.toolCall.name}]\n${capturedConsole.join("\n")}`
+      : ""
+    return { ...item, result: `Error: ${error.message}${ctx}${consolePart}`, ok: false }
+  }
+}