@thincoder/core 0.9.5 → 0.10.1

package/agent/dispatch.mjs

@@ -1,136 +1,27 @@
 /**
  * agent/dispatch.mjs — two-phase tool call execution
+ * 2026-09-28 拆分（Module Split Policy——498/499 贴 500 硬限跨档）：门面谓词 ∕ 记账外提
+ * `./dispatch-gates.mjs`（四谓词 + logToolError + noteExecutedMutation）、单条执行体外提
+ * `./dispatch-run.mjs`（runPreparedItem——原 runOne 闭包，verbatim + 形参代入）；
+ * `executeToolCalls` 签名与对外缝零改（本档导出面零变）。
  */
-import { logEvent, errText, headText } from "../log.mjs"
-import { offloadToolResult, FILE_MUTATORS } from "./helpers.mjs"
+import { FILE_MUTATORS, toolTouchPaths } from "./helpers.mjs"
 import { runHooks } from "../hooks.mjs"
-import { snapshotForUndo } from "../undo-stack.mjs"
-import { isCodePath, loadConventions } from "../conventions.mjs"
-// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b / §4.4 D-MI17–D-MI21)：写工具钩子——peerCollabNote
-// （执行前冲突与认领命中检测——软提示不阻止）+ recordPeerWrites（成功后足迹与认领登记）。
-import { PEER_WRITE_TOOLS, peerCollabNote, recordPeerWrites, markClaimNoted } from "../peer-domains.mjs"
-import { writeFileSync, mkdirSync, existsSync } from "node:fs"
-import { join, resolve, relative } from "node:path"
-import { homedir } from "node:os"
-// §29 fix A（AGENT-LOOP.md §29——2026-09-07）：FILE_MUTATORS 的 mutation-seq 记账从
-// 批后提交（record-results noteMutations）移到执行成功即刻——唯一记账点（取代批后段
-// + agent.mjs 中断分支记账——不双计）——同消息 [写 + async advisor launch] 时 launch 前
-// 完成的写在 launchSeq 之前落地 → settle 不再误判 stale（§29 症状根因）。
-import { noteMutations } from "../agent-tools/advisor-async.mjs"
+import { isCodePath, loadProjectDeclaration } from "../conventions.mjs"
+import { resolve, relative } from "node:path"
 import { anyLiveDesignSlot } from "../token-ttl.mjs"
 // M4 写权门禁（模块设计 §2.1#2）：冻结窗口判据组装（被审文件集 = 声明文档集 + 批次档
 // 的合流点）落 write-gate.mjs 单一权威源——本档只 import 消费（KD-M4-4 拆分点）。
