dsh-subagent-profile 0.3.1 → 0.3.3

package/lib/core/dispatch-tool.mjs

@@ -2,100 +2,41 @@
 // 结果 schema 一致性锁与 syncTool 注册/注销逻辑，从 index.mjs 逐字拆出。
 // 仅引用 lib + shims；无 @deepseek-ai 依赖（shims 是唯一入口）。
 //
-// Injection: every apply-closure / ctx dependency is an explicit parameter —
-//   register    ctx.tools.register (the tool is registered/unregistered by
-//               syncTool, so the settings switch can remove it at runtime),
-//   store       the profile store (resolveProfile for the base profile,
-//               getAllowFailOpen for the cost guard),
-//   getEnabled  reads the apply-closure `enabled` flag (continuable fail-loud
-//               gate + syncTool registration condition),
-//   getService  request-time service getter (ctx.get('toolResultPruner') /
-//               ctx.get('jobs') are read per call, never at apply time),
-//   logger      ctx.logger (decision-level dispatch log + continuable warns),
-//   subagents   ctx.subagents (start / startContinuable drive the child).
-// The factory returns { syncTool, dispose }: syncTool is handed to the HTTP
-// routes (/set-enabled), dispose runs on plugin teardown.
+// 注入：所有 apply 闭包 / ctx 依赖都是显式参数——
+//   register    ctx.tools.register（工具由 syncTool 注册/注销，设置开关可运行时移除），
+//   store       profile store（resolveProfile 取基方案、getAllowFailOpen 供 cost guard），
+//   getEnabled  读取 apply 闭包 `enabled` 标志（continuable fail-loud 门 +
+//               syncTool 注册条件），
+//   getService  请求时服务 getter（ctx.get('toolResultPruner') / ctx.get('jobs')
+//               按次读取，绝不在 apply 时读），
+//   logger      ctx.logger（决策级派发日志 + continuable 告警），
+//   subagents   ctx.subagents（start / startContinuable 驱动子 Agent），
+//   guard       dispatch guard（execute 入口 acquire / 结算 release+记账 /
+//               syncTool 禁用时 cancelAll+reset）。
+// 工厂返回 { syncTool, dispose }：syncTool 交给 HTTP 路由（/set-enabled），
+// dispose 在插件卸载时运行。
 //
-// execute 按预检段 + 前台/后台/continuable 三分支拆为模块级私有函数；
-// parameters 声明为纯数据，驻留模块级常量（与数据表同性质，不受函数行门约束）；
-// output 结果 schema 已拆至 lib/core/dispatch-schema.mjs（守文件行门）——
-// 工厂保持装配态；除各任务明示的新增行为外，执行路径零漂移。
+// execute 按预检段 + 三分支拆为模块级私有函数；parameters / output schema 拆至
+// dispatch-schema.mjs，预检闸应用拆至 dispatch-gates.mjs（守文件行门），零漂移。
 
 import { defineTool } from './shims.mjs';
-import { computeContinuableAllow, textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency } from './pure.mjs';
+import { textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency, trustLabel, trustAudit, dispatchLabel, tierSortKey } from './pure.mjs';
 import { resolveWhitelist } from './whitelist.mjs';
-import { assertCostGuard } from './cost-guard.mjs';
-import { settleStart } from './delegation.mjs';
-import { DISPATCH_OUTPUT_SCHEMA } from './dispatch-schema.mjs';
+import { recordEscapeAllow } from './escape.mjs';
+import { settleStart, collectChildUsage, collectChildCalls } from './delegation.mjs';
+import { DISPATCH_OUTPUT_SCHEMA, DISPATCH_PARAMETERS, DISPATCH_RENDER } from './dispatch-schema.mjs';
+import { createDecisionTrace, finalizeTrace, assertTraceSize, parentContextOf, requestedOf, effectiveMeta, recordApprovalGate, recordFailure, profileSnapshotOf } from './decision-trace.mjs';
+import { applyWhitelistGate, applyCostGuardGate, applyIntersectionGate, assertContinuableEnabled, readParentToolNames, applyBudgetGate } from './dispatch-gates.mjs';
+import { trackForegroundInflight, trackBackgroundInflight, trackContinuableInflight } from './dispatch-guard.mjs';
+import { finishForegroundLedger, finishBackgroundLedger, finishContinuableLedger } from './evolution-ledger.mjs';
 
