thincoder 0.12.59 → 0.12.60

package/src/agent-tools/subagent.mjs

@@ -1,92 +1,43 @@
-import {
-  createAgent,
-  readonlyToolNames, escapeXml,
-  EXPLORE_OVERLAY, CODER_OVERLAY, PLAN_OVERLAY, ENG_CODER_OVERLAY,
-} from "../agent.mjs"
-import { makeRelay, wrapChildCallbacks, gateEngCoderSpawn, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
-import { validateDesignToken } from "./advisor.mjs"
-import { pushReal } from "../context.mjs"
+/**
+ * subagent.mjs — subagent tool（ONE tool, EIGHT actions + spawn 路径驱动器）。
+ * 2026-09-07 token 链终消费制：+action: consume-design（ENGINEERING-MODE.md §2.6 F1——
+ * 父侧链终核销消费 designId 槽——执行器 executeConsumeDesignAction 在 subagent-spawn.mjs）。
+ *
+ * 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
+ *（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
+ *（async 分支 + 阻塞路径）原样保留于本文件；导出面由文末 re-export shim 兜住。
+ * 2026-09-03 §19 合体轮: subagent_check/escalate 工具退役——status/escalate
+ * 动作执行器并入 ./subagent-async.mjs，本文件只承载工具面（action schema）与
+ * spawn 路径 + 动作分流。
+ * 2026-09-06 §19.8 删 check 轮: check 动作删除——工具面五动作（spawn/status/
+ * escalate/cancel/panel）——async 结果仅自动通道送达。
+ * 2026-09-05 拆分轮: status/escalate/panel 动作执行器 → ./subagent-actions.mjs；§20
+ * 调度器全套 → ./subagent-scheduler.mjs——本文件 import 源随之改写。
+ * 2026-09-05 模块拆分轮（726 > 500 硬限）: spawn 前置 helpers（summarizeEngTaskBook/
+ * effectiveSubagentModel/resolveDesignSlot）+ §20 准入（prepareScheduling）+ child
+ * 装配（buildSpawnChild）→ ./subagent-spawn.mjs；async 分支（executeAsyncSpawn）
+ * → ./subagent-run.mjs——execute 只保留动作分流 + 装配调用 + 阻塞路径。
+ */
+
+import { gateEngCoderSpawn, TURN_CAP_MARK, emitNestedChildEvent } from "../agent/spawn-child.mjs"
 import { logEvent, errText } from "../log.mjs"
 import {
-  runChildPipeline, resolveChildProvider, ASYNC_SUBAGENT_LIMIT,
-  buildChildRunOpts, executeCheckAction, executeCancelAction,
+  runChildPipeline, executeCancelAction,
 } from "./subagent-async.mjs"
-import { executeStatusAction, executeEscalateAction, executePanelAction } from "./subagent-actions.mjs"
-import {
-  // §20 调度器（AGENT-LOOP.md §20——D-SD1..SD5）：文件域归一化/等待态派生/环防御/
-  // 排队态面板刷新/依赖者标注/补位——2026-09-05 拆分轮后独立模块。
-  normalizeFileList, describeBlockers, queueRunnable, refreshQueuedTokens,
-  assertNoDepCycle, depInfo, dependentLabels, maybeRefillAsync,
-} from "./subagent-scheduler.mjs"
-
-// 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
-//（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
-//（async 分支 + 阻塞路径）原样保留于本文件；导出面由文末 re-export shim 兜住。
-// 2026-09-03 §19 合体轮: subagent_check/escalate 工具退役——check/status/escalate
-// 动作执行器并入 ./subagent-async.mjs，本文件只承载工具面（action schema）与
-// spawn 路径 + 动作分流。
-// 2026-09-05 拆分轮: status/escalate/panel 动作执行器 → ./subagent-actions.mjs；§20
-// 调度器全套（normalizeFileList/describeBlockers/queueRunnable/refreshQueuedTokens/
-// assertNoDepCycle/depInfo/dependentLabels/maybeRefillAsync）→ ./subagent-scheduler.mjs
-// ——本文件 import 源随之改写；check/cancel 与机械/管线仍来自 ./subagent-async.mjs。
+import { executeStatusAction, executeEscalateAction, executePanelAction, executeObserveAction, executeSendAction } from "./subagent-actions.mjs"
+import { prepareScheduling, buildSpawnChild, executeConsumeDesignAction } from "./subagent-spawn.mjs"
+import { executeAsyncSpawn } from "./subagent-run.mjs"
 
 /**
- * §18.7 D-TS5 (A2): mechanically summarize the parent spawn task book for the
- * audit spawn — the three audit-relevant elements VERBATIM (design doc paths /
- * affected-file list / acceptance criteria); verbose context/background is
- * dropped (the auditor can read the design docs themselves — they stay
- * available outside this input). Independence preserved: the input is
- * _engTaskInput (mechanically kept by the parent spawn) — never the
- * eng-coder's self-report. Sections are located by header marker, prioritizing
- * header lines (structured task books: "## 文件清单 …") and falling back to
- * inline markers (flat one-line task books); a section runs to the next header
- * of the SAME OR HIGHER level ("## 文件清单" survives a "### 修改" sub-header).
- * Marker not found → the section is reported as missing (never fabricate).
- */
-function summarizeEngTaskBook(taskInput) {
-  if (!taskInput) return "(unavailable)"
-  const SECTIONS = [
-    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/] },
-    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/] },
-    { name: "Acceptance criteria", markers: [/Acceptance(?: criteria)?/i, /验收标准/] },
-  ]
-  const lines = taskInput.split("\n")
-  const headerLevel = (l) => {
-    const m = l.match(/^\s*(#{1,6})\s/)
-    return m ? m[1].length : 0
-  }
-  const headerIdx = lines.map((l, i) => (headerLevel(l) > 0 ? i : -1)).filter((i) => i >= 0)
-  const boundsFor = (from, level) => {
-    for (const j of headerIdx) {
-      if (j > from && (level === 0 || headerLevel(lines[j]) <= level)) return j
-    }
-    return lines.length
-  }
-  const out = []
-  for (const { name, markers } of SECTIONS) {
-    let from = -1
-    let level = 0
-    for (const i of headerIdx) {
-      if (markers.some((m) => m.test(lines[i]))) { from = i; level = headerLevel(lines[i]); break }
-    }
-    if (from === -1) {
-      for (let i = 0; i < lines.length; i++) {
-        if (markers.some((m) => m.test(lines[i]))) { from = i; level = 0; break }
-      }
-    }
-    if (from === -1) { out.push(`${name}: (not found in the parent task book)`); continue }
-    const body = lines.slice(from, boundsFor(from, level)).join("\n").trim()
-    out.push(body || `${name}: (empty section)`)
-  }
-  return out.join("\n\n")
-}
-
-/**
- * subagent tool — ONE tool, SIX actions (AGENT-LOOP.md §19/§19.5/§19.6): spawn
- * (default) / check (fetch async results, blocking + consuming) / status
- * (non-blocking pool query) / escalate (飞刀 — hand implementation to a
- * stronger model) / cancel (stop ONE background subagent — §19.5) / panel
- * (view + fix the live subagent panel — §19.6).
+ * subagent tool — ONE tool, EIGHT actions (AGENT-LOOP.md §19/§19.5/§19.6/§19.8 +
+ * SUBAGENT-OBSERVE-SEND): spawn (default) / status (non-blocking pool query) / observe
+ * (inspect a running/queued/done async child's recent activity + current tool — §7.2) /
+ * send (inject a direction into a RUNNING async child — consumed at its next turn
+ * boundary as an ordinary instruction — §7.2) / escalate (飞刀 — hand implementation to
+ * a stronger model) / cancel (stop ONE background subagent — §19.5) / panel (view + fix
+ * the live subagent panel — §19.6) / consume-design (parent-side chain-terminal token
+ * consumption — ENGINEERING-MODE.md §2.6, 2026-09-07). The check
+ * action was deleted (§19.8): async results reach the model only via the auto channel.
  * - action:"spawn" roles: "explore" — read-only tools, search/read/analyze
  *   (suitable for codebase exploration); "coder" — full tool set, self-contained
  *   implementation tasks; "plan" — read-only planning; "eng-coder" —
@@ -97,65 +48,17 @@ function summarizeEngTaskBook(taskInput) {
  * - non-recursive: child agents do not get the subagent tool (depth > 0 is not injected)
  */
 
-/**
- * Effective subagent model override for a role (CLI parity shared with VS Code):
- * priority — subagent tool `model` arg > config.agent.subagentModels[role] > config.agent.subagentModel > null (inherit parent).
- * The literal "default" (case-insensitive) means "no tool-arg override → run the
- * chain" — same as omitting the parameter (2026-09-05 user ruling).
- */
-export function effectiveSubagentModel(parent, role, modelArg) {
-  // "default" alias (2026-09-05 user ruling — ARCHITECTURE.md 子 agent 模型指定):
-  // the literal "default", matched case-insensitively, explicitly declares "no
-  // override at the tool-arg level → run the default priority chain" (type-level
-  // subagentModels[role] → global subagentModel → null = inherit parent). It is
-  // equivalent to omitting the parameter / passing ""/null/undefined (which fall
-  // through below). Any other value still overrides.
-  if (modelArg && String(modelArg).toLowerCase() !== "default") return modelArg
-  const cfg = parent.config?.agent ?? {}
-  return cfg.subagentModels?.[role] ?? cfg.subagentModel ?? null
-}
-
-/**
- * Resolve the design-token slot for an eng-coder spawn (2026-09-01 multi-design, FR3):
- * - designId given → exact slot lookup (no match = explicit error, never a fuzzy guess)
- * - designId omitted → exactly ONE slot must exist (single-design compatibility); with
- *   multiple slots we refuse rather than pick one (T16: never silently aim the wrong design)
- * Returns { token } on success; throws with a parent-actionable message otherwise.
- * The HMAC/TTL check itself stays in validateDesignToken (unchanged).
- */
-export function resolveDesignSlot(parent, designIdArg) {
-  const slots = parent._engDesignTokens
-  const hasSlots = slots instanceof Map && slots.size > 0
-  const legacy = parent._engDesignToken
-  // eng(exit/enter) resets the single mirror to force a fresh review (eng.mjs) —
-  // a non-empty slot map surviving that reset must NOT resurrect stale tokens:
-  // mirror cleared + slots present = re-entered engineering mode → re-review.
-  if (!legacy && hasSlots) {
-    throw new Error("Design tokens were reset (engineering mode was re-entered) — run advisor with type='design' again and spawn with the fresh designId+token pair.")
-  }
-  if (designIdArg) {
-    if (!hasSlots || !slots.has(designIdArg)) {
-      throw new Error(`designId not found — no approved design review holds this id. Run advisor with type='design' again and pass the designId echoed with the token. (session holds ${hasSlots ? slots.size : 0} approved design slot(s))`)
-    }
-    return { token: slots.get(designIdArg) }
-  }
-  if (hasSlots && slots.size > 1) {
-    throw new Error(`Multiple approved designs in this session (${slots.size}) — pass the designId parameter (echoed with each token) to choose which design this eng-coder spawn belongs to.`)
-  }
-  if (hasSlots && slots.size === 1) return { token: [...slots.values()][0] }
-  if (legacy) return { token: legacy } // single-slot mirror fallback (pre-multi-slot sessions)
-  throw new Error("Invalid or missing design token — run advisor with type='design' first and pass the returned token as designToken.")
-}
-
 export const subagentTool = {
   name: "subagent",
   description:
-    "ONE tool, SIX actions (AGENT-LOOP.md §19/§19.5/§19.6) — pick by what you need:\n" +
+    "ONE tool, EIGHT actions (AGENT-LOOP.md §19/§19.5/§19.6/§19.8 + SUBAGENT-OBSERVE-SEND) — pick by what you need:\n" +
     "- action:'spawn' (DEFAULT): spawn a sub-agent to handle an independent subtask in an isolated context; the sub-agent returns only its final report. Spawn MULTIPLE subagents in the SAME response for parallel work—they run concurrently.\n" +
-    "- action:'check': fetch the report of an async spawn (async:true). BLOCKS until the target finishes — this is the explicit consuming fetch, NOT a progress query. Multiple async children return in completion (arrival) order, first finished first. Pass n = 1 on the first check of the turn, 2 on the next... (loop guard; at most 3 per turn — the rest arrive at turn end).\n" +
-    "- action:'status': NON-BLOCKING progress query — returns immediately and consumes nothing. Give the spawn's id for one child ({id, role, status: running|queued|done, model, elapsedSec, turn, maxTurns, position?), or omit it for an overview of the whole pool ({overview: {running: [{id, role, model, elapsedSec, turn, maxTurns}], queued: [{id, role, position}], done: [{id, role}]}}). §19.5.6 touched-files summary: running entries also carry touchedFiles (first 5, relative to your cwd), touchedMore (count beyond 5) and, when nothing was touched yet, the placeholder touched (\"—（尚无改动）\"); queued (not yet started) entries carry the placeholder touched (\"—（未启动）\") — see what a running child has changed BEFORE deciding to cancel it. Use THIS to check progress — action:'check' blocks until the target finishes (checking progress with check is what hangs a parallel turn).\n" +
-    "- action:'escalate' (飞刀 — a flown-in expert): hand an implementation task to a STRONGER model from your consult models (agent.consultModels). It gets WRITE access and does the work itself — reads, edits, runs tests — then returns a post-op report (what changed, why, verification). Use it when YOU judge the task calls for stronger hands (complex multi-file refactoring, an intractable bug, intricate algorithm work — or work beyond your comfortable ability); escalate EARLY, not after burning attempts. model: pick a candidate as 'provider:model' (default = the first consult model). Not available in engineering mode (implementation goes through eng-coder spawns there).\n" +
+    "- action:'status': NON-BLOCKING progress query — returns immediately and consumes nothing. Give the spawn's id for one child ({id, role, status: running|queued|done, model, elapsedSec, turn, maxTurns, position?), or omit it for an overview of the whole pool ({overview: {running: [{id, role, model, elapsedSec, turn, maxTurns}], queued: [{id, role, position}], done: [{id, role}]}}). §19.5.6 touched-files summary: running entries also carry touchedFiles (first 5, relative to your cwd), touchedMore (count beyond 5) and, when nothing was touched yet, the placeholder touched (\"—（尚无改动）\"); queued (not yet started) entries carry the placeholder touched (\"—（未启动）\") — see what a running child has changed BEFORE deciding to cancel it. Use THIS to see progress — it never blocks and never consumes a result (async results are delivered to you automatically).\n" +
+    "- action:'observe': SEE what a running async subagent is DOING right now (progress vs stuck) — pass the spawn id. Returns {id, role, status, turn, maxTurns, touched…, currentTool? — array of tool name(s) currently executing (read from its dispatch state; omitted when none in flight — present when stuck in a long tool call), recentTurns: [last N one-line turn summaries, newest-first; default 5, parameterizable via recent]}. Readonly — observable on running/queued/done: running shows live activity, queued (not started) returns a placeholder, done (settled, report auto-delivered) returns the activity summary only — NOT the full report (that rides the auto channel; observe stays terse to keep your context lean). Use it to judge whether a long-running child is stuck vs progressing BEFORE deciding to cancel or steer it.\n" +
+    "- action:'send': STEER a running async subagent mid-flight — pass the spawn id + message (a direction like \"check X, don't fixate on Y\"). The message queues and the child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting — its current tool finishes first; its convergence/audit discipline is unchanged — injection is guidance, not a deviation waiver). Returns {id, status:'delivered', queued}. Only a RUNNING async subagent is targetable — sync (you're waiting on it, no relay), queued (not started), settled or unknown ids error clearly. If the child settles before its next turn boundary, its settle report carries an 'undelivered' note so you don't assume the guidance landed.\n" +
+    "- action:'escalate' (飞刀 — a flown-in expert): hand an implementation task to a STRONGER model from your consult models (agent.consultModels). It gets WRITE access and does the work itself — reads, edits, runs tests — then returns a post-op report (what changed, why, verification). Use it when YOU judge the task calls for stronger hands (complex multi-file refactoring, an intractable bug, intricate algorithm work — or work beyond your comfortable ability); escalate EARLY, not after burning attempts. model: pick a candidate as 'provider:model' (default = the first consult model). Not available in engineering mode (implementation goes through eng-coder spawns there). DEFAULT-ASYNC at depth 0 (AGENT-LOOP.md §25 D-R17b): the launch returns an ack {id, role:'escalate', status:'running'} and the flight runs in the background (pooled with the other role-domain spawns) — its post-op report is delivered to you automatically with its mutations merged into your bookkeeping; pass async:false to run it synchronously.\n" +
     "- action:'cancel': STOP one background subagent — pass the id from the async spawn return (REQUIRED — omitting it errors; a blanket cancel is unsupported, Ctrl+C stops everything). Running target aborts immediately ({id, status:'cancelled'}); a queued target is removed from the queue ({id, status:'cancelled', was:'queued'} and later queue positions shift forward). Other children and the session keep running — cancellation is targeted. Use it when a background child is going the wrong way (e.g. burning turns) and you must stop it before its report arrives. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first; prefer scoped recovery (restore a single affected file) over killing the child — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited.\n" +
+    "- action:'consume-design' (engineering mode, parent side — chain-terminal token consumption): after the delivery is verified and the chain closes out, consume this design's token slot — pass the designId (optional for a single-design session). The slot is consumed; a further spawn for the same designId is mechanically rejected, and any new work (including deviation fixes) requires a fresh design review and token. Idempotent: an unknown designId / already-consumed slot is a no-op notice, never an error. Do NOT call it while the chain is still open — fix rounds reuse the same slot (same designId + designToken).\n" +
     "- action:'panel': DIAGNOSE + fix the subagent panel — the collapsible blocks under the conversation the user sees (CLI TUI panel mirror; headless/VS Code degrade to a 'no panel' pool view). view (default — call it with no params or view:true): returns the live panel blocks [{key, role, status: running|done|awaitingDigest} — running entries also carry elapsedSec; awaitingDigest entries whose report is ALREADY digested carry digested:true (stuck blocks — the freezable ones — explain odd panel states here)] exactly as the user sees them. freeze: pass the block key of a digested-stuck block ({action:'panel', freeze:'role#N'}) to reclaim it into the conversation — the freeze ONLY passes for awaitingDigest blocks with no live pool entry and no pending report (gated); freezing a block whose report is still pending would break the digestion order and is refused with a clear error.\n\n" +
     "Why delegate? A sub-agent runs in its own isolated context — its reads, searches, tool calls and edits never enter your history or pollute your window; only its final report comes back. Delegation keeps your working context lean (you see the whole session, not the child's noise) and the child single-mindedly focused on one task. Parallel children run concurrently, saving wall-clock time. Every coder/eng-coder child carries its own verify + advisor self-review discipline — handed-off work is already verified before you read a word of it.\n\n" +
     "Available roles (which roles are exposed depends on the active mode — see Mode filtering below):\n" +
@@ -164,8 +67,8 @@ export const subagentTool = {
     "- coder — full implementation. The parent's complete read/write/execute toolset plus verify and advisor for self-review. Its final report must include a delivery transparency table with one row per task requirement (Done / Simplified / Not done — no deferred column).\n" +
     "- eng-coder — engineering-mode coder (available only in engineering mode, replacing coder). Same full toolset as coder plus the design-driven methodology overlay; REQUIRES a valid designToken arg obtained from a passed advisor(type='design') review. The advisor's Approved reply also echoes a designId — pass it as the designId arg: required to pick between designs when several approved reviews are active, optional for a single design. The delivery report echoes the designId back for the audit fix round.\n" +
     "Mode filtering: normal mode exposes explore/plan/coder; engineering mode exposes explore/plan/eng-coder. The schema enum reflects the active mode.\n\n" +
-    "Async spawn (AGENT-LOOP.md §15/§18): pass async:true to spawn WITHOUT waiting — returns {id, role, status:\"running\"} immediately so you can keep working in your own turn (read/check files, run other tools) while the child runs in the background. Fetch the report later with action:'check' — multiple async children return in completion (arrival) order, first finished first, so fast results are handled immediately. Query progress with action:'status' (non-blocking) — action:'check' BLOCKS until the target finishes. The DEFAULT is role-level: role='eng-coder' spawns async (its delivery protocol runs fully inside the child — implementation → audit → self-fix → advisor re-review → converged delivery; pass async:false only when you must handle the report synchronously); every other role defaults to blocking. Use async when your own turn must keep moving; use a blocking spawn when you must see the report before continuing. Async spawns are capped at 4 concurrent (further spawns queue with a position), and top-level only.\n\n" +
-    "Task scheduling (AGENT-LOOP.md §20): declare the scheduling metadata to let the SCHEDULER order your spawns — files: the file paths this task will modify, dependsOn: ids from prior async spawn returns whose outcome this task needs. Overlapping-file tasks are serialized and dependent tasks are started in order automatically: a spawn that would conflict, or whose dependencies have not settled, queues instead of running ({id, status:\"queued\", position, reason} — the waiting task auto-starts when the conflict clears / its dependency settles; cancel a queued task to drop it). A spawn whose dependency was cancelled or failed stays queued and marked \"dependency cancelled\" until you decide (cancel it) — in an AUTO session it starts by itself. Referencing an unknown id errors; an id already consumed by check counts as satisfied. Omit both parameters for the plain immediate spawn (no scheduler involvement).\n\n" +
+    "Async spawn (AGENT-LOOP.md §15/§18/§24): pass async:true to spawn WITHOUT waiting — returns {id, role, status:\"running\"} immediately so you can keep working in your own turn (read/check files, run other tools) while the child runs in the background. The child's report is delivered to you automatically — there is no fetch action; use action:'status' only to see progress, never to wait for the result. The DEFAULT is depth-gated (AGENT-LOOP.md §18 D-E1a): at the top level (depth 0) EVERY role spawns async by default — eng-coder's delivery protocol runs fully inside the child (implementation → audit → self-fix → advisor re-review → converged delivery); depth>0 spawns are always synchronous. Pass async:false only when you must handle the report synchronously. Use a blocking spawn when you must see the report before continuing. Async spawns are pooled per role domain (AGENT-LOOP.md §24): at most 4 concurrent eng-coders and 4 concurrent other-role spawns by default (agent.poolLimits overrides both) — a full domain queues further spawns with a position while the other domain keeps starting (domains never block each other), and top-level only. After an async spawn the turn winds down normally — nothing expects you to wait for it: the child runs in the background and its report is delivered to you automatically — before your next turn, or digested in the suspension session — so end the turn; do not poll or wait for the result. If your next step genuinely needs the report, use a synchronous spawn instead — pass `async:false` (at depth 0 every role defaults to async — async:false is the only way to block; depth>0 is always sync).\n\n" +
+    "Task scheduling (AGENT-LOOP.md §20): declare the scheduling metadata to let the SCHEDULER order your spawns — files: the file paths this task will modify, dependsOn: ids from prior async spawn returns whose outcome this task needs. Overlapping-file tasks are serialized and dependent tasks are started in order automatically: a spawn that would conflict, or whose dependencies have not settled, queues instead of running ({id, status:\"queued\", position, reason} — the waiting task auto-starts when the conflict clears / its dependency settles; cancel a queued task to drop it). A spawn whose dependency was cancelled or failed stays queued and marked \"dependency cancelled\" until you decide (cancel it) — in an AUTO session it starts by itself. Referencing an unknown id errors; an id already consumed (auto-delivered by the auto channel) counts as satisfied. Omit both parameters for the plain immediate spawn (no scheduler involvement).\n\n" +
     "Writing the prompt:\n" +
     "- The sub-agent starts with zero context — it has not seen this conversation. Brief it like a colleague who just walked into the room: state the goal, list what you already know, hand over the specifics.\n" +
     "- Put exact paths and commands in the prompt when you know them. The sub-agent should not search for things you already know.\n" +
@@ -174,20 +77,21 @@ export const subagentTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["spawn", "check", "status", "escalate", "cancel", "panel"], description: "Which subagent-family action — spawn (default), check (fetch async results — BLOCKS until the target finishes and consumes the report), status (non-blocking progress query — never consumes), escalate (飞刀 — hand implementation to a stronger consult model), cancel (stop ONE background subagent — pass its id; never omit), panel (view the live subagent panel / freeze a digested-stuck block — §19.6). See the tool description for the full action matrix." },
+      action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send"], description: "Which subagent-family action — spawn (default), status (non-blocking progress query — never consumes; async results arrive automatically — no fetch action), observe (inspect a running/queued/done async subagent's recent activity — recent turn summaries + current in-flight tool + turn/touched — §7.2), send (inject a direction into a RUNNING async subagent, consumed at its next turn boundary as an ordinary instruction — §7.2), escalate (飞刀 — hand implementation to a stronger consult model), cancel (stop ONE background subagent — pass its id; never omit), panel (view the live subagent panel / freeze a digested-stuck block — §19.6), consume-design (engineering mode, parent side: chain-terminal token consumption — close out a design's token slot after the delivery is verified and the chain closes out — §2.6, 2026-09-07). See the tool description for the full action matrix." },
       view: { type: "boolean", description: "action:'panel' only: true (default) = return the live panel blocks (the mirror of what the user sees). false with no freeze = nothing to do — error. Mutually exclusive with freeze (freeze wins)." },
       freeze: { type: "string", description: "action:'panel' only: block key of a digested-stuck awaitingDigest block (e.g. \"eng-coder#9\") to reclaim into the conversation via the gated done-freeze event. Refused when the block is running/done/unknown or its report is still pending digestion (would break the digestion order). Requires the CLI TUI panel mirror — headless/VS Code report the freeze unavailable." },
-      task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria). Not used by check/status." },
+      task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria). Not used by status." },
       context: { type: "string", description: "Optional background the sub-agent needs (it cannot see this conversation); action:'spawn' only." },
       role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder"], description: "The sub-agent role — see the tool description for the role capability matrix. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
       model: { type: "string", description: "action:'spawn': provider/model override for this sub-agent ('provider:model', a provider name, or a model name on the parent's provider — defaults to config.agent.subagentModels[role], then config.agent.subagentModel, then the parent's provider). pass \"default\" to explicitly inherit the default model — equivalent to omitting the parameter. action:'escalate': pick a consult candidate as 'provider:model' (default = the first consult model)." },
       designToken: { type: "string", description: "Required when role='eng-coder': the token returned by advisor(type='design') after the design review passed. Without a valid token, eng-coder cannot modify files." },
