@v587d/capital-generation 2.9.1 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@
 - **第三位（patch）**：不破坏既有工具 / 配置 / 会话的新增与修复（如 2.1.1、2.1.2）。
 - **第二位（minor）**：有需要用户知晓的行为变更，且段内附迁移说明（如 2.1.0 的图表呈现通道重做、2.2.0 的数据源与检索来源扩容、2.4.0 的**必须换宿主版本**、2.9.0 的选择器收敛与质检前置——本插件自己的工具与数据契约没变，所以只抬第二位）。
 
+## [2.10.0] - 2026-10-23
+
+自动模式收口为**单轮等待 + 一次交付**：主 Agent 委派后等整棵子树收敛，再把结论和图表一次交到最后
+一轮；同时补上图表交付去重/标题校验、可读文件名，以及数据窗口、成交量单位与财务口径的硬规则。
+本插件自己的工具与数据契约不变，不需要改配置。
+
+### Added
+
+- **自动模式单轮等待**：主 Agent 新增 `wait_for_agents`（仅根会话）。委派或发消息后先等整棵子 Agent
+  树收敛，子角色回传在同一轮内处理，不再每条回执都单独落成一个可见轮次。
+- **四态回执**：`all_settled` / `message` / `user_input` / `timeout`；`timeout` 会列出仍在运行的
+  子 Agent，既不是完成也不是失败。
+- **图表交付质量闸门**：`present_charts` 登记前按 `dataset + kind + 标题` 去重，并校验标题里的
+  6 位股票代码与 dataset 一致；重复图/错标题图进 `failed`，不再进入交付卡片。
+- **可读图表产物与读图指引**：新图文件名带股票代码/ASCII 标题词与图形类型（如
+  `300803-kline-ab12cd34.html`），HTML 顶部补图形类型、来源、时间字段和横轴/纵轴/序列/K 线说明。
+
+### Changed
+
+- **等待不再以可见等待行结束回合**：主 Agent 先调用 `wait_for_agents`；`message` / `user_input`
+  先处理后继续等，`all_settled` 才进入逐行对账，`timeout` 才写等待行。等待期间仍禁止外部检索、
+  反复 `list_agents` 与轮询。
+- **单轮等待只归根会话**：`tools/orchestration` 只挂在根 preset；子 Agent 继续用 `send_message`
+  回传，不能等待兄弟或父 Agent。
+- **派生统计算子收紧**：`N 日` 一律按最近 N 个交易日计算；MA20/10 日高不再用自然日窗口，成交量
+  明确按股展示，量比注明分母是否含当日。
+- **财务与估值口径对齐**：`operating_income` 与媒体“营业总收入”、H1 累计与 Q2 单季、归母与
+  净利润、结构化扣非与媒体扣非分开标注；PE/PB/PS/PCF 并列，倍数分化时写“估值分化”。
+- **Specialist 调度收紧**：单次最多 8 个并发，使用 `Promise.allSettled`，按
+  `dataset_id + chart_source_ref` 记录成功并只重试失败项，禁止重发已成功图表。
+
+### Fixed
+
+- **MA20/10 日高窗口错误**：修复把 12 个交易日当 MA20、8 个交易日当 10 日高的问题；同类问题
+  在 data_junior 的派生统计与主 Agent 的结论复核中都会被协议拦下。
+- **成交量单位误写**：A 股 `history.volume` 原值为股，不再写成“万手”。
+- **H1/单季与扣非混用**：不再把媒体 H1 营业总收入与结构化 Q2 `operating_income` 放在同一增速
+  对比，也不在“扣非缺失”的同时引用媒体扣非。
+- **重复 K 线与错标题图**：`present_charts` 不再接受同 dataset/kind/标题的重复图，也不会把
+  “同花顺 300803”这类标题登记进交付卡片。
+- **Specialist 并发失败吞任务**：`Promise.all` 遇到并发上限错误时不再吞掉整批，失败任务可被
+  单独重试；已成功的 K 线不再被重复创建。
+
+## [2.9.2] - 2026-10-23
+
+`data_junior` 接入官方 PTC（`run_code`）：内层工具调用压进一段程序，多 Dataset 并发、`too_large`
+收窄与 skill 读取不再逐次往返模型。实机同类任务由 15 分钟级降到 2–3 分钟级；工具、数据契约、
+用户配置与宿主基线都不变。图表交付的收尾闸门同时修复结算通知竞争与同轮重复写入。
+
+### Added
+
+- **分析师的 PTC 执行面**：`data_junior` 只保留 `run_code` 直调，Dataset / skill / 出图委派 /
+  回传都通过 SDK `tools.*` 在程序内完成；不再挂 bash / pwsh，同时保住了“不读原始行”的边界。
+- **多 Dataset 并发与 `too_large` 自愈**：同一程序里可以 `Promise.all` 多份 `describe_dataset`；
+  结果过大时按 hint 收窄后继续，不再多开模型轮次。
+- **PTC 会话报告**：`npm run ptc:report` 汇总 `run_code` 段数、`Promise.all`、skill 打印、
+  `too_large` 与并发窗口，供实机验收。
+
+### Changed
+
+- **分析师提示词与三册协议同步 PTC 写法**：第一次加载协议就明确 skill 也要在 `run_code` 内用
+  `tools.skill`，不要直调原生工具；查询、profile 与可视化协议同步程序内调度。
+- **图表交付继续由收尾流写入**：`present_charts` 只记录清单，宿主在最终答复前统一落
+  `deliverables/presented`；结算通知不再阻塞收尾，且同一 exchange 不会重复写卡。
+
+### Fixed
+
+- **图表卡在结算通知竞争时丢失**：子 Agent 的 `subagent-settled` 通知在收尾流中途到达时，
+  不再被当成“还有待处理消息”；通知同时清掉已结算的直属子 Agent。
+- **同一轮重复交付**：后续 `finish` 帧缺少 `turn` 时不再写第二张卡。
+- **直调 skill 误调用**：软约束已把 `tools.skill` 提到第一次加载协议处；模型仍可能试错一次，
+  宿主拒绝后会自愈，不影响结果。
+
 ## [2.9.1] - 2026-10-21
 
 修复实机 `dsh web` 反馈的两处收尾体验：图表交付不再散落在等待轮，最终答复不再只剩一句

