dsh-subagent-profile 0.3.0 → 0.3.1

package/lib/core/cost-guard.mjs

@@ -1,6 +1,6 @@
-// lib/core/cost-guard.mjs — 运行时推导的 cost guard，从 index.mjs 逐字拆出。
+// lib/core/cost-guard.mjs — 运行时推导的 cost guard，从 index.mjs 逐字拆出。
 // 仅引用 lib/core/pure.mjs 的 assertHardLimits；无 @deepseek-ai 依赖。
-
+//
 // 运行时推导的 cost guard，两部分：
 //   ① always-on hard caps (assertHardLimits, in lib/core/pure.mjs) — maxTokens /
 //      maxDepth are hard delegation caps, independent of the `llm` service, so
@@ -13,11 +13,15 @@
 //      fail-open compat (warn + skip; v1 数据迁移中) or fail-loud reject. A
 //      profile that requests none of provider/model/reasoningEffort has nothing
 //      to verify and always passes (valid in a headless deployment).
+//
+// 目录读取改走共享 catalog 快照（lib/core/catalog-cache.mjs）：assertCostGuard 的
+// `catalog` 参数是缓存实例，`catalog.getSnapshot(llm)` 返回缓存过的 providers /
+// modelsByProvider。缓存只提速目录解析、不复检安全门——provider/model/effort 的
+// 校验逻辑与 fail-loud 文案逐字不变；reasoningEffort 走直连 resolveCallConfig
+// （校验调用，非目录读取，不入缓存）。
 // Used by both the provider's authoritative check and the dispatch tool's
 // pre-check. `allowFailOpen`/`logger` are injected because this function is
 // module-scoped and cannot reach the apply closure's `allowFailOpen`/`ctx.logger`.
-//
-// ①-⑥ 校验段按行门抽为模块级私有纯函数（行为逐字不变）。
 
 import { assertHardLimits } from './pure.mjs';
 
@@ -29,22 +33,19 @@ function needsLlmCheck(profile) {
   );
 }
 
