@feng0531/dsh-code-review 0.88.0 → 0.89.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 本文件介绍对使用者有意义的变化。安装与参数见 [README](README.md)，本次发布正文见 [发布说明](RELEASE-NOTES.md)。历史提交和安装包保留在 [GitHub Releases](https://github.com/f-e-n-g-0531/dsh-code-review/releases)；本文不把开发日志当作功能介绍。
 
+## 0.89.0 — 超限分组的真实子智能体并行
+
+- 整体路径只有完整输入超限分组时创建真实spawn子会话，默认2组、可配1～4；同组持续上下文补读，主审全部收尾后集中复核。默认策略仍staged。
+- 受限快照工具强绑定child身份，共用唯一读取账本和模型生成尝试额度；能力或身份变化拒绝，不隐藏串行回退。逻辑LLM输入检查不冒充最终HTTP字节。
+- FIFO检查点、取消join和首个致命原因保真，按批准顺序汇总；跨组未核查仍partial。
+- 实际宿主独立离线Context通过两个真实child的并行、持续读取和结构化终态验证；模型、快照和cwd为fixture，不宣称真实提供方质量或业务提速。
+
 ## 0.88.0 — 整体主审实验路径与自动回归
 
 - 新增whole-scope完整文件字节合批与候选集中复核，显式输入容量绑定预览和执行；默认仍staged，fresh单轮changes限定，超大文件及跨批缺口如实保留。

package/README.md

@@ -280,7 +280,11 @@ Git / SVN 历史审查也能使用这些参数；依赖和调用方按对应版
 
 插件配置 `executionStrategy: "whole-scope"` 启用完整文件按字节合批的变更审查。能装下时，一次主审同时检查全部成员；超限才分批，不按四个文件强切，不再额外调用逐文件风险规划、业务分组及旧专门综合。候选集中独立复核，缺少上下文时仍可能增加检索调用，因此不承诺总调用仅一次。
 
-`maxInputBytes` 是插件显式输入保护，不是模型上下文容量探测；默认仍为 98304 字节，允许配置为 1～4194304 的整数。预算包含完整新旧正文、JSON 转义、规则、检索目录、指令与原生结果工具，预览的 `plan.maxInputBytes` 与执行使用同一值。提高前应核实当前模型容量、费用及提供方限制，插件不会自动猜测容量或因失败不断加大输入重试。
+实际超限分为多组时，整体路径使用宿主真实 `spawn` 子智能体有界并行，`wholeScopeConcurrency` 可设1～4（默认2）；只有一组时不创建子智能体。每组保持独立会话和持续上下文，补读不重新建组；全部主审收尾后集中复核。宿主须具备受限预设、结构化子会话和活动父Agent；能力缺失或变化明确拒绝，不暗中退回串行。子智能体共用唯一批准快照读取账本与模型生成尝试总账，取消须等待所有子会话清理。跨组关系未核查仍partial，并行不提高完成标准。
+
+内部 `review_snapshot` 工具可能在父会话目录可见，但只有本次注册且身份绑定的审查子会话可执行；父会话和其他子会话读取前拒绝。子会话作为宿主管理的独立Session按宿主规则记录，可能含批准源码和工具响应，不等同于插件私有模型工件留存。
+
+`maxInputBytes` 是插件显式输入保护，不是模型上下文容量探测；默认仍为 98304 字节，允许配置为 1～4194304 的整数。主审计划计入完整新旧正文、JSON转义、规则、检索目录、指令与原生结果工具；持续子会话发送前另外检查包含历史消息和工具的逻辑LLM envelope，不是提供方最终HTTP字节。宿主系统提示与历史开销可能使已规划组在发送前受限，届时保留未完成而不截断源码。预览的 `plan.maxInputBytes` 与执行使用同一值。提高前应核实当前模型容量、费用及提供方限制，插件不会自动猜测容量或因失败不断加大输入重试。
 
 当前仅支持 fresh 单轮 changes；多轮、旧任务恢复及 project 明确拒绝，预览显示 `resumeSupported:false`。超大完整文件显示 blocked，不截断或把差异窗口冒充全文；多批跨边界未核查保持 partial。身份、原文定位、归因、独立复核回执及来源新鲜度校验不变。默认仍为 `staged`；整体路径尚无真实业务同条件质量与耗时验收，不宜把单测调用减少当作业务问题已解决。配置由宿主插件管理方式加载，发布不会自动安装或重启宿主。
 

package/RELEASE-NOTES.md

@@ -1,17 +1,17 @@
-# v0.88.0 发布说明
+# v0.89.0 发布说明
 
-## 整体主审实验路径
+## 真正超限后，分组由子智能体并行处理
 
-新增插件配置 `executionStrategy:"whole-scope"`：完整文件按实际输入字节合批，批内一次整体主审，候选每最多50条集中独立复核；不额外执行逐文件风险规划、业务分组和旧专门综合。缺上下文仍可补读，不承诺总调用一次。默认仍为 `staged`。
+整体路径保持能装下就整体主审；只有完整输入超限形成多个组时，使用宿主真实spawn子智能体，`wholeScopeConcurrency` 默认2、可设1～4。每组一个独立Session和持续上下文，补读使用原会话，不把普通ctx.llm并发包装称为子智能体。全部主审收尾后仍集中独立复核；默认策略仍staged，整体路径需显式开启。
 
-`maxInputBytes` 是显式输入保护，默认98304字节、最多4194304字节，不是模型容量探测；同一配置绑定预览与执行。当前整体路径仅支持fresh单轮changes；多轮、旧任务恢复及project明确拒绝。超大完整文件blocked，多批跨边界未核查仍partial，不截断全文换取完成。身份、原文定位、归因、独立新回执及来源新鲜度保护不放宽；取消保留已验收批次，存储失败不吞。
+预览绑定并发数及执行方式，执行前重核宿主能力；缺失受限预设或结构化子会话能力明确拒绝，不隐藏回退。子会话只获得批准快照broker与结构化提交工具，不继承任意文件、shell、网络或递归委托能力。内部snapshot工具虽可能在父目录可见，但父会话及未绑定child在读取前拒绝。
 
-组主审补上仅同成员同来源侧唯一精确原文的坐标纠正，随后仍严格校验；不得模糊匹配或跨文件借用。新增注入活宿主registered tools的自动回归编排：每轮fresh preview、固定模型及范围、终态等待与分页保存，失败和partial留在分母；不直连provider、不自动读取私有工件。
+多个child共享唯一读取账本与同步模型生成尝试总账；每次实际逻辑LLM调用先校验身份、路由、工具集合与输入容量再扣账。这里统计模型生成尝试和逻辑LLM输入，不声称统计adapter内部HTTP重试或最终HTTP字节。宿主提示及历史开销可能使规划组在发送前受限，不截断完整文件掩盖。
 
-## 实测边界
+取消主动停止并等待子会话清理；检查点FIFO入队时冻结，存储错误中断并等待其他工作收尾，保留首个致命原因。统一报告按批准顺序汇总。多组跨边界未核查仍partial，不降低质量门槛。子会话由宿主按独立Session记录，可能含批准源码，不等同插件私有工件存储；不自动读这些会话作为审查证据。
 
-用户r7364归档实际为0.87.9：74条目中48完成、4失败、1阻断、21待审，综合3/33，156次模型调用，执行861.351秒。四项关键主审原文定位失败，且全局读取仍有余量；此前小样例不能代表该业务闭环。
+## 验证边界
 
-同修订新鲜快照完整新旧源码约1.96MB。静态规划在96KiB下17批且15完整文件超限；256KiB下13批、1MiB下3批、3MiB下1批，后三者均装入73个可审条目。这些只是输入规划，不是模型可接收能力、实际调用数或质量提升证明；新鲜快照不冒充归档原身份。
+使用实际安装宿主的Agent/Session/Inbox/Loop/LLM/原生执行器/预设/子智能体运行时，在独立离线Context中验证file与group结构化路径：两个真实child并行，每个同id两次模型生成，中间读取批准fixture后保留上下文；只暴露snapshot与structured_output，结构化终态完成后释放，未绑定父读取拒绝。工作目录get/set、snapshot和模型提供方使用离线fixture，没有真实提供方调用、没有修改运行宿主。此证据证明执行契约，不证明真实业务质量、r7364闭环或提速。
 
-本版通过离线合同测试及宿主工具兼容验收，尚无新策略真实模型同条件质量与耗时成绩，**不宣称r7364已解决或已提速**。按用户要求正式发布实验能力，默认不切换，不自动安装、改配置或重启运行宿主。配置见[使用说明](README.md)，正式发布门禁见[开发说明](DEVELOPMENT.md)。
+本版不自动安装、改配置或重启宿主。配置见[使用说明](README.md)，发布门禁见[开发说明](DEVELOPMENT.md)。

package/index.mjs

@@ -2,6 +2,9 @@ import { registerBackgroundReview } from './src/background-review.mjs';
 import { createReviewService } from './src/service.mjs';
 import { DEFAULT_PROJECT_CONCURRENCY } from './src/project-execution.mjs';
 import { reviewToolOutput } from './src/tool-view.mjs';
+import { createHostReviewChildren } from './src/host-review-children.mjs';
+import { attachReviewChildMiddleware } from './src/review-child-broker.mjs';
+import { registerSnapshotTool } from './src/review-child-plugin.mjs';
 
 export const name = 'dsh-code-review';
 export const inject = ['tools', 'llm'];
@@ -14,7 +17,11 @@ const EXECUTE_PARAMETERS = { type: 'object', additionalProperties: false, proper
 export function apply(ctx, config = {}) {
   // This entry runs only when the host invokes the registered tool.
   // Host tool policy owns permission; do not request a second approval here.
-  const service = createReviewService(ctx.llm, { executionStrategy: config.executionStrategy ?? 'staged', maxInputBytes: config.maxInputBytes ?? 96 * 1024, allowModelSending: true, nativeOutputTools: true, enableGroupPrimary: true, enableEvidenceContext: config.enableEvidenceContext ?? true, inlineInteractionRisks: config.inlineInteractionRisks ?? true, enableMigrationContracts: config.enableMigrationContracts ?? true, enableMigrationRegression: config.enableMigrationRegression ?? true, enableGroupInteractions: config.enableGroupInteractions ?? true, enableStageContinuation: config.enableStageContinuation ?? true, enableRiskPlanning: true, enableBusinessGrouping: true, enableAnchorCorrection: true, projectConcurrency: config.projectConcurrency ?? DEFAULT_PROJECT_CONCURRENCY, riskPlanningMode: config.riskPlanningMode ?? 'auto', readerBudgetPolicy: config.readerBudgetPolicy ?? 'scaled', optimizeReviewCalls: true, enablePrimarySeeds: true, focusPrimaryContext: config.focusPrimaryContext ?? true, enableSearchSeeds: config.enableSearchSeeds ?? true, changesConcurrency: config.changesConcurrency ?? 2, maxRetrievalRounds: config.maxRetrievalRounds ?? 3, authorize: async () => true });
+  const hostChildren = createHostReviewChildren(ctx);
+  registerSnapshotTool(ctx);
+  attachReviewChildMiddleware(ctx);
+  ctx.on('dispose', () => hostChildren.dispose());
+  const service = createReviewService(ctx.llm, { hostChildren, wholeScopeConcurrency: config.wholeScopeConcurrency ?? 2, executionStrategy: config.executionStrategy ?? 'staged', maxInputBytes: config.maxInputBytes ?? 96 * 1024, allowModelSending: true, nativeOutputTools: true, enableGroupPrimary: true, enableEvidenceContext: config.enableEvidenceContext ?? true, inlineInteractionRisks: config.inlineInteractionRisks ?? true, enableMigrationContracts: config.enableMigrationContracts ?? true, enableMigrationRegression: config.enableMigrationRegression ?? true, enableGroupInteractions: config.enableGroupInteractions ?? true, enableStageContinuation: config.enableStageContinuation ?? true, enableRiskPlanning: true, enableBusinessGrouping: true, enableAnchorCorrection: true, projectConcurrency: config.projectConcurrency ?? DEFAULT_PROJECT_CONCURRENCY, riskPlanningMode: config.riskPlanningMode ?? 'auto', readerBudgetPolicy: config.readerBudgetPolicy ?? 'scaled', optimizeReviewCalls: true, enablePrimarySeeds: true, focusPrimaryContext: config.focusPrimaryContext ?? true, enableSearchSeeds: config.enableSearchSeeds ?? true, changesConcurrency: config.changesConcurrency ?? 2, maxRetrievalRounds: config.maxRetrievalRounds ?? 3, authorize: async () => true });
   ctx.tools.register({
     name: 'code_review_preview', description: PREVIEW_DESCRIPTION, parameters: PREVIEW_PARAMETERS, output: reviewToolOutput,
     async execute(args, exec) { const preview = await service.preview(args, exec); return { json: JSON.stringify(preview), markdown: '' }; },

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@feng0531/dsh-code-review",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
   "main": "./index.mjs",
-  "exports": { ".": "./index.mjs", "./package.json": "./package.json", "./locale/*.json": "./locale/*.json" },
+  "exports": { ".": "./index.mjs", "./package.json": "./package.json", "./child": "./src/review-child-plugin.mjs", "./locale/*.json": "./locale/*.json" },
   "files": ["scripts/review-bench-adapter.mjs", "evaluation/REVIEWBENCH-LOCAL.md", "index.mjs", "cordis.patch.yml", "src/", "locale/", "README.md", "CHANGELOG.md", "RELEASE-NOTES.md", "DEVELOPMENT.md", "CORE-ALIGNMENT-TASKS.md", "CORE-SOURCE-INVENTORY.md", "SVN-SUPPORT-MATRIX.md", "SVN-RELEASE-EVIDENCE.md", "LICENSE", "LICENSES/"],
   "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
   "repository": { "type": "git", "url": "https://github.com/f-e-n-g-0531/dsh-code-review.git" },

package/src/child-output-schema.mjs

@@ -0,0 +1,22 @@
+// The host's structured_output accepts a documented finite JSON Schema subset.
+// Numeric/length bounds remain mandatory in the ordinary review validators.
+const annotations = new Set(['title', 'description', 'default']);
+const scalars = new Set(['type', 'enum', 'const', 'required', 'additionalProperties', ...annotations]);
+export function childOutputSchema(schema) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) throw new Error('Invalid child output schema');
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'properties') result.properties = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, childOutputSchema(child)]));
+    else if (key === 'items') result.items = childOutputSchema(value);
+    else if (key === 'oneOf') result.oneOf = value.map(childOutputSchema);
+    else if (scalars.has(key)) result[key] = structuredClone(value);
+    else if (!['minimum','maximum','minItems','maxItems','minLength','maxLength','pattern'].includes(key)) throw new Error('Unknown child schema constraint: ' + key);
+  }
+  if (!result.type && !result.oneOf) {
+    const values = result.enum ?? (Object.hasOwn(result, 'const') ? [result.const] : []);
+    const types = [...new Set(values.map(value => value === null ? 'null' : typeof value))];
+    if (types.length === 1 && ['string','number','boolean','null'].includes(types[0])) result.type = types[0];
+    else if (values.length) throw new Error('Ambiguous child enum type');
+  }
+  return result;
+}

