thincoder 0.12.58 → 0.12.59

package/src/advisor.mjs

@@ -45,12 +45,13 @@ import { readFileSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { extractAgentResponseTable } from "./advisor/history.mjs"
-import { buildAdvisorUserMessage, resolveScopeFiles } from "./advisor/messages.mjs"
+import { buildAdvisorUserMessage, resolveScopeFiles, buildObjectDeclarationBlock } from "./advisor/messages.mjs"
 import { buildConvergenceBody } from "./advisor/convergence.mjs"
 import { escapeLiteralEscapes } from "./escape.mjs"
 // Re-export for run.mjs and tests (keeps their imports from "../advisor.mjs" stable)
 export { ADVISOR_MD_PATH, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
 export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
+export { buildObjectDeclarationBlock } from "./advisor/messages.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -135,13 +136,15 @@ 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
+ *   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
  *   '['-prefixed content as structured data / expand escapes) when no prior
  *   review exists at all (caller misuse; the response-table extraction would
  *   otherwise scan history from index 0 and could match an unrelated stale table)
  */
-export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
+export function buildAdvisorFollowUp(agent, prior, scopeFiles = null, object = null) {
   // Convergence follow-up REQUIRES a prior review record — the full output of
   // the last review, injected VERBATIM (decision 2026-08-08: the model
   // understands the review output; no table/header/phrase parsing). The caller
@@ -164,7 +167,9 @@ export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
     : "(Agent did not provide a response table — perform a fresh full review; the review surface is unknown, ask the user for the file list)"
   const response = extractAgentResponseTable(agent.history) || noResponseFallback
   const round = (agent._advisorRound || 0) + 1
-  return buildConvergenceBody(p, response, round, scopeFiles)
+  // Review-object declaration FIRST (T-OA2 — round 2+ stays anchored, no re-archaeology).
+  const declaration = buildObjectDeclarationBlock(object)
+  return (declaration ? declaration + "\n" : "") + buildConvergenceBody(p, response, round, scopeFiles)
 }
 
 /**
@@ -187,8 +192,11 @@ 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
+ *   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.
  */
-export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null) {
+export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null) {
   // Deterministic convergence state (decision 2026-08-08): round 2+ requires
   // _advisorRound > 0 AND a stored prior review output. No history parsing.
   // priorParam (direct callers) wins over the stored output — same derivation
@@ -201,7 +209,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)) },
+      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object)) },
     ]
   }
 
@@ -226,7 +234,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
       agent._advisorRound = 0
     }
     // Mutations exist → KEEP the round (cap keeps advancing through retries).
-    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)
+    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object)
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
       {
@@ -257,6 +265,6 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   const scopeFiles = resolveScopeFiles(agent, paths)
   return [
     { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-    { role: "user", content: escapeLiteralEscapes(buildAdvisorFollowUp(agent, prior, scopeFiles)) },
+    { role: "user", content: escapeLiteralEscapes(buildAdvisorFollowUp(agent, prior, scopeFiles, object)) },
   ]
 }

package/src/agent/dispatch.mjs

@@ -1,6 +1,7 @@
 /**
  * agent/dispatch.mjs — two-phase tool call execution
  */
+import { logEvent, errText, headText } from "../log.mjs"
 import { offloadToolResult, FILE_MUTATORS } from "./helpers.mjs"
 import { runHooks } from "../hooks.mjs"
 import { snapshotForUndo } from "../tui/cmd-undo.mjs"
@@ -37,6 +38,55 @@ function logToolError(toolName, args, error) {
   }
 }
 