-// --- 工具声明纯数据（从工厂提到模块级；defineTool 只读不改）----------------------
-
-const DISPATCH_PARAMETERS = {
-  profile: { type: 'string', description: 'Optional profile id from the profile registry (built-ins: swap-standard, researcher, plus any you define in the settings page); omit to inherit the parent preset and tools as-is.' },
-  preset: { type: 'string', description: 'Explicit target preset override; must be a system-trust preset of this runtime.' },
-  model: { type: 'string', description: 'Explicit model override for the child.' },
-  provider: { type: 'string', description: 'Explicit provider override for the child.' },
-  reasoningEffort: { type: 'string', description: 'Explicit reasoning-effort override injected into every child request.' },
-  tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）：cheap 省 token、balanced 均衡、premium 高成本。覆盖 profile 的 tokenTier；缺省 balanced。' },
-  persona: { type: 'string', description: 'Persona text shadowing the child deployment:persona section.' },
-  toolFilter: {
-    type: 'object',
-    // DSL 对象参数默认拒绝未知键，toolFilter 必须闭合其 schema，
-    // 否则 defineTool 在 apply 时 throw、插件加载失败。
-    additionalProperties: false,
-    description: 'Extra tool whitelist intersection for the child (intersected with the parent tool set).',
-    properties: {
-      allow: { type: 'array', items: { type: 'string' }, description: 'When present, only these tool names are kept.' },
-      deny: { type: 'array', items: { type: 'string' }, description: 'These tool names are always removed.' }
-    }
-  },
-  maxTokens: { type: 'number', description: 'Explicit max-tokens budget for the child.' },
-  maxDepth: { type: 'number', description: 'Absolute delegation-depth cap for this child.' },
-  run_in_background: { type: 'boolean', description: '异步 one-shot：走 jobs.start 包 start()，返回 jobId；仍单轮即弃，非 continuable' },
-  continuable: { type: 'boolean', description: 'Start a durable continuable subagent instead of a one-shot: returns a subagentId immediately and keeps the child conversation available for later turns via the send_message tool. Defaults to false.' },
-  // 信封模式 = opt-in（仅「中段即交付物」的任务用）：true 时把信封骨架追加进
-  // 子 persona（systemPrompt 影子段，模型可见），子 Agent 按结构化信封汇报；
-  // 默认 false 走结果剪枝回收。
-  envelope: { type: 'boolean', description: 'true 时子 Agent 按结构化信封汇报（简短结论 + 结构分项 + 关键发现落点），适合中段即交付物的长任务；默认 false 走剪枝回收' },
-  prompt: { type: 'string', required: true, description: 'The complete, self-contained task for the child (it does not see this conversation).' }
-};
-
-// 信封骨架：envelope:true 时追加进子 persona 的结构化汇报契约。三分支共享此
-// 常量；骨架只进 persona（systemPrompt 影子段、模型可见），不进 descriptor
-// （model-hidden、仅 session 记录），故 execute 在三分支创建子 Agent 前统一
-// 追加到 merged.persona。
+// 信封骨架：envelope:true 时追加进子 persona 的结构化汇报契约（三分支共享）；骨架
+// 只进 persona（systemPrompt 影子段、模型可见），不进 descriptor（model-hidden，仅 session 记录）。
 const ENVELOPE_SKELETON = '完成前按以下骨架输出：## 结论（1-2 句）\n## 结构分项（逐项）\n## 关键发现落点（文件路径/数据位置）';
 
