thincoder 0.12.50 → 0.12.51

package/src/agent-tools/consult.mjs

@@ -11,9 +11,14 @@
  * CONSULT_BASE overlay }); activity streams to the parent TUI via the relay
  * prefix `consult#<id>/` (same channel subagent uses), not onSubagent/onToolPanel.
  */
-import { createAgent, runAgent, readonlyToolNames, ContinueError } from "../agent.mjs"
+import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
 import { resolveChildProvider } from "./subagent.mjs"
-import { specForModel } from "../config.mjs"
+import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
+
+// Named consult defaults (consult P2, 2026-08-30).
+const CONSULT_TIMEOUT_MS = 600_000 // default consult lifecycle timeout
+const CONSULT_TURNS = 40           // default per-child turn cap
+
 
 function consultLabel(m) {
   return `${m.provider}:${m.model}`
@@ -21,7 +26,9 @@ function consultLabel(m) {
 
 /** Narrow the configured consultModels pool to a requested subset.
  *  Each selector is "provider:model", a bare provider name, or a bare model name
- *  (case-insensitive). Returns { models, error } — error set when a selector matches
+ *  (case-insensitive). A trailing " (effort)" suffix is tolerated (round2 复核
+ *  对齐 escalate.mjs：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
+ *  Returns { models, error } — error set when a selector matches
  *  nothing (surface the typo rather than silently dropping it). Absent/empty selectors
  *  → the full pool. */
 function selectConsultModels(pool, selectors) {
@@ -31,7 +38,8 @@ function selectConsultModels(pool, selectors) {
   const seen = new Set()
   const unknowns = []
   for (const raw of list) {
-    const s = String(raw).trim().toLowerCase()
+    // eslint-disable-next-line no-control-regex -- fixed non-control suffix
+    const s = String(raw).replace(/\s+\([^)]*\)\s*$/, "").trim().toLowerCase()
     const matches = pool.filter((m) =>
       consultLabel(m).toLowerCase() === s ||
       String(m.provider ?? "").toLowerCase() === s ||
@@ -85,11 +93,18 @@ export function makeMainHistoryTool(parentAgent) {
           : ""
         return `--- [${m.role}] ---\n${content}${calls ? "\n" + calls : ""}`
       }
-      const BUDGET = 60_000
+      const BUDGET = 60_000            // per-consult token budget (tokens)
       let out = ""
       for (let i = slice.length - 1; i >= 0; i--) {
         const line = render(slice[i])
-        if (out.length + line.length > BUDGET) { out = `(earlier messages trimmed — budget ${BUDGET} chars)\n\n` + out; break }
+        if (out.length + line.length > BUDGET) {
+          // A single message over the whole budget: truncate IT (it is the newest
+          // and most relevant) instead of dropping everything with a misleading
+          // "earlier messages trimmed" note. Older accumulation still trims.
+          if (out === "") { out = line.slice(0, BUDGET) + "\n(… truncated — single message exceeded budget " + BUDGET + " chars)"; break }
+          out = `(earlier messages trimmed — budget ${BUDGET} chars)\n\n` + out
+          break
+        }
         out = out ? line + "\n\n" + out : line
       }
       return out
@@ -119,7 +134,7 @@ function settleChild(session, id, label, ok, payload) {
 
 async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   const agent = ctx.agent
-  const timeoutMs = agent?.config?.agent?.consultTimeoutMs ?? 600_000
+  const timeoutMs = agent?.config?.agent?.consultTimeoutMs ?? CONSULT_TIMEOUT_MS
   let timedOut = false
   const armWatchdog = () => {
     const t = setTimeout(() => {
@@ -135,7 +150,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
     const provider = resolveChildProvider(agent, `${m.provider}:${m.model}`)
-    if (!provider?.apiKey?.trim()) {
+    if (!ensureChildApiKey(provider)) {
       // resolveChildProvider may still lack a key; fail loudly like the plugin precheck
       // (settleChild turns this message into a clear failed reply instead of a raw 401)
       throw new Error(`consult model ${label} has no API key — check providers[${m.provider}].apiKey in config.json`)
@@ -145,14 +160,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // Symmetric with escalate.mjs; 2026-08-16 a real consult died on qwen3.8-max
     // effort "high" (enum is xhigh/medium/low). Out-of-enum: DROP the effort entirely
     // (the provider preset default may ALSO be out-of-enum for this override model).
-    if (m.effort) {
-      const enumList = specForModel(m.model).reasoningEffortEnum
-      if (enumList && !enumList.includes(m.effort)) {
-        delete provider.reasoningEffort
-      } else {
-        provider.reasoningEffort = m.effort
-      }
-    }
+    clampEffort(provider, m.model, m.effort)
 
     // Read-only consultant: filter the parent tool set down to readonly tools + main_history.
     const allowed = readonlyToolNames(agent.tools ?? [])
@@ -172,57 +180,57 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       role: "consult",
     })
 
-    // Activity relay: `consult#<subId>/` prefix → the parent TUI's subTasks panel
-    // (same channel subagent uses — parallel consultants stay independent).
-    agent._subAgentCounter = (agent._subAgentCounter ?? 0) + 1
-    const subId = agent._subAgentCounter
-    const relayPrefix = `consult#${subId}/`
-    // Report this consultant's model to the display layer (each consultant may use a different model).
-    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? ""))
-    const childCallbacks = {
-      onToken: ctx.callbacks?.onToken ? (t) => ctx.callbacks.onToken(`${relayPrefix}${t}`) : null,
-      onReasoning: ctx.callbacks?.onReasoning ? (r) => ctx.callbacks.onReasoning(`${relayPrefix}${r}`) : null,
-      onToolCall: ctx.callbacks?.onToolCall ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args) : null,
-    }
+    // Activity relay via the unified spawn-child pipeline (§7.2 D3): `consult#<subId>/`
+    // prefix (same channel subagent uses — parallel consultants stay independent) +
+    // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
+    const relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
+    let declined = false // review #1: guard against double-settle when onDeclined fired
 
-    // Turn-cap continue loop (TURN-CAP-CONTINUE.md): hitting the cap asks the user via
-    // the SAME y/n panel the main agent uses (ctx.onPermissionRequest "continue") —
-    // unlimited continues, each with a fresh turn budget AND a re-armed wall-clock
-    // watchdog (a continue is a fresh budget, the clock restarts too). Parallel
-    // consultants serialize their prompts through a session-level queue. Declined /
-    // headless → failed reply (partial diagnosis).
+    // Turn-cap continue loop (TURN-CAP-CONTINUE.md) via runWithContinue (§7.2 D3): hitting
+    // the cap asks the user via the SAME y/n panel the main agent uses — unlimited
+    // continues, each with a fresh turn budget AND a re-armed wall-clock watchdog (a
+    // continue is a fresh budget, the clock restarts too). Parallel consultants serialize
+    // their prompts through a session-level queue. Declined / headless → failed reply
+    // (partial diagnosis).
     const runner = ctx.runAgent ?? runAgent
-    for (let resume = false; ; resume = true) {
-      try {
-        const result = await runner(child, "# Problem\n" + problem, childCallbacks, {
-          depth: 1,
-          maxTurns: agent?.config?.agent?.consultTurns ?? 40,
-          signal: ctrl.signal,
-          resume,
-        })
-        settleChild(session, id, label, true, String(result ?? ""))
-        return
-      } catch (e) {
-        if (e instanceof ContinueError) {
-          let go = false
-          if (ctx.onPermissionRequest) {
+    try {
+      const result = await runWithContinue(
+        (childAgent, input, cbs, opts) => runner(childAgent, input, cbs, opts),
+        child, "# Problem\n" + problem,
+        childCallbacks,
+        { depth: 1, maxTurns: agent?.config?.agent?.consultTurns ?? CONSULT_TURNS, signal: ctrl.signal },
+        {
+          askContinue: (e) => {
+            if (!ctx.onPermissionRequest) return Promise.resolve(false)
             const ask = () => ctx.onPermissionRequest("continue", { turns: e.turn, agent: label })
             session.continueQueue = (session.continueQueue ?? Promise.resolve()).then(ask, ask)
-            go = await session.continueQueue
-          }
-          if (go) {
-            clearTimeout(watchdog)
-            timedOut = false // fresh budget → fresh clock
-            watchdog = armWatchdog()
-            continue
-          }
-          settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
-          return
-        }
-        const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
-        settleChild(session, id, label, false, note)
-        return
-      }
+            return session.continueQueue.then((go) => {
+              if (go) {
+                clearTimeout(watchdog)
+                timedOut = false // fresh budget → fresh clock
+                watchdog = armWatchdog()
+              }
+              return go
+            })
+          },
+          onDeclined: (e) => {
+            declined = true
+            settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            return undefined
+          },
+        },
+      )
+      // Review #1 fix: onDeclined already settled this child as a failed reply —
+      // settling again here would push a phantom empty success reply and decrement
+      // `pending` twice (negative pending → consult_check's two exits both
+      // unreachable → permanent block until user abort).
+      if (!declined) settleChild(session, id, label, true, String(result ?? ""))
+    } catch (e) {
+      // Runner errors (incl. the watchdog's abort) settle as a failed reply — the
+      // continue/declined paths are already handled inside runWithContinue.
+      const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
+      settleChild(session, id, label, false, note)
     }
   } catch (e) {
     // Errors BEFORE the runner (provider resolution, createAgent) or a throwing
@@ -243,6 +251,11 @@ export function cleanupConsultSessions(agent) {
     for (const w of s.waiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
   }
   agent._consultSessions?.clear()
+  // NOTE: deliberately void (consult P3, 2026-08-30). The { stopped: true } marker
+  // only reaches the TUI via the consult_stop TOOL return (onToolResult freezes
+  // blocks on tool calls) — cleanup runs from the turn finally, where the block
+  // freeze is owned by freezeAllSubTasks + sweepToolBlocks, so a return here is
+  // dead weight. Blocks still get frozen on interrupt via that sweep.
 }
 
 export const consultStartTool = {
@@ -313,14 +326,19 @@ export const consultCheckTool = {
     "have settled. The reply is raw and unjudged — verify/adopt it with your own tools. When done is true, no more " +
     "replies are coming.\n" +
     "Call it ALONE in a turn — do NOT batch it with calls that depend on its reply (readonly tools run in parallel).\n" +
+    "Replies arrive in arrival order: call it repeatedly (n = 1, 2, 3, …) until done is true.\n" +
     "Parameters:\n" +
-    "- id (required): the consult id from consult_start",
+    "- id (required): the consult id from consult_start\n" +
+    "- n (required): the 1-based read number for this consult — pass 1 on the first check, 2 on the next, and so on. It exists so consecutive checks are distinct tool calls (loop detectors) and the transcript reads as a sequence.",
   parameters: {
     type: "object",
-    properties: { id: { type: "string", description: "Consult id" } },
-    required: ["id"],
+    properties: {
+      id: { type: "string", description: "Consult id" },
+      n: { type: "number", description: "1-based read number: 1 for the first check, incrementing with each subsequent check of the same consult" },
+    },
+    required: ["id", "n"],
   },
-  async execute({ id }, ctx) {
+  async execute({ id, n: _n }, ctx) {
     const s = ctx.agent?._consultSessions?.get(String(id))
     if (!s) return JSON.stringify({ error: "unknown consult id" })
     const abortAll = () => { for (const c of s.controllers) { try { c.abort() } catch { /* noop */ } } }
@@ -367,18 +385,22 @@ export const consultStopTool = {
     "Terminate the still-running consultations of a session once a reply is good enough — saves tokens and time. " +
     "Already-answered replies stay available for consult_check.\n" +
     "Parameters:\n" +
-    "- id (required): the consult id from consult_start",
+    "- id (required): the consult id from consult_start\n" +
+    "- n (required): incrementing call number for this consult (next value after the last consult_check/consult_stop) — keeps repeated calls distinct.",
   parameters: {
     type: "object",
-    properties: { id: { type: "string", description: "Consult id" } },
-    required: ["id"],
+    properties: {
+      id: { type: "string", description: "Consult id" },
+      n: { type: "number", description: "Incrementing call number for this consult (see consult_check)" },
+    },
+    required: ["id", "n"],
   },
-  async execute({ id }, ctx) {
+  async execute({ id, n }, ctx) {
     const s = ctx.agent?._consultSessions?.get(String(id))
     if (!s) return JSON.stringify({ error: "unknown consult id" })
-    const n = s.pending
+    const abandoned = s.pending
     s.stopped = true
     for (const c of s.controllers) { try { c.abort() } catch { /* already settled */ } }
-    return JSON.stringify({ stopped: n })
+    return JSON.stringify({ stopped: n, abandoned })
   },
 }

package/src/agent-tools/escalate.mjs

@@ -16,9 +16,9 @@
  * CLI mergeChildMutations(parent, child) (agent object, not a state sink).
  */
 import { isAbsolute, relative } from "node:path"
-import { createAgent, runAgent, ContinueError, CODER_OVERLAY } from "../agent.mjs"
+import { createAgent, runAgent, CODER_OVERLAY, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
 import { resolveChildProvider, mergeChildMutations } from "./subagent.mjs"
-import { specForModel } from "../config.mjs"
+import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
 
 const label = (m) => `${m.provider}:${m.model}`
 
@@ -70,31 +70,21 @@ export const escalateTool = {
     } catch (e) {
       return `Error: ${e.message}`
     }
-    if (!provider?.apiKey?.trim()) {
+    if (!ensureChildApiKey(provider)) {
       return `Error: provider "${pick.provider}" has no API key — set it in config.json before flying it in`
     }
     let effortNote = ""
-    if (pick.effort) {
-      // Clamp the pool's effort to the model's reasoningEffortEnum — an out-of-enum
-      // value makes provider/core.mjs throw on EVERY chat call (candidate dies on takeoff).
-      // Out-of-enum: DROP the effort entirely (the provider preset default may ALSO be
+    if (pick.effort && !clampEffort(provider, pick.model, pick.effort)) {
+      // Out-of-enum effort dropped (see clampEffort): the provider preset default may ALSO be
       // out-of-enum for this override model — e.g. qwenplan preset default "high" is
-      // invalid for qwen3.8-max, enum xhigh/medium/low).
-      const enumList = specForModel(pick.model).reasoningEffortEnum
-      if (enumList && !enumList.includes(pick.effort)) {
-        effortNote = ` (effort "${pick.effort}" unsupported by ${pick.model}, dropped)`
-        delete provider.reasoningEffort
-      } else {
-        provider.reasoningEffort = pick.effort
-      }
+      // invalid for qwen3.8-max, enum xhigh/medium/low.
+      effortNote = ` (effort "${pick.effort}" unsupported by ${pick.model}, dropped)`
     }
 
-    parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
-    const subId = parent._subAgentCounter
     const tag = label(pick)
-    const relayPrefix = `escalate#${subId}/`
-    // Report the escalated model to the display layer (it may differ from the parent's).
-    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? tag))
+    const relayPrefix = makeRelay(parent, "escalate", ctx.callbacks?.onToken, provider.model ?? tag)
+    // Report the escalated model to the display layer (it may differ from the parent's)
+    // — makeRelay already emitted the `[model]` metadata token above.
 
     // No wall-clock watchdog — turn cap only, exactly like subagent (the verified write
     // path). Rationale (2026-08-16): a fixed wall-clock aborts NORMAL-but-slow surgery —
@@ -103,12 +93,12 @@ export const escalateTool = {
     // signal propagates directly below). maxTurns is the cost budget; hitting it asks
     // the user whether to continue (main-agent parity), falling back to partial work.
 
-    let output = ""
-    const childCallbacks = {
-      onToken: ctx.callbacks?.onToken ? (t) => { output += t; ctx.callbacks.onToken(`${relayPrefix}${t}`) } : (t) => { output += t },
-      onReasoning: ctx.callbacks?.onReasoning ? (r) => ctx.callbacks.onReasoning(`${relayPrefix}${r}`) : null,
-      onToolCall: ctx.callbacks?.onToolCall ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args) : null,
-    }
+    // No custom onToken here (consult P2, 2026-08-30): wrapChildCallbacks already
+    // applies the prefixed relay + D7 sentinel strip for the display path, and
+    // runWithContinue owns the capture (stripEventTokensForCapture) for the
+    // partial-output return — a hand-rolled duplicate ran the strip twice and
+    // maintained a second output buffer.
+    const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
 
     // Declared outside try so the catch can merge mutations even on a partial failure.
     let child = null
@@ -127,48 +117,49 @@ export const escalateTool = {
       const runner = ctx.runAgent ?? runAgent
       const runOpts = {
         depth: 1,
-        maxTurns: parent.config?.agent?.subagentTurns ?? 100,
+        maxTurns: parent.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS, // review #7: constant, not literal (single source with subagent.mjs)
         signal: ctx.signal ?? null,
       }
-      // Turn-cap continue, main-agent parity (tui/agent-turn.mjs): when the child hits
-      // ContinueError, ask the user through the SAME channel as child write approval
-      // (ctx.onPermissionRequest). The name "continue" renders the TUI's dedicated y/n
-      // Continue panel — the same panel the main agent's turn-cap pause uses. The
-      // resumed run passes resume:true, so runAgent does NOT re-inject the task text
-      // (setup.mjs skips input on resume) and keeps the child's history + mutation
-      // bookkeeping, with a fresh maxTurns budget per run. No permission handler
-      // (headless) or a declined prompt falls through to the partial-work return.
+      // Turn-cap continue via runWithContinue (§7.2 D3), main-agent parity (tui/agent-turn.mjs):
+      // when the child hits ContinueError, ask the user through the SAME channel as child
+      // write approval (ctx.onPermissionRequest). The name "continue" renders the TUI's
+      // dedicated y/n Continue panel. The resumed run passes resume:true, so runAgent does
+      // NOT re-inject the task text (setup.mjs skips input on resume) and keeps the child's
+      // history + mutation bookkeeping, with a fresh maxTurns budget per run. No permission
+      // handler (headless) or a declined prompt falls through to the partial-work return.
       // Continues are UNLIMITED — the user can decline at any prompt.
-      for (let resumes = 0; ; resumes++) {
-        try {
-          const report = await runner(child, task, {
-            ...childCallbacks,
-            // AUTO parity with subagent.mjs: parent.autoApprove must reach the child even
-            // when no onPermissionRequest exists (ACP/headless embeds) — otherwise every
-            // child write burns a turn on "no permission handler" rejections.
-            onPermissionRequest: parent.autoApprove ? async () => true : (ctx.onPermissionRequest ?? null),
-          }, { ...runOpts, resume: resumes > 0 })
-          // Escalate mutations are the parent's mutations: verify/advisor guards must see them
-          mergeChildMutations(parent, child)
-          return `escalate (${tag})${effortNote} post-op report:\n${report || output.slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
-        } catch (e) {
-          // Even a failed surgery may have written files — merge whatever the child touched.
-          mergeChildMutations(parent, child)
-          const msg = e?.message ?? String(e)
-          if (ctx.signal?.aborted || e?.name === "AbortError") throw e
-          if (e instanceof ContinueError) {
-            if (ctx.onPermissionRequest) {
-              const go = await ctx.onPermissionRequest("continue", { turns: e.turn, agent: tag })
-              if (go) continue // fresh maxTurns budget; task NOT re-injected (resume:true)
-            }
-            return `escalate (${tag}) stopped: turn cap reached (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`
+      const report = await runWithContinue(
+        async (childAgent, input, cbs, opts) => {
+          // Merge mid-run mutations even when the run throws — the outer catch keeps
+          // handling createAgent failures; AbortError still propagates (user Stop).
+          try {
+            return await runner(childAgent, input, cbs, opts)
+          } catch (e) {
+            mergeChildMutations(parent, childAgent)
+            throw e
           }
-          return `escalate (${tag}) error: ${msg}\nPartial output: ${output.slice(0, 2000)}`
-        }
-      }
+        },
+        child, task, { ...childCallbacks, onPermissionRequest: parent.autoApprove ? async () => true : (ctx.onPermissionRequest ?? null) },
+        runOpts,
+        {
+          // escalate has NO permQueue: prompts go straight to the user (T-L spec).
+          askContinue: (e) => (ctx.onPermissionRequest
+            ? ctx.onPermissionRequest("continue", { turns: e.turn, agent: tag })
+            : Promise.resolve(false)),
+          onDeclined: (e, output) => `escalate (${tag}) ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`,
+        },
+      ).catch((e) => {
+        // Generic run failure (not ContinueError): match the original loop's return shape —
+        // error text + partial output, mutations already merged in the runner wrapper.
+        if (ctx.signal?.aborted || e?.name === "AbortError") throw e
+        return `escalate (${tag}) error: ${e?.message ?? String(e)}\nPartial output: ${(child._capturedOutput ?? "").slice(0, 2000)}`
+      })
+      // Escalate mutations are the parent's mutations: verify/advisor guards must see them
+      mergeChildMutations(parent, child)
+      return `escalate (${tag})${effortNote} post-op report:\n${report || (child._capturedOutput ?? "").slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
     } catch (e) {
       // Reached only when createAgent itself fails or the continue prompt throws —
-      // run failures are handled inside the loop above.
+      // run failures are handled above (mutations merge inside the runner wrapper).
       if (child) mergeChildMutations(parent, child)
       if (ctx.signal?.aborted || e?.name === "AbortError") throw e
       return `escalate (${tag}) error: ${e?.message ?? String(e)}`

package/src/agent-tools/subagent.mjs

@@ -1,16 +1,19 @@
 import {
-  createAgent, runAgent, ContinueError,
+  createAgent, runAgent,
   readonlyToolNames, collectGitContext, escapeXml,
   EXPLORE_OVERLAY, CODER_OVERLAY, PLAN_OVERLAY, ENG_CODER_OVERLAY,
   MIN_REPORT_CHARS, REPORT_CONTINUATION, DEFAULT_SUBAGENT_TURNS,
 } from "../agent.mjs"
+import { makeRelay, wrapChildCallbacks, runWithContinue, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
 import { validateDesignToken } from "./advisor.mjs"
 
 /**
  * subagent tool: spawn a child agent to handle an independent subtask (isolated context, only the report is returned).
  * - role: "explore" — read-only tools, search/read/analyze (suitable for codebase exploration)
  * - role: "coder" — full tool set, self-contained implementation tasks (suitable for isolated coding)
- * - no role specified — default behavior, same tool set as parent agent
+ * - no role specified — invalid by design since the 2026-08-25 fail-closed gate
+ *   (role is mandatory; "no role → same tool set as parent" was removed with the
+ *   coder-leak fix and the header text above predates it)
  * - parallel subagent calls via the parallel channel (parallel: true)
  * - non-recursive: child agents do not get the subagent tool (depth > 0 is not injected)
  */
@@ -169,54 +172,48 @@ export const subagentTool = {
       if (gitCtx) input = `<untrusted_git_context>\n${escapeXml(gitCtx)}\n</untrusted_git_context>\n\n${input}`
     }
 
-    // Relay content/reasoning tokens + tool calls to the parent TUI (child agent panel shows activity).
-    // Prefix includes a unique id: parallel child agents with the same role stay independent and don't overwrite each other.
+    // Relay content/reasoning/tool/output to the parent TUI via the unified spawn-child
+    // pipeline (AGENT-LOOP.md §7.2 D3). Prefix includes a unique id: parallel child agents
+    // with the same role stay independent and don't overwrite each other.
     // Format: role#id/  →  onToken("coder#2/writing..."), onToolCall("coder#2/read", args)
-    parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
-    const subId = parent._subAgentCounter
-    const relayPrefix = `${role ?? "sub"}#${subId}/`
-    // Report the subagent's effective model to the display layer (it may differ from the
-    // parent's). Emitted as a `[model]` metadata token via the relay prefix — the TUI/webview
-    // parse it into the subagent block's header instead of showing it as content.
-    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (childProvider.model ?? ""))
+    const relayPrefix = makeRelay(parent, role ?? "sub", ctx.callbacks?.onToken, childProvider.model ?? "")
     const childOpts = {
       onPermissionRequest: childPermission,
-      onToken: ctx.callbacks?.onToken
-        ? (t) => ctx.callbacks.onToken(`${relayPrefix}${t}`)
-        : null,
-      onReasoning: ctx.callbacks?.onReasoning
-        ? (t) => ctx.callbacks.onReasoning(`${relayPrefix}${t}`)
-        : null,
-      onToolCall: ctx.callbacks?.onToolCall
-        ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args)
-        : null,
+      ...wrapChildCallbacks(relayPrefix, ctx.callbacks),
     }
     const childRunOpts = buildChildRunOpts(ctx)
     let report = ""
-    // Turn-cap continue loop (TURN-CAP-CONTINUE.md): hitting the cap asks the user via
-    // the SAME y/n panel the main agent uses (ctx.onPermissionRequest "continue") —
+    // Turn-cap continue loop (TURN-CAP-CONTINUE.md) via runWithContinue (§7.2 D3):
+    // hitting the cap asks the user via the SAME y/n panel the main agent uses —
     // unlimited continues, resume:true keeps the child's history + mutation bookkeeping,
     // fresh budget each run. Prompts queue through parent._permQueue (same as write
     // approval) so parallel children never pop two panels at once. Declined / headless
     // → partial-work return. Non-ContinueError errors still propagate (dispatch.mjs
     // turns them into Error tool results — unchanged behavior).
-    for (let resume = false; ; resume = true) {
-      try {
-        report = await runAgent(child, input, childOpts, { ...childRunOpts, resume })
-        break
-      } catch (e) {
-        if (!(e instanceof ContinueError)) throw e
-        let go = false
-        if (ctx.onPermissionRequest) {
-          const ask = () => ctx.onPermissionRequest("continue", { turns: e.turn, agent: `${role ?? "sub"}#${subId}` })
-          parent._permQueue = (parent._permQueue ?? Promise.resolve()).then(ask, ask)
-          go = await parent._permQueue
-        }
-        if (go) continue
-        if (role === "eng-coder" && child._mutatedThisRun) mergeChildMutations(parent, child)
-        return `Subagent (${role}) stopped: turn cap reached (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${report || ""}`
-      }
+    const askSubagentContinue = (e) => {
+      if (!ctx.onPermissionRequest) return Promise.resolve(false)
+      const ask = () => ctx.onPermissionRequest("continue", { turns: e.turn, agent: relayPrefix.slice(0, -1) })
+      parent._permQueue = (parent._permQueue ?? Promise.resolve()).then(ask, ask)
+      return parent._permQueue
     }
+    const declined = { partial: null }
+    report = await runWithContinue(
+      (child, input, cbs, opts) => runAgent(child, input, cbs, opts), // opts = childRunOpts + resume (managed by the pipeline)
+      child, input, childOpts, childRunOpts,
+      {
+        askContinue: askSubagentContinue,
+        onDeclined: (e, output) => {
+          if (role === "eng-coder" && child._mutatedThisRun) mergeChildMutations(parent, child)
+          // Early return semantics (unchanged from the inline loop): the declined
+          // partial-work message is returned WITHOUT the MIN_REPORT_CHARS expansion —
+          // re-prompting a capped child for a longer report is wrong.
+          // Review #2 fix: use the pipeline-captured output (the `report` variable is
+          // still "" at this point — runWithContinue hasn't returned yet).
+          declined.partial = `Subagent (${role}) ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output || ""}`
+        },
+      },
+    )
+    if (declined.partial !== null) return declined.partial
 
     // Report too short = incomplete handoff: send back for expansion once (inspired by kimi-code's summaryPolicy: min 200 chars, retry 1 time).
     // The child agent's history is still intact; the continuation instruction is appended as new input so it can see its own earlier work.
@@ -230,6 +227,10 @@ export const subagentTool = {
     // promised in the engineering prompt.
     // CRITICAL: Only merge if child actually mutated files (defense-in-depth against
     // runAgent throwing before any writes occurred).
+    // Review #8 clarification: eng-coder ONLY is intentional — the mechanical
+    // two-gate merge exists for engineering mode; plain `coder` children carry
+    // their own verify/advisor self-review discipline (per tool description), and
+    // normal mode has no parent advisor/verify gate to feed.
     if (role === "eng-coder" && child._mutatedThisRun) {
       mergeChildMutations(parent, child)
     }