package/README.md

@@ -18,8 +18,9 @@
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a>
-  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.9.1-9cf" alt="Version"></a>
+  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.10.0-9cf" alt="Version"></a>
   <a href="https://www.npmjs.com/package/@v587d/capital-generation"><img src="https://img.shields.io/npm/v/%40v587d%2Fcapital-generation" alt="npm version"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered-by-dsh"></a>
 </p>
 
 # Capital Generation
@@ -114,11 +115,13 @@ https://github.com/v587d/capital-generation
 
 **每份结构化数据都会先做质检。** 无论你有没有提图表，自动模式收到行情或财务数据后都会先交给分析师检查结构、时间轴、缺失与基础统计；要不要图是检查之后的一个判断。明确说“不要图”时，质检照做，只是停在出图之前。
 
+自动模式会把子角色工作期间的中间回执留在同一轮里处理，等材料收齐后再给出完整结论，而不是每条中间进展都单独回一段。
+
 ## 试试这么用
 
 在新的自动模式会话中使用以下指令。将方括号内容换成自己的标的、公告或持仓；证券代码写完整市场后缀，例如 `600519.SH`。每条指令单独发送，便于观察结果。
 
-[样例：假期后研判报告（20261007）](docs/sample/假期后研判报告.md)
+[样例：指南针、同花顺复盘分析报告（20261023）](docs/sample/指南针-同花顺-复盘分析报告.md)
 
 **完整投资研究报告**
 