package/src/host-review-children.mjs

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { modelResultTools } from './model-tools.mjs';
+import { childOutputSchema } from './child-output-schema.mjs';
+import { parseRetrievalResponse, executeRetrievalBatch } from './retrieval-protocol.mjs';
+import { registerReviewChild } from './review-child-broker.mjs';
+
+export const REVIEW_CHILD_PRESET = 'dsh-code-review-restricted';
+const failure = (code, message) => Object.assign(new Error(message), { code });
+// One managed spawn activation owns the entire primary loop, including snapshot tools.
+// No credentials or free-form filesystem tools are passed into that activation.
+export function createHostReviewChildren(ctx) {
+  let ready, unregisterPreset;
+  const service = () => ctx.get?.('subagents');
+  const presets = () => ctx.get?.('agentPresets');
+  function capability() {
+    const runtime = service(), provider = runtime?.getProvider?.('spawn');
+    return !!(provider?.capabilities?.outputSchema && provider.capabilities.agentPreset && provider.capabilities.agentOptions && runtime.resolveMaxDepth && presets()?.register && ctx.get?.('agents')?.get);
+  }
+  async function prepare() {
+    if (!capability()) throw failure('REVIEW_SUBAGENTS_UNAVAILABLE', 'Restricted host spawn subagents are unavailable; no hidden direct fallback');
+    ready ??= presets().register({ id: REVIEW_CHILD_PRESET, name: 'Read-only snapshot review', plugins: [
+      { name: '@deepseek-ai/dsh-tool-executor-native' },
+      { name: '@feng0531/dsh-code-review/child' },
+    ] }).then(dispose => { unregisterPreset = dispose; });
+    await ready;
+  }
+  return { capability, prepare,
+    async create({ parent, route, cwd, signal }) {
+      await prepare(); signal.throwIfAborted();
+      const runtime = service(), childId = randomUUID();
+      let handle, revoked, stop, started = false;
+      const child = { transport: 'host-subagent', childId,
+        async runPrimary({ request, scope, maxRounds, maxInputBytes, reserveModelCall, onRetrieved, onBudgetLimited, onTruncated, onProgress }) {
+          if (started) throw new Error('A review child cannot be reused for another primary');
+          started = true; let rounds = 0, modelCalls = 0, bindingFatal;
+          const abortBinding = error => { bindingFatal ??= error; handle?.dispose().catch(() => {}); };
+          const assertAgent = agent => {
+            if (!agent || agent.id !== childId || agent.session.header.parentSession !== (parent.session.header.id ?? parent.id) || agent.session.header.agentPreset !== REVIEW_CHILD_PRESET) throw failure('REVIEW_CHILD_IDENTITY', 'Review child ownership changed');
+          };
+          const binding = { parent, parentId: parent.session.header.id ?? parent.id, presetId: REVIEW_CHILD_PRESET, route, assertAgent, onFatal: abortBinding,
+            beforeModelCall(options) {
+              try {
+                signal.throwIfAborted();
+                if (bindingFatal) throw bindingFatal;
+                if (options.provider !== route.provider || options.model !== route.model || options.reasoningEffort !== route.reasoningEffort) throw failure('REVIEW_CHILD_ROUTE', 'Review child model route changed');
+                // This is the complete logical LLM envelope, not provider-specific HTTP bytes.
+                const bytes = Buffer.byteLength(JSON.stringify({ system: options.system, messages: options.messages, tools: options.tools }));
+                if (bytes > maxInputBytes) throw failure('WHOLE_SCOPE_INPUT_BUDGET', 'Child logical model input exceeds approved capacity');
+                if (modelCalls >= maxRounds + 2) throw failure('WHOLE_SCOPE_MODEL_CALL_LIMIT', 'Child primary loop call limit exceeded');
+                reserveModelCall(); modelCalls++;
+              } catch (error) { abortBinding(error); throw error; }
+            },
+            executeRequests(args, exec) {
+              assertAgent(exec.agent); signal.throwIfAborted();
+              if (bindingFatal) throw bindingFatal;
+              const requests = parseRetrievalResponse(args);
+              if (rounds >= maxRounds) {
+                const info = { code: 'RETRIEVAL_ROUND_BUDGET_EXCEEDED', reason: 'Child snapshot tool rounds exhausted' };
+                onBudgetLimited?.(info); throw failure(info.code, info.reason);
+              }
+              try {
+                scope.preflight(requests);
+                const results = scope.transaction(() => executeRetrievalBatch(args, scope, signal));
+                rounds++;
+                for (const { request: operation, result } of results) {
+                  if (result.truncated) onTruncated?.();
+                  onRetrieved?.([{ kind: operation.kind, snapshotId: result.snapshotId, stage: 'retrieved-locally', sourceId: result.sourceId, hash: result.hash, start: result.start, count: result.count, resultBytes: Buffer.byteLength(JSON.stringify(result)) }]);
+                }
+                return { snapshotId: JSON.parse(request.input).snapshotId, results, budget: scope.budget() };
+              } catch (error) {
+                if (['READER_CALL_BUDGET_EXCEEDED','READER_OUTPUT_BUDGET_EXCEEDED'].includes(error.code)) onBudgetLimited?.({code:error.code,reason:error.message});
+                throw error;
+              }
+            },
+          };
+          revoked = registerReviewChild(childId, binding);
+          const finalEnvelope = JSON.parse(request.input); finalEnvelope.retrievalFinalization = { reason: 'Use review_snapshot tool for supplemental reading; structured_output submits final reviews only' };
+          const schema = childOutputSchema(modelResultTools(JSON.stringify(finalEnvelope), request.instructions)[0].parameters);
+          stop = () => { handle?.dispose().catch(() => {}); }; signal.addEventListener('abort', stop, { once: true });
+          try {
+            handle = await runtime.startActivation({ provider: 'spawn', childId, label: 'Whole-scope review batch', request: {
+              parent, cwd, agentPreset: REVIEW_CHILD_PRESET, maxDepth: runtime.resolveMaxDepth(undefined),
+              agentOptions: { ...route, maxTokens: 4096 }, outputSchema: schema,
+              prompt: [{ type: 'text', text: request.instructions + '\nUse only review_snapshot for approved catalog sources. Preserve this child context for all supplemental reads. Return final reviews via structured_output, never requests.\n' + JSON.stringify({ ...JSON.parse(request.input), catalog: scope.catalog(), retrievalBudget: scope.budget() }) }],
+            }, signal, delivery: 'caller' });
+            if (signal.aborted || bindingFatal) await handle.dispose();
+            const result = await handle.result;
+            signal.throwIfAborted(); if (bindingFatal) throw bindingFatal;
+            if (result.stopReason !== 'completed' || !result.structured) throw failure('REVIEW_CHILD_INCOMPLETE', 'Host child did not commit a structured final result');
+            await onProgress?.({stage:'host-child-complete',childId,modelCalls});
+            return result.structured;
+          } catch (error) { throw bindingFatal ?? error; } finally { signal.removeEventListener('abort', stop); }
+        },
+        async dispose() { revoked?.(); if (handle) await handle.dispose(); },
+      };
+      return child;
+    },
+    async dispose() { if (ready) await ready; await unregisterPreset?.(); },
+  };
+}

