dsh-subagent-profile 0.3.2 → 0.3.4

package/lib/core/dispatch-gates.mjs

@@ -0,0 +1,153 @@
+// lib/core/dispatch-gates.mjs — dispatch 预检段各道闸的应用 + 决策轨迹记录，
+// 从 dispatch-tool.mjs 拆出以守文件行门。闸逻辑与 fail-loud 文案逐字不变；
+// 这里只「应用闸并就地记录 decisionTrace 的 pass/fail」，不改变任何派发行为。
+//
+// 依赖边界（无 @deepseek-ai 依赖）：只 import lib/core 纯模块——cost-guard
+// （assertCostGuard）、decision-trace（recordGate / hardLimitChecks）、pure
+// （MAX_TOKENS / MAX_DEPTH）。
+
+import { assertCostGuard } from './cost-guard.mjs';
+import { recordGate, hardLimitChecks } from './decision-trace.mjs';
+import { MAX_TOKENS, MAX_DEPTH, computeContinuableAllow } from './pure.mjs';
+
+// 预检：显式具体 preset 必须在运行时推导的白名单内；与父 composed 预设相同的
+// preset 改写为 'inherit'（不换装）。纯函数化：whitelist / parentComposed 由调用方
+// 预检段 resolve 一次后注入（避免重复 list()），throw 语义与文案逐字不变。
+function assertPresetWhitelist(merged, whitelist, parentComposed) {
+  if (typeof merged.preset !== 'string' || merged.preset === 'inherit') return;
+  if (!whitelist.has(merged.preset)) {
+    throw new Error(`dispatch: 预设 "${merged.preset}" 不在 system-trust 白名单（可在设置页改用受信任预设）`);
+  }
+  if (merged.preset === parentComposed) merged.preset = 'inherit';
+}
+
+// 白名单闸：预检段只 resolve 一次名单，结果同时喂本闸与 trace。'inherit' 改写
+// 也如实记入 resolvedPreset；fail 时先记 fail 闸再 rethrow（文案不变）。
+export function applyWhitelistGate(trace, merged, whitelist, parentComposed) {
+  const input = { requestedPreset: typeof merged.preset === 'string' ? merged.preset : undefined, systemTrustCandidates: [...whitelist] };
+  try {
+    assertPresetWhitelist(merged, whitelist, parentComposed);
+    recordGate(trace, { name: 'whitelist', input, output: { allowed: true, resolvedPreset: merged.preset ?? 'inherit' }, verdict: 'pass' });
+  } catch (error) {
+    recordGate(trace, { name: 'whitelist', input, output: { allowed: false, resolvedPreset: input.requestedPreset }, verdict: 'fail', reason: error.message });
+    throw error;
+  }
+}
+
+// 成本闸：硬上限（maxTokens/maxDepth）在调 assertCostGuard 前自行预判（不重复
+// throw，真 throw 仍在 assertHardLimits）；llm 能力面各检查项经 assertCostGuard
+// 的 onCheck 回调逐项回填。预判读 merged（profile 合并后的实际判定值）而非原始
+// args——保证轨迹 check 与真闸判定口径一致（profile 携带超限值时两者必须同 fail）。
+// fail 时先记 fail 闸再 rethrow（文案不变）。
+export async function applyCostGuardGate(trace, merged, parent, deps) {
+  const allowFailOpen = deps.store.getAllowFailOpen();
+  const input = { provider: merged.provider, model: merged.model, reasoningEffort: merged.reasoningEffort, maxTokens: merged.maxTokens, maxDepth: merged.maxDepth, allowFailOpen };
+  // 决策输入快照补充：请求 model 的 reasoning-effort 支持档位（catalog 快照，
+  // 有缓存；拿不到 fail-soft 省略）——台账可见「该模型当时可选哪些档位」。
+  if (typeof merged.model === 'string' && merged.model !== '') {
+    try {
+      const snapshot = await deps.catalog.getSnapshot(parent.ctx.get('llm'));
+      const efforts = snapshot?.efforts?.[merged.model];
+      if (Array.isArray(efforts) && efforts.length > 0) {
+        input.modelEfforts = efforts.map((effort) => (effort && typeof effort.id === 'string' ? effort.id : String(effort))).slice(0, 6);
+      }
+    } catch { /* fail-soft：快照不可用不影响闸判定 */ }
+  }
+  const checks = hardLimitChecks(merged, MAX_TOKENS, MAX_DEPTH);
+  try {
+    await assertCostGuard(parent, merged, allowFailOpen, deps.logger, deps.catalog, (entry) => checks.push(entry));
+    recordGate(trace, { name: 'cost', input, output: { checks }, verdict: 'pass' });
+  } catch (error) {
+    recordGate(trace, { name: 'cost', input, output: { checks }, verdict: 'fail', reason: error.message });
+    throw error;
+  }
+}
+
+// 禁用门（continuable 专属显式检查）：provider start 的 !enabled 只拦 start、
+// 不拦 startContinuable；syncTool 注销工具对 continuable 是间接门，故在此显式
+// fail-loud。检查位于全部闸之前——与「禁用时不得静默派生子树」的既有语义一致，
+// 且保证交集闸不会在禁用态先于本门抛其它文案。
+export function assertContinuableEnabled(deps, args) {
+  if (args.continuable === true && !deps.getEnabled()) {
+    throw new Error('dispatch: 插件已禁用（设置 → 子 Agent 方案 重新启用）');
+  }
+}
+
+// 交集闸（三分支统一在 approval 之前记录，闸序一致）：前/后台真交集由宿主在
+// 子会话启动时计算（execute 返回之后），记 deferred；continuable 在此预加工
+// 闭集 allow（空集 fail-loud），同一结果同时用于轨迹记录与 request 组装。
+// 返回 continuable 的 effectiveAllow（非 continuable 返回 undefined）。
+export function applyIntersectionGate(trace, mode, intersectionInput, merged, parentToolNames) {
+  if (mode !== 'continuable') {
+    recordGate(trace, { name: 'intersection', input: intersectionInput, output: { mode: 'deferred' }, verdict: 'pass', reason: '子工具交集由宿主在子会话启动时计算（restrictChildTools），结果体现在结算 stopReason/error' });
+    return undefined;
+  }
+  try {
+    const effectiveAllow = computeContinuableAllow(parentToolNames, merged.toolFilter);
+    // 工具集子节数据（continuable 可计算闭集与移除清单）。名单类数组超 8 项由
+    // recordGate 的 truncateLists 自动截断为 { values, truncated }（台账展示时认标记）。
+    const removedRaw = parentToolNames
+      .filter((name) => !effectiveAllow.includes(name))
+      .map((name) => ({ name, reason: name === 'run_code' ? '安全策略：子代理不执行代码' : '不在白名单' }));
+    const removedTools = removedRaw.length > 8 ? { values: removedRaw.slice(0, 8), truncated: true } : removedRaw;
+    recordGate(trace, { name: 'intersection', input: intersectionInput, output: { effectiveAllowCount: effectiveAllow.length, effectiveAllowNames: effectiveAllow, removedTools }, verdict: 'pass' });
+    return effectiveAllow;
+  } catch (error) {
+    recordGate(trace, { name: 'intersection', input: intersectionInput, output: {}, verdict: 'fail', reason: error.message });
+    throw error;
+  }
+}
+
+// 总预算闸（并发上限 + 每父累计 token）：前/后台在派发入口占并发额度（continuable
+// 不占——持久会话启动、非在途 one-shot）。拒绝时记一道 budget fail 闸 + warn + 抛
+// 可行动中文错误（只拦新增派发，数值内零影响）；无父 sessionId 时 acquire 内部跳过
+// 守卫。返回 { parentSessionId, finish }：finish(key, childTotalTokens) 是结算共用
+// 钩子（untrack + recordTokens + release），前/后台 settle 时恰好调用一次。
+export function applyBudgetGate(deps, parent, args, trace) {
+  if (args.continuable === true) return { parentSessionId: undefined, finish: () => {}, release: () => {} };
+  const parentSessionId = parent.session?.header?.id;
+  const budget = deps.guard.snapshot(parentSessionId);
+  const acquired = deps.guard.acquire(parentSessionId);
+  if (!acquired.ok) {
+    const message = acquired.reason === 'concurrency'
+      ? `dispatch: 并发派发数已达上限 ${acquired.limit}，请等待在途任务完成`
+      : `dispatch: 本会话累计派发 token 已达上限 ${acquired.limit}，请等待在途任务完成或开启新会话`;
+    recordGate(trace, {
+      name: 'budget',
+      input: { parentSessionId, current: budget, reason: acquired.reason, limit: acquired.limit },
+      output: { allowed: false },
+      verdict: 'fail',
+      reason: message,
+    });
+    deps.logger.warn(`[dsh-subagent-profile] ${message}`);
+    throw new Error(message);
+  }
+  // 通过也记闸（与 whitelist/cost/intersection 同口径：pass/fail 均记，台账时间线可
+  // 见预算检查项；无父 sessionId 时 acquire 跳过守卫，同样记 pass 并注明 skipped）。
+  recordGate(trace, {
+    name: 'budget',
+    input: { parentSessionId, current: budget },
+    output: { allowed: true, skipped: acquired.skipped === true },
+    verdict: 'pass',
+  });
+  return {
+    parentSessionId,
+    finish: (key, childTotalTokens) => {
+      deps.guard.untrack(key);
+      if (childTotalTokens !== undefined) deps.guard.recordTokens(parentSessionId, childTotalTokens);
+      acquired.release();
+    },
+    // 错误路径兜底：分支 throw 时 runDispatch 的 catch 幂等释放并发槽（不记账、不
+    // untrack——untrack 由正常结算路径负责；acquire 的 release 本身幂等）。
+    release: () => acquired.release(),
+  };
+}
+
+// 读取父工具名（失败软回退为空数组）。真实宿主 ctx.tools.schemas 恒存在；测试
+// fake 父 Agent 可能缺 tools，故此处守卫，避免预检段破坏前/后台路径。
+export function readParentToolNames(parent) {
+  const tools = parent.ctx?.tools;
+  if (tools === undefined || typeof tools.schemas !== 'function') return [];
+  const schemas = tools.schemas(parent);
+  return Array.isArray(schemas) ? schemas.map((schema) => schema.name) : [];
+}