-      designId: { type: "string", description: "Optional when role='eng-coder': the designId echoed with the approved token by advisor(type='design'). Required to pick between designs when several approved reviews are active in the session — each eng-coder carries its own designId+token pair so parallel implementations never overwrite each other. Optional for a single design." },
-      async: { type: "boolean", description: "true = spawn without waiting — returns {id, status:\"running\"} immediately, fetch results later via action:'check'. Default is role-level: role='eng-coder' → true (async; its internal delivery protocol runs in the background — pass async:false to force the blocking spawn when you must process the report before continuing); all other roles → false (blocking)." },
+      designId: { type: "string", description: "Optional when role='eng-coder': the designId echoed with the approved token by advisor(type='design'). Required to pick between designs when several approved reviews are active in the session — each eng-coder carries its own designId+token pair so parallel implementations never overwrite each other. Optional for a single design. action:'consume-design': the design whose slot to close out — optional for a single-design session; required to pick when several approved designs are active (the consume gate refuses to guess)." },
+      async: { type: "boolean", description: "action:'spawn': true = spawn without waiting — returns {id, status:\"running\"} immediately; the report is delivered to you automatically (there is no fetch action). Default: depth-0 → true (async — every role, AGENT-LOOP.md §18 D-E1a); depth>0 → sync (forced). Pass async:false to force the blocking spawn when you must process the report before continuing. action:'escalate': same semantics (AGENT-LOOP.md §25 D-R17b) — default async at depth 0; async:false keeps the legacy synchronous flight." },
       files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares (cwd-relative or absolute paths). files must be file-level paths (one per file you will modify). Directory declarations are NOT supported — they bypass the conflict detector and are rejected with an error. Tasks with overlapping files are serialized automatically — a conflicting spawn queues ({id, status:\"queued\", position, reason}) instead of running concurrently and starts when the conflict clears. Omit to skip conflict detection (plain immediate spawn)." },
-      dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async spawn returns whose outcome this task needs — the task queues ({id, status:\"queued\", position, reason}) until every dependency settles, then starts automatically. Ids consumed by action:'check' count as satisfied; a dependency cancelled or failed leaves the task queued marked 'dependency cancelled' until you decide (cancel it — AUTO sessions auto-start). Unknown ids error." },
-      id: { type: "string", description: "action:'check'/'status'/'cancel': the subagent id from the async spawn return. check: omit = the next completed child (arrival order); status: omit = overview of the whole pool; cancel: REQUIRED (never omit — a blanket cancel is unsupported)." },
-      n: { type: "number", description: "action:'check' (required): 1-based read counter — 1 for the first check of the turn, incrementing with each subsequent check (loop detector — consecutive checks must be distinct tool calls)." },
+      dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async spawn returns whose outcome this task needs — the task queues ({id, status:\"queued\", position, reason}) until every dependency settles, then starts automatically. Ids already consumed (auto-delivered to the model) count as satisfied; a dependency cancelled or failed leaves the task queued marked 'dependency cancelled' until you decide (cancel it — AUTO sessions auto-start). Unknown ids error." },
+      id: { type: "string", description: "action:'status'/'observe'/'send'/'cancel': the subagent id from the async spawn return. status: omit = overview of the whole pool; observe/send/cancel: REQUIRED (observe needs the child to inspect; send needs the target; never omit on cancel — a blanket cancel is unsupported)." },
+      message: { type: "string", description: "action:'send' only (REQUIRED there): the direction to inject — the running async subagent consumes it at its next turn boundary as an ordinary user instruction (non-interrupting; its convergence/audit discipline is unchanged — injection is guidance, not a deviation waiver)." },
+      recent: { type: "integer", description: "action:'observe' only (optional, default 5): how many recent-turn summaries to return (clamped 1..20 — N2 keeps observe terse)." },
     },
     required: [],
   },
@@ -203,10 +107,10 @@ export const subagentTool = {
     if (action !== "spawn") {
       // §19 restricted-variant action gate (round2 #3): the eng-coder audit
       // channel (depth>0, role eng-coder) is spawn-only — escalate spawns a
-      // coder+WRITE child (violates explore-only intent) and check/status/panel
-      // have no async pool / panel mirror to query in a child context.
+      // coder+WRITE child (violates explore-only intent) and status/panel/
+      // observe/send have no async pool / panel mirror to query in a child context.
       if ((ctx.depth ?? 0) > 0 && ctx.agent?._role === "eng-coder") {
-        throw new Error(`only action:'spawn' (sync explore audits) is available inside an eng-coder — escalate/check/status/cancel/panel are not (AGENT-LOOP.md §19 D-M3)`)
+        throw new Error(`only action:'spawn' (sync explore audits) is available inside an eng-coder — escalate/status/cancel/panel/consume-design/observe/send are not (AGENT-LOOP.md §19 D-M3)`)
       }
       // §17 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn —
       // async OR blocking — the digest must stay organize-only. The escalate
@@ -215,16 +119,23 @@ export const subagentTool = {
       if (action === "escalate" && ctx.agent?._inAutoTurn && !ctx.agent?.autoApprove) {
         return JSON.stringify({ status: "error", error: "cannot spawn subagents from a manual auto-turn — wait for user input" })
       }
-      if (action === "check") return await executeCheckAction(args, ctx)
       if (action === "status") return executeStatusAction(args, ctx)
       if (action === "escalate") return await executeEscalateAction(args, ctx)
       // §19.5 控制类动作：digest 内放行（D-S7 分类——控制/自省；dispatch 控制类
       // 豁免同批生效——19.5.2b round2 #4；escalate 的 digest 拒绝在上一分支）
       if (action === "cancel") return executeCancelAction(args, ctx)
+      // 2026-09-07 token 链终消费制（ENGINEERING-MODE.md §2.6 F1）：父侧核销消费——
+      // 非只读控制动作——depth-0 + 工程模式限定（本分流已过受限变体门；工程模式门在
+      // 执行器内）——planMode 拒绝（dispatch 不豁免）——不入批审批分组（dispatch 免审）。
+      if (action === "consume-design") return executeConsumeDesignAction(args, ctx)
       // §19.6 panel 动作：view（readonly 面——digest 内放行——自省类）与 freeze
       // （控制类——同 cancel——digest 内放行）。深度/门控检查在 executePanelAction 内。
       if (action === "panel") return executePanelAction(args, ctx)
-      throw new Error(`Unknown subagent action: ${JSON.stringify(action)}. Valid actions: spawn, check, status, escalate, cancel, panel.`)
+      // SUBAGENT-OBSERVE-SEND：observe = readonly 查询（同 status——digest/planMode 放行）；
+      // send = 控制类豁免（同 cancel——父回合内显式调用即授权）。深度门在各自执行器内。
+      if (action === "observe") return executeObserveAction(args, ctx)
+      if (action === "send") return executeSendAction(args, ctx)
+      throw new Error(`Unknown subagent action: ${JSON.stringify(action)}. Valid actions: spawn, status, escalate, cancel, panel, consume-design, observe, send.`)
     }
 
     const parent = ctx.agent
@@ -235,9 +146,12 @@ export const subagentTool = {
     if (typeof args.task !== "string" || !args.task.trim()) {
       throw new Error("subagent action:'spawn' requires a task (the self-contained task brief).")
     }
-    // §18 F1/D-E1 role-level async default: eng-coder spawns async unless the
-    // caller explicitly passes async:false; every other role stays blocking.
-    const wantAsync = args.async ?? role === "eng-coder"
+    // §18 D-E1a depth-gated async default (2026-09-06 需求池 R12): depth-0 spawns
+    // default to async for EVERY role (the old role-level default — eng-coder only —
+    // is superseded); depth>0 spawns default to sync (子代理内部强制同步现状保留).
+    // async:false remains the explicit escape hatch; async:true at depth>0 is
+    // refused downstream (executeAsyncSpawn top-level gate).
+    const wantAsync = args.async ?? ((ctx.depth ?? 0) === 0)
 
     // Role normalization + whitelist (2026-08-25, coder-leak fix): exact-string gates let
     // variant roles ("Coder", " coder") bypass BOTH mode gates and fall through to
@@ -271,208 +185,17 @@ export const subagentTool = {
       return JSON.stringify({ status: "error", error: "cannot spawn subagents from a manual auto-turn — wait for user input" })
     }
 
-    // ── §20 spawn 调度参数准入（AGENT-LOOP.md §20 D-SD1/D-SD3 + 20.4 round2 #5/#7）──
-    // files/dependsOn 声明即契约（v1：不做任务书文本自动解析——不可靠）。缺省（两者皆
-    // 缺）= 既有语义零改动（不参与冲突检测/无校验——legacy spawn 零开销直通）。
-    // 校验序：参数形态 → 依赖 unknown id（非 consumed 墓碑——T-SD10）→ 依赖环可达
-    // （T-SD5——防御断言：自然流程不可达）→ 等待态判定。判定结果：wait/depc 阻塞 →
-    // async 入 queued 等位（spawn 返回带 reason——D-SD3b）；**sync spawn（async:false）
-    // 命中阻塞 → 明确错误——不队列化 sync——sync 语义零变更（round2 #7——T-SD13）**。
-    const filesRaw = args.files
-    const dependsRaw = args.dependsOn
-    // §20.8 D-F1.1：目录声明 fail-closed——检测器 throw → catch → 错误即工具结果
-    // （模型可见"文件级明细"提示——不加静默——目录绕过冲突检测的通道闭合）。
-    let files = []
-    if (filesRaw !== undefined && filesRaw !== null) {
-      try {
-        files = normalizeFileList(filesRaw, parent.cwd)
-      } catch (e) {
-        return JSON.stringify({ status: "error", error: e.message })
-      }
-    }
-    if (filesRaw !== undefined && filesRaw !== null && !Array.isArray(filesRaw)) {
-      throw new Error("subagent files must be an array of file paths (the write domain this task declares)")
-    }
-    const dependsOn = []
-    if (dependsRaw !== undefined && dependsRaw !== null) {
-      if (!Array.isArray(dependsRaw)) throw new Error("subagent dependsOn must be an array of async subagent ids (from prior spawn returns)")
-      for (const d of dependsRaw) {
-        if (typeof d !== "string" && typeof d !== "number") {
-          throw new Error(`subagent dependsOn entries must be async subagent ids — got ${JSON.stringify(d)}`)
-        }
-        dependsOn.push(String(d))
-      }
-    }
-    if (files.length > 0 || dependsOn.length > 0) {
-      for (const d of dependsOn) {
-        if (depInfo(parent, d).state === "unknown") {
-          throw new Error(`subagent dependsOn: unknown async subagent id: ${d} — dependsOn references ids from prior async spawn returns; an id already consumed by action:'check' (or auto-injected) counts as satisfied, anything else is a mistake (AGENT-LOOP.md §20 D-SD5)`)
-        }
-      }
-      assertNoDepCycle(parent, dependsOn)
-      const block = describeBlockers(parent, { _files: files, _dependsOn: dependsOn })
-      if (!wantAsync && block.kind !== "slot") {
-        throw new Error(`sync spawn (async:false) cannot queue behind a scheduling conflict: ${block.detail} — pass async:true to queue the task (the scheduler starts it when the blockers clear), or wait for them to finish first (AGENT-LOOP.md §20 round2 #7)`)
-      }
-    }
-
-    // Provider/model override: tool `model` arg > subagentModels[role] > subagentModel > parent provider
-    const childProvider = resolveChildProvider(parent, effectiveSubagentModel(parent, role, args.model))
-
-    // eng-coder token gate: the design review must have passed and the caller must
-    // present the exact token advisor issued — otherwise the child is not authorized to code.
-    // 2026-09-01: multi-design slots — the token is located by designId (exact slot,
-    // single-slot fallthrough); HMAC/TTL validation itself is unchanged.
-    let issuedToken
-    if (role === "eng-coder") {
-      issuedToken = resolveDesignSlot(parent, args.designId).token
-      if (!issuedToken || args.designToken !== issuedToken || !validateDesignToken(args.designToken)) {
-        throw new Error("Invalid or missing design token — run advisor with type='design' first and pass the returned token as designToken.")
-      }
-    }
-
-    // Filter tool set by role: explore/plan are read-only (plan is a planning agent, its deliverable is the plan itself)
-    let tools
-    if (role === "explore" || role === "plan") {
-      const allowed = readonlyToolNames(parent.tools)
-      tools = parent.tools.filter((t) => allowed.has(t.name))
-    } else {
-      tools = parent.tools
-    }
+    // §20 准入（2026-09-05 module-split——prepareScheduling verbatim 迁
+    // subagent-spawn.mjs：参数形态/unknown id/依赖环/阻塞 sync 判定；files 目录声明
+    // fail-closed——检测器错误即工具结果 JSON）
+    const prep = prepareScheduling(parent, args.files, args.dependsOn, wantAsync)
+    if (prep.errorJson) return prep.errorJson
 
-    // Select prompt overlay by role
-    let overlay = ""
-    if (role === "explore") overlay = EXPLORE_OVERLAY
-    else if (role === "coder") overlay = CODER_OVERLAY
-    else if (role === "plan") overlay = PLAN_OVERLAY
-    else if (role === "eng-coder") overlay = ENG_CODER_OVERLAY
-
-    // explore/plan: force read-only permission; coder/default: AUTO passes through directly,
-    // manual mode queues permission requests for the parent agent's approval UI (human in the loop, child agent is no longer silently rejected)
-    let childPermission
-    if (role === "explore" || role === "plan") {
-      childPermission = async () => false
-    } else if (parent.autoApprove) {
-      childPermission = async () => true
-    } else {
-      childPermission = async (name, toolArgs) => {
-        if (!ctx.onPermissionRequest) return false
-        const ask = () => ctx.onPermissionRequest(`${role ?? "sub"}/${name}`, toolArgs)
-        // Queue parallel child agent permission requests to avoid two popups simultaneously overwriting each other (lesson from question tool)
-        parent._permQueue = (parent._permQueue ?? Promise.resolve()).then(ask, ask)
-        return parent._permQueue
-      }
-    }
-
-    // eng-coder: force engineering=true on child config so setup.mjs applies engineering prompt
-    const childConfig = role === "eng-coder"
-      ? { ...parent.config, agent: { ...parent.config.agent, engineering: true } }
-      : parent.config
-
-    const child = createAgent({
-      provider: childProvider,
-      tools,
-      config: childConfig,
-      cwd: parent.cwd,
-      memory: parent.memory,
-      overlay,
-      role,
-    })
-
-    // Token-verified design review → child is authorized to modify files without re-reviewing
-    if (role === "eng-coder") child._engDesignReviewed = true
-    // §18 D-E3 task-domain authorization: approved design + spawn task = authorization.
-    // The child's OWN tools skip ONLY the onPermissionRequest ask (autoApprove
-    // equivalent — dispatch.mjs permission stage); every other gate (JSON parse /
-    // unknown tool / planMode / design-token) still applies (T-E14). Non-eng-coder
-    // children keep the manual per-write parent approval (human in the loop).
-    if (role === "eng-coder") child._engTaskAuthorized = true
-    // designId+token ride the child bookkeeping: the delivery report carries the designId
-    // so the divergence-audit fix round re-spawns with the SAME slot (2026-09-01 FR3).
-    if (role === "eng-coder" && issuedToken) {
-      child._engDesignId = args.designId ?? null
-      child._engDesignToken = issuedToken
-    }
-
-    // §18.5 子代理零 git（D-AG1——2026-09-04 用户裁定）：explore/plan 一律不注入
-    // git 上下文——子代理证据链 = 任务书 ∪ 磁盘当前状态（read/glob/grep）∪（审计时）
-    // _touchedFiles，无一项来自 git；注入的全工作区脏状态快照与任务域无关，会误导
-    // 审计/探索（"status 里这个文件算不算超清单？"）。注入分支整体删除（B 方案
-    // git 只读变体亦随裁定废弃——D-AG5）。顶层主 agent 注入保留（§3 prepareRun——
-    // setup.mjs depth===0——D-AG7 范围边界）。
-    let input = args.context ? `Context:\n${args.context}\n\nTask:\n${args.task}` : args.task
-    // §18 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
-    // the eng-coder's OWN spawn task — mechanically kept as _engTaskInput by the
-    // parent spawn and injected as the D-TS5 A2 mechanical summary (design docs /
-    // affected-file list / acceptance criteria verbatim, verbose context dropped)
-    // — ∪ the mechanically tracked _touchedFiles — NEVER the eng-coder's
-    // self-written list: a self-report could omit exactly the out-of-scope file
-    // the audit must catch.
-    if (engAuditAttempt !== null) {
-      const touched = (ctx.agent._touchedFiles ?? []).map((f) => `- ${f}`).join("\n") || "- (none yet)"
-      input += `\n\n[Audit scope — mechanical context, independent of the eng-coder's self-report:]\n` +
-        // §18.7 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
-        // 不再靠模型自悟；范围限制是 §18.5 D-AG3 声明（下方 Zero-git scope authority）
-        // 的同源一句指注，不重复声明。
-        `[Audit instructions — mechanical template (AGENT-LOOP.md §18.7 D-TS4 A1):]\n` +
-        `You are auditing an eng-coder delivery against its approved design — audit for EXACTLY these four deviation categories:\n` +
-        `- PARTIAL: an acceptance criterion implemented partially or not at all;\n` +
-        `- SILENT-SIMPLIFICATION: a "simpler approximation" of a specified behavior substituted for the spec;\n` +
-        `- DOC-DRIFT: code changed without the owning design-doc section (module map / affected-files table) updated in the same delivery;\n` +
-        `- OUT-OF-LIST: changes outside the approved file list.\n` +
-        `Audit scope = _touchedFiles above UNION the files confirmed by the parent task book (single source — the Zero-git scope authority note below, AGENT-LOOP.md §18.5 D-AG3; NOT a second copy): ` +
-        `workspace changes not listed there are unrelated to this delivery and are NOT grounds for an out-of-list finding.\n` +
-        `Scope discipline (F-TS6 A1): read ONLY the audited files and the design-doc sections relevant to this delivery — do NOT re-read whole documents.\n` +
-        `Every deviation item MUST be fieldized: file:line + design reference (doc path + section/AC id) + severity + evidence (quoted code or doc text).\n` +
-        // §18.7 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
-        `[Parent spawn task book — mechanical summary (AGENT-LOOP.md §18.7 D-TS5 A2): design docs + affected-file list + acceptance criteria verbatim; verbose context/background dropped — the design docs are still available for reading outside this input:]\n` +
-        `${summarizeEngTaskBook(ctx.agent._engTaskInput)}\n` +
-        `Files actually touched by the eng-coder (mechanical union — audit these against the file list):\n${touched}\n` +
-        // §18.5 D-AG3（2026-09-04）：审计零 git 范围权威声明——本审计任务零 git（不注入
-        // git 上下文——§18.5 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
-        // _touchedFiles 的改动与本任务无关，不作超清单依据（VS Code auditTaskBook 同款措辞）。
-        "Zero-git scope authority (AGENT-LOOP.md §18.5 D-AG3): this audit task receives NO git context — nothing is injected. " +
-        "The evidence base is the design documents, the current disk state (read/glob/grep), and the _touchedFiles list above. " +
-        "Workspace changes NOT listed in _touchedFiles are unrelated to this delivery — they are NOT grounds for an out-of-file-list finding." +
-        // §18.13 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
-        // 逐字设计锚（D-A1.2 代码块）：只读该读的——10 轮机械预算——超时报 PROBLEM 下结论。
-        // 前导 \n 与 A3 同款块分隔约定（上一句 Zero-git 句末无换行——不触碰既有句）。
-        `\n[Audit budget — mechanical]: read ONLY the touched files listed above and the design-doc sections the parent task book names (affected-files table, acceptance criteria, status line). Do NOT read whole documents. Budget = 10 tool rounds max — if you cannot conclude within it, report PROBLEM (inconclusive) rather than continuing to explore.\n` +
-        // §18.7 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
-        `\n[Audit report format — mechanical template (AGENT-LOOP.md §18.7 D-TS6 A3):]\n` +
-        `Report EXACTLY one of three states:\n` +
-        `- CLEAN — no deviation across the four categories: reply the line "Four deviation categories: none found." (四类偏差均未发现);\n` +
-        `- DEVIATIONS — one row per deviation, every row fieldized: | category | file:line | design reference | severity | evidence |;\n` +
-        `- PROBLEM — the audit itself could not run / inconclusive: state what blocked it.\n`
-    }
-    // The child's own task input rides the child object: an eng-coder's audit
-    // spawns reuse it as the task-book SOURCE — injected as the D-TS5 A2
-    // mechanical summary, not verbatim (see above).
-    if (role === "eng-coder") child._engTaskInput = input
-
-    // 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)
-    // Async id allocation (AGENT-LOOP.md §15 D-A1): reserve the relay counter at
-    // spawn time — the returned id must be stable while the item sits in the queue.
-    // The [model] token (TUI block creation) is DEFERRED to actual start so queued
-    // children don't paint an empty panel block ("queued 态不显示").
-    let relayPrefix
-    if (wantAsync) {
-      parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
-      relayPrefix = `${role}#${parent._subAgentCounter}/`
-    } else {
-      relayPrefix = makeRelay(parent, role ?? "sub", ctx.callbacks?.onToken, childProvider.model ?? "")
-    }
-    // LOGGING（LOGGING.md）：子代理内部事件（子内 llm:*/tool:*）以 childId 归属——
-    // agent._logId 随 runAgent 的 logCtx 透出（主文件单文件全记、按 childId grep）。
-    child._logId = relayPrefix.slice(0, -1)
-    const childOpts = {
-      onPermissionRequest: childPermission,
-      ...wrapChildCallbacks(relayPrefix, ctx.callbacks),
-    }
-    const childRunOpts = buildChildRunOpts(ctx)
+    // child 装配（2026-09-05 module-split——buildSpawnChild verbatim 迁
+    // subagent-spawn.mjs：provider/model 覆盖、角色门、design-token 门、工具集/
+    // overlay/permission 装配、审计任务书注入、relay 前缀分配、childOpts/runOpts）
+    const built = buildSpawnChild(parent, ctx, args, role, wantAsync, prep.files, prep.dependsOn, engAuditAttempt)
+    const { child, input, childOpts, childRunOpts, relayPrefix } = built
     // 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,
@@ -487,199 +210,10 @@ export const subagentTool = {
       return parent._permQueue
     }
 
-    // ── Async branch (AGENT-LOOP.md §15 D-A1/D-A6): spawn without waiting ──
-    // The child runs the EXACT blocking pipeline (runChildPipeline below — relay /
-    // turn-cap / permission / MIN_REPORT_CHARS / mergeChildMutations all unchanged),
-    // but the parent does not await it: the promise is parked in _asyncSubagents and
-    // consumed via action:'check' or the turn-end auto-wait. Slot queue: running
-    // count < ASYNC_SUBAGENT_LIMIT → start now; ≥ limit → enqueue (status "queued",
-    // position = queue index) — never rejected, never requiring the model to batch.
+    // ── Async branch（2026-09-05 module-split——executeAsyncSpawn verbatim 迁
+    // subagent-run.mjs：条目构建/等位/启动/controller 链/turn 镜像/补位释放）──
     if (wantAsync) {
-      if ((ctx.depth ?? 0) > 0) {
-        throw new Error("async spawn only available at the top level")
-      }
-      parent._asyncSubagents ??= new Map()
-      parent._asyncQueue ??= []
-      const running = [...parent._asyncSubagents.values()].filter((e) => e.status === "running").length
-      const id = parent._subAgentCounter
-      const entry = {
-        id, role, relayPrefix,
-        status: "queued", // 下面按等待态/槽位重定（避免两处判断漂移）
-        position: undefined,
-        report: null, error: null, done: false, cancelled: false,
-        promise: null, _settle: null, _settleSeq: 0,
-        // §19.5 D-M5 可决策字段（status 数据装配锚点）：model 在 spawn 时记录；
-        // startedAt 在 ACTUAL start（queued 等待不计 elapsed）；turn/maxTurns 由
-        // 下方 onToken 拦截层从子代理 ⟦ev⟧turn 事件镜像（T-M18 正确性断言）。
-        model: childProvider?.model ?? null,
-        startedAt: null,
-        turn: 0, maxTurns: 0,
-        // §19.5 D-M6 (round2 #2)：条目级 AbortController——cancel 定向 abort 本
-        // 条目（runAgent signal 链）；Ctrl+C 全停语义不变（基信号 abort 逐链传播）。
-        controller: null,
-        // §20 D-SD2 域元数据（AGENT-LOOP.md §20）：running ∪ queued 条目全带——
-        // _files（归一化绝对路径）/ _dependsOn（字符串 id）——冲突检测与补位判据
-        // 的事实源；无调度参数 spawn 两字段皆空（legacy——不参与冲突检测——零改动）。
-        _files: files,
-        _dependsOn: dependsOn,
-        _lastQueuedSig: null, // ⟦ev⟧queued 去重 sig（refreshQueuedTokens）
-      }
-      // §20 D-SD3 准入落点：等待态（依赖未满足/域冲突/depc）→ queued（waiting-deps——
-      // 不占槽不启动——即使槽空）；纯槽满（kind slot）→ queued（等位）；否则立即启动。
-      // 派生实时计算（describeBlockers——池状态在 spawn 同步段内不变——与前面准入一致）。
-      const blockers = describeBlockers(parent, entry)
-      if (blockers.kind === "slot") {
-        entry.status = running >= ASYNC_SUBAGENT_LIMIT ? "queued" : "running"
-      } else {
-        entry.status = "queued" // waiting-deps / dependency-cancelled——slot 空也不启动
-      }
-      // The settle signal — resolves when the run chain settles (never rejects).
-      entry.promise = new Promise((res) => { entry._settle = res })
-      // §19.5 D-M6：条目 controller 链到会话/回合基信号（_sessionSignal 优先——
-      // §17 挂起会话内 children 持会话 signal，digest 自身 Ctrl+C 不误伤）。
-      const ctrl = new AbortController()
-      entry.controller = ctrl
-      const baseSignal = parent._sessionSignal ?? ctx.signal ?? null
-      if (baseSignal) {
-        if (baseSignal.aborted) ctrl.abort()
-        else baseSignal.addEventListener("abort", () => ctrl.abort(), { once: true })
-      }
-      // §19.5 D-M5：turn 镜像拦截层（callbacks 包装层——选改动最小方案：在既有
-      // wrapChildCallbacks 之外再包一层，只解析 ⟦ev⟧turn 更新条目，其余原样转发）。
-      const trackOpts = { ...childOpts }
-      const parentOnToken = trackOpts.onToken
-      if (parentOnToken) {
-        trackOpts.onToken = (t) => {
-          const ev = String(t).match(/^⟦ev⟧turn\x1e(\d+)\x1e(\d+)\x1e/)
-          if (ev) {
-            entry.turn = Number(ev[1]) || 0
-            entry.maxTurns = Number(ev[2]) || 0
-          }
-          return parentOnToken(t)
-        }
-      }
-      entry.start = () => {
-        entry.status = "running"
-        entry.position = undefined
-        entry.startedAt = Date.now()
-        // §19.5.6 D-SF1（round3 #1）：绑定子代理对象引用——绑定时刻 = 实际启动时
-        // （queued 条目 spawn-ack 时刻尚无子代理对象——§20 D-SD3b）；绑定对象 = 子代理
-        // 对象（不是 _touchedFiles 数组引用——per-run 记账在 prepareRun 重置——数组
-        // 引用会陈旧——对象引用保证 status 查询时实时读——杀前一刻最新）。
-        entry.childAgent = child
-        // §19.5 D-M7b ①: async 标记事件——零字段 ⟦ev⟧async token（sync 不发）。
-        // 锚点 = 实际启动（与 [model] 同步——queued 入队不 paint，补位启动才发）；
-        // 先于 [model] 发出——区块创建即知 sub.async（routeSubToken 解析——
-        // ⏹ 门控与头标 async 的判定源）。父级直接 emit（depth-0 专属路径——
-        // 不经子代理文本 strip 白名单——与 ⟦ev⟧stopped/settled 同族）。
-        ctx.callbacks?.onToken?.(relayPrefix + "⟦ev⟧async\x1e")
-        // Deferred [model] emit: the TUI block is created at ACTUAL start.
-        ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (childProvider.model ?? ""))
-        // Turn-cap on background children NEVER pops the continue panel (D-A3):
-        // §15 D-A3 exception (2026-09-02 unified rule, AGENT-LOOP.md §2): in an
-        // engineering && AUTO session the child auto-resumes — the user authorized
-        // unattended runs, no one is at the panel. Every other tier auto-declines
-        // and the partial-work report carries the cap reason. §18 D-E2 relies on
-        // this exception as the turn-cap fallback for the default-async eng-coder
-        // delivery (the internal protocol does not raise the 100-turn cap).
-        runChildPipeline(child, input, trackOpts, { ...childRunOpts, signal: entry.controller.signal }, {
-          parent, role, args,
-          askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
-        })
-          .then((report) => { entry.report = report })
-          .catch((err) => { entry.error = err?.message ?? String(err) })
-          .finally(() => {
-            entry.status = "done" // running 数口径（D-A1/D-A2/T6）：已完成未消费不计入
-            entry.done = true
-            // LOGGING（LOGGING.md）：settle 分流事件——child:done/child:error（结果）+
-            // ev:cancelled/ev:settled（settle 回调分流——取消/挂起移交；正常回合内 settle
-            // 由 child:done 覆盖不另发 ev——ev:stopped 见中止清池点）
-            const childLogId = `${entry.role}#${entry.id}`
-            const childMs = entry.startedAt ? Date.now() - entry.startedAt : 0
-            // 中止守卫（2026-09-03 code review #5）：Ctrl+C/会话中止时子代理以 error 形态
-            // settle——不落 child:error/done/ev:settled（ev:stopped 已在中止清池点表达；
-            // 同文件阻塞路径同款抑制——"用户停——不落错误事件"）。定向 cancel 走 ev:cancelled。
-            const parentAborted = ctx.signal?.aborted || entry.controller?.signal?.aborted
-            if (entry.cancelled) {
-              logEvent("ev:cancelled", { id: childLogId })
-            } else if (!parentAborted) {
-              if (entry.error != null) logEvent("child:error", { role: entry.role, id: childLogId, ms: childMs, err: errText(entry.error, 200) })
-              else logEvent("child:done", { role: entry.role, id: childLogId, ms: childMs, kind: String(entry.report ?? "").includes(TURN_CAP_MARK) ? "partial" : "ok" })
-              if (parent._suspended) logEvent("ev:settled", { id: childLogId, kind: "suspended" })
-            }
-            // §19.5 cancelled settle 分支（D-M6 round1 #1 + round2 #3）：cancel 定向
-            // 中止的条目——不入 _pendingAsyncResults、不参与 collectSettledAsync 直注入
-            // （清池规则同 Ctrl+C 全停但只清该条目——陈旧错误零注入）；发 ⟦ev⟧stopped
-            // 冻结事件（TUI 区块 interrupted 语义冻结——标题 "stopped"）；取消事实与半成品
-            // 警示对模型可见（user-role 提醒——形态仿 injectAsyncResult、XML 转义——防基于
-            // 半成品树继续：mergeChildMutations 不覆盖 abort 路径）。
-            // §20 D-SD5：running 依赖取消的 settle 终态点——写终态墓碑（running 取消无
-            // 出队事件——出池在 settle）；queued 依赖者随之标注 dependency cancelled
-            // （refreshQueuedTokens——settle 后统一段）；提醒文本列出依赖者（供模型决策）。
-            if (entry.cancelled) {
-              parent._asyncSubagents?.delete(String(entry.id))
-              const tombstones = (parent._asyncTombstones ??= new Map())
-              tombstones.set(String(entry.id), { status: "cancelled", role: entry.role })
-              ctx.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧stopped\x1e0\x1e0\x1estopped\x1e`)
-              const dependents = dependentLabels(parent, String(entry.id))
-              const autoNote = parent.autoApprove
-                ? " — AUTO session: they auto-start on slot availability (round2 #3)"
-                : " — they stay queued until you cancel them or an AUTO session starts them"
-              pushReal(parent, {
-                role: "user",
-                content: `[System reminder: subagent ${escapeXml(entry.role)}#${entry.id} cancelled by user — partial changes not merged/audited${dependents.length > 0 ? `; queued dependents ${dependents.join(", ")} marked "dependency cancelled"${autoNote}` : ""}]`,
-              })
-            } else if (!ctx.signal?.aborted) {
-              // 完成信号按会话态分流（§17 D-S8 冻结门控 + D-S3 记账——以读取时刻为准，确定性）：
-              // - 非挂起态（普通回合内 settle）：照发 ⟦ev⟧done —— TUI 立即冻结区块，冻结位置 =
-              //   完成时刻的流位置（§15 D-A3 2026-09-02 用户实证修正：收尾统一发会把块堆在结论之后）。
-              //   §17.5 supersede：回合尾 collectSettledAsync（suspDriven）不再直注入——条目留池
-              //   由挂起会话首轮 sweep → digest 消化（17.5.2 方案 B——块已冻结不受影响）。
-              // - 挂起态（_suspended：回合已结束或 auto-turn 消化中）：冻结延迟——改发 ⟦ev⟧settled
-              //   （区块显示 "done · awaiting digestion" 驻留面板），条目移交 _pendingAsyncResults
-              //   由下个回合 prepareRun 前注入（D-S3 ②；注入即从池/pending 移除，无重复）；
-              //   §17.5.5：注入完成后 freezeReclaimDigestedBlocks 逐条回收冻结（不等池空）。
-              // 父会话 abort 两种都不发：TUI 已按 interrupted 冻结，晚到 token 经 tombstone 丢弃。
-              if (parent._suspended) {
-                parent._pendingAsyncResults ??= []
-                parent._pendingAsyncResults.push(entry)
-                parent._asyncSubagents?.delete(String(entry.id))
-                ctx.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
-              } else {
-                ctx.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
-              }
-            }
-            entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
-            entry._settle()
-            for (const w of parent._asyncWaiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
-            // §20 D-SD4 释放点：settle 腾槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
-            // 解除者自动启动——槽 ≤4）→ 排队态面板刷新（等待块头标注随终态更新——
-            // dependency cancelled / 位置前移）。
-            maybeRefillAsync(parent)
-            refreshQueuedTokens(parent, ctx.callbacks?.onToken)
-          })
-      }
-      parent._asyncSubagents.set(String(id), entry)
-      // LOGGING（LOGGING.md）：child:spawn（async——注册即事件；status 记 queued/running 分流；
-      // 实际启动由补位 start() 触发——运行中由子内 llm/tool 事件可见）
-      logEvent("child:spawn", { role, id: `${role}#${id}`, kind: "async", status: entry.status, ms: 0 })
-      if (entry.status === "queued") {
-        parent._asyncQueue.push(entry)
-        entry.position = parent._asyncQueue.length
-        // §20 D-SD3b：排队 spawn 返回即建面板 waiting 块（⟦ev⟧queued 事件——spawn 侧
-        // 发——TUI routeSubToken 消费建块/更新头；启动后 ⟦ev⟧async 转 running——同 key
-        // 不重建）。refreshQueuedTokens 同时校正既有排队条目的位置/等待态头。
-        refreshQueuedTokens(parent, ctx.callbacks?.onToken)
-        const blk = describeBlockers(parent, entry)
-        const out = { id: String(id), role, status: "queued", position: entry.position }
-        if (blk.kind !== "slot") {
-          out.waiting = blk.kind === "depc" ? "dependency-cancelled" : "waiting-deps"
-          out.reason = blk.detail
-        }
-        return JSON.stringify(out)
-      }
-      entry.start()
-      return JSON.stringify({ id: String(id), role, status: "running" })
+      return executeAsyncSpawn(parent, ctx, role, args, child, input, childOpts, childRunOpts, relayPrefix, built.childProvider, prep.files, prep.dependsOn)
     }
 
     // ── Blocking path (unchanged semantics): await the full pipeline ──
@@ -692,6 +226,11 @@ export const subagentTool = {
         parent, role, args,
         askContinue: askSubagentContinue,
       })
+      // §27 R23 D-R23c1（评审 #1 🅰——生成侧补发射）：sync spawn 同步收尾——若本 spawn
+      // 处于嵌套上下文（ctx.callbacks 已是嵌套 wrapper——eng-coder 内 explore 审计）→
+      // 发内层 ⟦ev⟧done（完整嵌套前缀——wrapper 链自动补外层）→ 主 TUI 路由子块定格
+      // （T-R23c.1）。非嵌套（depth-0）零变化——冻结仍由 dispatch subKey 精确冻承接。
+      emitNestedChildEvent(ctx, relayPrefix, "done")
       logEvent("child:done", { role, id: child._logId, ms: Date.now() - blockT0, kind: String(pipelineReport).includes(TURN_CAP_MARK) ? "partial" : "ok" })
       // §7.2.3 sync spawn 完成精确冻结（方案 e）：execute 返回前 ctx 留子代理 key
       // （relayPrefix 去尾 = `role#N`）——dispatch runOne 读它作 onToolResult 第 4 参 →
@@ -702,25 +241,38 @@ export const subagentTool = {
       ctx._subagentKey = relayPrefix.slice(0, -1)
       return pipelineReport
     } catch (e) {
-      if (ctx.signal?.aborted || e?.name === "AbortError") throw e // 用户停——不落错误事件
+      if (ctx.signal?.aborted || e?.name === "AbortError") {
+        // §27 R23：外层 abort 传播的中断——内层开块随之外层冻结前先收尾定格
+        // （D-R23c1 stopped——T-R23c.2a 生成侧路径；TUI 冻结兜底仍在 freezeSubTaskLines）
+        emitNestedChildEvent(ctx, relayPrefix, "stopped")
+        throw e // 用户停——不落错误事件
+      }
+      // §27 R23 error-run 映射（实现批补一行）：run 错误（非 abort）→ 同样发 stopped
+      // ——内层子块定格不悬空（T-R23a.3——工具错/运行错误路径）。
+      emitNestedChildEvent(ctx, relayPrefix, "stopped")
       logEvent("child:error", { role, id: child._logId, ms: Date.now() - blockT0, err: errText(e, 200) })
       throw e
     }
   },
 }
 