package/src/review-child-broker.mjs

@@ -0,0 +1,65 @@
+// Process-local ownership broker. Fixtures exercise this contract, not host integration.
+const bindings = new Map();
+const revoked = new Set();
+const attachments = new WeakMap();
+const allowedTools = new Set(['review_snapshot', 'structured_output']);
+const failure = (message) => Object.assign(new Error(message), { code: 'REVIEW_CHILD_IDENTITY' });
+
+export function registerReviewChild(childId, binding) {
+  if (typeof childId !== 'string' || !childId || bindings.has(childId) || revoked.has(childId)) throw failure('Child id is invalid, already reserved, or revoked');
+  if (!binding || typeof binding.parentId !== 'string' || !binding.parentId || typeof binding.presetId !== 'string' || !binding.presetId || typeof binding.assertAgent !== 'function' || typeof binding.executeRequests !== 'function' || typeof binding.beforeModelCall !== 'function') throw failure('Incomplete restricted child binding');
+  const entry = { binding };
+  bindings.set(childId, entry);
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    bindings.delete(childId);
+    // Do not allow a late stream event to become an unrelated, unguarded call.
+    revoked.add(childId);
+  };
+}
+
+export function getReviewChildBinding(childId) {
+  if (revoked.has(childId)) throw failure('Review child binding was revoked');
+  return bindings.get(childId)?.binding;
+}
+export const getBinding = getReviewChildBinding;
+
+export function assertReviewChildAgent(childId, agent) {
+  const binding = getReviewChildBinding(childId);
+  const header = agent?.session?.header;
+  if (!binding || agent?.id !== childId || header?.id !== childId || header.parentSession !== binding.parentId || header.agentPreset !== binding.presetId) throw failure('Review child session, parent, or preset does not match its reservation');
+  binding.assertAgent(agent);
+  return binding;
+}
+
+export function executeReviewChildRequests(args, exec) {
+  const childId = exec?.agent?.id;
+  const binding = assertReviewChildAgent(childId, exec?.agent);
+  return binding.executeRequests(args, exec);
+}
+
+export function attachReviewChildMiddleware(ctx) {
+  if (attachments.has(ctx)) return attachments.get(ctx);
+  const dispose = ctx.on('llm/stream', function (options, next) {
+    const childId = options?.sessionId;
+    const binding = getReviewChildBinding(childId);
+    if (!binding) return next();
+    try {
+      const agent = ctx.get?.('agents')?.get?.(childId);
+      assertReviewChildAgent(childId, agent);
+      if (!Array.isArray(options.tools) || !options.tools.some(tool => tool?.name === 'structured_output') || options.tools.some(tool => !allowedTools.has(tool?.name)) || new Set(options.tools.map(tool => tool.name)).size !== options.tools.length) throw failure('Restricted child model tools changed');
+      // Reservation/route/budget guard executes synchronously, before next dispatch.
+      const result = binding.beforeModelCall(options);
+      if (result && typeof result.then === 'function') throw failure('Child model-call guard must be synchronous');
+    } catch (error) {
+      // Poison the owner's activation even when failure precedes its budget guard.
+      binding.onFatal?.(error);
+      throw error;
+    }
+    return next();
+  });
+  attachments.set(ctx, dispose);
+  return dispose;
+}