-import { freezeWindowConflict } from "./write-gate.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).
- */
-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）即控制类——否则只读类。
- */
-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"
-  }
-  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
-}
-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，单独谓词只接权限豁免位。
- */
-function isSubagentConsumeDesignAction(toolName, args) {
-  return toolName === "subagent" && args?.action === "consume-design"
-}
-function isSubagentEscalateAction(toolName, args) {
-  return toolName === "subagent" && args?.action === "escalate"
-}
-
-/**
- * §29 fix A — 唯一记账点：FILE_MUTATORS 工具执行成功即刻记 mutation seq（abs 路径）。
- * 取代 record-results 批后段 + agent.mjs 中断分支的 noteMutations（不双计——中断+同批
- * launch 场景 seq 单计，AGENT-LOOP.md §29 T-A1i）。调用时机 = 写执行成功（非 Error 前缀
- * 结果——recordPeerWrites 同款门）；routed（M2 ACP 客户端执行）成功同样记账。
- */
-function noteExecutedMutation(agent, tool, args) { 
-  let paths
-  try {
-    paths = tool.touchedPaths ? tool.touchedPaths(args ?? {}) : [args?.path]
-  } catch { return }
-  const abs = (paths ?? [])
-    .filter((p) => typeof p === "string" && p)
-    .map((p) => resolve(agent.cwd, p))
-  if (abs.length > 0) noteMutations(agent, abs)
-}
+import { freezeWindowConflict, batchRecordWriteConflict } from "./write-gate.mjs"
+// 门面谓词 ∕ 记账（2026-09-28 拆分外提——见头注）：动作级四谓词 + logToolError 住 ./dispatch-gates.mjs。
+import {
+  logToolError, isSubagentConsumeDesignAction, isSubagentEscalateAction,
+  readonlyActionOf, controlActionOf, // E1（§2.5）：工具面动作谓词钩子优先 ∕ 核名面谓词回落
+} from "./dispatch-gates.mjs"
+// 单条执行体（2026-09-28 拆分外提——见头注）：runPreparedItem（原 runOne 闭包；本档两处调用点改指）。
+import { runPreparedItem } from "./dispatch-run.mjs"
+// B7 3a：作用域规则 JIT 注入（核单源——`../rules.mjs`；相位一末打点见下方缝注释）。
+import { injectScopedRules } from "../rules.mjs"
 
 /**
  * Two-phase execution:
@@ -143,7 +34,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
   // ---- Phase 1: serial preparation ----
   // Pre-gates run per tool (parse/planMode/engineering gates); non-readonly tools
   // that REACH the permission stage are collected into one batch — a single merged
-  // ask covers the whole toolCalls array (§16 D-B1, "approve all / one by one /
+  // ask covers the whole toolCalls array (D-B1, "approve all / one by one /
   // deny"). Tools stopped by a pre-gate never join the batch (review #7).
   const prepared = []
   const permPending = [] // { toolCall, tool, args } — reached the permission stage
@@ -164,7 +55,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       continue
     }
 
-    if (agent.planMode && !tool.readonly && !isSubagentReadonlyAction(toolCall.name, args) && !isSubagentControlAction(toolCall.name, args)) {
+    if (agent.planMode && !tool.readonly && !readonlyActionOf(tool, toolCall.name, args) && !controlActionOf(tool, toolCall.name, args)) {
       prepared.push({ toolCall, tool, denied: true, reason: "plan mode" })
       continue
     }
@@ -186,11 +77,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     // before the design review passed. Signaled by a live design slot (design-review
     // approval — persists in the session slot, survives across turns; _engDesignReviewed
     // is eng-coder-only and reset per run). Exemptions = the non-code classes of
-    // src/conventions.mjs (documentation and temp scratch files) — writing a design
+    // thincoder-core/conventions.mjs (documentation and temp scratch files) — writing a design
     // document IS the design step. Anything inside a declared code segment (default:
     // src — incl. src/prompts/*.md) is product code, not documentation, and needs a
-    // design token. The project can declare its own code paths (.thincoder/
-    // conventions.json) so a non-src layout is not silently exempted. Mechanically
+    // design token. The project can declare its own code paths (the manifest's
+    // `codePaths`) so a non-src layout is not silently exempted. Mechanically
     // blocks "talk then code".
     // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：资格判据 = 权威槽"任一活槽存在"
     // （anyLiveDesignSlot——查内存 Map，miss 回读槽文件——单值镜像 `_engDesignToken`
@@ -198,8 +89,8 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     if (agent.config?.agent?.engineering && depth === 0
         && !anyLiveDesignSlot(agent)
         && FILE_MUTATORS.has(toolCall.name)) {
-      const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
-      const conv = loadConventions(agent.cwd)
+      const paths = toolTouchPaths(tool, args)
+      const conv = loadProjectDeclaration(agent.cwd)
       // Unknown/missing paths (non-string, e.g. no path argument) are treated
       // as code — cannot tell what they touch, so block conservatively. Known
       // paths go through the single shared classifier: a declared code segment
@@ -209,7 +100,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         // Undeclared project → point at the declaration file (§4.3 降级可见契约).
         const convNote = conv.declared
           ? ""
-          : ` — this path was classified as product code by the default conventions (code paths: ${conv.codePaths.join(", ")}); declare project conventions in .thincoder/conventions.json to adjust.`
+          : ` — this path was classified as product code by the default conventions (code paths: ${conv.codePaths.join(", ")}); declare project conventions in PROJECT-MANIFEST.json to adjust.`
         prepared.push({
           toolCall, tool, denied: true,
           reason: "engineering design gate",
@@ -219,20 +110,28 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       }
     }
 
-    // E（第 11 批·F17/§14.14 E-3d）：D5 冻结窗口写前拦截——设计评审在途（点火 → 结算）期间，
+    // E（第 11 批·F17/ADVISOR-GUARDS.md §5 E-3d）：D5 冻结窗口写前拦截——设计评审在途（点火 → 结算）期间，
     // 父侧对被审文件集（声明文档集 + 批次档）的写入会被拒绝：在途写使本轮结算 stale——pass 轮
-    // = token 直接丢失（实证：第 10 批 id=20 整轮作废）。工具面 = FILE_MUTATORS（与变更记账
-    // 同集——不记入日志的写面既不判 stale 也不拦）；判据与 reviewIsStale 同源、单一权威源 =
+    // = token 直接丢失（实证：第 10 批 id=20 整轮作废）。工具面 = FILE_MUTATORS ∪ `file_ops`
+    // （E2——冻结腿覆盖面；批次档腿仍 = FILE_MUTATORS：与变更记账同集——不记入日志的写面既不判 stale 也不拦）；判据与 reviewIsStale 同源、单一权威源 =
     // agent/write-gate.mjs 的 freezeWindowConflict（声明文档集腿 = inflightDesignReviewConflict
     // 同 docAbs / 同 normAbs；批次档腿 = run.batchDoc——M4 合流点，仅扫 running 未取消的设计条目）。
     // 位置：只读 / autoApprove 短路之前——审批不得绕过冻结；拒绝 = 可见 denied + 逃生门
     // （先 cancel → 改 → 重发）。
-    if (FILE_MUTATORS.has(toolCall.name)) {
-      let touched = []
-      try { touched = tool.touchedPaths ? tool.touchedPaths(args) : [args.path] } catch { touched = [] }
-      const absPaths = (touched ?? [])
+    if (FILE_MUTATORS.has(toolCall.name) || toolCall.name === "file_ops") {
+      // #327：单源谓词（同集合内两处消费共用）；#309 批次档写门与 D5 冻结窗同区、共用同一路径集。
+      // E2（parity-b1 §2.5——缺省取核形）：外门扩 `file_ops`（冻结窗覆盖面与端壳对齐——`file_ops`
+      // 的 move ∕ copy ∕ rename 亦为写面）；**批次档写门判据集不变**（= `FILE_MUTATORS`，file_ops 不入）。
+      const absPaths = toolTouchPaths(tool, args)
         .filter((p) => typeof p === "string" && p)
         .map((p) => resolve(agent.cwd, p))
+      if (FILE_MUTATORS.has(toolCall.name)) {
+        const crossBatch = batchRecordWriteConflict(agent, depth, absPaths)
+        if (crossBatch) {
+          prepared.push({ toolCall, tool, denied: true, reason: "cross-batch record write", hint: crossBatch.message })
+          continue
+        }
+      }
       const conflict = freezeWindowConflict(agent, absPaths)
       if (conflict) {
         prepared.push({
@@ -246,7 +145,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
 
     // Readonly tools (and autoApprove — the short-circuit, unchanged for the
     // whole batch too) skip the permission stage entirely.
-    // §18 D-E3 task-domain authorization (spawn-time): an eng-coder child's
+    // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 task-domain authorization (spawn-time): an eng-coder child's
     // tools skip the permission ASK stage exactly like autoApprove — granted by
     // the parent spawn (approved design + task = authorization; subagent.mjs
     // sets _engTaskAuthorized on the child). Everything EARLIER in Phase 1
@@ -254,7 +153,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     // — the exemption never widens what reaches this stage (round4 #3, T-E14).
     // PreToolUse hooks still run below. Non-eng-coder children keep the manual
     // parent ask (human in the loop).
-    if (tool.readonly || isSubagentReadonlyAction(toolCall.name, args) || isSubagentControlAction(toolCall.name, args) || isSubagentConsumeDesignAction(toolCall.name, args) || agent.autoApprove || agent._engTaskAuthorized) {
+    if (tool.readonly || readonlyActionOf(tool, toolCall.name, args) || controlActionOf(tool, toolCall.name, args) || isSubagentConsumeDesignAction(toolCall.name, args) || agent.autoApprove || agent._engTaskAuthorized) {
       if (!(await runHooks("PreToolUse", { agent, toolName: toolCall.name, toolArgs: args }))) {
         prepared.push({ toolCall, tool, denied: true, reason: "blocked by PreToolUse hook" })
         continue
@@ -267,7 +166,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     permPending.push({ toolCall, tool, args })
   }
 
-  // ---- Permission stage: one merged ask for the whole batch (§16 D-B1) ----
+  // ---- Permission stage: one merged ask for the whole batch (D-B1) ----
   // >1 non-readonly tools in the same toolCalls array → a single
   // onBatchPermissionRequest({ tools, count }) ask; verdicts:
   //   "approveAll" → batch-scope allowance (autoApprove style, NOT persistent)
@@ -292,7 +191,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       else if (batchAllowed === false) allowed = false
       else if (callbacks.onPermissionRequest) {
         allowed = await (async () => {
-          // D2 (AGENT-LOOP.md §7.2): announce the wait BEFORE prompting — the TUI
+          // D2 (AGENT-LOOP-SUBAGENT.md §6.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.
@@ -322,161 +221,20 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     }
   }
 
-  // ---- Phase 2: order-preserving execution ----
-  const runOne = async (item) => {
-    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"
-          ? `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)
-          // §29 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 对象提升为变量（§7.2.3）：subagent 阻塞 execute 返回前在 ctx 上留
-      // _subagentKey（relayPrefix 去尾）——runOne 在 execute 返回后读它作 onToolResult
-      // 第 4 参（普通工具/错误路径无此字段——undefined 兼容既有签名）。每次工具调用
-      // 独立 ctx——并行同名工具（批并行 runOne）各自带自己的 key，互不串扰。
-      const toolCtx = {
-        cwd: agent.cwd,
-        agent,
-        depth,
-        signal,
-        callbacks,
-        // §11.2 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)
-      }
-      // §29 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 so the model can reason about what went wrong
-      const ctxParts = []
-      if (item.args.path) ctxParts.push(`path=${item.args.path}`)
-      if (item.args.pattern) ctxParts.push(`pattern=${item.args.pattern}`)
-      if (item.args.command) ctxParts.push(`cmd=${item.args.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 }
-    }
+  // ---- B7 3a JIT 缝（相位一末 ∕ 相位二前——原 VSC「派发前」语义；`depth === 0` 门）--------
+  // 作用域规则注入：打点 = `prepared` 非拒项 `{tool, args}`（即将执行集）；注入源 = 本 run 尾块
+  // 读点缓存 `agent._rules.scoped`（核 `prepareRun` 同点写入），去重域 = 会话。子代不注入。
+  if (depth === 0) {
+    injectScopedRules(agent, agent.history, prepared.filter((p) => p.tool && p.args).map(({ tool, args }) => ({ tool, args })))
   }
 
+  // ---- Phase 2: order-preserving execution ----
+
   const results = []
   let batch = []
   const flush = async () => {
     if (batch.length === 0) return
-    results.push(...await Promise.all(batch.map(runOne)))
+    results.push(...await Promise.all(batch.map((item) => runPreparedItem(item, agent, depth, signal, callbacks))))
     batch = []
   }
   for (const item of prepared) {
@@ -486,11 +244,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     if (item.tool && !item.tool.readonly
         && (!item.tool.parallel || isSubagentEscalateAction(item.tool.name, item.args))) {
       await flush()
-      results.push(await runOne(item))
+      results.push(await runPreparedItem(item, agent, depth, signal, callbacks))
     } else {
       batch.push(item)
     }
   }
   await flush()
   return results
-}
+}

package/agent/family-tools.mjs

@@ -13,7 +13,7 @@
  *
  * 登记册**动态**载入：`agent-tools.mjs` 静态图经 consult/subagent 族可达核 agent 栈
  * （`../agent/setup.mjs` → `../memory.mjs` → `node:sqlite`）——静态引入会破端壳 W8 契约②
- * （`thincoder-vscode/test/engine-floor-guard.test.mjs`：端壳静态链不得到达 `node:sqlite`）。
+ * （W8 契约②判据（现载体 = 批件 `docs/batches/2026-09-29-residuals-round2.test.mjs`；单测树重建时回迁端侧单测档）：端壳静态链不得到达 `node:sqlite`）。
  * 核内先例 = 登记册头注「Loaded from agent.mjs via dynamic import to avoid ESM circular
  * dependencies」（本档先于 `agent/setup.mjs` 的调用点载入，同一语义）。
  */