@@ -190,7 +193,7 @@ https://github.com/v587d/capital-generation
 - **安装后找不到模式？** 确认插件出现在「插件」→ 已安装列表；Web / CLI profile 安装后要重启该 profile，并在新会话选择模式。选择器里应看到自动模式、行情专家、资讯专员；分析师和绘图专员是自动模式的内部角色，不会出现在这里。
 - **配置在哪？** 打开「插件」→ 已安装的 **Capital Generation**，页面顶部就是「数据源 / 精选 Skills / 包含的组件」三格，五把密钥都在第一格；不在 DSH 的普通「设置」页面，也不用点进任何一行组件。保存密钥后新建会话再试。
 - **升级到 2.9.0 后，分析师和绘图专员去哪了？** 这一版把它们收进自动模式内部，不再出现在选择器与预设管理里，避免误开一个没有取数入口的空会话。旧会话仍能按原身份恢复；新任务直接用自动模式提出即可。
-- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.9.1` 或 `@2.9.1`。
+- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.10.0` 或 `@2.10.0`。
 - **刚发布的新版本装不到？** 桌面端取包时会跳过**刚发布不久**的版本（宿主侧包管理器的发布冷却策略，实测会静默装成上一个版本），国内镜像的同步也可能滞后一段时间。急着用最新代码，改用仓库地址安装最直接。
 - **网页抓取失败？** 配置卡片中的「允许启动本地提取网页内容」默认开启：AnySearch 提取失败时可尝试本机直连。关闭后，本机直连的具名来源查询也不可用；请检查该开关和网络连接。
 - **Wind 那部分会消耗积分？** 会。公告与新闻检索、宏观 / 行业 / 汇率指标、按日期区间取的历史 K 线都按次消耗你在 Wind 侧的额度；额度与条款以 Wind 为准，插件不做用量封顶。没配 `WIND_API_KEY` 时这几类不可用，其余功能照常。

package/chart-ui/README.md

@@ -90,9 +90,9 @@ route owner 自己负责，平台自己的 `/api` 与首页分别走 `connection
 
 ## 本轮呈现（官方交付通道）
 
-auto 模式下 `render_chart` 不再自动登记：主 Agent 在写最终答复前调用一次 `present_charts`，
-把本轮 `chart_ref` 汇总成一条**官方** `deliverables/presented` 事件写进"用户正在看的根会话"，
-把 `capital-analysis/charts/<chart_id>/chart.html` 登记为**收尾轮交付物**（单体载体仍在出图时
+auto 模式下 `render_chart` 不再自动登记：`present_charts` 只记录本轮图表，宿主在**收尾流结束、
+收尾消息落盘之前**写一条**官方** `deliverables/presented` 事件到"用户正在看的根会话"，把
+`capital-analysis/charts/<chart_id>/chart.html` 登记为**收尾轮交付物**（单体载体仍在出图时
 自动登记）：
 
 - 载荷只有官方契约字段：`turn` / `callId`（`capital-chart:<chart_id>` 句柄）/ `files[]`

package/chart-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/capital-charts",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "自动模式的图表前端组件（浏览器半边 + 序列旁路路由）：由 @v587d/capital-generation 随包携带并作为 host 平面行挂载。",
   "license": "MIT",
   "type": "module",

package/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/config",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "自动模式的取数凭据与偏好配置行：卡片坐在 @v587d/capital-generation 插件主页的「配置」段，点这一行本身没有表单。",
   "license": "MIT",
   "type": "module",

package/lib/agents/bash-guard.d.ts

@@ -1,13 +1,17 @@
-/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
- * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
- * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
- * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
- * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
+/** Execution guard for bash/pwsh/run_code: blocks only doomed sandbox escalation; command/program
+ * content is never inspected (the sandbox blocks writes, not reads/network). Delegated approvals
+ * are fixed to `never`, so escalation auto-rejects with a misleading "user rejected"; block early
+ * instead. Root escalation still uses ask; do not pin delegated sessions read-only
+ * (`store.writeContext` needs workspace-write). `tools.guard` is monotonic; pre-execute is a
+ * rewritable waterfall. */
 import { type GuardedExecution, type PolicyContext } from './root-tool-policy.js';
+/** Both shell names on every platform plus the PTC transport: the preset mounts one shell pair for
+ * the root and `run_code` for data_junior, so matching only the local platform kills the Windows gate. */
+export declare const EXECUTION_ESCALATION_TOOL_NAMES: readonly ["bash", "pwsh", "run_code"];
 export type BashGuardExecution = GuardedExecution;
 /** States that the rejection is the system's, not the user's, and gives the recovery path. */
 export declare const SHELL_ESCALATION_UNREACHABLE: string;
-/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`/`code`; unknown identity fails closed. */
 export declare function bashGuardReason(exec: BashGuardExecution | undefined): string | undefined;
 /** Installs on every Capital preset agent. Must listen on `ctx.root`: agent/created routes by
  * the agent object, so tagged standing-scope listeners never fire. Failures only warn. */