package/src/review-child-plugin.mjs

@@ -0,0 +1,32 @@
+import { assertReviewChildAgent, executeReviewChildRequests } from './review-child-broker.mjs';
+
+export const name = 'dsh-code-review-restricted-child';
+export const inject = ['tools'];
+
+export function registerSnapshotTool(ctx) {
+  // Presets are shared generations: never capture a particular child here.
+  // Restrict inherited tools before resolution; host-owned structured_output remains.
+  ctx.tools.register({
+    name: 'review_snapshot',
+    description: 'Internal tool for registered review children only; ordinary parent/other agents cannot call it. Read only the approved review snapshot using catalog retrieval requests. No filesystem, shell, network, or additional agents.',
+    parameters: { type: 'object', additionalProperties: false, properties: { requests: { type: 'array', items: { type: 'object' } } }, required: ['requests'] },
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { json: { type: 'string' } }, required: ['json'] },
+      render: (_args, value) => [{ type: 'text', text: value.json }],
+    },
+    async execute(args, exec) {
+      const result = await executeReviewChildRequests(args, exec);
+      // Recheck after asynchronous business logic: revoked work cannot leak a result.
+      assertReviewChildAgent(exec?.agent?.id, exec?.agent);
+      return { json: JSON.stringify(result) };
+    },
+  });
+}
+export function apply(ctx) {
+  ctx.tools.restrict({ allow: ['review_snapshot'] });
+  // Identity only: installation above must precede the host's tool assembly.
+  ctx.on('agent/pre-step', ({ agent }, next) => {
+    assertReviewChildAgent(agent?.id, agent);
+    return next();
+  });
+}

package/src/service.mjs

@@ -56,10 +56,11 @@ function buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcur
   return scopeNotice + (snapshot.history?.vcs==='svn'&&options.autoContext===true?'SVN历史autoContext为精确依赖定位读取固定版本父目录有界清单，包含同目录非匹配名字元数据；仅匹配捕获正文发送模型，不扫描全仓，不用工作树替代历史版本。':'') + (options.oldContextPaths !== undefined ? 'oldContextPaths仅为baseline旧侧正文，无目标侧替代；选中变更复用原old身份，旧侧不能证明新侧行为。' : '') + (snapshot.callerDiscovery ? 'callerScopePaths已授权预览读取限定目录内tracked候选正文，包括不匹配文件；非匹配正文不发送模型，匹配捕获上下文会发送。仅字面引用导航，不是函数调用或完整调用覆盖。' : '') + (enableRiskPlanning ? '执行按plan阈值决定风险假设规划，小变更可跳过独立规划但仍主审并复核；计划不是证据，所有阶段共享原预算。' : '') + `执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多${maxRetrievalRounds}轮检索；独立文件审查链最多${changesConcurrency}条并发，不设插件内部默认时间或总模型调用次数截止，遵循宿主/用户取消；输入字节和检索轮次保护仍保留；复核不能证明缺陷成立。plan.reviewRounds为独立审查工作量，非模型reasoning effort；后续轮不带首轮风险计划，所有轮共享原超时与预算。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先内部核对预览与当前人类授权。用户已明确要求审核且范围、模型和发送目的地一致时直接执行，不重复询问确认；只要求预览或明确要求等待确认时不得执行，超出授权或边界不明确时才询问。宿主权限和快照／身份校验仍须通过。`;
 }
 