+/**
+ * §19 action-level classification (AGENT-LOOP.md §19 D-M1): the merged subagent
+ * tool expresses spawn (side effect) and check/status (read-only queries) through
+ * its `action` parameter — the tool-level readonly flag can no longer express both.
+ * dispatch Phase-1/Phase-2 classifies per action: check/status behave 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).
+ * §19.5 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 放行).
+ * §19.6 panel (round1 #5): view 面归只读类（同 check/status——planMode 放行、免
+ * 审批、可批并行）；freeze 面归控制类（同 cancel——planMode 放行、免权限审批、
+ * 批审批不入组、digest 内放行）。freeze 存在（非空 key）即控制类——否则只读类。
+ */
+function isSubagentReadonlyAction(toolName, args) {
+  // §6 memory 工具面重构（MEMORY.md §6 D-M5）：memory search/list 是只读动作——与
+  // subagent check/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
+  if (action === "check" || action === "status") return true
+  // §19.6 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
+  // §19.6 panel freeze 面（D-P3 门控在 executor——只读/控制分类在此）
+  if (args?.action === "panel" && args.freeze !== undefined && args.freeze !== null && String(args.freeze) !== "") return true
+  return false
+}
+function isSubagentEscalateAction(toolName, args) {
+  return toolName === "subagent" && args?.action === "escalate"
+}
+
 /**
  * Two-phase execution:
  * Phase 1 (serial): parse args one by one + planMode check + permission confirmation (side-effecting tools)
@@ -69,7 +119,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       continue
     }
 
-    if (agent.planMode && !tool.readonly) {
+    if (agent.planMode && !tool.readonly && !isSubagentReadonlyAction(toolCall.name, args) && !isSubagentControlAction(toolCall.name, args)) {
       prepared.push({ toolCall, tool, denied: true, reason: "plan mode" })
       continue
     }
@@ -113,7 +163,15 @@ 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.
-    if (tool.readonly || agent.autoApprove) {
+    // §18 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
+    // (JSON parse / unknown tool / planMode / design-token gates) ran unchanged
+    // — 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) || 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
@@ -203,6 +261,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     // 捕获分离（父恢复原始后子的拦截期间父捕获停止、子恢复后父继续）——正确。
     // 声明在 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 {
       // Snapshot for undo before side-effect tools (setupOutputPanel already fired in Phase 1)
       if (!item.tool?.readonly && item.args) {
@@ -214,6 +277,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
         if (routed?.handled) {
           callbacks.onToolResult?.(item.toolCall.name, routed.result, item.toolCall.id)
+          logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(routed.result, 200), child: agent?._logId })
           return { ...item, result: routed.result, ok: true }
         }
       }
@@ -222,17 +286,22 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       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,
+        onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk, item.toolCall.id),
+        onQuestion: callbacks.onQuestion,
+        onPermissionRequest: callbacks.onPermissionRequest,
+      }
       try {
-        rawResult = await item.tool.execute(item.args, {
-          cwd: agent.cwd,
-          agent,
-          depth,
-          signal,
-          callbacks,
-          onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk, item.toolCall.id),
-          onQuestion: callbacks.onQuestion,
-          onPermissionRequest: callbacks.onPermissionRequest,
-        })
+        rawResult = await item.tool.execute(item.args, toolCtx)
       } finally {
         console.log = origConsoleLog
         console.error = origConsoleErr
@@ -247,9 +316,10 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       const resultWithConsole = capturedConsole.length > 0
         ? `${result}\n[console during ${item.toolCall.name}]\n${capturedConsole.join("\n")}`
         : result
-      callbacks.onToolResult?.(item.toolCall.name, resultWithConsole, item.toolCall.id)
+      callbacks.onToolResult?.(item.toolCall.name, resultWithConsole, 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(resultWithConsole, 200), child: agent?._logId })
       return { ...item, result: resultWithConsole, 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)
@@ -259,6 +329,9 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       // 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 = []
@@ -282,7 +355,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     batch = []
   }
   for (const item of prepared) {
-    if (item.tool && !item.tool.readonly && !item.tool.parallel) {
+    // escalate action keeps the retired escalate tool's serial placement (no
+    // parallel flag): it flushes the batch and runs alone in call order (§19 —
+    // spawn stays parallel; check/status classify as readonly and batch freely).
+    if (item.tool && !item.tool.readonly
+        && (!item.tool.parallel || isSubagentEscalateAction(item.tool.name, item.args))) {
       await flush()
       results.push(await runOne(item))
     } else {

package/src/agent/helpers.mjs

@@ -33,7 +33,9 @@ export const REPORT_CONTINUATION =
   "4. Anything left undone or worth follow-up"
 
 const TOOL_RESULT_OFFLOAD_LIMIT = 64 * 1024 // 65536 chars — offload only above 64K (2026-08-24)
-const TOOL_RESULT_PREVIEW = 64 * 1024 // chars shown inline when offloaded (aligns with CLI/VS Code webview)
+const TOOL_RESULT_PREVIEW = 64 * 1024 // total preview budget: head + middle note + tail ≤ 65536 (aligns with CLI/VS Code webview)
+const TOOL_RESULT_PREVIEW_HEAD = 16 * 1024 // head slice preserved (2026-09-04 §5 — dual-end preview)
+const TOOL_RESULT_PREVIEW_TAIL = 48 * 1024 // nominal tail slice (results/errors/stats live here — actual tail = budget remainder, see buildDualEndPreview)
 
 /** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
  *  高代理（如 🔴=U+D83D+DD34 只剩 D83D）——deepseek 解析器严格 UTF-16 报 400
@@ -46,6 +48,33 @@ function safeSliceUTF16(text, max) {
   return text.slice(0, max)
 }
 
+/** UTF-16 safe END slice (2026-09-04 §5 dual-end preview — review #5: both boundaries must not split
+ *  a surrogate pair). Same rule as safeSliceUTF16, mirrored: if the slice START lands on a LOW
+ *  surrogate (DC00-DFFF — the second half of a pair whose high half sits just before the boundary),
+ *  advance one code unit so the slice never begins with an orphan low surrogate. */
+function safeSliceUTF16End(text, max) {
+  if (text.length <= max) return text
+  const start = text.length - max
+  const cp = text.charCodeAt(start)
+  if (cp >= 0xdc00 && cp <= 0xdfff) return text.slice(start + 1)
+  return text.slice(start)
+}
+
+/** Dual-end preview (design §5 D-4.1): head + middle-omitted note + tail — the tail carries
+ *  results/errors/stats that a pure-head truncation would cut off.
+ *  Budget (round1 review #2, fixed): head + note + tail ≤ TOOL_RESULT_PREVIEW (65536) — tail is
+ *  computed from constants (tail = TOOL_RESULT_PREVIEW − head − noteLen), never hardcoded.
+ *  The note length depends on the omitted digit count; text.length's digit count is an upper bound
+ *  for omitted (< text.length), so budgeting with it keeps the total ≤ 65536 while the printed
+ *  note reports the actual omitted count. Both boundaries run surrogate-safe slices (review #5). */
+function buildDualEndPreview(text) {
+  const head = safeSliceUTF16(text, TOOL_RESULT_PREVIEW_HEAD)
+  const noteFn = (omitted) => `\n\n… [middle omitted: ${omitted} chars] …\n\n`
+  const tailLen = Math.min(TOOL_RESULT_PREVIEW_TAIL, TOOL_RESULT_PREVIEW - TOOL_RESULT_PREVIEW_HEAD - noteFn(text.length).length)
+  const tail = safeSliceUTF16End(text, tailLen)
+  return head + noteFn(Math.max(0, text.length - head.length - tail.length)) + tail
+}
+
 /** Offload-dir write-time self-cleanup retention window (2026-08-21): files older than 3 days are deleted on the next offload. */
 export const TMP_RETENTION_MS = 3 * 24 * 3600 * 1000
 