package/lib/agents/bash-guard.js

@@ -1,23 +1,26 @@
-/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
- * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
- * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
- * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
- * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
+/** Execution guard for bash/pwsh/run_code: blocks only doomed sandbox escalation; command/program
+ * content is never inspected (the sandbox blocks writes, not reads/network). Delegated approvals
+ * are fixed to `never`, so escalation auto-rejects with a misleading "user rejected"; block early
+ * instead. Root escalation still uses ask; do not pin delegated sessions read-only
+ * (`store.writeContext` needs workspace-write). `tools.guard` is monotonic; pre-execute is a
+ * rewritable waterfall. */
 import { agentSessionId, isCapitalPresetAgent, SHELL_TOOL_NAMES } from './root-tool-policy.js';
-/** Both names on every platform: the preset mounts a pair, so matching only the local platform kills the Windows gate. */
-const shellToolNames = new Set(SHELL_TOOL_NAMES);
+/** Both shell names on every platform plus the PTC transport: the preset mounts one shell pair for
+ * the root and `run_code` for data_junior, so matching only the local platform kills the Windows gate. */
+export const EXECUTION_ESCALATION_TOOL_NAMES = [...SHELL_TOOL_NAMES, 'run_code'];
+const executionToolNames = new Set(EXECUTION_ESCALATION_TOOL_NAMES);
 /** One listener set per root context: host policy and legacy call sites install once. */
 const installedRoots = new WeakSet();
 /** States that the rejection is the system's, not the user's, and gives the recovery path. */