-function createSessionReviewService(llm, { capture = captureSnapshot, executionStrategy = 'staged', maxInputBytes = 96 * 1024, now = Date.now, ttlMs = 300000, maxPreviews = 8, allowModelSending = false, enableRiskPlanning = false, skipSmallRiskPlans = true, reviewRounds = 1, enableBusinessGrouping = false, enableAnchorCorrection = false, changesConcurrency = 2, maxRetrievalRounds = 3, riskPlanningMode = 'separate', readerBudgetPolicy = 'fixed', optimizeReviewCalls = false, enablePrimarySeeds = false, focusPrimaryContext = false, enableSearchSeeds = false, nativeOutputTools = false, enableGroupPrimary = false, enableEvidenceContext = false, inlineInteractionRisks = false, enableMigrationContracts = false, enableMigrationRegression = false, enableGroupInteractions = false, enableStageContinuation = false, authorize = async () => false } = {}) {
+function createSessionReviewService(llm, { capture = captureSnapshot, hostChildren, wholeScopeConcurrency = 2, executionStrategy = 'staged', maxInputBytes = 96 * 1024, now = Date.now, ttlMs = 300000, maxPreviews = 8, allowModelSending = false, enableRiskPlanning = false, skipSmallRiskPlans = true, reviewRounds = 1, enableBusinessGrouping = false, enableAnchorCorrection = false, changesConcurrency = 2, maxRetrievalRounds = 3, riskPlanningMode = 'separate', readerBudgetPolicy = 'fixed', optimizeReviewCalls = false, enablePrimarySeeds = false, focusPrimaryContext = false, enableSearchSeeds = false, nativeOutputTools = false, enableGroupPrimary = false, enableEvidenceContext = false, inlineInteractionRisks = false, enableMigrationContracts = false, enableMigrationRegression = false, enableGroupInteractions = false, enableStageContinuation = false, authorize = async () => false } = {}) {
   for (const value of [ttlMs, maxPreviews]) if (!Number.isSafeInteger(value) || value < 1) throw new Error('Invalid preview limit');
   if (!Number.isSafeInteger(maxInputBytes) || maxInputBytes < 1 || maxInputBytes > 4 * 1024 * 1024) throw new Error('Invalid configured input capacity');
   if (!['staged', 'whole-scope'].includes(executionStrategy)) throw new Error('Invalid review execution strategy');
+  wholeScopeConcurrency = reviewConcurrency(wholeScopeConcurrency);
   changesConcurrency = reviewConcurrency(changesConcurrency);
   maxRetrievalRounds = reviewRetrievalRounds(maxRetrievalRounds);
   riskPlanningMode = validateRiskPlanningMode(riskPlanningMode);
@@ -67,7 +68,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, executionS
   for (const value of [optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation]) if (typeof value !== 'boolean') throw new Error('Invalid review optimization option');
   const lifetime = new AbortController();
   const bind = exec => ({ ...exec, signal: exec.signal ? AbortSignal.any([exec.signal, lifetime.signal]) : lifetime.signal });
-  const resumeOptions = (options, route, rounds) => ({ captureOptions: options, route, runtime: REVIEW_RUNTIME, instructionsHash: hash(REVIEW_INSTRUCTIONS), execution: { executionStrategy, maxInputBytes, rounds, enableRiskPlanning, skipSmallRiskPlans, enableBusinessGrouping, enableAnchorCorrection, changesConcurrency, maxRetrievalRounds, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation } });
+  const resumeOptions = (options, route, rounds) => ({ captureOptions: options, route, runtime: REVIEW_RUNTIME, instructionsHash: hash(REVIEW_INSTRUCTIONS), execution: { executionStrategy, maxInputBytes, wholeScopeConcurrency, rounds, enableRiskPlanning, skipSmallRiskPlans, enableBusinessGrouping, enableAnchorCorrection, changesConcurrency, maxRetrievalRounds, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation } });
   const previews = new Map();
   let busy = false;
   function prune() { for (const [id, p] of previews) if (p.expires <= now()) previews.delete(id); }
@@ -102,11 +103,13 @@ function createSessionReviewService(llm, { capture = captureSnapshot, executionS
         const resumeState = savedResume === undefined ? undefined : validateResumeState(savedResume, snapshot, resumeOptions(options, current.route, rounds));
         const readerBudget = reviewReaderBudget(snapshot, readerBudgetPolicy);
         const plan = buildCoveragePlan(snapshot, { executionStrategy, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, enableGroupPrimary, resumeState, focusPrimaryContext, riskPlanningMode, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:rounds, enableBusinessGrouping, instructions: REVIEW_INSTRUCTIONS, scope: configureWireBudget(createRetrievalScope(snapshot, { ...readerBudget, signal: exec.signal, ...(optimizeReviewCalls ? { reuseResults: true } : {}) }), { nativeOutputTools }), grouping: buildReviewGroups(snapshot.files, inferFileRelations(snapshot.files)), maxInputBytes, signal: exec.signal });
+        const useHostChildren = executionStrategy === 'whole-scope' && plan.primaryGroups.length > 1 && !!hostChildren;
+        if (useHostChildren) await hostChildren.prepare();
         prune();
         while (previews.size >= maxPreviews) previews.delete(previews.keys().next().value);
         const previewId = randomUUID();
         const expires = now() + ttlMs;
-        previews.set(previewId, { ...current, target, options, rounds, snapshotId: snapshot.id, resumeState, sourceJobId, expires });
+        previews.set(previewId, { ...current, target, options, rounds, snapshotId: snapshot.id, resumeState, sourceJobId, useHostChildren, expires });
         return {
   ...(options.businessRequirement !== undefined
     ? { businessRequirement: { text: options.businessRequirement, hash: hash(options.businessRequirement), bytes: Buffer.byteLength(options.businessRequirement) } }
@@ -118,7 +121,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, executionS
   plan,
   snapshotId: snapshot.id,
   privateArtifacts: { enabled: typeof exec.onModelArtifact === 'function', sourceBearing: true, maxArtifactBytes: 1048576, maxJobBytes: 8388608, maxArtifacts: 4096, notice: 'Background jobs retain bounded untrusted model output outside the reviewed workspace; omissions/truncation explicit. Never included in ordinary status or reused as evidence; explicit consent required to read.' },
-  execution: { executionStrategy, ...(executionStrategy === 'whole-scope' ? { resumeSupported: false, maxInputBytes } : {}), nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, fileConcurrency: changesConcurrency, maxRetrievalRounds, ...(optimizeReviewCalls ? { riskPlanningMode, readerBudget: { policy: readerBudgetPolicy, ...readerBudget }, missingContextSeeds: enablePrimarySeeds, focusPrimaryContext, searchContextSeeds: enableSearchSeeds } : {}) },
+  execution: { executionStrategy, ...(executionStrategy === 'whole-scope' ? { resumeSupported: false, maxInputBytes, batchExecution: useHostChildren ? 'host-subagents' : 'direct', batchConcurrency: useHostChildren ? Math.min(wholeScopeConcurrency, plan.primaryGroups.length) : 1 } : {}), nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, fileConcurrency: changesConcurrency, maxRetrievalRounds, ...(optimizeReviewCalls ? { riskPlanningMode, readerBudget: { policy: readerBudgetPolicy, ...readerBudget }, missingContextSeeds: enablePrimarySeeds, focusPrimaryContext, searchContextSeeds: enableSearchSeeds } : {}) },
   repositoryRoot: snapshot.root,
   vcs: snapshot.vcs,
   ...(snapshot.changeScope ? { changeScope: snapshot.changeScope } : options.changeScope !== undefined ? { changeScope: options.changeScope } : {}),
@@ -148,7 +151,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, executionS
   ...(snapshot.callerDiscovery ? { callerDiscovery: snapshot.callerDiscovery } : {}),
   ...(snapshot.autoContext ? { autoContext: snapshot.autoContext } : {}),
   rules: (snapshot.rules ?? []).map(({ path, hash }) => ({ path, hash })),
-  notice: executionStrategy === 'whole-scope' ? '整体优先主审：批准完整双侧按实际输入字节合批；不执行逐文件风险规划、业务分组或旧专门综合。候选集中独立复核；补读可增加调用，共享读取账本不重置。超大文件明确阻断，多批跨边界未核查保持部分完成；不承诺一次请求或审查通过。不支持旧阶段恢复或多轮。' : buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcurrency, maxRetrievalRounds) + (enableMigrationContracts ? ' 迁移契约仅由批准快照的明确旧/新入口与调用绑定产生，无法解析的语言结构保持未解决，不以相似名称推断迁移。' : '') + (enableMigrationRegression ? ' 显式跨文件旧新比较仅在host契约限定来源和本次独立回执齐备时成立，因果仍未证明。' : '') + (enableGroupInteractions ? ' 组主审可附带交互结果，只有当前代全组编辑实读且host校验通过时替代匹配专门阶段；缺失/非法回退，候选仍独立复核。' : '') + (enableStageContinuation ? ' 未完成阶段可在其他阶段释放额度后有限继续，不重置总账或原超时；已验收主审生成可精确续用，但复核重新读取、新回执，不继承旧证据。' : '') + (enableEvidenceContext ? ' 可将本次实际交付过的批准原行按相关性经当前阶段reader有限重新投递；缓存仍计交付字节，不继承历史读取覆盖或复核回执。' : '') + (inlineInteractionRisks ? ' 预算适配的精确跨文件单元可在交互主审同次返回风险假设，省去独立规划；缺失或无效风险不补发、不代表已完成风险核查。' : '') + (optimizeReviewCalls ? ` 完整正文或覆盖全部精确编辑的单批窗口可将风险问题合并入主审（非独立规划）；仅对批准上下文的确定坐标预取小片段，不代表完整核查。${focusPrimaryContext ? " 主审优先保留主文件全文，仅附带有关联的有界完整上下文；其余批准来源保留目录按需读，不表示不存在或已核查。" : ""}${enableSearchSeeds ? " 可将模型搜索命中的批准原行小片段与搜索结果同轮提供，每阶段最多2次额外读取，共用原预算；不猜测另侧坐标，不增加检索轮次。" : ""}共享检索上限按本次范围计算：${readerBudget.maxCalls}次唯一操作结果生成／${readerBudget.maxOutputBytes}交付字节，所有阶段共用、不逐文件重置；同快照相同请求可复用原始结果，每次交付仍计字节并重新签发复核回执；主审、综合及复核按权重预留最低额度，未用额度释放，额度不足仍如实标记未完成。` : ''),
+  notice: executionStrategy === 'whole-scope' ? '整体优先主审：批准完整双侧按实际输入字节合批；不执行逐文件风险规划、业务分组或旧专门综合。候选集中独立复核；补读可增加调用，共享读取账本不重置。超大文件明确阻断，多批跨边界未核查保持部分完成；不承诺一次请求或审查通过。不支持旧阶段恢复或多轮。' + (useHostChildren ? ` 超限多组使用真实spawn子智能体，最多${wholeScopeConcurrency}组并行，每组保留独立持续上下文，仅批准快照读取工具；逐模型生成尝试共用总账，逻辑LLM输入预算不代表最终HTTP字节。` : '') : buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcurrency, maxRetrievalRounds) + (enableMigrationContracts ? ' 迁移契约仅由批准快照的明确旧/新入口与调用绑定产生，无法解析的语言结构保持未解决，不以相似名称推断迁移。' : '') + (enableMigrationRegression ? ' 显式跨文件旧新比较仅在host契约限定来源和本次独立回执齐备时成立，因果仍未证明。' : '') + (enableGroupInteractions ? ' 组主审可附带交互结果，只有当前代全组编辑实读且host校验通过时替代匹配专门阶段；缺失/非法回退，候选仍独立复核。' : '') + (enableStageContinuation ? ' 未完成阶段可在其他阶段释放额度后有限继续，不重置总账或原超时；已验收主审生成可精确续用，但复核重新读取、新回执，不继承旧证据。' : '') + (enableEvidenceContext ? ' 可将本次实际交付过的批准原行按相关性经当前阶段reader有限重新投递；缓存仍计交付字节，不继承历史读取覆盖或复核回执。' : '') + (inlineInteractionRisks ? ' 预算适配的精确跨文件单元可在交互主审同次返回风险假设，省去独立规划；缺失或无效风险不补发、不代表已完成风险核查。' : '') + (optimizeReviewCalls ? ` 完整正文或覆盖全部精确编辑的单批窗口可将风险问题合并入主审（非独立规划）；仅对批准上下文的确定坐标预取小片段，不代表完整核查。${focusPrimaryContext ? " 主审优先保留主文件全文，仅附带有关联的有界完整上下文；其余批准来源保留目录按需读，不表示不存在或已核查。" : ""}${enableSearchSeeds ? " 可将模型搜索命中的批准原行小片段与搜索结果同轮提供，每阶段最多2次额外读取，共用原预算；不猜测另侧坐标，不增加检索轮次。" : ""}共享检索上限按本次范围计算：${readerBudget.maxCalls}次唯一操作结果生成／${readerBudget.maxOutputBytes}交付字节，所有阶段共用、不逐文件重置；同快照相同请求可复用原始结果，每次交付仍计字节并重新签发复核回执；主审、综合及复核按权重预留最低额度，未用额度释放，额度不足仍如实标记未完成。` : ''),
 };
       } finally { busy = false; }
     },
@@ -170,13 +173,14 @@ function createSessionReviewService(llm, { capture = captureSnapshot, executionS
         const snapshot = await capture(target, { ...preview.options, signal: exec.signal });
         exec.signal?.throwIfAborted();
         if (snapshot.id !== preview.snapshotId || owner(exec).cwd !== current.cwd) throw new Error('Files changed since preview; preview again');
+        if (preview.useHostChildren && !hostChildren?.capability()) throw new Error('Approved child execution capability changed; preview again');
         const resumeIdentity = resumeOptions(preview.options, preview.route, preview.rounds);
         const resumeState = preview.resumeState ? validateResumeState(preview.resumeState, snapshot, resumeIdentity) : undefined;
         if (await authorize({ snapshot, route: preview.route, exec }) !== true) throw new Error('Model sending approval denied or unavailable');
         exec.signal?.throwIfAborted();
         if (owner(exec).cwd !== current.cwd || JSON.stringify(owner(exec).route) !== JSON.stringify(preview.route)) throw new Error('Agent changed during approval');
         await exec.reviewCheckpoint?.({stage:'approved-manifest',snapshotId:snapshot.id,files:snapshot.files.map(f=>({fileId:f.id,path:f.path,status:f.eligibility==='reviewable'?'pending':f.eligibility}))});
-        const report = await reviewSnapshot(snapshot, createDshModel(llm, preview.route,{correctJson:true,useNativeTools:nativeOutputTools}), { executionStrategy, maxInputBytes, signal: exec.signal, enableRetrieval: true, enableGrouping: true, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, nativeOutputTools, enableVerification: true, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:preview.rounds, enableBusinessGrouping, enableAnchorCorrection,changesConcurrency,maxRetrievalRounds,correctProtocol:true, onProgress:exec.reviewCheckpoint, resumeState, onModelArtifact: exec.onModelArtifact, onResumeCheckpoint: exec.reviewResumeCheckpoint ? async checkpoint => { await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, checkpoint)); } : undefined });
+        const report = await reviewSnapshot(snapshot, createDshModel(llm, preview.route,{correctJson:true,useNativeTools:nativeOutputTools}), { executionStrategy, maxInputBytes, wholeScopeConcurrency, childExecution: preview.useHostChildren ? 'host-subagents' : undefined, createBatchModel: preview.useHostChildren ? args => hostChildren.create({ ...args, parent: exec.agent, route: preview.route, cwd: target }) : undefined, signal: exec.signal, enableRetrieval: true, enableGrouping: true, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, nativeOutputTools, enableVerification: true, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:preview.rounds, enableBusinessGrouping, enableAnchorCorrection,changesConcurrency,maxRetrievalRounds,correctProtocol:true, onProgress:exec.reviewCheckpoint, resumeState, onModelArtifact: exec.onModelArtifact, onResumeCheckpoint: exec.reviewResumeCheckpoint ? async checkpoint => { await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, checkpoint)); } : undefined });
         report.model = preview.route;
         if (exec.reviewResumeCheckpoint) await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, report));
         // reviewSnapshot preserves cancelled coverage; do not replace it with a freshness error.