package/lib/core/dispatch-guard.mjs

@@ -0,0 +1,156 @@
+// lib/core/dispatch-guard.mjs — 派发总预算守卫（进程级并发上限 + 每父累计 token
+// 记账）+ 在途登记表（级联取消）。import-free（仅 node 内置），工厂式参数注入、
+// 无模块级单例：每次 apply 各持一份独立状态。
+//
+// 三职责：
+//   1. 并发上限：同一父会话的在途 one-shot 派发数封顶（acquire/release，release 幂等，
+//      计数归零删键）；
+//   2. 每父累计 token：子结算时的 childTotalTokens 独立进程级记账（不复用 profiles
+//      Map，避免与 registry 状态耦合），累计达到上限后该父会话后续派发被拒；
+//   3. 在途登记：track/untrack/cancelAll（前台 run.dispose、后台 jobs.kill、
+//      continuable 宿主 interrupt），禁用/卸载时级联取消在途派发。
+//
+// 边界（后来开发者须知）：
+//   * 并发上限 8 与 token 上限 200_000 为建议值，待实测后校准。
+//   * 守卫只拦「新增派发」（acquire 拒绝），不拦现有任何合法路径（数值内零影响）。
+//   * 父会话结束的记账释放不依赖宿主生命周期事件（插件侧无法可靠观测父会话结束）：
+//     释放依赖禁用/卸载清账（reset）+ 上限轮换兜底，见 index.mjs 的 syncTool 禁用
+//     分支与 dispose 钩子。
+//   * continuable 子会话只可「中断当前 turn」（宿主 interrupt 为 fire-and-return
+//     中断、非终止，子会话仍驻留），详见 dispatch-tool.mjs 的 in-flight 登记注释。
+//   * continuable 的 in-flight 登记无 untrack 点（持久子会话无结算时刻）：登记只服务
+//     禁用/卸载时的 interrupt 级联，条目随 reset 或进程生命周期释放——这是有意的
+//     fire-and-return 口径，勿按 one-shot 的结算-释放模式补 untrack。
+
+function emptyKey(key) {
+  return key === undefined || key === null || key === '';
+}
+
+// acquire 主体：并发 +1；token 累计已达上限或并发已满时拒绝（不 +1）。无父
+// sessionId 时跳过守卫（返回 ok + no-op release，数值内零影响）。
+function acquireSlot(concurrency, tokenTotals, maxConcurrent, maxParentTokens, parentSessionId) {
+  if (emptyKey(parentSessionId)) {
+    return { ok: true, release: () => {}, skipped: true };
+  }
+  const current = concurrency.get(parentSessionId) ?? 0;
+  if (current >= maxConcurrent) {
+    return { ok: false, reason: 'concurrency', limit: maxConcurrent };
+  }
+  const tokens = tokenTotals.get(parentSessionId) ?? 0;
+  if (tokens >= maxParentTokens) {
+    return { ok: false, reason: 'tokens', limit: maxParentTokens };
+  }
+  concurrency.set(parentSessionId, current + 1);
+  let released = false;
+  return {
+    ok: true,
+    release: () => {
+      if (released) return;
+      released = true;
+      const next = (concurrency.get(parentSessionId) ?? 1) - 1;
+      if (next <= 0) concurrency.delete(parentSessionId);
+      else concurrency.set(parentSessionId, next);
+    },
+  };
+}
+
+// recordTokens 主体：结算时把子 childTotalTokens 记入父会话累计，返回累计是否已达
+// 上限（>= 上限）。空 id / 已 dispose 的父 / 非有限非负数跳过并返回 false（fail-soft，
+// 绝不阻断结算）。disposed 守卫是 H2 修复：父会话结束（resetParent）后后台任务才
+// 结算时，若仍 set 会把 tokenTotals 键重新插回，导致 Map 随会话数无界增长。
+function addTokens(tokenTotals, disposed, maxParentTokens, parentSessionId, childTotalTokens) {
+  if (emptyKey(parentSessionId) || disposed.has(parentSessionId)) return false;
+  if (typeof childTotalTokens !== 'number' || !Number.isFinite(childTotalTokens) || childTotalTokens < 0) return false;
+  const next = (tokenTotals.get(parentSessionId) ?? 0) + childTotalTokens;
+  tokenTotals.set(parentSessionId, next);
+  return next >= maxParentTokens;
+}
+
+// track/untrack 主体：登记一个在途派发（key=前台 run.id / 后台 jobId / continuable
+// childId）。cancel 可能为 undefined（continuable 宿主无 interrupt 时注明边界）。
+function registerInflight(inflight, key, cancel) {
+  if (emptyKey(key)) return;
+  inflight.set(key, typeof cancel === 'function' ? cancel : undefined);
+}
+
+function dropInflight(inflight, key) {
+  if (emptyKey(key)) return;
+  inflight.delete(key);
+}
+
+// cancelAll 主体：级联取消全部在途派发（禁用/卸载）。每项 cancel 恰好调用一次并清空
+// 登记表；cancel 缺失或抛错时 warn（fail-soft，绝不因单项失败阻断整体取消）。
+function cancelInflight(inflight, warn, reason) {
+  const entries = [...inflight.entries()];
+  inflight.clear();
+  for (const [key, cancel] of entries) {
+    if (typeof cancel !== 'function') continue;
+    try {
+      cancel(reason);
+    } catch (error) {
+      warn(`dispatch: 取消在途派发 ${key} 失败（${error instanceof Error ? error.message : String(error)}）`);
+    }
+  }
+}
+
+// 按父释放（见 index.mjs 的 agent/disposed 挂钩）：父会话逻辑结束（Agent 注册
+// fiber 卸载）时删该父的并发计数与 token 累计键。在途登记表键为子标识
+// （run.id/jobId/childId）不含父 id，不在此清——在途子随自身结算或禁用/卸载级联
+// 取消自然收敛。
+export function createDispatchGuard({ maxConcurrent = 8, maxParentTokens = 200000, warn = () => {} } = {}) {
+  const concurrency = new Map();
+  const tokenTotals = new Map();
+  const inflight = new Map();
+  // H2：已 dispose 的父会话 id 集合。resetParent（agent/disposed 挂钩）登记，防止
+  // 后台任务在父结束后结算时经 recordTokens 把 tokenTotals 键重插回来（无界增长）。
+  // 该集合按会话数线性增长（每会话一条小字符串），远小于原泄漏的每次结算一插。
+  const disposed = new Set();
+  return {
+    acquire: (parentSessionId) => acquireSlot(concurrency, tokenTotals, maxConcurrent, maxParentTokens, parentSessionId),
+    recordTokens: (parentSessionId, childTotalTokens) => addTokens(tokenTotals, disposed, maxParentTokens, parentSessionId, childTotalTokens),
+    track: (key, cancel) => registerInflight(inflight, key, cancel),
+    untrack: (key) => dropInflight(inflight, key),
+    cancelAll: (reason = 'dispatch: 插件已禁用或卸载，取消在途派发') => cancelInflight(inflight, warn, reason),
+    resetParent: (parentSessionId) => {
+      if (emptyKey(parentSessionId)) return;
+      disposed.add(parentSessionId);
+      concurrency.delete(parentSessionId);
+      tokenTotals.delete(parentSessionId);
+    },
+    snapshot: (parentSessionId) => ({
+      concurrency: typeof parentSessionId === 'string' && parentSessionId !== '' ? (concurrency.get(parentSessionId) ?? 0) : 0,
+      tokens: typeof parentSessionId === 'string' && parentSessionId !== '' ? (tokenTotals.get(parentSessionId) ?? 0) : 0,
+      maxConcurrent,
+      maxParentTokens,
+    }),
+    reset: () => {
+      concurrency.clear();
+      tokenTotals.clear();
+      inflight.clear();
+      disposed.clear();
+    },
+  };
+}
+
+// 在途登记 helper：前台 one-shot key=run.id，cancel=run.dispose（禁用/卸载级联取消）。
+export function trackForegroundInflight(guard, run) {
+  guard.track(run.id, () => run.dispose().catch(() => {}));
+}
+
+// 在途登记 helper：后台 job key=jobId，cancel=jobs.kill（owner=parent 作 caller 授权；
+// 未知 job 抛错、已结算 job 返回 already-finished——两者均由 guard.cancelAll 的
+// fail-soft 兜底，级联取消不因单项失败中断）。
+export function trackBackgroundInflight(guard, jobs, jobId, parent) {
+  guard.track(jobId, (reason) => {
+    if (typeof jobs.kill === 'function') jobs.kill(jobId, parent, reason);
+  });
+}
+
+// 在途登记 helper：continuable 子会话 key=childId，cancel=宿主 interrupt（fire-and-
+// return 中断当前 turn，非终止——子会话仍驻留，后续 send_message 可唤醒；插件侧无法
+// 终止持久子会话）。无 interrupt 能力时不登记取消（cancelAll 跳过）。
+export function trackContinuableInflight(guard, subagents, childId, parentSessionId) {
+  if (typeof subagents.interrupt === 'function') {
+    guard.track(childId, () => subagents.interrupt(childId, { kind: 'user', parentSessionId }));
+  }
+}