-export const SHELL_ESCALATION_UNREACHABLE = 'shell 工具（bash / pwsh）的沙箱升级只有主 Agent 的会话能拿到用户审批：被委派的子会话拿不到'
+export const SHELL_ESCALATION_UNREACHABLE = '执行工具（bash / pwsh / run_code）的沙箱升级只有主 Agent 的会话能拿到用户审批：被委派的子会话拿不到'
     + '（框架把委派会话的审批策略固定为 never，不会去问用户），当前调用方也不是可确认的主 Agent 会话。'
     + '不要重试升级：缺数值用 describe_dataset / query_dataset，缺数据用 send_message 发 data_gap 回主 Agent。';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`/`code`; unknown identity fails closed. */
 export function bashGuardReason(exec) {
-    if (exec === undefined || typeof exec.name !== 'string' || !shellToolNames.has(exec.name))
+    if (exec === undefined || typeof exec.name !== 'string' || !executionToolNames.has(exec.name))
         return undefined;
     const args = isRecord(exec.arguments) ? exec.arguments : undefined;
     const escalated = args !== undefined && (args.sandbox_permissions !== undefined || args.justification !== undefined);
@@ -64,7 +67,7 @@ export function registerBashGuard(ctx) {
                     return;
                 const dispose = installAgentGuard(agent);
                 if (dispose === undefined) {
-                    ctx.logger?.warn('capital-generation: shell 闸门未生效（agent scope 上没有 tools.guard）：沙箱升级拦截只剩 persona 软约束');
+                    ctx.logger?.warn('capital-generation: 执行工具闸门未生效（agent scope 上没有 tools.guard）：沙箱升级拦截只剩 persona 软约束');
                     return;
                 }
                 const id = agentSessionId(agent);
@@ -72,7 +75,7 @@ export function registerBashGuard(ctx) {
                     guards.set(id, dispose);
             }
             catch (error) {
-                ctx.logger?.warn(`capital-generation: bash 闸门安装异常：${error instanceof Error ? error.message : String(error)}`);
+                ctx.logger?.warn(`capital-generation: 执行工具闸门安装异常：${error instanceof Error ? error.message : String(error)}`);
             }
         });
         const stopDisposed = listenCtx.on?.('agent/disposed', (payload) => {

package/lib/agents/root-tool-policy.js

@@ -47,6 +47,8 @@ export const ROOT_AGENT_DENIED_TOOLS = [
     'write',
     'edit',
 ];
+// ⛔ `run_code` belongs nowhere in this list: it is a reserved PTC transport name, so `restrict()`
+// throws on it. The root stays native; deployment-level `dsh-tools.mode` must not be set to ptc.
 export const CAPITAL_PRESET_ID = ROOT_PRESET_ID;
 export function isRootAgent(agent) {
     if (agent?.session === undefined)

package/lib/agents/settled-wake.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Removes redundant `subagent-settled` notices at the closing frame; otherwise the host loop opens
+ * another step after a complete answer and folds it. Only children with an admitted relay are
+ * dropped — a silent child may carry its only outcome in the notice.
+ * Rationale: docs/dev/chart-delivery-events.md §6.3.
+ */
+import type { SessionLike } from '../data-collector/store.js';
+export interface WakeMessageLike {
+    readonly id?: string;
+    readonly source?: {
+        readonly kind?: string;
+        readonly senderSessionId?: string;
+    };
+}
+interface InboxLike {
+    readonly nextTurn?: readonly unknown[];
+    readonly nextStep?: readonly unknown[];
+    remove?(messageId: string): boolean;
+}
+export interface WakeAgentLike {
+    readonly session?: SessionLike;
+    readonly inbox?: InboxLike;
+}
+export interface SettledWakeGuard {
+    /** `user/message` events: human resets the exchange, an admitted child relay marks that child. */
+    acceptUserMessage(session: SessionLike, source: {
+        kind?: string;
+        senderSessionId?: string;
+    }): void;
+    /** Terminal assistant-stream frame: the closing answer is being written. */
+    acceptClosing(agent: WakeAgentLike | undefined): void;
+    /** A notice inserted after the closing frame must not wake a new step. */
+    acceptInboxInserted(agent: WakeAgentLike | undefined, message: WakeMessageLike | undefined): void;
+    /** A fresh activation invalidates the previous exchange's relay marker. */
+    acceptSubagentStart(info: {
+        id?: string;
+    }): void;
+    /** Diagnostics/tests. */
+    closing(): boolean;
+    admitted(): readonly string[];
+}
+export declare function createSettledWakeGuard(): SettledWakeGuard;
+export {};

package/lib/agents/settled-wake.js

@@ -0,0 +1,81 @@
+function messageOf(value) {
+    return value !== null && typeof value === 'object' ? value : undefined;
+}
+export function createSettledWakeGuard() {
+    let rootSessionId;
+    let closing = false;
+    const admitted = new Set();
+    const owns = (session) => {
+        if (session?.id === undefined)
+            return false;
+        // A child's own user/message events must not clear the root's state.
+        if (session.header?.origin === 'subagent')
+            return false;
+        rootSessionId ??= session.id;
+        return session.id === rootSessionId;
+    };
+    const dropNotice = (agent, message) => {
+        const childId = message.source?.senderSessionId;
+        if (typeof childId !== 'string' || !admitted.has(childId))
+            return false;
+        if (agent?.inbox?.remove === undefined || typeof message.id !== 'string')
+            return false;
+        let removed = false;
+        try {
+            removed = agent.inbox.remove(message.id);
+        }
+        catch {
+            removed = false;
+        }
+        if (removed)
+            admitted.delete(childId);
+        return removed;
+    };
+    const dropPending = (agent) => {
+        if (agent?.inbox === undefined)
+            return;
+        for (const value of [...(agent.inbox.nextTurn ?? []), ...(agent.inbox.nextStep ?? [])]) {
+            const message = messageOf(value);
+            if (message?.source?.kind !== 'subagent-settled')
+                continue;
+            dropNotice(agent, message);
+        }
+    };
+    return {
+        acceptUserMessage(session, source) {
+            if (!owns(session))
+                return;
+            if (source.kind === 'user') {
+                admitted.clear();
+                closing = false;
+                return;
+            }
+            if (source.kind !== 'agent-message')
+                return;
+            if (typeof source.senderSessionId !== 'string' || source.senderSessionId.length === 0)
+                return;
+            admitted.add(source.senderSessionId);
+            // The answer that follows this relay is not the previous closing answer.
+            closing = false;
+        },
+        acceptClosing(agent) {
+            if (agent?.session !== undefined && !owns(agent.session))
+                return;
+            closing = true;
+            dropPending(agent);
+        },
+        acceptInboxInserted(agent, message) {
+            if (agent?.session !== undefined && !owns(agent.session))
+                return;
+            if (message?.source?.kind !== 'subagent-settled' || !closing)
+                return;
+            dropNotice(agent, message);
+        },
+        acceptSubagentStart(info) {
+            if (typeof info?.id === 'string' && info.id.length > 0)
+                admitted.delete(info.id);
+        },
+        closing: () => closing,
+        admitted: () => [...admitted],
+    };
+}

package/lib/agents/wait-for-agents.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Root-only `wait_for_agents`: hold one turn across child relays; returns on the first relay, on
+ * the tree settling, or after 30s. `waitForChildren` has no abort parameter; the slice races it.
+ * Host contract: docs/reference/dsh-surface-ledger.md L36.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export interface WaitInboxLike {
+    readonly nextTurn?: readonly unknown[];
+    readonly nextStep?: readonly unknown[];
+}
+export interface WaitAgentLike {
+    readonly session?: {
+        readonly id?: string;
+        readonly header?: {
+            readonly parentSession?: string;
+            readonly origin?: 'subagent';
+        };
+    };
+    readonly inbox?: WaitInboxLike;
+    readonly status?: 'idle' | 'running';
+}
+export interface WaitDescendantLike {
+    readonly kind?: string;
+    readonly id?: string;
+    readonly label?: string;
+    readonly activity?: string;
+}
+export interface WaitSubagentsLike {
+    waitForChildren(parent: WaitAgentLike): Promise<boolean>;
+    listDescendants?(rootSessionId: string, signal?: AbortSignal): Promise<readonly WaitDescendantLike[]>;
+}
+interface AgentsLike {
+    get?(id: string): {
+        readonly status?: 'idle' | 'running';
+    } | undefined;
+}
+interface EventContextLike {
+    on?(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+export interface WaitForAgentsOptions {
+    /** Bounded slice; the model cannot extend it. */
+    readonly waitSliceMs?: number;
+    readonly now?: () => number;
+}
+export interface WaitForAgentsDeps extends WaitForAgentsOptions {
+    subagents: () => WaitSubagentsLike | undefined;
+    events?: EventContextLike;
+    agents?: () => AgentsLike | undefined;
+}
+export type WaitForAgentsStatus = 'all_settled' | 'message' | 'user_input' | 'timeout';
+export interface WaitForAgentsReceipt {
+    readonly status: WaitForAgentsStatus;
+    readonly waited_ms: number;
+    readonly pending_messages: number;
+    readonly running: Array<{
+        readonly id: string;
+        readonly label?: string;
+    }>;
+    readonly hint: string;
+}
+declare function render(_args: unknown, value: unknown): Array<{
+    type: 'text';
+    text: string;
+}>;
+export declare function waitForAgentsToolDefinition(deps: WaitForAgentsDeps): {
+    name: string;
+    description: string;
+    parameters: object;
+    output: {
+        schema: object;
+        render: typeof render;
+    };
+    execute(_args: Record<string, unknown>, exec: {
+        signal: AbortSignal;
+        agent?: WaitAgentLike;
+    }): Promise<WaitForAgentsReceipt>;
+};
+export declare function registerWaitForAgentsTool(ctx: Context, options?: WaitForAgentsOptions): void;
+export {};