package/src/whole-scope-review.mjs

@@ -1,4 +1,6 @@
 import { REVIEW_INSTRUCTIONS } from './prompts.mjs';
+import { runWholeScopeWorkers, createCheckpointQueue } from './whole-scope-workers.mjs';
+import { changesConcurrency } from './review-execution-policy.mjs';
 import { createReviewReader } from './review.mjs';
 import { prepareWholeScope } from './whole-scope-plan.mjs';
 import { retrievalLoop } from './retrieval-loop.mjs';
@@ -21,6 +23,8 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0) throw new Error('Invalid whole-scope timeout');
   if (options.enableAnchorCorrection !== undefined && typeof options.enableAnchorCorrection !== 'boolean') throw new Error('Invalid anchor correction option');
   const maxRounds = retrievalRounds(options.maxRetrievalRounds);
+  const concurrency = changesConcurrency(options.wholeScopeConcurrency ?? 2);
+  if (options.createBatchModel !== undefined && typeof options.createBatchModel !== 'function') throw new Error('Invalid child agent factory');
   const input = structuredClone(snapshot);
   if (!input || !['git', 'svn'].includes(input.vcs) || !Array.isArray(input.files) || input.files.length > 200 || input.projectScope || input.files.some(file => file.reviewMode === 'project')) throw new Error('Whole-scope review requires a changes snapshot');
   const identities = new Set(), paths = new Set();