-// Re-export shim (2026-09-03 拆分轮 + §19 合体轮): 机械与合体动作执行器迁至
-// ./subagent-async.mjs——保留本文件导出面，消费点（agent.mjs / agent-turn.mjs /
-// consult.mjs / 测试）导入路径零改动。execute 仍直接使用 ASYNC_SUBAGENT_LIMIT /
-// maybeRefillAsync / buildChildRunOpts / runChildPipeline（文件头部 import）。
+// Re-export shim (2026-09-03 拆分轮 + §19 合体轮 + 2026-09-05 拆分轮): 机械与动作
+// 执行器迁至 ./subagent-async.mjs、./subagent-actions.mjs、./subagent-scheduler.mjs
+// ——本文件保留导出面，消费点（agent.mjs / agent-turn.mjs / consult.mjs / 测试）导入
+// 路径零改动；池逻辑/准入见 subagent-run.mjs（executeAsyncSpawn）与 subagent-scheduler.mjs
+// （maybeRefillAsync——execute 不再直接使用池常量）。
 // 2026-09-05 拆分轮: maybeRefillAsync 随 §20 调度器独立（./subagent-scheduler.mjs）——
 // 再导出源改写，消费面（agent.mjs 动态 import 等）不变。
+// 2026-09-06 §24 拆分轮: ASYNC_SUBAGENT_LIMIT 导出 → ASYNC_POOL_LIMITS（分域常量——
+// 定义在 subagent-async.mjs——re-export 面同步）。
 export {
-  ASYNC_SUBAGENT_LIMIT,
-  MAX_ASYNC_CHECKS,
+  ASYNC_POOL_LIMITS,
   resolveChildProvider,
   injectAsyncResult,
   buildChildRunOpts,
   mergeChildMutations,
 } from "./subagent-async.mjs"
 export { maybeRefillAsync } from "./subagent-scheduler.mjs"
+// 2026-09-05 module-split：spawn 装配 helpers 迁 subagent-spawn.mjs——re-export 保测试
+// import 面（subagent-core.test.mjs 从本文件动态 import）
+export { effectiveSubagentModel, resolveDesignSlot } from "./subagent-spawn.mjs"