@@ -88,7 +117,8 @@ export async function cleanupOldToolResults(dir) {
   }
 }
 
-/** Offload oversized tool results (>64K chars) to disk, returning a preview + file path.
+/** Offload oversized tool results (>64K chars) to disk, returning a head+tail preview + file path
+ *  (2026-09-04 §5 — dual-end preview; the failed-offload fallback uses the same dual-end slice).
  *  Writes trigger write-time self-cleanup of the offload dir first (dir param overridable for tests). */
 export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results")) {
   if (text.length <= TOOL_RESULT_OFFLOAD_LIMIT) return text
@@ -98,12 +128,13 @@ export async function offloadToolResult(text, callId, dir = join(configDir, "too
     const file = join(dir, `${Date.now()}-${String(callId).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
     await writeFile(file, text, "utf8")
     return (
-      safeSliceUTF16(text, TOOL_RESULT_PREVIEW) +
+      buildDualEndPreview(text) +
       `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
       `Page through it with the read tool (offset/limit) or sed -n 'START,ENDp' — do NOT re-run the tool blindly.]`
     )
   } catch {
-    return safeSliceUTF16(text, TOOL_RESULT_OFFLOAD_LIMIT) + `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
+    // review #3: fallback uses the same dual-end slice (head + omitted note + tail, no path hint)
+    return buildDualEndPreview(text) + `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
   }
 }
 