@@ -41,21 +45,23 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
     interactions: [], rules: (input.rules ?? []).map(({ path, hash }) => ({ path, hash })),
   };
   const stateById = new Map();
-  let reader, checkpointFailed = false;
-  const checkpoint = async () => {
-    if (!options.onResumeCheckpoint) return;
-    try { await options.onResumeCheckpoint(structuredClone(report)); } catch (error) { checkpointFailed = true; throw error; }
+  let reader, checkpointFailed = false, fatalError;
+  const checkpoints = createCheckpointQueue(options.onResumeCheckpoint, error => { checkpointFailed = true; fatalError ??= error; controller.abort(error); });
+  const reportOrder = new Map(input.files.map((file, index) => [file.id, index]));
+  const checkpoint = () => {
+    report.findings.sort((a, b) => reportOrder.get(a.fileId) - reportOrder.get(b.fileId));
+    return checkpoints.enqueue(report);
   };
   const gate = () => {
     signal.throwIfAborted();
     if (report.modelCalls >= maxCalls) throw failure('WHOLE_SCOPE_MODEL_CALL_LIMIT', 'Model call budget exceeded');
     if (options.remainingCalls?.() <= 0) throw failure('PROJECT_MODEL_CALL_LIMIT', 'Shared project model call limit exceeded');
   };
-  const trackedModel = async request => {
+  const trackModel = delegate => async request => {
     gate();
     if (!modelWireBudget(request, maxInputBytes).fits) throw failure('WHOLE_SCOPE_INPUT_BUDGET', 'Actual model wire input budget exceeded');
     report.modelCalls++;
-    const result = await model({ ...request, maxInputBytes,
+    const result = await delegate({ ...request, maxInputBytes,
       onModelArtifact: options.onModelArtifact ? async artifact => {
         try {
           const reference = await options.onModelArtifact({ ...artifact, snapshotId: input.id, phase: request.reviewPhase });
@@ -83,6 +89,7 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
     signal.throwIfAborted();
     return result;
   };
+  const trackedModel = trackModel(model);
   const requestFor = batch => ({ input: batch.payload, instructions: batch.instructions, signal,
     reviewPhase: 'group-primary', nativeOutputTools: options.nativeOutputTools === true,
     onProtocolEvent: options.onProtocolEvent });
@@ -112,12 +119,27 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
     if (plan.batches.length > 1) report.limitations.push({ text: '整体范围按字节分为多个批次；跨 batch 边界关系未核查，不声明整体范围完整覆盖。' });
     report.scopeNotices = [{ text: '整体主审结合当前 batch 完整文件；批准关联源须按需检索，不声明专门 interaction 阶段或全部上下文覆盖。' }];
     const generatedBatches = [];
-    for (const batch of plan.batches) {
-      const stage = { id: batch.id, fileIds: [...batch.fileIds], status: 'pending' };
-      report.orchestration.batches.push(stage);
+    const parallelChildren = plan.batches.length > 1 && typeof options.createBatchModel === 'function';
+    report.orchestration.batchExecution = parallelChildren ? (options.childExecution ?? 'child-factory') : 'direct';
+    report.orchestration.batchConcurrency = parallelChildren ? Math.min(concurrency, plan.batches.length) : 1;
+    const accepted = new Array(plan.batches.length);
+    report.orchestration.batches = plan.batches.map(batch => ({ id: batch.id, fileIds: [...batch.fileIds], status: 'pending' }));
+    const runBatch = async (batch, index) => {
+      const stage = report.orchestration.batches[index];
+      let child;
       try {
         gate();
-        const response = await retrievalLoop(trackedModel, requestFor(batch), reader, loopOptions(stage));
+        if (parallelChildren) {
+          child = await options.createBatchModel({ batchId: batch.id, fileIds: [...batch.fileIds], signal });
+          if (!child || (typeof child.invoke !== 'function' && typeof child.runPrimary !== 'function') || typeof child.dispose !== 'function') throw new Error('Invalid host child model');
+          signal.throwIfAborted();
+        }
+        const batchModel = child ? trackModel(request => child.invoke(request)) : trackedModel;
+        const response = child?.runPrimary ? await child.runPrimary({ request: requestFor(batch), scope: reader, maxRounds, maxInputBytes,
+          reserveModelCall: () => { gate(); report.modelCalls++; },
+          onRetrieved: loopOptions(stage).onRetrieved, onBudgetLimited: loopOptions(stage).onBudgetLimited, onTruncated: loopOptions(stage).onTruncated,
+          onProgress: options.onProgress }) : await retrievalLoop(batchModel, requestFor(batch), reader, loopOptions(stage));
+        if (child?.transport === 'host-subagent') { stage.childId = child.childId; stage.execution = 'host-subagent'; }
         const members = validateGroupPrimary(response, batch, input, options.validateFindingResponse, reader.catalog(), { enableAnchorCorrection: options.enableAnchorCorrection === true, signal });
         signal.throwIfAborted();
         // Validate the entire member set before publishing any member result.
@@ -130,18 +152,23 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
           report.limitations.push(...generated.limitations.map(text => ({ fileId: id, text })));
         }
         stage.status = stage.retrievalLimited ? 'pending' : 'completed';
-        generatedBatches.push(batch);
+        accepted[index] = batch;
         await checkpoint();
       } catch (error) {
         signal.throwIfAborted();
-        if (checkpointFailed || error.code === 'MODEL_ARTIFACT_FAILED') throw error;
+        if (checkpointFailed || error.code === 'MODEL_ARTIFACT_FAILED') { fatalError ??= error; controller.abort(error); throw error; }
         stage.status = isBudget(error) ? 'pending' : 'failed';
         stage.failureCode = error.code ?? 'WHOLE_SCOPE_PRIMARY_FAILED'; stage.reason = error.message;
         for (const id of batch.fileIds) Object.assign(stateById.get(id), { status: stage.status, primaryStatus: stage.status, failureCode: stage.failureCode, reason: error.message });
         report.limitations.push({ text: '整体主审未完成：' + error.message });
-        if (isBudget(error)) break;
+      } finally {
+        if (child) { try { await child.dispose(); } catch (error) { fatalError ??= error; controller.abort(error); throw error; } }
       }
-    }
+    };
+    await runWholeScopeWorkers(plan.batches, runBatch, { concurrency: report.orchestration.batchConcurrency, signal, onFatal: error => { if (!signal.aborted) { fatalError ??= error; controller.abort(error); } } });
+    generatedBatches.push(...accepted.filter(Boolean));
+    const order = new Map(input.files.map((file, index) => [file.id, index]));
+    report.findings.sort((a, b) => order.get(a.fileId) - order.get(b.fileId));
     // One global verification queue, not a per-file chain. Receipt ownership and
     // primary-file regression checks remain entirely in verificationLoop.
     for (const finding of report.findings) finding.verification = { status: 'pending', causality: 'unverified' };
@@ -181,9 +208,12 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
     await options.onProgress?.({ stage: 'batch-complete', snapshotId: input.id, files: report.files, findings: report.findings, limitations: report.limitations });
     return report;
   } catch (error) {
+    if (fatalError) throw fatalError;
     if (!signal.aborted || checkpointFailed || error.code === 'MODEL_ARTIFACT_FAILED') throw error;
     if (!report.files.length) report.files = input.files.map(file => ({ fileId: file.id, path: file.path, status: file.eligibility === 'reviewable' ? 'cancelled' : file.eligibility }));
     for (const state of report.files) if (state.status === 'pending') state.status = 'cancelled';
+    const cancelledOrder = new Map(input.files.map((file, index) => [file.id, index]));
+    report.findings.sort((a, b) => cancelledOrder.get(a.fileId) - cancelledOrder.get(b.fileId));
     for (const finding of report.findings) if (finding.verification?.status !== 'completed') finding.verification = { status: 'incomplete', causality: 'unverified' };
     report.status = 'cancelled';
     report.limitations.push({ text: '整体审查已取消或超时；已验收成果保留，其他范围未完成。' });
@@ -193,6 +223,6 @@ export async function reviewWholeScope(snapshot, model, options = {}) {
     await checkpoint();
     return report;
   } finally {
-    clearTimeout(timer);
+    try { await checkpoints.drain(); } catch (error) { throw fatalError ?? error; } finally { clearTimeout(timer); }
   }
 }

package/src/whole-scope-workers.mjs

@@ -0,0 +1,88 @@
+/** Run a bounded set of workers, always joining admitted work before rejecting.
+ * Cancellation rejects with signal.reason after the join; a worker failure takes
+ * precedence, including when onFatal synchronously aborts the outer controller.
+ */
+export async function runWholeScopeWorkers(items, run, { concurrency = 2, signal, onFatal } = {}) {
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) {
+    throw new RangeError('concurrency must be an integer from 1 to 4');
+  }
+  const results = new Array(items.length);
+  let next = 0, failed = false, failure;
+  async function worker() {
+    while (!failed && !signal?.aborted && next < items.length) {
+      const index = next++;
+      try {
+        results[index] = await run(items[index], index);
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          failure = error;
+          // Invoke before yielding so outer abort reaches other active work.
+          // A throwing notification cannot replace the original worker failure.
+          onFatal?.(error);
+        }
+      }
+    }
+  }
+  await Promise.allSettled(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+  if (failed) throw failure;
+  if (signal?.aborted) throw signal.reason;
+  return results;
+}
+
+/** Serialize immutable checkpoint values. The first failure is permanent.
+ * Internal rejection handlers prevent fire-and-forget enqueue calls from causing
+ * unhandled rejections; callers still receive the original rejecting promise.
+ */
+export function createCheckpointQueue(save, onFatal) {
+  let tail = Promise.resolve(), failed = false, failure;
+  function rejectFirst(error) {
+    if (!failed) {
+      failed = true;
+      failure = error;
+      onFatal?.(error);
+    }
+    throw failure;
+  }
+  function observe(promise) {
+    // Normalize notification exceptions back to the first persistence failure.
+    tail = promise.catch(error => {
+      if (failed) throw failure;
+      return rejectFirst(error);
+    });
+    tail.catch(() => {});
+    return tail;
+  }
+  return {
+    enqueue(value) {
+      if (save == null) return Promise.resolve();
+      if (failed) return observe(Promise.reject(failure));
+      let checkpoint;
+      try {
+        checkpoint = structuredClone(value);
+      } catch (error) {
+        // Retain FIFO even if cloning an enqueued value fails.
+        return observe(tail.then(() => rejectFirst(error)));
+      }
+      return observe(tail.then(async () => {
+        if (failed) throw failure;
+        try {
+          await save(checkpoint);
+        } catch (error) {
+          return rejectFirst(error);
+        }
+      }));
+    },
+    async drain() {
+      // Also join values enqueued while a save is in progress.
+      for (;;) {
+        const pending = tail;
+        await pending.catch(() => {});
+        if (pending === tail) {
+          if (failed) throw failure;
+          return;
+        }
+      }
+    },
+  };
+}