package/lib/core/dispatch-schema.mjs

@@ -1,18 +1,70 @@
-// lib/core/dispatch-schema.mjs — dispatch 工具的 output 结果 schema（closed oneOf），
-// 从 dispatch-tool.mjs 拆出的纯数据声明（拆出时同步新增 elapsedMs/stopReason 共享
-// 字段）。三个分支（background / continuable / foreground）共享同一套元数据键集
+// lib/core/dispatch-schema.mjs — dispatch 工具的纯数据声明（零依赖）：输入参数
+// schema（DISPATCH_PARAMETERS）与 output 结果 schema（DISPATCH_OUTPUT_SCHEMA，
+// closed oneOf），均从 dispatch-tool.mjs 拆出以守文件行门。
+//
+// 三个结果分支（background / continuable / foreground）共享同一套元数据键集
 // （判别键 kind/jobId/subagentId/output 除外），由 pure.mjs 的
 // assertResultSchemaConsistency 在 apply 时锁定——任一分支漏补共享字段即 throw。
-// 纯数据、零依赖。
+// decisionTrace 是共享键：三分支都必须携带，但只锁「存在性」（深层结构由
+// lib/core/decision-trace.mjs 的纯函数与单测保证），它经 output.presentationMeta
+// 投影进会话块 meta 供客户端台账展示，不进模型可见面。
+
+// 输入参数 schema（从 dispatch-tool.mjs 逐字移入；defineTool 只读不改）。
+export const DISPATCH_PARAMETERS = {
+  // 参数轴归属与约束（能力轴 / 预算轴 / 防护 / 模式）：
+  //   能力轴 preset→whitelist 闸；model/provider→llm 目录核验；persona→仅 shadow
+  //   order 0（不进任何闸）；toolFilter→工具交集闸（只减不增）。
+  //   预算轴 reasoningEffort→resolveCallConfig；maxTokens→MAX_TOKENS 硬上限；
+  //   tokenTier→档位元数据（估算口径）。
+  //   防护 maxDepth→MAX_DEPTH 硬上限。
+  //   模式字段（run_in_background/continuable/envelope）是派发方式选择，不入配置覆盖。
+  // 新增字段时须按上列轴归类，并同步键集测试（percall-spec）的 WHITELIST_KEYS。
+  // per-call 规范化清单闭合：宿主 dsh-tools 的 DSL 参数解析**默认拒绝
+  // 未知键**（2026-08 实测：参数级 additionalProperties 只接受 value schema 对象、
+  // 不接受 boolean，故无法显式声明；键集闭合由 percall-spec 测试「键集恰为 14 键」
+  // 锁定，mergeProfileArgs 只透传白名单 9 键，未知字段到不了子请求）。
+  profile: { type: 'string', description: '容器选择（profile 注册表 id：内建 swap-standard/researcher，或设置页自建）；省略则该 subagent 原样继承父预设与工具集，不加配置覆盖。' },
+  preset: { type: 'string', description: '能力轴·目标预设强制覆盖；必须是本运行时 system-trust 预设（白名单内的受信任预设），否则 fail-loud 拒绝；与父 composed 预设相同时改写为 inherit（不换装）。' },
+  model: { type: 'string', description: '能力轴·子 Agent 显式模型覆盖，per-call 优先于 profile；必须在该 provider 目录中已发布，否则 fail-loud 拒绝（无发现能力的空目录 adapter 无法校验时按兼容模式开关决定）。' },
+  provider: { type: 'string', description: '能力轴·子 Agent 显式 provider 覆盖，per-call 优先于 profile；必须已注册在其 provider 目录中，否则 fail-loud 拒绝。' },
+  reasoningEffort: { type: 'string', description: '预算轴·注入每个子请求的推理档位覆盖，per-call 优先于 profile；经 resolveCallConfig 校验该档受显式 provider/model 支持，否则 fail-loud 拒绝；continuable 模式忽略本字段（子会话不支持）。' },
+  tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '预算轴·成本/深度档位（估算口径，非计费）：cheap 省 token、balanced 均衡、premium 高成本。覆盖 profile 的 tokenTier；缺省 balanced。' },
+  persona: { type: 'string', description: '能力轴·覆盖子 Agent 的部署 persona 段（只 shadow order 0 的 persona 影子段，不进 descriptor）；per-call 优先于 profile。' },
+  toolFilter: {
+    type: 'object',
+    // 能力轴·工具白名单交集：只减不增，不能给子 Agent 添加任何父集没有的工具。
+    // DSL 对象参数默认拒绝未知键，toolFilter 必须闭合其 schema，
+    // 否则 defineTool 在 apply 时 throw、插件加载失败。
+    additionalProperties: false,
+    description: '能力轴·给子工具集额外做白名单交集（与父工具集求交，只减不增）：不能给子 Agent 添加任何父集没有的工具。',
+    properties: {
+      allow: { type: 'array', items: { type: 'string' }, description: '提供时，仅保留这些工具名。' },
+      deny: { type: 'array', items: { type: 'string' }, description: '这些工具名总是被移除。' }
+    }
+  },
+  maxTokens: { type: 'number', description: '预算轴·子 Agent 显式 token 预算覆盖，per-call 优先于 profile；超过部署硬上限（MAX_TOKENS）fail-loud 拒绝。' },
+  maxDepth: { type: 'number', description: '防护·子 Agent 显式绝对递归深度上限覆盖，per-call 优先于 profile；超过部署硬上限（MAX_DEPTH）fail-loud 拒绝。' },
+  run_in_background: { type: 'boolean', description: '模式选择·异步 one-shot：走 jobs.start 包 start()，返回 jobId；仍单轮即弃，非 continuable。不入配置覆盖。' },
+  continuable: { type: 'boolean', description: '模式选择·启动持久可 continuation 的 subagent 而非 one-shot：立即返回 subagentId 并经 send_message 工具在后续轮次延续对话；默认 false。不入配置覆盖；与 run_in_background 同真时本字段优先，忽略 preset 换用与 reasoningEffort。' },
+  // 信封模式 = opt-in（仅「中段即交付物」的任务用）：true 时把信封骨架追加进
+  // 子 persona（systemPrompt 影子段，模型可见），子 Agent 按结构化信封汇报；
+  // 默认 false 走结果剪枝回收。
+  envelope: { type: 'boolean', description: '模式选择·true 时子 Agent 按结构化信封汇报（简短结论 + 结构分项 + 关键发现落点），适合中段即交付物的长任务；默认 false 走剪枝回收。不入配置覆盖。' },
+  prompt: { type: 'string', required: true, description: '任务文本·该 subagent 完成的自包含任务（它看不到当前对话）。' }
+};
+
+// 已知 per-call 参数键集（单一事实来源）：decisionTrace 的 requested 快照据此把
+// 未知字段记录为 unknown_keys（fail-visible，不静默吞）。宿主 dsh-tools DSL 对
+// 参数默认拒绝未知键，此处是插件侧决策轨迹的可观测兜底。
+export const DISPATCH_PARAMETER_KEYS = Object.freeze(Object.keys(DISPATCH_PARAMETERS));
 
 export const DISPATCH_OUTPUT_SCHEMA = {
-  // Observability metadata on every result. OneOf covers the
-  // background variant (kind/jobId) and the foreground variant (output),
-  // both closed and both carrying the effective delegation values.
-  // `ignored` must appear in ALL three branches (with the shared `preset`
-  // / `provider` / `model` / `reasoningEffort` / `profile`), keeping the
-  // closed oneOf consistent — assertResultSchemaConsistency(dispatchTool
-  // .output.schema) in apply() fires if any 分支 忘补该字段.
+  // 每个结果上的可观测元数据。oneOf 覆盖 background 变体（kind/jobId）与
+  // foreground 变体（output），两者闭合且都携带生效的委派值。`ignored` 必须
+  // 出现在全部三个分支（连同共享的 `preset` / `provider` / `model` /
+  // `reasoningEffort` / `profile`），保持闭合 oneOf 一致——
+  // apply() 里 assertResultSchemaConsistency(dispatchTool.output.schema)
+  // 任一分支漏补该字段即 throw。
   oneOf: [
     {
       type: 'object',
@@ -41,7 +93,8 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；后台结算经 job 结果携带，dispatch 结果不带。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；后台结算经 job 结果携带，dispatch 结果不带。' },
-        ignored: { type: 'array', items: { type: 'string' } }
+        ignored: { type: 'array', items: { type: 'string' } },
+        decisionTrace: { type: 'object', additionalProperties: true, description: '派发决策轨迹（供客户端台账展示，不进模型可见面）' }
       }
     },
     {
@@ -71,7 +124,8 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；continuable 不结算，实际省略。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；continuable 不结算，实际省略。' },
-        ignored: { type: 'array', items: { type: 'string' } }
+        ignored: { type: 'array', items: { type: 'string' } },
+        decisionTrace: { type: 'object', additionalProperties: true, description: '派发决策轨迹（供客户端台账展示，不进模型可见面）' }
       }
     },
     {
@@ -100,8 +154,43 @@ export const DISPATCH_OUTPUT_SCHEMA = {
         },
         elapsedMs: { type: 'number', description: '派发耗时（毫秒，execute 入口到结算时刻）；前台 completed 结算时携带。' },
         stopReason: { type: 'string', enum: ['completed', 'max-tokens', 'aborted', 'refusal', 'error'], description: '子 Agent 结束原因；前台 completed 结算时携带。' },
-        ignored: { type: 'array', items: { type: 'string' } }
+        ignored: { type: 'array', items: { type: 'string' } },
+        decisionTrace: { type: 'object', additionalProperties: true, description: '派发决策轨迹（供客户端台账展示，不进模型可见面）' }
       }
     }
   ]
 };
+
+// 结果 render 行（从 dispatch-tool.mjs 逐字移入以守文件行门）：continuable 丢弃
+// preset 换用与 reasoningEffort —— 渲染行把 `ignored` 列表回显出来
+// （`reasoningEffort=<值>(ignored)`，再加 ignored 项明细），让模型「看见」被丢弃项；
+// background/foreground 无忽略项时该后缀为空。
+export 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}`
+    : '';
+  // childUsage 是嵌套对象，render 行是扁平的 key=value，故 JSON 序列化为单段
+  // 供 client 侧 parseDispatchText 解析回对象（五段分解）。仅前台 completed 结算
+  // 携带；后台结算经 job 结果携带，continuable 不携带，故该段只在 foreground 行。
+  const usage = value.childUsage !== undefined && value.childUsage !== null && typeof value.childUsage === 'object'
+    ? ` · childUsage=${JSON.stringify(value.childUsage)}`
+    : '';
+  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}${usage}${elapsed}${stopReason}\n\n${value.output}`;
+  return [{ type: 'text', text }];
+};