-// continuable 丢弃 preset 换用与 reasoningEffort —— 渲染行把 `ignored`
-// 列表回显出来（`reasoningEffort=<值>(ignored)`，再加 ignored 项明细），让模型
-// 「看见」被丢弃项；background/foreground 无忽略项时该后缀为空。
-const DISPATCH_RENDER = (_args, value) => {
-  const ignored = value.ignored !== undefined && value.ignored.length > 0
-    ? `(ignored: ${value.ignored.join(', ')})`
-    : '';
-  const tier = typeof value.tokenTier === 'string' && value.tokenTier !== ''
-    ? ` · tokenTier=${value.tokenTier}`
-    : '';
-  const tokens = typeof value.childTotalTokens === 'number'
-    ? ` · childTotalTokens=${value.childTotalTokens}`
-    : '';
-  const elapsed = typeof value.elapsedMs === 'number'
-    ? ` · elapsedMs=${value.elapsedMs}`
-    : '';
-  const stopReason = typeof value.stopReason === 'string' && value.stopReason !== ''
-    ? ` · stopReason=${value.stopReason}`
-    : '';
-  const text = value.kind === 'background'
-    ? `[dispatch] background job ${value.jobId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}`
-    : value.kind === 'continuable'
-      ? `[dispatch] started subagent ${value.subagentId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}`
-      : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}${tier}${tokens}${elapsed}${stopReason}\n\n${value.output}`;
-  return [{ type: 'text', text }];
-};
-
 // --- execute 预检段（从 execute 拆出；行为逐字不变）-----------------------------
 
-// Resolve the base profile (side channel), then overlay explicit args.
+// 解析基方案（旁路），再叠加显式参数。
 function mergeProfileArgs(args, store) {
   const base = args.profile !== undefined ? store.resolveProfile(args.profile) : {};
   const merged = { ...base };
@@ -105,21 +46,7 @@ function mergeProfileArgs(args, store) {
   return merged;
 }
 
-// Pre-check: explicit concrete preset must be in the runtime-derived whitelist;
-// a preset equal to the parent's composed preset is rewritten to
-// 'inherit' (no swap).
-async function assertPresetWhitelist(parent, merged) {
-  if (typeof merged.preset !== 'string' || merged.preset === 'inherit') return;
-  const whitelist = new Set(await resolveWhitelist(parent.ctx.get('agentPresets')));
-  if (!whitelist.has(merged.preset)) {
-    throw new Error(`dispatch: preset "${merged.preset}" is not in the target-preset whitelist`);
-  }
-  const parentPresets = parent.ctx.get('agentPresets');
-  const parentComposed = parentPresets !== undefined ? parentPresets.composedPreset(parent.ctx) : undefined;
-  if (merged.preset === parentComposed) merged.preset = 'inherit';
-}
-
-// Effective delegation values for observability.
+// 生效的委派值（供可观测元数据）。
 function buildMeta(args, merged, parent) {
   return {
     profile: args.profile ?? '(inline)',
@@ -131,10 +58,10 @@ function buildMeta(args, merged, parent) {
   };
 }
 
-// Assemble the foreground/background request (continuable builds its own below).
+// 组装前台/后台请求（continuable 在下方自建）。
 function buildRequest(args, merged, parent, signal) {
   return {
-    label: String(args.prompt ?? '').slice(0, 60),
+    label: dispatchLabel(args, merged),
     prompt: [{ type: 'text', text: args.prompt }],
     parent,
     signal,
@@ -145,8 +72,7 @@ function buildRequest(args, merged, parent, signal) {
   };
 }
 
-// Decision-level log: resolved effective delegation inputs, after the cost
-// guard and after request assembly, before dispatch.
+// 决策级日志：经 cost guard 与请求组装之后、派发之前的生效委派输入。
 function logDispatchDecision(logger, args, merged, parent) {
   logger.info('[dsh-subagent-profile] dispatch:', JSON.stringify({
     profile: args.profile ?? '(inline)',
@@ -168,10 +94,9 @@ function logDispatchDecision(logger, args, merged, parent) {
 // 假设：continuable 继承父预设（preset swap 被忽略）⇒ 子工具集 ≈ 父工具集；
 // 失效条件：任何导致子工具集与父工具集不一致的宿主行为变化，父集都可能含
 // 子集上不存在之工具 → tools.restrict 抛「未知工具」→ 本缓解自动降级为
-// fail-loud（保守安全）。
-function buildContinuableRequest(args, merged, parent) {
-  const parentNames = new Set(parent.ctx.tools.schemas(parent).map((schema) => schema.name));
-  const effectiveAllow = computeContinuableAllow(parentNames, merged.toolFilter);
+// fail-loud（保守安全）。effectiveAllow 由调用方（runDispatch 交集闸处）算好
+// 传入——同一结果同时用于 request 组装与决策轨迹记录，不重复计算。
+function buildContinuableRequest(args, merged, parent, effectiveAllow) {
   const hasAgentOptions = merged.provider !== undefined || merged.model !== undefined || merged.maxTokens !== undefined;
   return {
     prompt: [{ type: 'text', text: args.prompt }],
@@ -189,15 +114,12 @@ function buildContinuableRequest(args, merged, parent) {
   };
 }
 
-// Continuable (durable) path — startContinuable publishes a persistent child
-// and returns its durable id; the official send_message tool drives later
-// turns. Treated first so a caller asking for both background and continuable
-// gets the continuable child.
-async function runContinuable(args, merged, meta, parent, exec, deps) {
-  // provider `start` 的 !enabled 检查只拦
-  // `start`，不拦 `startContinuable` —— 这里显式补上。当前 syncTool 会在
-  // 禁用时注销 dispatch 工具（间接门），此处是防御性兜底：禁用后
-  // dispatch(continuable:true) 必须 fail-loud，不得静默派生子树。
+// Continuable（持久）路径：startContinuable 发布持久子会话并返回其持久 id，
+// 后续轮次由官方 send_message 工具驱动。优先处理——同时要 background 与
+// continuable 的调用方得到 continuable 子会话。
+async function runContinuable(args, merged, meta, parent, exec, deps, trace, effectiveAllow, base) {
+  // provider `start` 的 !enabled 检查只拦 `start` 不拦 `startContinuable`——此处
+  // 显式兜底（syncTool 注销工具是间接门）：禁用后不得静默派生子树，必须 fail-loud。
   if (!deps.getEnabled()) {
     throw new Error('dispatch: 插件已禁用（设置 → 子 Agent 方案 重新启用）');
   }
@@ -211,19 +133,21 @@ async function runContinuable(args, merged, meta, parent, exec, deps) {
   if (merged.reasoningEffort !== undefined) {
     deps.logger.warn(`[dsh-subagent-profile] continuable mode cannot set reasoningEffort; ignoring "${merged.reasoningEffort}"`);
   }
-  const continuableRequest = buildContinuableRequest(args, merged, parent);
+  const continuableRequest = buildContinuableRequest(args, merged, parent, effectiveAllow);
   const { childId } = await deps.subagents.startContinuable({
     provider: 'profile',
-    label: String(args.prompt ?? '').slice(0, 60),
+    label: dispatchLabel(args, merged),
     request: continuableRequest,
     signal: exec.signal
   });
-  // Continuable drops the profile's preset swap and reasoningEffort (the child
-  // inherits the parent preset), so the observability meta must report what
-  // actually took effect, not the requested-but-ignored values.
+  trackContinuableInflight(deps.guard, deps.subagents, childId, parent.session?.header?.id);
+  // Continuable 丢弃方案的 preset swap 与 reasoningEffort（子继承父预设），
+  // 故可观测 meta 必须报告实际生效值，而非被忽略的请求值。
   // 可见性修复：`reasoningEffort` 回显**请求值**（经 meta.reasoningEffort），
   // `preset:'inherit'` 是真实生效值；`ignored` 明确列出被丢弃项。
-  return {
+  // 信任标注不适用：continuable 只回 subagentId、无文本 output（后续经宿主的
+  // send_message 流转），没有可加前缀的回收文本，故此处不加 trustLabel。
+  const out = {
     kind: 'continuable',
     subagentId: childId,
     profile: meta.profile,
@@ -234,21 +158,33 @@ async function runContinuable(args, merged, meta, parent, exec, deps) {
     tokenTier: meta.tokenTier,
     ignored: ['preset', 'reasoningEffort']
   };
+  finalizeTrace(trace, {
+    effective: effectiveMeta({ ...meta, preset: 'inherit' }, ['preset', 'reasoningEffort']),
+    execution: { kind: 'continuable', parentSessionId: parent.session?.header?.id, childSessionId: childId, mode: 'continuable' },
+  });
+  out.decisionTrace = assertTraceSize(trace);
+  finishContinuableLedger(deps.evoLedger, base, childId); // 无结算：continuable 只写静态元数据（无 outcome）
+  return out;
 }
 
 // --- 后台 / 前台分支（从 execute 拆出）--------------------------------------------
 
-// Background one-shot (job) path — jobs.start wraps start() with a native
-// AbortController (a Node global in a bundle; the dynamic-plugin sandbox needed
-// the hand-rolled shim instead); still one turn, not continuable.
-async function runBackground(args, meta, request, parent, deps, pruneResultOutput, t0) {
+// 后台 one-shot（job）路径：jobs.start 包 start() 并提供原生
+// AbortController；仍是一轮即弃，非 continuable。
+async function runBackground(args, merged, meta, request, parent, deps, pruneResultOutput, t0, trace, guardHandle, base) {
   const jobs = deps.getService('jobs');
   if (jobs === undefined) {
-    throw new Error('dispatch: background jobs unavailable (load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs)');
+    throw new Error('dispatch: 后台派发不可用：缺少 jobs 服务（请安装 @deepseek-ai/dsh-jobs 与 @deepseek-ai/dsh-tool-jobs，或改用前台派发）');
   }
-  const jobId = jobs.start({
+  // jobId 由 jobs.start 同步返回，故用提升的 let 在结算（异步）时读取。
+  let jobId;
+  const onSettled = (settled) => {
+    guardHandle.finish(jobId, settled.childTotalTokens);
+    finishBackgroundLedger(deps.evoLedger, base, jobId, settled);
+  };
+  jobId = jobs.start({
     kind: 'subagent',
-    label: String(args.prompt ?? '').slice(0, 60),
+    label: dispatchLabel(args, merged),
     owner: parent,
     run: () => {
       const controller = new AbortController();
@@ -260,18 +196,23 @@ async function runBackground(args, meta, request, parent, deps, pruneResultOutpu
           meta,
           pruneResultOutput,
           (session) => measureChildTokens(deps.getService, session),
-          t0
+          t0,
+          deps.logger,
+          onSettled
         )
       };
     }
   });
-  return { kind: 'background', jobId, ...meta };
+  trackBackgroundInflight(deps.guard, jobs, jobId, parent);
+  // 后台：execute 返回时 start 尚未 resolve，无 settled（结算经 job 结果携带，不入会话块）。
+  const out = { kind: 'background', jobId, ...meta };
+  finalizeTrace(trace, { effective: effectiveMeta(meta, []), execution: { kind: 'background', parentSessionId: parent.session?.header?.id, jobId, mode: 'one-shot' } });
+  out.decisionTrace = assertTraceSize(trace);
+  return out;
 }
 
-// childTotalTokens：子 Agent 会话的宿主启发式估算 token 总量（surface 口径），
-// 非 provider 计费 usage token。仅 completed 结算时测量；tokenMeter 服务缺失、
-// measure 非函数、返回缺 totalTokens 或抛错时均返回 undefined（fail-soft），
-// 使测量绝不阻断派发结算。
+// childTotalTokens：宿主 tokenMeter 启发式估算（surface 口径，非计费 usage）。
+// 仅 completed 结算时测量；服务缺失/非函数/抛错均返回 undefined（fail-soft）。
 function measureChildTokens(getService, session) {
   if (session === undefined || session === null) return undefined;
   const meter = getService('tokenMeter');
@@ -286,90 +227,163 @@ function measureChildTokens(getService, session) {
   }
 }
 
-// Foreground: collect, always release the handle (dispose even when
-// run.result rejects), then fail loud on a non-completed stop reason.
-async function runForeground(meta, request, parent, deps, pruneResultOutput, t0) {
+// 仅 completed 结算时测量一次（tokenMeter 估算 + usage 分解 + 调用明细），dispose
+// 前读子 session 保证事件流完整；全 fail-soft（缺失/抛错 → undefined）绝不阻断结算。
+function measureForegroundRun(deps, run) {
+  const childSession = run.localAgent?.session;
+  return {
+    childTotalTokens: measureChildTokens(deps.getService, childSession),
+    childUsage: collectChildUsage(childSession),
+    childCalls: collectChildCalls(childSession),
+  };
+}
+
+// 前台：收集结果，无论 reject 与否都释放句柄，非 completed 停因 fail-loud；
+// run.result reject（undefined）也写失败 outcome（M9）。
+async function runForeground(meta, request, parent, deps, pruneResultOutput, t0, trace, guardHandle, base) {
   const run = await deps.subagents.start('profile', request);
+  finalizeTrace(trace, { execution: { kind: 'foreground', parentSessionId: parent.session?.header?.id, childSessionId: run.id, mode: 'one-shot' } });
+  trackForegroundInflight(deps.guard, run);
   let result;
-  let childTotalTokens;
+  let measurement;
   try {
     result = await run.result;
-    // 仅 completed 结算时测量（stopReason 非 completed 走失败路径，不测）；
-    // 在 dispose 之前读子 session，保证 measure 拿到完整 surface。
-    if (result.stopReason === 'completed') {
-      childTotalTokens = measureChildTokens(deps.getService, run.localAgent?.session);
-    }
+    if (result.stopReason === 'completed') measurement = measureForegroundRun(deps, run);
   } finally {
+    if (result === undefined) finishForegroundLedger(deps.evoLedger, base, run.id, { stopReason: 'error', output: [] }, [], Date.now() - t0, undefined);
     await run.dispose().catch(() => {});
+    guardHandle.finish(run.id, measurement?.childTotalTokens); // untrack + recordTokens + release
   }
-  // A non-'completed' stop reason is a failure; attach the child's
-  // partial output text (withPartialText style).
+  const childTotalTokens = measurement?.childTotalTokens;
+  const childUsage = measurement?.childUsage;
+  const childCalls = measurement?.childCalls;
+  // 台账：completed 与非 completed 都写 outcome（对照 settleStart 语义），随后非 completed 仍 throw。
+  const pruned = pruneResultOutput(result.output);
+  const elapsedMs = Date.now() - t0;
+  finishForegroundLedger(deps.evoLedger, base, run.id, result, pruned, elapsedMs, childCalls);
   const failure = stopReasonError(result);
   if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
-  // 结算 meta：elapsedMs 从 execute 入口 t0 计；stopReason 取底层结算值
-  // （此分支已达 return 必为 completed）。childTotalTokens 仍仅测量时携带。
   const metaOut = {
     ...meta,
     ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
-    elapsedMs: Date.now() - t0,
+    ...(childUsage !== undefined ? { childUsage } : {}),
+    elapsedMs,
     stopReason: result.stopReason
   };
-  return { output: textFrom(pruneResultOutput(result.output)), ...metaOut };
+  finalizeTrace(trace, {
+    effective: effectiveMeta(metaOut, []),
+    settled: {
+      stopReason: result.stopReason,
+      elapsedMs: metaOut.elapsedMs,
+      ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+      ...(childUsage !== undefined ? { childUsage } : {}),
+      ...(childCalls !== undefined ? { calls: childCalls } : {}),
+    },
+  });
+  // 信任标注：completed 子结果回灌父上下文前加结构化前缀（profile/preset 元数据、
+  // 无 prompt 原文），审计同字段 JSON 只进 logger、不进结果字符串。render 行首部
+  // 格式不变——前缀只进 output 文本（模型看到的正文带头）。
+  const output = `${trustLabel(metaOut)}${textFrom(pruned)}`;
+  deps.logger.info('[dsh-subagent-profile] trusted-output: ' + trustAudit(metaOut));
+  return { output, ...metaOut, decisionTrace: assertTraceSize(trace) };
+}
+
+// 预检段读取：whitelist / parentComposed / parentToolNames 只读取一次，同时喂闸
+// 与轨迹（避免重复 list() / schemas()），并组装 trace 骨架与交集闸 input。
+async function prepareTrace(args, parent, deps) {
+  const agentPresets = parent.ctx.get('agentPresets');
+  const whitelist = new Set(await resolveWhitelist(agentPresets, deps.getEscapeSet()));
+  const parentComposed = agentPresets !== undefined ? agentPresets.composedPreset(parent.ctx) : undefined;
+  const parentToolNames = readParentToolNames(parent);
+  const parentToolCount = parentToolNames.length;
+  // 决策输入快照：与 dispatch:profiles section 同源同序（enabled、cheap-first）——
+  // 「模型当时看到哪些候选」是回答「为什么这么选」的记录面（P5 补偿）。
+  const snapshot = profileSnapshotOf([...deps.store.profiles.values()].filter((p) => p.enabled !== false).sort((a, b) => tierSortKey(a.tokenTier) - tierSortKey(b.tokenTier)));
+  const trace = createDecisionTrace(
+    parentContextOf({
+      parentPreset: parentComposed,
+      parentProvider: parent.options.provider,
+      parentModel: parent.options.model,
+      parentToolCount,
+      allowFailOpen: deps.store.getAllowFailOpen(),
+    }),
+    requestedOf(args, { profiles: snapshot.entries })
+  );
+  const mode = args.continuable === true ? 'continuable' : (args.run_in_background === true ? 'background' : 'foreground');
+  const intersectionInput = { parentToolCount, requestedToolFilter: args.toolFilter, mode };
+  return { whitelist, parentComposed, parentToolNames, trace, mode, intersectionInput };
 }
 
-// execute 主体：预检段 + 三分支分派，行为逐字不变。
+// execute 主体：预检段 + 三分支分派。任一闸 fail 先记 fail 闸再 rethrow 原错误
+// 对象，失败 trace 进进程内台账（deps.ledger）。
 async function runDispatch(args, exec, deps) {
   const parent = exec.agent;
-  if (!parent) throw new Error('dispatch requires calling agent');
+  if (!parent) throw new Error('dispatch: 缺少调用 Agent（值需来自模型/编排者会话，请勿直接调用本工具）');
   // 派发耗时基准：execute 入口记 t0，前台/后台各自在结算处算 elapsedMs。
-  // continuable 不结算、不携带，故 t0 仅穿线到前台/后台。
   const t0 = Date.now();
-  const merged = mergeProfileArgs(args, deps.store);
-  // 信封模式 opt-in：三分支创建子 Agent 前，把信封骨架追加进子 persona。
-  // persona 是 systemPrompt 影子段（模型可见）；descriptor 是 model-hidden，
-  // 故骨架只追加 persona、不触碰 descriptor。既有 persona 为空/未设时直接
-  // 置为骨架，非空时以空行衔接追加，不覆盖原文。
-  if (args.envelope === true) {
-    const hasPersona = merged.persona !== undefined && merged.persona.trim() !== '';
-    merged.persona = hasPersona
-      ? `${merged.persona}\n\n${ENVELOPE_SKELETON}`
-      : ENVELOPE_SKELETON;
+  const { whitelist, parentComposed, parentToolNames, trace, mode, intersectionInput } = await prepareTrace(args, parent, deps);
+  // 预算闸句柄提至 try 外：任何分支 throw（前台 start reject / 后台 jobs 缺失等）
+  // 都在 catch 里幂等 release 并发槽——防错误路径把父会话的并发额度永久耗尽
+  // （正常路径 finish 已 release，catch 再调为 no-op）。
+  let guardHandle = { release: () => {} };
+  try {
+    const merged = mergeProfileArgs(args, deps.store);
+    // 信封模式 opt-in：三分支创建子 Agent 前，把信封骨架追加进子 persona（systemPrompt
+    // 影子段、模型可见），不触碰 descriptor；既有 persona 非空时以空行衔接追加。
+    if (args.envelope === true) {
+      const hasPersona = merged.persona !== undefined && merged.persona.trim() !== '';
+      merged.persona = hasPersona ? `${merged.persona}\n\n${ENVELOPE_SKELETON}` : ENVELOPE_SKELETON;
+    }
+    assertContinuableEnabled(deps, args);
+    applyWhitelistGate(trace, merged, whitelist, parentComposed);
+    // Cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
+    await applyCostGuardGate(trace, merged, parent, deps);
+    // 交集闸（三分支统一闸序，见 dispatch-gates.mjs）；continuable 的 effectiveAllow
+    // 同时用于 request 组装。
+    const effectiveAllow = applyIntersectionGate(trace, mode, intersectionInput, merged, parentToolNames);
+    recordApprovalGate(trace);
+    const meta = buildMeta(args, merged, parent);
+    const request = buildRequest(args, merged, parent, exec.signal);
+    // 结果回收默认剪枝：在 textFrom 前复用宿主 toolResultPruner.pruneContent 预剪；
+    // pruner 缺失时 pruneBlocks 回退为不剪（剪枝是增强、非硬依赖）。
+    const pruneResultOutput = (blocks) => pruneBlocks(blocks, deps.getService('toolResultPruner'));
+    logDispatchDecision(deps.logger, args, merged, parent);
+    // 总预算守卫：前/后台在 execute 入口占并发额度（continuable 不占），结算处 release
+    // + recordTokens。guardHandle 传入分支用于释放与父 sessionId 记账。
+    guardHandle = applyBudgetGate(deps, parent, args, trace);
+    // 派发台账静态元数据（双栏 cfg/task 指纹），分支结算处补 child_id+outcome 写盘。
+    const base = deps.evoLedger.baseEntry({ parent, args, merged, mode });
+    recordEscapeAllow(deps, parent, merged, trace);
+    if (args.continuable === true) return await runContinuable(args, merged, meta, parent, exec, deps, trace, effectiveAllow, base);
+    if (args.run_in_background === true) return await runBackground(args, merged, meta, request, parent, deps, pruneResultOutput, t0, trace, guardHandle, base);
+    return await runForeground(meta, request, parent, deps, pruneResultOutput, t0, trace, guardHandle, base);
+  } catch (error) {
+    guardHandle.release();
+    recordFailure(deps.ledger, parent, trace);
+    throw error;
   }
-  await assertPresetWhitelist(parent, merged);
-  // Cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控；
-  // llm 目录读取走共享 catalog 快照）。
-  await assertCostGuard(parent, merged, deps.store.getAllowFailOpen(), deps.logger, deps.catalog);
-  const meta = buildMeta(args, merged, parent);
-  const request = buildRequest(args, merged, parent, exec.signal);
-  // 结果回收默认剪枝：在 textFrom(result.output) 之前复用宿主
-  // toolResultPruner.pruneContent 预剪。`pruneResultOutput` 每次现取
-  // ctx.get('toolResultPruner') 以反映服务就绪状态；pruner 缺失时
-  // pruneBlocks 回退为不剪（剪枝是增强、非硬依赖）。envelope:true 时信封
-  // 骨架已在上方追加进 merged.persona（不改变此处的剪枝回收路径）。
-  const pruneResultOutput = (blocks) => pruneBlocks(blocks, deps.getService('toolResultPruner'));
-  logDispatchDecision(deps.logger, args, merged, parent);
-  if (args.continuable === true) return runContinuable(args, merged, meta, parent, exec, deps);
-  if (args.run_in_background === true) return runBackground(args, meta, request, parent, deps, pruneResultOutput, t0);
-  return runForeground(meta, request, parent, deps, pruneResultOutput, t0);
 }
 
-export function createDispatchTool({ register, store, getEnabled, getService, logger, subagents, catalog }) {
-  const deps = { store, getEnabled, getService, logger, subagents, catalog };
+export function createDispatchTool({ register, store, getEnabled, getService, logger, subagents, catalog, ledger, guard, evoLedger, getEscapeSet }) {
+  const deps = { store, getEnabled, getService, logger, subagents, catalog, ledger, guard, evoLedger, getEscapeSet };
   const dispatchTool = defineTool({
     name: 'dispatch',
-    description: 'Dispatch a subtask to a derived subagent, optionally overriding its preset, model, provider, reasoning effort, persona, tool whitelist, token budget, or recursion depth. Foreground waits for the result; run_in_background: true starts a background job (single turn); continuable: true starts a durable subagent whose conversation stays available for later turns via the send_message tool. 前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
+    description: '派发子任务给派生子 Agent，可逐个覆盖其 preset、model、provider、推理档位、persona、工具白名单、token 预算或递归深度。前台等待结果；run_in_background: true 启动后台任务（单轮即弃）；continuable: true 启动持久子 Agent，后续轮次经 send_message 工具延续对话。前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
     parameters: DISPATCH_PARAMETERS,
-    output: { schema: DISPATCH_OUTPUT_SCHEMA, render: DISPATCH_RENDER },
+    output: {
+      schema: DISPATCH_OUTPUT_SCHEMA,
+      render: DISPATCH_RENDER,
+      // 决策轨迹经 presentationMeta 投影进会话块 meta（客户端账本数据源），不进 render 行。
+      presentationMeta: (_args, value) => value.decisionTrace,
+    },
     isConcurrencySafe: () => true,
     execute: (args, exec) => runDispatch(args, exec, deps),
   });
-  // 共享一致性规则 lock: the closed oneOf result schema must carry an identical
-  // shared meta key set across all three branches. Fires only at apply time; a
-  // future meta-field add that forgets one 分支 throws here (once), so the
-  // model-side schema never silently rejects a分支.
+  // 共享一致性规则锁：闭合 oneOf 结果 schema 的三个分支必须携带同一套共享
+  // 元数据键集。只在 apply 时触发；未来加元数据字段时若漏掉某个分支，在这里
+  // throw 一次（而不是让模型侧 schema 静默拒绝某个分支）。
   assertResultSchemaConsistency(dispatchTool.output.schema);
-  // Register the tool only while enabled; unregister it the moment the switch
-  // turns off so it disappears from the model's tool list without a restart.
+  // 只在启用时注册工具；开关一关立即注销，使工具无需重启就从模型的工具列表消失。
   let disposeTool;
   function syncTool() {
     if (getEnabled() && disposeTool === undefined) {
@@ -377,7 +391,10 @@ export function createDispatchTool({ register, store, getEnabled, getService, lo
     } else if (!getEnabled() && disposeTool !== undefined) {
       const dispose = disposeTool;
       disposeTool = undefined;
-      dispose();
+      if (typeof dispose === 'function') dispose();
+      // 禁用：级联取消在途派发 + 清空并发/token 记账（重开后记账从零起步）。
+      deps.guard.cancelAll();
+      deps.guard.reset();
     }
   }
   syncTool();
@@ -387,7 +404,7 @@ export function createDispatchTool({ register, store, getEnabled, getService, lo
       if (disposeTool !== undefined) {
         const dispose = disposeTool;
         disposeTool = undefined;
-        dispose();
+        if (typeof dispose === 'function') dispose();
       }
     }
   };