-// ③ 目录为空检测：llm 存在但其 provider 目录为空（无发现能力）→ 无法核验。
-// 读取失败同样视为空目录（保守，随后走 allowFailOpen 门）。
-async function isLlmDirectoryEmpty(llm) {
-  try {
-    const providers = await llm.listProviders();
-    return (providers ?? []).length === 0;
-  } catch {
-    return true;
+// llm 缺失或目录为空时统一走 allowFailOpen 门（fail-open warn 或 fail-loud 拒绝）。
+function handleUnverifiable(allowFailOpen, logger) {
+  if (allowFailOpen === true) {
+    logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
+    return;
   }
+  throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
 }
 
-// ④ provider 注册校验（目录非空时才能判定「不在目录」）。
-async function assertProviderRegistered(llm, profile) {
+// ④ provider 注册校验（目录非空时才能判定「不在目录」）。providers 来自 catalog 快照。
+function assertProviderRegistered(dir, profile) {
   if (typeof profile.provider !== 'string' || profile.provider.length === 0) return;
-  const providers = await llm.listProviders();
-  if (!(providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
+  if (!(dir.providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
     throw new Error(`dispatch: provider "${profile.provider}" is not a registered provider`);
   }
 }
@@ -56,13 +57,25 @@ async function assertProviderRegistered(llm, profile) {
 //    per-provider 空目录。A non-empty catalog that does not advertise the model
 //    fails loud. An unverifiable lookup (listModels(undefined) when no provider
 //    is known) becomes a clean fail-loud error instead of leaking "undefined".
-async function assertModelAdvertised(llm, profile, effectiveProvider) {
+//    modelsByProvider 来自快照；快照未覆盖的 provider（undefined / 不在名册）
+//    走直连 listModels 兜底，保持原 fail-loud 文案逐字。
+async function assertModelAdvertised(llm, profile, effectiveProvider, modelsByProvider) {
   if (typeof profile.model !== 'string' || profile.model.length === 0) return;
+  const cached = modelsByProvider !== undefined ? modelsByProvider[String(effectiveProvider)] : undefined;
   let models;
-  try {
-    models = await llm.listModels(effectiveProvider);
-  } catch (error) {
-    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  let modelsError;
+  if (cached !== undefined) {
+    if (cached.ok === true) models = cached.models;
+    else modelsError = cached.error;
+  } else {
+    try {
+      models = await llm.listModels(effectiveProvider);
+    } catch (error) {
+      modelsError = error;
+    }
+  }
+  if (modelsError !== undefined) {
+    throw new Error(`dispatch: cannot validate model "${profile.model}" without a provider: ${modelsError instanceof Error ? modelsError.message : String(modelsError)}`, { cause: modelsError });
   }
   const listed = models ?? [];
   const known = listed.length > 0 && listed.some((model) => model && (model.id === profile.model || model.name === profile.model));
@@ -81,7 +94,7 @@ async function assertReasoningSupported(llm, profile, effectiveProvider, effecti
   }
 }
 
-export async function assertCostGuard(parent, profile, allowFailOpen, logger) {
+export async function assertCostGuard(parent, profile, allowFailOpen, logger, catalog) {
   // ① 硬上限 always-on（不依赖 llm）。
   assertHardLimits(profile.maxTokens, profile.maxDepth);
 
@@ -89,20 +102,21 @@ export async function assertCostGuard(parent, profile, allowFailOpen, logger) {
   if (!needsLlmCheck(profile)) return;
 
   const llm = parent.ctx.get('llm');
-  // ③ llm 缺失或目录为空 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
-  if (llm === undefined || await isLlmDirectoryEmpty(llm)) {
-    if (allowFailOpen === true) {
-      logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
-      return;
-    }
-    throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
+  // ③ llm 缺失 → 无法核验：按 allowFailOpen 决定 fail-open / fail-loud。
+  if (llm === undefined) return handleUnverifiable(allowFailOpen, logger);
+
+  // llm 存在：目录读取走共享 catalog 快照（缓存只提速目录解析，校验逻辑不变）。
+  const snapshot = await catalog.getSnapshot(llm);
+  const dir = snapshot.llm;
+  if (dir.providersError !== undefined || dir.providers.length === 0) {
+    return handleUnverifiable(allowFailOpen, logger);
   }
 
   // ④ provider 注册校验。
-  await assertProviderRegistered(llm, profile);
+  assertProviderRegistered(dir, profile);
   const effectiveProvider = profile.provider !== undefined ? profile.provider : parent.options.provider;
   const effectiveModel = profile.model !== undefined ? profile.model : parent.options.model;
   // ⑤ model 校验 + ⑥ reasoningEffort 校验。
-  await assertModelAdvertised(llm, profile, effectiveProvider);
+  await assertModelAdvertised(llm, profile, effectiveProvider, dir.modelsByProvider);
   await assertReasoningSupported(llm, profile, effectiveProvider, effectiveModel);
 }

package/lib/core/delegation.mjs

@@ -1,4 +1,4 @@
-// lib/core/delegation.mjs — background one-shot settling + delegation metadata
+// lib/core/delegation.mjs — background one-shot settling + delegation metadata
 // assembly, moved from index.mjs. Local lib references only: imports
 // stopReasonError / withPartialText / textFrom from lib/core/pure.mjs (the shipped
 // shims.readResult is NOT used by settleStart — it is used only by the
@@ -14,19 +14,39 @@ import { stopReasonError, withPartialText, textFrom } from './pure.mjs';
 // `prune` is the result-recycle pre-clipper: the caller (dispatch
 // execute) injects a closure that calls the host toolResultPruner.pruneContent
 // before textFrom; defaulting to identity keeps the background path safe when no
-// pruner is available.
-export async function settleStart(start, signal, meta, prune = (blocks) => blocks) {
+// pruner is available. `t0` is the dispatch execute entry timestamp; the settled
+// outcome carries `elapsedMs = now - t0` and the underlying `stopReason` (the
+// shipped terminal vocabulary). Defaulting t0 to now keeps direct callers (tests)
+// working without threading a timestamp.
+export async function settleStart(start, signal, meta, prune = (blocks) => blocks, measureChild = () => undefined, t0 = Date.now()) {
   let run;
   try {
     run = await start;
     const result = await run.result;
     const failure = stopReasonError(result);
     if (failure !== undefined) {
-      return { status: result.stopReason === 'aborted' ? 'killed' : 'failed', detail: withPartialText(failure, result.output), ...meta };
+      return {
+        status: result.stopReason === 'aborted' ? 'killed' : 'failed',
+        detail: withPartialText(failure, result.output),
+        ...meta,
+        elapsedMs: Date.now() - t0,
+        stopReason: result.stopReason
+      };
     }
-    return { status: 'completed', output: textFrom(prune(result.output)), ...meta };
+    // 仅 completed 结算时测量（非 completed 走上方失败分支，不测）；在 dispose
+    // 之前读子 session。measureChild 缺失/失败返回 undefined → 省略字段（fail-soft）。
+    const childTotalTokens = measureChild(run.localAgent?.session);
+    const metaOut = {
+      ...meta,
+      ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+      elapsedMs: Date.now() - t0,
+      stopReason: 'completed'
+    };
+    return { status: 'completed', output: textFrom(prune(result.output)), ...metaOut };
   } catch (error) {
-    return signal.aborted ? { status: 'killed', ...meta } : { status: 'failed', detail: String(error), ...meta };
+    return signal.aborted
+      ? { status: 'killed', ...meta, elapsedMs: Date.now() - t0, stopReason: 'aborted' }
+      : { status: 'failed', detail: String(error), ...meta, elapsedMs: Date.now() - t0, stopReason: 'error' };
   } finally {
     // Release the child handle no matter how the result settled — run.result
     // rejecting must not leak the subagent (same discipline as the foreground

package/lib/core/dispatch-schema.mjs

@@ -0,0 +1,71 @@
+// lib/core/dispatch-schema.mjs — dispatch 工具的 output 结果 schema（closed oneOf），
+// 从 dispatch-tool.mjs 拆出的纯数据声明（拆出时同步新增 elapsedMs/stopReason 共享
+// 字段）。三个分支（background / continuable / foreground）共享同一套元数据键集
+// （判别键 kind/jobId/subagentId/output 除外），由 pure.mjs 的
+// assertResultSchemaConsistency 在 apply 时锁定——任一分支漏补共享字段即 throw。
+// 纯数据、零依赖。
+
+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: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'background' },
+        jobId: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；后台结算经 job 结果携带，dispatch 结果不带。' },
+        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' } }
+      }
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        kind: { type: 'string', required: true, const: 'continuable' },
+        subagentId: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台/后台结算时携带，continuable 实际省略。' },
+        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' } }
+      }
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        output: { type: 'string', required: true },
+        profile: { type: 'string' },
+        preset: { type: 'string' },
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        reasoningEffort: { type: 'string' },
+        tokenTier: { type: 'string', enum: ['cheap', 'balanced', 'premium'], description: '成本/深度分层（估算口径，非计费）。' },
+        childTotalTokens: { type: 'number', description: '子 Agent 会话 token 估算总量（宿主启发式估算，非计费 usage token）；仅前台 completed 结算时携带。' },
+        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' } }
+      }
+    }
+  ]
+};

package/lib/core/dispatch-tool.mjs

@@ -1,4 +1,4 @@
-// lib/core/dispatch-tool.mjs — `dispatch` 工具（defineTool schema + execute）、
+// lib/core/dispatch-tool.mjs — `dispatch` 工具（defineTool schema + execute）、
 // 结果 schema 一致性锁与 syncTool 注册/注销逻辑，从 index.mjs 逐字拆出。
 // 仅引用 lib + shims；无 @deepseek-ai 依赖（shims 是唯一入口）。
 //
@@ -17,14 +17,16 @@
 // routes (/set-enabled), dispose runs on plugin teardown.
 //
 // execute 按预检段 + 前台/后台/continuable 三分支拆为模块级私有函数；
-// parameters/output 声明为纯数据，驻留模块级常量（与数据表同性质，不受函数
-// 行门约束）——工厂保持装配态，行为逐字不变。
+// parameters 声明为纯数据，驻留模块级常量（与数据表同性质，不受函数行门约束）；
+// output 结果 schema 已拆至 lib/core/dispatch-schema.mjs（守文件行门）——
+// 工厂保持装配态；除各任务明示的新增行为外，执行路径零漂移。
 
 import { defineTool } from './shims.mjs';
 import { computeContinuableAllow, textFrom, stopReasonError, withPartialText, pruneBlocks, assertResultSchemaConsistency } 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';
 
 // --- 工具声明纯数据（从工厂提到模块级；defineTool 只读不改）----------------------
 
@@ -34,6 +36,7 @@ const DISPATCH_PARAMETERS = {
   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',
@@ -50,65 +53,18 @@ const DISPATCH_PARAMETERS = {
   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（仅「中段即交付物」的任务用）。当前**仅预留**：工具
-  // schema 暴露此参数作字段契约，execute 不消费它（结构化信封回收尚未启用）。
-  // 见 execute 内注释。
-  envelope: { type: 'boolean', description: '预留：结构化信封回收（V2.0 中期启用，当前不生效）' },
+  // 信封模式 = 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).' }
 };
 
-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: [
-    {
-      type: 'object',
-      additionalProperties: false,
-      properties: {
-        kind: { type: 'string', required: true, const: 'background' },
-        jobId: { type: 'string', required: true },
-        profile: { type: 'string' },
-        preset: { type: 'string' },
-        provider: { type: 'string' },
-        model: { type: 'string' },
-        reasoningEffort: { type: 'string' },
-        ignored: { type: 'array', items: { type: 'string' } }
-      }
-    },
-    {
-      type: 'object',
-      additionalProperties: false,
-      properties: {
-        kind: { type: 'string', required: true, const: 'continuable' },
-        subagentId: { type: 'string', required: true },
-        profile: { type: 'string' },
-        preset: { type: 'string' },
-        provider: { type: 'string' },
-        model: { type: 'string' },
-        reasoningEffort: { type: 'string' },
-        ignored: { type: 'array', items: { type: 'string' } }
-      }
-    },
-    {
-      type: 'object',
-      additionalProperties: false,
-      properties: {
-        output: { type: 'string', required: true },
-        profile: { type: 'string' },
-        preset: { type: 'string' },
-        provider: { type: 'string' },
-        model: { type: 'string' },
-        reasoningEffort: { type: 'string' },
-        ignored: { type: 'array', items: { type: 'string' } }
-      }
-    }
-  ]
-};
+// 信封骨架：envelope:true 时追加进子 persona 的结构化汇报契约。三分支共享此
+// 常量；骨架只进 persona（systemPrompt 影子段、模型可见），不进 descriptor
+// （model-hidden、仅 session 记录），故 execute 在三分支创建子 Agent 前统一
+// 追加到 merged.persona。
+const ENVELOPE_SKELETON = '完成前按以下骨架输出：## 结论（1-2 句）\n## 结构分项（逐项）\n## 关键发现落点（文件路径/数据位置）';
 
 // continuable 丢弃 preset 换用与 reasoningEffort —— 渲染行把 `ignored`
 // 列表回显出来（`reasoningEffort=<值>(ignored)`，再加 ignored 项明细），让模型
@@ -117,11 +73,23 @@ 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}`
+    ? `[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}`
-      : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}\n\n${value.output}`;
+      ? `[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 }];
 };
 
@@ -131,7 +99,7 @@ const DISPATCH_RENDER = (_args, value) => {
 function mergeProfileArgs(args, store) {
   const base = args.profile !== undefined ? store.resolveProfile(args.profile) : {};
   const merged = { ...base };
-  for (const key of ['preset', 'model', 'provider', 'reasoningEffort', 'persona', 'toolFilter', 'maxTokens', 'maxDepth']) {
+  for (const key of ['preset', 'model', 'provider', 'reasoningEffort', 'persona', 'toolFilter', 'maxTokens', 'maxDepth', 'tokenTier']) {
     if (args[key] !== undefined) merged[key] = args[key];
   }
   return merged;
@@ -158,7 +126,8 @@ function buildMeta(args, merged, parent) {
     preset: merged.preset ?? 'inherit',
     provider: merged.provider ?? parent.options.provider ?? '(parent)',
     model: merged.model ?? parent.options.model ?? '(parent)',
-    reasoningEffort: merged.reasoningEffort ?? '(default)'
+    reasoningEffort: merged.reasoningEffort ?? '(default)',
+    tokenTier: merged.tokenTier ?? 'balanced'
   };
 }
 
@@ -262,6 +231,7 @@ async function runContinuable(args, merged, meta, parent, exec, deps) {
     provider: meta.provider,
     model: meta.model,
     reasoningEffort: meta.reasoningEffort,
+    tokenTier: meta.tokenTier,
     ignored: ['preset', 'reasoningEffort']
   };
 }
@@ -271,7 +241,7 @@ async function runContinuable(args, merged, meta, parent, exec, deps) {
 // 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) {
+async function runBackground(args, meta, request, parent, deps, pruneResultOutput, t0) {
   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)');
@@ -284,20 +254,51 @@ async function runBackground(args, meta, request, parent, deps, pruneResultOutpu
       const controller = new AbortController();
       return {
         cancel: (reason) => controller.abort(reason ?? 'dispatch: background subagent task killed'),
-        done: settleStart(deps.subagents.start('profile', { ...request, signal: controller.signal }), controller.signal, meta, pruneResultOutput)
+        done: settleStart(
+          deps.subagents.start('profile', { ...request, signal: controller.signal }),
+          controller.signal,
+          meta,
+          pruneResultOutput,
+          (session) => measureChildTokens(deps.getService, session),
+          t0
+        )
       };
     }
   });
   return { kind: 'background', jobId, ...meta };
 }
 
+// childTotalTokens：子 Agent 会话的宿主启发式估算 token 总量（surface 口径），
+// 非 provider 计费 usage token。仅 completed 结算时测量；tokenMeter 服务缺失、
+// measure 非函数、返回缺 totalTokens 或抛错时均返回 undefined（fail-soft），
+// 使测量绝不阻断派发结算。
+function measureChildTokens(getService, session) {
+  if (session === undefined || session === null) return undefined;
+  const meter = getService('tokenMeter');
+  if (meter === undefined || typeof meter.measure !== 'function') return undefined;
+  try {
+    const measured = meter.measure(session);
+    return measured !== null && typeof measured === 'object' && typeof measured.totalTokens === 'number'
+      ? measured.totalTokens
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // 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) {
+async function runForeground(meta, request, parent, deps, pruneResultOutput, t0) {
   const run = await deps.subagents.start('profile', request);
   let result;
+  let childTotalTokens;
   try {
     result = await run.result;
+    // 仅 completed 结算时测量（stopReason 非 completed 走失败路径，不测）；
+    // 在 dispose 之前读子 session，保证 measure 拿到完整 surface。
+    if (result.stopReason === 'completed') {
+      childTotalTokens = measureChildTokens(deps.getService, run.localAgent?.session);
+    }
   } finally {
     await run.dispose().catch(() => {});
   }
@@ -305,33 +306,55 @@ async function runForeground(meta, request, parent, deps, pruneResultOutput) {
   // partial output text (withPartialText style).
   const failure = stopReasonError(result);
   if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
-  return { output: textFrom(pruneResultOutput(result.output)), ...meta };
+  // 结算 meta：elapsedMs 从 execute 入口 t0 计；stopReason 取底层结算值
+  // （此分支已达 return 必为 completed）。childTotalTokens 仍仅测量时携带。
+  const metaOut = {
+    ...meta,
+    ...(childTotalTokens !== undefined ? { childTotalTokens } : {}),
+    elapsedMs: Date.now() - t0,
+    stopReason: result.stopReason
+  };
+  return { output: textFrom(pruneResultOutput(result.output)), ...metaOut };
 }
 
 // execute 主体：预检段 + 三分支分派，行为逐字不变。
 async function runDispatch(args, exec, deps) {
   const parent = exec.agent;
   if (!parent) throw new Error('dispatch requires calling 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;
+  }
   await assertPresetWhitelist(parent, merged);
-  // Cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
-  await assertCostGuard(parent, merged, deps.store.getAllowFailOpen(), deps.logger);
+  // 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 参数虽已在
-  // 工具 schema 暴露（预留），但 execute **不消费**它。
+  // 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);
-  return runForeground(meta, request, parent, deps, pruneResultOutput);
+  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 }) {
-  const deps = { store, getEnabled, getService, logger, subagents };
+export function createDispatchTool({ register, store, getEnabled, getService, logger, subagents, catalog }) {
+  const deps = { store, getEnabled, getService, logger, subagents, catalog };
   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 提示）。',