@@ -77,7 +77,7 @@ export async function assembleFamilyTools({
     },
   } : subagentTool
 
-  // §18 D-E3 + ENGINEERING-MODE.md §2.15 D（第 2 批——参数化复用，不并列第二个 IIFE）：
+  // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 + ENGINEERING-MODE.md §2.15 D（第 2 批——参数化复用，不并列第二个 IIFE）：
   // 工程子代理（depth>0；eng-coder = 偏差审计 / eng-designer = 自己勘察）get a restricted
   // spawn channel — role enum limited to explore, NO async parameter (sync only) and action
   // pinned to spawn（AGENT-LOOP-SUBAGENT.md §6.7 D-M3 restricted-variant action gate——escalate/check/status are
@@ -132,7 +132,7 @@ export async function assembleFamilyTools({
   // consult 工具仅在配置时注册（consultModels 空池时注册会让模型调用后吃一个错误回合）——
   // AGENT-LOOP-SUBAGENT.md §6.7: escalate 已并入常驻 subagent 的 action:"escalate"（无空池注册问题——动作在
   // 池空时返回既有错误语义，工程模式 fail-closed 在 execute 内拒绝）。
-  // §25 D-R17a: consult_check 已退役（digest 自动注入是唯一消费通道）——consult 家族
+  // CONSULTATION.md §6.2 D-R17a: consult_check 已退役（digest 自动注入是唯一消费通道）——consult 家族
   // 只剩 2 工具（consult_start/consult_stop——setup 注册点与描述面同步清零）。
   const consultTools = consultModels.length
     ? [decorate?.consultStart ?? withPool(consultStartTool), decorate?.consultStop ?? consultStopTool]
@@ -155,12 +155,12 @@ export async function assembleFamilyTools({
     // the system prompt names verify (system.md) and advisor (discipline.md) — without them an
     // escalate hit "unknown tool" and fell back to bash node --check / npm test to
     // self-verify (2026-08-16 deepseek escalate diagnosis; plugin parity).
-    // eng-coder: advisor + verify + the §18 audit-only subagent channel (D-E3).
+    // eng-coder: advisor + verify + the AGENT-LOOP-SUBAGENT.md §6.7.6 audit-only subagent channel (D-E3).
     // eng-designer (§2.15 D): the survey-only subagent channel alone — no advisor
     // (it does not fire reviews) and no verify (its deliverable is documents, not code).
     // BATCH-RECORD §4.3 挂载表（批次档生命周期工具化批）：eng 两分支各挂主名 `batch`
     // （绑定段 append/status；目标 = spawn 绑定 `child._batchDoc`）——BATCH-RECORD.md §4.2 的 batch_segment
-    // 挂载形态已随单名化收口退役（过渡别名 §4.14 不入生产挂载面）；depth-0 主 agent 同表挂载
+    // 挂载形态已随单名化收口退役；depth-0 主 agent 同表挂载
     // `batch`（D-BR18 扩权——create/close + append §1/§4/§6 + status §1（轮 2 裁定②：§4/§6
     // 状态面走普通文档写），目标走可选 path / 在飞扫描）。
     // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 装配接线）：子代理上行通道

package/agent/helpers.mjs

@@ -85,6 +85,38 @@ const MAX_GIT_CHANGES_DISPLAY = 20
 export const OUTLINE_INJECT_PREFIX = "[System reminder: project dependency outline:"
 export const FILE_MUTATORS = new Set(["write", "edit", "insert_after", "apply_patch", "delete", "hashline_edit"])
 
+/**
+ * 工具自报触达面提取**单源谓词**（`docs/core/design/TOOLS.md` §6.17 / D-TO12——批 GUARD-SCHEDULER ·
+ * 台账 #327）：与 `FILE_MUTATORS` 同址（门禁 / 变更记账 / L3 足迹 / 作用域规则四条面的公共输入）。
+ * 契约（恒数组 · 恒零抛）：
+ * - `args` 为 null **或非对象** ⇒ 一律规范化为 `{}` 再交钩子；
+ * - 有钩子 ⇒ **钩子裁决**；无钩子 ⇒ `file_ops` **动作感知**（D-TO13 · 台账 #333）——`action === "copy"`
+ *   ⇒ `[args.dest]`（源仅读取，不属写域）；`move` / `rename` / 未知或缺失 `action` ⇒ `[args.source,
+ *   args.dest]`（保守双算）；其余工具单参兜底（形态零变——缺 path 同样返含 `undefined` 的单元素
+ *   数组，由消费方按「未知路径 ⇒ 保守」自行判定）；
+ * - 钩子 throw / 返回非数组 ⇒ `[]`；
+ * - **不过滤非字符串项**（未知路径的保守判据归门禁自身——`thincoder-cli/test/portability-classification.test.mjs`
+ *   T-22 语义零变）。
+ * @param {Object|undefined} tool — 工具对象（可选钩子 `touchedPaths(args)`）
+ * @param {unknown} args — 工具入参（畸形入参不抛）
+ * @returns {unknown[]} 触达路径候选（可能含非字符串项——消费方过滤）
+ */
+export function toolTouchPaths(tool, args) {
+  const a = args && typeof args === "object" ? args : {}
+  const hook = tool?.touchedPaths
+  if (typeof hook !== "function") {
+    if (tool?.name === "file_ops") return a.action === "copy" ? [a.dest] : [a.source, a.dest]
+    return [a.path]
+  }
+  try {
+    const out = hook(a)
+    return Array.isArray(out) ? out : []
+  } catch {
+    return []
+  }
+}
+
+
 /** Escape XML special characters in a string for safe embedding in XML/HTML */
 export function escapeXml(s) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;")
@@ -342,9 +374,18 @@ export function readonlyToolNames(tools) {
  *  the repo: the shell-side depth>0 filter consumes this set (design = TOOLS.md §6.16 / D-TO11). */
 export const SUBAGENT_TOOL_EXCLUSIONS = new Set(["question"])
 
-/** Apply the depth>0 exclusion set — always returns a NEW array (parent table untouched). */
+/** Apply the depth>0 exclusion set — always returns a NEW array (parent table untouched).
+ *  #9（TOOLS.md §6.19）：`bash` 的 `async` 参仅 depth-0——子代副本删参（照 `family-tools.mjs:98`
+ *  先例；返回值仍恒新数组、未命中条目原对象直传）。运行期第二道在 `tools/bash.mjs` execute
+ *  （照 `read_image`「schema 门 + 运行期第二道」双线先例）。 */
 export function excludeSubagentTools(tools) {
-  return tools.filter((t) => !SUBAGENT_TOOL_EXCLUSIONS.has(t.name))
+  return tools
+    .filter((t) => !SUBAGENT_TOOL_EXCLUSIONS.has(t.name))
+    .map((t) => {
+      if (t.name !== "bash" || !t.parameters?.properties || !("async" in t.parameters.properties)) return t
+      const { async: _asyncDrop, ...restProps } = t.parameters.properties
+      return { ...t, parameters: { ...t.parameters, properties: restProps } }
+    })
 }
 
 const MAX_INSTRUCTION_CHARS = 32_000
@@ -384,7 +425,7 @@ export async function loadProjectInstructions(cwd) {
 
 /** Engineering mode reminder — shared with eng.mjs tool. */
 export const ENG_ON_REMINDER =
-  "[System reminder: engineering mode is ON — design-before-code enforced. " +
+  "[System reminder: engineering mode is ON (session-scoped) — design-before-code enforced. " +
   "Workflow: Requirements doc → Design doc → advisor(type='design') → " +
   "user approval → eng-coder implementation. Code changes go through eng-coder " +
   "subagents only. Advisor calls are NOT per-turn-mandatory — call only at " +
@@ -418,6 +459,15 @@ export const AUTO_TURN_DIGEST_DOMAIN_ENG =
 export const UPSTREAM_TURN_DOMAIN =
   "[System reminder: auto-turn — a running subagent sent you an in-flight message (shown below). No user message is waiting. Decide it now and reply with subagent action:'send' (id + message) — the child consumes the reply at its next turn boundary and keeps working on the unaffected parts; if the message needs no answer, say so in one line and move on. If finished subagent reports are also present above, summarize them as usual in the same turn. Do not start new work: FORBIDDEN this turn (mechanically enforced): modifying files, bash/execute/verify, spawning subagents, asking questions — those need a real user message. End the turn once the reply is sent.]"
 
+/** Timer wake-turn domain (AGENT-LOOP-ASYNC-POOL.md §6.30.3 D-TW4): a pending timer
+ *  expired while the session was idle and the end's latch opened this turn automatically —
+ *  neither the digest domain ("no one is waiting", organize-only) nor the up-stream domain
+ *  (a subagent waiting for a reply) fits: the timer's own semantics is "act on what the
+ *  timer was for". Verbatim from the parent-side final text (single line — no newlines).
+ *  Content authority = parent side. */
+export const TIMER_TURN_DOMAIN =
+  "[System reminder: auto-turn — a timer you set earlier has expired (reminder above). No user message is waiting. Act on what the timer was for now: pull the data or run the check rather than continuing to reason in the abstract. Stay within the work that was in flight when the timer was set; do not open unrelated new work. Wrap up as soon as the action is done or blocked.]"
+
 /** Engineering-mode status injection — one reminder on EVERY transition (2026-08-25:
  *  OFF is announced too — the model must know the gates lifted; silence after /eng-off
  *  left it guessing. Covers TUI /eng, resume, and any path bypassing the eng tool.) */