package/src/agent/setup.mjs

@@ -36,7 +36,7 @@ function safeSliceUTF16(text, max) {
 const MEMORY_SEARCH_LIMIT = 3
 
 /** Build engineering-mode system prompt by reading METHODOLOGY.md and wrapping it in the engineering template */
-async function buildEngineeringPrompt(cwd, role) {
+export async function buildEngineeringPrompt(cwd, role) {
   const engFile = role === "eng-coder" ? "engineering-sub.md" : "engineering.md"
   const engTemplatePath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "prompts", engFile)
   let engTemplate = ""
@@ -49,8 +49,17 @@ async function buildEngineeringPrompt(cwd, role) {
   const methodologyPath = resolve(cwd, "METHODOLOGY.md")
   if (!existsSync(methodologyPath)) {
     // Template-only — engineering constraints stay active, minus project rules.
-    // The caller injects a warning into the history.
-    return { prompt: engTemplate || null, templateMissing, methodologyMissing: true }
+    // The caller injects a warning into the history. Resolve the built-in
+    // methodology template to an absolute path (same-source join as the
+    // engineering template above — the packaged path is unreachable from the
+    // user's cwd) and carry its body so the warning can embed it verbatim
+    // (2026-09-02 D-M1/D-M2: template reachability for the model).
+    const methodologyTemplatePath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "prompts", "methodology-template.md")
+    let methodologyTemplateBody = null
+    try { methodologyTemplateBody = readFileSync(methodologyTemplatePath, "utf8") } catch {
+      // Template unreadable (packaging) — degraded: base warning only (no path/body injected), same as VS Code.
+    }
+    return { prompt: engTemplate || null, templateMissing, methodologyMissing: true, methodologyTemplatePath, methodologyTemplateBody }
   }
   const methodology = readFileSync(methodologyPath, "utf8")
   const prompt = engTemplate
@@ -178,13 +187,13 @@ export async function prepareRun(agent, input, callbacks, {
 
   // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
   // eng-coder subagents get advisor for mandatory design review before coding
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool } = await import("../agent-tools.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool } = await import("../agent-tools.mjs")
   const { consultStartTool, consultCheckTool, consultStopTool } = await import("../agent-tools/consult.mjs")
-  const { subagentCheckTool } = await import("../agent-tools/subagent-check.mjs")
-  const { escalateTool } = await import("../agent-tools/escalate.mjs")
   const { CONSULT_BASE } = await import("../agent.mjs")
-  // withPool: decorate consult_start/escalate descriptions with the CURRENT candidate pool
-  // so the model knows which models it can pick (CLI parity with the plugin).
+  // withPool: decorate the consult_start description with the CURRENT candidate pool
+  // so the model knows which models it can pick (CLI parity with the plugin). The
+  // retired escalate tool surface is now the subagent action:"escalate" — its pool
+  // list is decorated onto the action property description below (same intent).
   const withPool = (tool) => {
     const models = agent.config?.agent?.consultModels ?? []
     const list = models.map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ")
@@ -211,28 +220,82 @@ export async function prepareRun(agent, input, callbacks, {
       properties: {
         ...subagentTool.parameters.properties,
         role: { ...subagentTool.parameters.properties.role, ...subagentRoles },
+        // §19: escalate 动作的候选池 = consultModels（缺省池首 / 指定 provider:model）。
+        // 池装饰挂在 action 属性描述（原 escalate 工具注册时 withPool 同款意图——模型
+        // 需要知道可选候选人）。escalate 在工程模式禁用——装饰只对正常模式有意义。
+        action: (agent.config?.agent?.consultModels?.length && !agent.config?.agent?.engineering)
+          ? {
+              ...subagentTool.parameters.properties.action,
+              description: subagentTool.parameters.properties.action.description +
+                `\nCurrently configured escalate candidates (agent.consultModels pool): ${agent.config.agent.consultModels.map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ")}`,
+            }
+          : subagentTool.parameters.properties.action,
       },
     },
   } : subagentTool
 
-  // Consult/escalate tools registered only when configured — an unconfigured pool would
-  // otherwise make the model call them and eat an error turn (plugin parity).
-  // escalate is fail-closed in engineering mode (execute() rejects there) — registering it
-  // anyway would hand the model a tool that is guaranteed to eat an error turn.
+  // §18 D-E3: eng-coder children (depth>0) get an audit-only subagent channel —
+  // role enum limited to explore, NO async parameter (sync only) and action pinned
+  // to spawn (§19 D-M3 restricted-variant action gate — escalate/check/status are
+  // refused here at the schema level too; the mechanical re-check lives in
+  // subagent.mjs execute → the §19 action gate + gateEngCoderSpawn (spawn-child.mjs)
+  // — schema enums are advisory, providers don't enforce them).
+  const engAuditSubagent = depth > 0 && agent._role === "eng-coder"
+    ? (() => {
+        const props = { ...subagentTool.parameters.properties }
+        // §19 review hygiene: the audit channel is spawn-only sync explore — drop
+        // async, the check/status params (id/n) and the eng-coder token params
+        // (designToken/designId are meaningless for a read-only audit spawn; the
+        // parent spawn already carried the token). Schema noise would invite the
+        // model to pass irrelevant args.
+        delete props.async // sync only — the eng-coder blocks on the audit report
+        delete props.id
+        delete props.n
+        delete props.designToken
+        delete props.designId
+        props.role = {
+          type: "string",
+          enum: ["explore"],
+          description: "explore only — the eng-coder's internal spawn channel is reserved for read-only divergence audits (AGENT-LOOP.md §18 D-E3).",
+        }
+        props.action = {
+          type: "string",
+          enum: ["spawn"],
+          description: "spawn only — the eng-coder's internal spawn channel is reserved for read-only divergence audits (AGENT-LOOP.md §19 D-M3); escalate/check/status are refused (escalate spawns a coder+WRITE child — against explore-only intent; check/status have no async pool in a child context).",
+        }
+        return {
+          ...subagentTool,
+          name: "subagent",
+          description: "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design (AGENT-LOOP.md §18 D-E2 ③): it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/check/status are not available (AGENT-LOOP.md §19). The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch).",
+          parameters: { ...subagentTool.parameters, properties: props },
+        }
+      })()
+    : null
+
+  // consult 工具仅在配置时注册（consultModels 空池时注册会让模型调用后吃一个错误回合）——
+  // §19: escalate 已并入常驻 subagent 的 action:"escalate"（无空池注册问题——动作在
+  // 池空时返回既有错误语义，工程模式 fail-closed 在 execute 内拒绝）。
   const consultModels = agent.config?.agent?.consultModels ?? []
-  const engineering = agent.config?.agent?.engineering
   const consultTools = consultModels.length
-    ? [withPool(consultStartTool), consultCheckTool, consultStopTool, ...(engineering ? [] : [withPool(escalateTool)])]
+    ? [withPool(consultStartTool), consultCheckTool, consultStopTool]
     : []
-  const depthOnly = depth === 0 ? [filteredSubagent, subagentCheckTool, skillTool, goalTool, engTool, verifyTool, recentChangesTool, advisorTool, ...consultTools]
-    // Write-permission coder sub-agents (subagent role="coder" + escalate): the
-    // system prompt names verify (system.md) and advisor (discipline.md) — without them an
+  const depthOnly = depth === 0 ? [filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, readHistoryTool, advisorTool, ...consultTools]
+    // SESSION.md §9 D-S2: read_history is depth-0 ONLY — a subagent querying "the session"
+    // would mix its throwaway context with the parent's record (semantic confusion).
+    // It is readonly:true, so planMode pass and no permission ask come automatically (T-S9).
+    // Write-permission coder sub-agents (subagent role="coder" + escalate action):
+    // 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).
-    : agent._role === "eng-coder" ? [advisorTool, verifyTool]
+    // eng-coder: advisor + verify + the §18 audit-only subagent channel (D-E3).
+    : agent._role === "eng-coder" ? [advisorTool, verifyTool, ...(engAuditSubagent ? [engAuditSubagent] : [])]
     : agent._role === "coder" ? [verifyTool, advisorTool]
     : agent._role === "consult" ? [recentChangesTool]
     : []
+  // NOTE: every depth-0 tool schema is estimated into the compaction overhead per turn
+  // (context.mjs extras.tools) — a tool-schema change shifts the compaction fixture
+  // knife-edges (agent.test T3b: read_history's schema +~470 tokens once crossed its
+  // 11000 threshold; fixture adjusted to 12500 — rationale in the test comment).
   const tools = [...agent.tools, taskTool, planTool, timerTool, ...depthOnly]
   const toolSchemas = tools.map(toOpenAISchema)
   const toolByName = new Map(tools.map((t) => [t.name, t]))
@@ -264,7 +327,15 @@ 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 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.")
+        let warning = "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; if the user confirms, write cwd/METHODOLOGY.md before designing."
+        // 2026-09-02 D-M1/D-M2 (template accessibility): absolute path + full body — the model
+        // can read the template directly instead of hand-writing one from an unreachable source
+        // path. Body read failure → degraded warning above (path/body not injected). VS Code
+        // setup-reminders.mjs parity (两端警告文本一致，本端以 CLI 为准).
+        if (engResult.methodologyTemplateBody) {
+          warning += `\n\nbuilt-in template（可 read ${engResult.methodologyTemplatePath} 或直接参考以下内容）:\n\n${engResult.methodologyTemplateBody}`
+        }
+        warnings.push(warning)
       }
       if (warnings.length > 0) {
         agent.history.push({

package/src/agent/spawn-child.mjs

@@ -26,6 +26,31 @@ const RS = "\x1e"
  *  单源化（2026-08-30 评审）：文案演进只改这里，消除文案与检测正则的漂移面。 */
 export const TURN_CAP_MARK = "stopped: turn cap reached"
 
+/**
+ * §18 D-E3 eng-coder 内部 spawn 机械门（AGENT-LOOP.md §18 D-E2 round5 #2 后备）：
+ * eng-coder 子代理（depth>0 且 parent._role==="eng-coder"）的内部 spawn 通道只做
+ * 偏差审计——role 仅 explore、async 强制同步；审计 spawn 预算 = 首审 1 + 修正轮
+ * ≤5 的再审（第 7 次审计 spawn 机械拒绝——5 轮纪律失效时不静默，错误即 stalled
+ * 信号）。返回 null = 非 eng-coder 上下文（不加限制）；返回审计尝试序号 = 通过。
+ * schema 层过滤（setup.mjs 受限变体）只是给模型的参数提示——本函数是机械强制。
+ */
+export const ENG_AUDIT_SPAWN_LIMIT = 6 // 允许 6 次审计 spawn；第 7 次拒绝
+export function gateEngCoderSpawn(parent, depth, role, async) {
+  if ((depth ?? 0) <= 0 || parent?._role !== "eng-coder") return null
+  if (role !== "explore") {
+    throw new Error("eng-coder subagents may only spawn role='explore' — internal spawns exist solely for the read-only divergence audit (AGENT-LOOP.md §18 D-E3)")
+  }
+  if (async === true) {
+    throw new Error("eng-coder internal spawns are sync-only — the audit report must return before the next protocol step; async spawn is only available at the top level (AGENT-LOOP.md §18 D-E3)")
+  }
+  const attempt = (parent._engAuditSpawns ?? 0) + 1
+  if (attempt > ENG_AUDIT_SPAWN_LIMIT) {
+    throw new Error("correction-round limit exceeded — deliver a stalled report (AGENT-LOOP.md §18: max 5 fix rounds; the 7th audit spawn is refused mechanically)")
+  }
+  parent._engAuditSpawns = attempt
+  return attempt
+}
+
 /**
  * 构造 relay 前缀 + 发送 `[model]` 元数据 token（显示层据此更新区块头部，
  * 不进内容流）。counter 挂在 parent agent 上，多轮/并行子代理互不冲突。

package/src/agent-tools/advisor.mjs

@@ -77,11 +77,26 @@ export const advisorTool = {
     "For design review: single-pass review against methodology and requirements. " +
     "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
     "After the review, you MUST produce a response table (see discipline rules for format). " +
-    "If advisor says all clear, call verify.",
+    "If advisor says all clear, call verify. " +
+    "Optionally pass object={type,target,status,reason,exclude} to anchor the review target " +
+    "(AGENT-LOOP.md §18.8 — the review-object declaration is mechanically injected into the review message); " +
+    "absent → legacy behavior (no injection). " +
+    "Returns the review report — the advisor's findings verdict: all-clear (call verify) or a findings list to fix.",
   parameters: {
     type: "object",
     properties: {
       type: { type: "string", enum: ["code", "design"], description: "Review type: 'design' for design doc review, 'code' for code review (default)" },
+      object: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "Review type as declared by the caller (design/code)" },
+          target: { type: "string", description: "Review target — document + section, or file(s)" },
+          status: { type: "string", description: "Object state: 待评审 / 已批准 / 已实现 (pending-review / approved / implemented)" },
+          reason: { type: "string", description: "Why this review runs: user-initiated / delivery verification" },
+          exclude: { type: "string", description: "Explicit exclusion list — approved/implemented items NOT in this review" },
+        },
+        description: "Review-object declaration (§18.8): mechanically injected at the start of the review user message so the advisor does not re-derive the review target. Absent → no injection (legacy behavior).",
+      },
       paths: {
         type: "array",
         items: { type: "string" },
@@ -101,6 +116,13 @@ export const advisorTool = {
     const agent = ctx.agent
     const reviewType = args.type || "code"
     const documents = args.documents || null
+    // Review-object declaration (§18.8 D-OA3): the PARENT constructs it and the
+    // advisor tool passes it through — mechanical anchoring, not model inference.
+    // Any non-object value (string/array/primitive, possibly from a malformed
+    // tool call) degrades to null = no injection (legacy calls unchanged).
+    const reviewObject = args.object && typeof args.object === "object" && !Array.isArray(args.object)
+      ? args.object
+      : null
     // Scope fallback: the runtime mutation record (zero git) covers guard-triggered
     // reviews where the model did not pass explicit paths.
     const paths = args.paths || (agent._touchedFiles?.length ? [...agent._touchedFiles] : null)
@@ -139,7 +161,7 @@ export const advisorTool = {
     const result = await runAdvisorReview(agent, reviewType, {
       onOutput: ctx.onOutput,
       signal: ctx.signal,
-    }, designToken, documents, paths)
+    }, designToken, documents, paths, reviewObject)
 
     if (reviewType === "design") {
       // Whitespace-tolerant match (LLM may add spaces or wrap in fences).