@qlzt/dsh-tool-subagent-control 0.0.0-stage → 0.2.1-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,106 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
+/:
+  en: 5413b8e52a0c8e3d
+  zh: 9b6d0385209ff9bb
+/deepseek-ai-dsh-tool-subagent-control:
+  en: 465d36925c792167
+  zh: 269cac314f638827
+/deepseek-ai-dsh-tool-subagent-control/summary:
+  en: 7464eb99b6f618eb
+  zh: 8c7628c8e9f163ca
+/deepseek-ai-dsh-tool-subagent-control/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-subagent-control/use-this-package:
+  en: 27c5bbe682f0b72b
+  zh: b16aeb2c43f3692e
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/minimal-configuration:
+  en: 4a52c81317ec9001
+  zh: ebd9f1ba920da50a
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/send-message:
+  en: d80bb1df2eb740b7
+  zh: e3203d9868a82910
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/interrupt-agent:
+  en: af01696cc8deaf83
+  zh: 86e40bc28d5362b1
+/deepseek-ai-dsh-tool-subagent-control/use-this-package/list-agents:
+  en: 631c0a34dadcb8f8
+  zh: dbc536512cae070f
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation:
+  en: c5cdf01a78c990f2
+  zh: 53c180d726ce4502
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/design-concept:
+  en: 0af7238c690ee8d6
+  zh: 5049eea23770ffed
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/delivery-and-signal-ownership:
+  en: 4c7698ccea49a60b
+  zh: fbf129ff583e6ab9
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/listing-projection:
+  en: 70e344022e6e535e
+  zh: 355488590648a82e
+/deepseek-ai-dsh-tool-subagent-control/understand-the-implementation/source-map:
+  en: 95f73146f8735ab1
+  zh: 9c67e064c4000613
+/deepseek-ai-dsh-tool-subagent-control/further-exploration:
+  en: df2bf39d0ffffd43
+  zh: 4cd02551f7433c90
+/deepseek-ai-dsh-tool-subagent-control/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/what-the-model-sees:
+  en: b32bc9bcb45a8c77
+  zh: 4bd3eba1e8612da7
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/token-effect:
+  en: db207dc8d5860684
+  zh: ad2663b4967fbca9
+/deepseek-ai-dsh-tool-subagent-control/model-experience/tool-schema/kv-cache-effect:
+  en: 4b77d42b96b3519d
+  zh: dd393d8f0f6536c1
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result:
+  en: d64e936e83e89a2b
+  zh: b9905c33af6cca45
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/what-the-model-sees:
+  en: 89305619897680ba
+  zh: e610a844fc09c53f
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/token-effect:
+  en: 5d1bcef28b5f18da
+  zh: 027d67d93d660e76
+/deepseek-ai-dsh-tool-subagent-control/model-experience/interrupt-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result:
+  en: ab964e307bd37dca
+  zh: 03f975252f838a42
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/what-the-model-sees:
+  en: 4a0a4955589012ae
+  zh: 2bbbb5196a8aa4fd
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/token-effect:
+  en: 0f134e37e4bd9965
+  zh: ceb858d01266e976
+/deepseek-ai-dsh-tool-subagent-control/model-experience/delivery-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result:
+  en: 094e55d258f2ec2e
+  zh: f364bc9046530bff
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/what-the-model-sees:
+  en: efbbd1e36c7b2edd
+  zh: a8a95475666ed1dc
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/token-effect:
+  en: 4688e849b3143dfc
+  zh: f22b5520c454f9e7
+/deepseek-ai-dsh-tool-subagent-control/model-experience/listing-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/deepseek-ai-dsh-tool-subagent-control/known-limitations-and-deferred-work:
+  en: 31cd8a1934cf0093
+  zh: 2fd07e05c8e58e9a
+/deepseek-ai-dsh-tool-subagent-control/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+---
+description: "Global send_message, interrupt_agent, and list_agents tools for users and maintainers composing or debugging continuable-child control."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-tool-subagent-control
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-tool-subagent-control` adds the global control tools for continuable children: `send_message` steers between a direct parent and child, `interrupt_agent` stops a child's current turn while keeping its inbox and descendants intact, and `list_agents` (from the separately loadable `list-agents` plugin) lists continuable children by durable id and label. Parents and continuable children inherit the same `send_message` definition and ordering, so model communication adds no child-only tool schema. No tool's presence decides whether a delegation tool starts continuable work.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this package in any composition with continuable children the model should message, interrupt, or list. The root plugin needs only the subagent service; the list tool is a separate plugin a deployment can omit.
+
+### Minimal configuration
+
+Load the subagent service, a backend, the delegation tool, and this package. Adding the separate list plugin exposes all three tools:
+
+```yaml
+- name: '@deepseek-ai/dsh-subagent'
+- name: '@deepseek-ai/dsh-subagent-spawn-in-process'
+- name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+- name: '@deepseek-ai/dsh-tool-subagent-control'
+- name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+```
+
+This package takes no configuration: the root plugin provides `send_message` and `interrupt_agent`, and the list plugin provides `list_agents`.
+
+### send_message
+
+Sends a message to an Agent named by `agent_id`: any exact live Agent may target its direct continuable child, while a resident continuable child may also target its direct parent. A working target receives the message at its nearest step boundary through Steer; an inactive target starts or resumes a turn through the continuation lifecycle. The call returns only acceptance (the accepted message's stable `messageId`), never a reply. A failure — an unsupported target, unavailable parent, unknown child, descriptor-less child that cannot be resumed, or rejected admission — states the message was not delivered.
+
+### interrupt_agent
+
+External executions stop permanently and cannot receive follow-ups. Local targets stop only their current turn: queued messages stay parked until a later `send_message`, descendants keep running, and the child stays available for follow-ups. The call returns when the stop request is accepted, not when the target is quiet; interrupting an already-finished agent is an accepted no-op, and self, sibling, stale, and non-ancestor callers get errored results.
+
+### list_agents
+
+Lists the continuable children below the calling agent: `children` (default) reads direct children from the parent catalog without opening child logs; `descendants` recursively reads child catalogs in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running` or `inactive`. External entries are omitted without reading a child Session. Readable one-shot children are omitted from output but their catalogs remain traversal nodes. Unknown modes and unreadable child catalogs, including one-shot children, appear as diagnostics only in `descendants` scope. Ordinary Session forks are not catalog entries, so neither those forks nor their descendants are listed from the source Session.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains what the tools delegate to the subagent service; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+Thin adapters over `ctx.subagents.sendMessage()`, `interrupt()`, and the list projections; the tools perform no lifecycle routing. Residency, cold resume, and authorization belong to the service, and the tools pass the exact live calling agent (`exec.agent`) as both sender and authority.
+
+### Delivery and signal ownership
+
+The tool forwards its execution signal, which owns admission only until inbox acceptance. Once the target accepts a message, it cannot be cancelled through this tool. Every message is framed as `Agent <sender-id> sent a message:` and recorded with `{ kind: 'agent-message', form: 'relay', senderSessionId: sender.id }`; the service derives that attribution and never treats it as authority.
+
+### Listing projection
+
+`list_agents` derives the root id from the calling agent, reads the service catalog without a cursor, refines each candidate's status through the live Agent registry, and omits one-shot children because they cannot accept `send_message`. Descendant traversal preserves each parent catalog's event order. Unknown modes produce diagnostics while their catalogs remain traversable; unreadable catalogs produce diagnostics and stop that branch. Descendants absent from reachable catalogs cannot be discovered.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `send_message` and `interrupt_agent` registration |
+| [`src/list-agents.ts`](src/list-agents.ts) | `list_agents` registration: direct-child discovery and status refinement |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough; they move from the tool schemas to the continuation service behind them.
+
+- [Subagent subsystem](../../../docs/subsystems/subagent.md) — continuable children, activations, inbox, interrupt, and follow-up authority.
+- [dsh-tool-subagent](../tool-subagent/README.md) — the delegation tool that starts continuable children.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control) — the three tool schemas.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `send_message` takes `agent_id` and `message`; `interrupt_agent` takes `agent_id`; `list_agents` takes no parameters.
+
+#### Token effect
+
+Fixed schema cost per parent request.
+
+#### KV Cache effect
+
+Prefix-stable; the schema does not change at runtime.
+
+### Interrupt result
+
+#### What the model sees
+
+`interrupt requested for agent <agent_id>` on acceptance. An unauthorized caller — self, sibling, stale, or non-ancestor — is an errored result naming the rejection; an absent or settled target still renders the acceptance line.
+
+#### Token effect
+
+One short acknowledgement per call; the interrupted turn's abort is visible only in the child's own transcript.
+
+#### KV Cache effect
+
+Append-only; each result follows the reusable request prefix.
+
+### Delivery result
+
+#### What the model sees
+
+`message delivered to agent <agent_id>` on acceptance; the canonical output carries the accepted `messageId`. A failure — a non-adjacent target, unavailable parent, unknown child, descriptor-less child that cannot be resumed, or admission rejected — is an errored result whose message states the message was not delivered.
+
+#### Token effect
+
+One short acknowledgement per call; the target's response never returns through this call. A child uses the same tool with its initial task's parent id to append selected content to parent history.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Listing result
+
+#### What the model sees
+
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = executing a turn; `inactive` = no turn executing, whether loaded or stored; neither status describes task completion or outcome). Only `descendants` scope adds `<id> [diagnostic: <reason>]` for an unknown mode or unreadable child catalog, including an unreadable one-shot child. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. Readable one-shot children are omitted; `(no subagents)` means no continuable child or diagnostic survived the projection.
+
+#### Token effect
+
+Grows linearly with the listed continuable children and diagnostics — reachable catalog descendants under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
+
+#### KV Cache effect
+
+Append-only; each result follows the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the control tools cannot observe or steer; they are current package constraints.
+
+- **A delivered message has no independent result** — acceptance returns only its inbox `messageId`; later target work lands in that target's durable Session and is never collected through this tool. A reply is another explicitly addressed `send_message`, not this call's result.
+- **Only supported adjacent Agents can communicate** — every sender may target a direct continuable child, only a sender with a resident continuable Activation may target its direct parent, and that parent must remain live; siblings and deeper descendants are not message targets, and only direct-child delivery supports cold activation.
+- **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `inactive`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
+- **No pagination or deletion** — the complete stably ordered set is returned, and persisted children remain listed for as long as their sessions remain in persistence; a service-level bound or delete operation is a later product decision.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,181 @@
+---
+description: "供用户与维护者在组合或调试可继续子级控制功能时使用的全局 send_message、interrupt_agent 与 list_agents 工具。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-subagent-control
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-tool-subagent-control` 为可继续子级添加全局控制工具：`send_message` 在直接父级与子级之间进行 steering（中途引导），`interrupt_agent` 停止子级当前轮次但保留其收件箱与后代，`list_agents`（来自可单独加载的 `list-agents` 插件）按持久化 ID 与标签列出可继续子级。父级与可继续子级继承相同的 `send_message` 定义和顺序，因此模型通信不会增加子级专属工具 schema。是否加载这些工具不会决定委派工具是否启动可继续工作。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在模型需要对可继续子级发消息、中断或列出的任何组合中挂载本包。根插件只需要 subagent 服务；列表工具是独立插件，部署方可以省略。
+
+### 最小配置
+
+先加载 subagent 服务、一个后端、委派工具与本包。加上独立的列表插件即可公开全部三个工具：
+
+```yaml
+- name: '@deepseek-ai/dsh-subagent'
+- name: '@deepseek-ai/dsh-subagent-spawn-in-process'
+- name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+- name: '@deepseek-ai/dsh-tool-subagent-control'
+- name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+```
+
+本包不接收任何配置：根插件提供 `send_message` 与 `interrupt_agent`，列表插件提供 `list_agents`。
+
+### send_message
+
+向 `agent_id` 指定的 Agent 发送消息：任何确切在线 Agent 都可以向自己的直接可继续子级发送消息，驻留的可继续子级还可以向自己的直接父级发送消息。正在工作的目标通过 Steer 在最近的步骤边界接收消息；非活跃目标会通过继续执行生命周期启动或恢复一个轮次。调用只返回接受结果（被接受消息的稳定 `messageId`），绝不返回回复。失败——不受支持的目标、不可用的父级、未知子级、缺少描述符而无法恢复的子级，或准入被拒——会明确说明消息未送达。
+
+### interrupt_agent
+
+外部执行会永久停止，不能接收后续消息。本地目标只停止当前轮次：已排队消息保持暂停，直到之后调用 `send_message`；后代继续运行，子级仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；中断已结束的 agent 会被接受并按空操作处理，而自身、同级、陈旧及非祖先调用方会收到出错结果。
+
+### list_agents
+
+列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序递归读取子级目录，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。外部条目被省略，不读取子 Session。可读取的一次性子级不出现在输出中，但其目录仍是遍历节点。未知模式与无法读取的子级目录（包括一次性子级）仅在 `descendants` 作用域中以诊断信息呈现。普通 Session fork 不是目录条目，因此从源 Session 列表中既无法发现这些 fork，也无法发现其后代。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释工具把什么委托给 subagent 服务；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+`ctx.subagents.sendMessage()`、`interrupt()` 与列表投影之上的轻量适配器；工具不执行任何生命周期路由。驻留、冷恢复与授权归服务所有，工具把确切在线的调用 Agent（`exec.agent`）同时作为 sender 与权限凭据传入。
+
+### 投递与信号所有权
+
+工具转发其执行信号，该信号只在 inbox 接受之前掌管准入。目标一旦接受消息，该消息便无法再通过本工具取消。每条消息都以 `Agent <sender-id> sent a message:` 作为前缀，并记录 `{ kind: 'agent-message', form: 'relay', senderSessionId: sender.id }`；该来源信息由服务推导，且绝不被视为权限。
+
+### 列表投影
+
+`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。后代遍历保留每个父目录的事件顺序。未知模式产生诊断，但其目录仍可遍历；无法读取的目录产生诊断，并停止该分支。可达目录中不存在的后代无法被发现。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `send_message` 与 `interrupt_agent` 注册 |
+| [`src/list-agents.ts`](src/list-agents.ts) | `list_agents` 注册：直接子级发现与状态细化 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面；它们从工具 schema 进入其背后的继续执行服务。
+
+- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——可继续子级、Activation、inbox、中断与后续消息权限。
+- [dsh-tool-subagent](../tool-subagent/README.zh.md)——启动可继续子级的委派工具。
+- [生成工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-subagent-control)——三个工具的 schema。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+已生成的 [schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-subagent-control)：`send_message` 接受 `agent_id` 与 `message`；`interrupt_agent` 接受 `agent_id`；`list_agents` 不接受参数。
+
+#### Token 影响
+
+每个父级请求支付固定的 schema 成本。
+
+#### KV Cache 影响
+
+前缀保持稳定；schema 不会在运行时改变。
+
+### 中断结果
+
+#### 模型看到什么
+
+接受时返回 `interrupt requested for agent <agent_id>`。未授权的调用方——self、sibling、陈旧或非 ancestor——会成为指明拒绝原因的出错结果；目标不存在或已结算仍渲染接受行。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；被中断轮次的中止只在子级自己的 transcript（文本记录）中可见。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
+### 投递结果
+
+#### 模型看到什么
+
+接受时返回 `message delivered to agent <agent_id>`；规范输出携带被接受的 `messageId`。失败——非相邻目标、不可用的父级、未知子级、缺少描述符而无法恢复的子级，或准入被拒——会成为出错的结果，其消息说明该消息未送达。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；目标的响应绝不会通过本次调用返回。子级使用同一个工具，并传入其初始任务中的父级 ID，将选定内容追加到父级历史中。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 列表结果
+
+#### 模型看到什么
+
+按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为未知模式或无法读取的子级目录添加 `<id> [diagnostic: <reason>]`，包括无法读取的一次性子级。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。可读取的一次性子级会被省略；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
+
+#### Token 影响
+
+随所列可继续子级和诊断数量线性增长——`descendants` 作用域下为目录可达后代；没有游标或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明控制工具无法观察或引导什么；它们是当前包约束。
+
+- **已投递消息没有独立结果**——接受时只返回其 inbox `messageId`；目标后续工作会落入该目标的持久化会话，绝不会通过本工具收集。回复是另一条显式指定地址的 `send_message`，而非本次调用的结果。
+- **只有受支持的相邻 Agent 可以通信**——每个发送方都可以向直接可继续子级发送消息；只有具备驻留可继续 Activation 的发送方可以向自己的直接父级发送消息，且该父级必须仍在线；同级与更深的后代不能作为消息目标，只有向直接子级投递才支持冷激活。
+- **列表是快照，而非投递承诺**——它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `inactive` 的子级；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
+- **没有分页或删除**——系统返回完整且稳定排序的集合；只要子级会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,95 @@
+import { brandString } from "@qlzt/dsh-brand";
+import { defineTool } from "@qlzt/dsh-tools";
+import { markAdjacentAgentSendMessageTool } from "@qlzt/dsh-subagent/internal";
+//#region lib/types/index.js
+/**
+* The globally named `send_message` and `interrupt_agent` tools: thin
+* model-facing adapters over `ctx.subagents.sendMessage()` and
+* `ctx.subagents.interrupt()`. They perform no lifecycle routing of their own —
+* residency, cold resume, and interrupt authorization belong to the subagent
+* service — and they live apart from the provider-bound
+* `@qlzt/dsh-tool-subagent` instances so multiple delegation tools share
+* one control API.
+* @module @qlzt/dsh-tool-subagent-control
+*/
+const name = "tool-subagent-control";
+const inject = ["tools", "subagents"];
+/**
+* Register the `send_message` and `interrupt_agent` tools.
+* @param ctx - context carrying the tool registry and subagent service.
+*/
+function apply(ctx) {
+	ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
+		name: "send_message",
+		description: "Send a message to an agent. A working agent receives it at its next step; an idle agent starts a new turn with it. Returns delivery confirmation, not the agent's answer.",
+		parameters: {
+			agent_id: {
+				type: "string",
+				required: true,
+				description: "The agent id of your direct continuable child, or your direct parent when you are a resident continuable child."
+			},
+			message: {
+				type: "string",
+				required: true,
+				description: "The message to deliver to the agent."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { messageId: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (args, _value) => [{
+				type: "text",
+				text: `message delivered to agent ${args.agent_id}`
+			}]
+		},
+		async execute(args, exec) {
+			const sender = exec.agent;
+			if (!sender) throw new Error("send_message requires a calling agent (exec.agent was undefined)");
+			const message = [{
+				type: "text",
+				text: args.message
+			}];
+			return { messageId: await ctx.subagents.sendMessage(sender, brandString(args.agent_id), message, { signal: exec.signal }) };
+		}
+	})));
+	ctx.tools.register(defineTool({
+		name: "interrupt_agent",
+		description: "Ask a subagent to stop its current work. This call returns without waiting for it to stop. You can continue a local direct child's conversation later with send_message. External executions stop permanently and cannot receive follow-ups. Subagents it started will keep running.",
+		parameters: { agent_id: {
+			type: "string",
+			required: true,
+			description: "The id of an agent created under you: your direct child or a deeper descendant."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { accepted: {
+					type: "boolean",
+					required: true
+				} }
+			},
+			render: (args, _value) => [{
+				type: "text",
+				text: `interrupt requested for agent ${args.agent_id}`
+			}]
+		},
+		execute(args, exec) {
+			const caller = exec.agent;
+			if (!caller) throw new Error("interrupt_agent requires a calling agent (exec.agent was undefined)");
+			ctx.subagents.interrupt(brandString(args.agent_id), {
+				kind: "ancestor",
+				agent: caller
+			});
+			return Promise.resolve({ accepted: true });
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The globally named `send_message` and `interrupt_agent` tools: thin
+ * model-facing adapters over `ctx.subagents.sendMessage()` and
+ * `ctx.subagents.interrupt()`. They perform no lifecycle routing of their own —
+ * residency, cold resume, and interrupt authorization belong to the subagent
+ * service — and they live apart from the provider-bound
+ * `@qlzt/dsh-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @qlzt/dsh-tool-subagent-control
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "tool-subagent-control";
+export declare const inject: string[];
+/**
+ * Register the `send_message` and `interrupt_agent` tools.
+ * @param ctx - context carrying the tool registry and subagent service.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,98 @@
+/**
+ * The globally named `send_message` and `interrupt_agent` tools: thin
+ * model-facing adapters over `ctx.subagents.sendMessage()` and
+ * `ctx.subagents.interrupt()`. They perform no lifecycle routing of their own —
+ * residency, cold resume, and interrupt authorization belong to the subagent
+ * service — and they live apart from the provider-bound
+ * `@qlzt/dsh-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @qlzt/dsh-tool-subagent-control
+ */
+import { brandString } from '@qlzt/dsh-brand';
+import { defineTool } from '@qlzt/dsh-tools';
+import { markAdjacentAgentSendMessageTool } from '@qlzt/dsh-subagent/internal';
+export const name = 'tool-subagent-control';
+export const inject = ['tools', 'subagents'];
+/**
+ * Register the `send_message` and `interrupt_agent` tools.
+ * @param ctx - context carrying the tool registry and subagent service.
+ */
+export function apply(ctx) {
+    ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
+        name: 'send_message',
+        description: 'Send a message to an agent. A working agent receives it at its next step; an idle agent starts a new turn with it. '
+            + 'Returns delivery confirmation, not the agent\'s answer.',
+        parameters: {
+            agent_id: {
+                type: 'string',
+                required: true,
+                description: 'The agent id of your direct continuable child, or your direct parent when you are a resident continuable child.',
+            },
+            message: {
+                type: 'string',
+                required: true,
+                description: 'The message to deliver to the agent.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    messageId: { type: 'string', required: true },
+                },
+            },
+            render: (args, _value) => [{
+                    type: 'text',
+                    text: `message delivered to agent ${args.agent_id}`,
+                }],
+        },
+        async execute(args, exec) {
+            const sender = exec.agent;
+            if (!sender) {
+                throw new Error('send_message requires a calling agent (exec.agent was undefined)');
+            }
+            const message = [{ type: 'text', text: args.message }];
+            const messageId = await ctx.subagents.sendMessage(sender, brandString(args.agent_id), message, { signal: exec.signal });
+            return { messageId };
+        },
+    })));
+    ctx.tools.register(defineTool({
+        name: 'interrupt_agent',
+        description: 'Ask a subagent to stop its current work. This call returns without waiting for it to stop. '
+            + 'You can continue a local direct child\'s conversation later with send_message. '
+            + 'External executions stop permanently and cannot receive follow-ups. Subagents it started will keep running.',
+        parameters: {
+            agent_id: {
+                type: 'string',
+                required: true,
+                description: 'The id of an agent created under you: your direct child or a deeper descendant.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    accepted: { type: 'boolean', required: true },
+                },
+            },
+            render: (args, _value) => [{
+                    type: 'text',
+                    text: `interrupt requested for agent ${args.agent_id}`,
+                }],
+        },
+        execute(args, exec) {
+            const caller = exec.agent;
+            if (!caller) {
+                // Ancestor authority requires an exact live calling agent.
+                throw new Error('interrupt_agent requires a calling agent (exec.agent was undefined)');
+            }
+            // The service authorizes the exact live caller against the target's
+            // recorded lineage; the tool adds no authority of its own.
+            ctx.subagents.interrupt(brandString(args.agent_id), { kind: 'ancestor', agent: caller });
+            return Promise.resolve({ accepted: true });
+        },
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/list-agents.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The globally named `list_agents` tool: a thin model-facing adapter over
+ * the continuable projection of `ctx.subagents.listChildren()` and, for the
+ * `descendants` scope, `ctx.subagents.listDescendants()`. It stays separately
+ * loadable from the root `send_message` plugin so a deployment can register
+ * continuation delivery without exposing discovery.
+ * @module @qlzt/dsh-tool-subagent-control/list-agents
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "tool-subagent-list-agents";
+export declare const inject: string[];
+/**
+ * Register the `list_agents` tool.
+ * @param ctx - context carrying the tool registry, subagent service, and live Agent registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=list-agents.d.ts.map

package/lib/types/list-agents.js

@@ -0,0 +1,136 @@
+/**
+ * The globally named `list_agents` tool: a thin model-facing adapter over
+ * the continuable projection of `ctx.subagents.listChildren()` and, for the
+ * `descendants` scope, `ctx.subagents.listDescendants()`. It stays separately
+ * loadable from the root `send_message` plugin so a deployment can register
+ * continuation delivery without exposing discovery.
+ * @module @qlzt/dsh-tool-subagent-control/list-agents
+ */
+import { defineTool } from '@qlzt/dsh-tools';
+import { assertNever } from '@qlzt/dsh-util-values';
+export const name = 'tool-subagent-list-agents';
+export const inject = ['tools', 'subagents', 'agents'];
+/** Resolve the optional model request into an internal required-scope spec. */
+function resolveListAgentsRequest(request) {
+    return { scope: request.scope ?? 'children' };
+}
+/** Report turn activity without exposing whether the child is loaded. */
+function statusOf(agents, id) {
+    return agents.get(id)?.status === 'running' ? 'running' : 'inactive';
+}
+/** Project one service row into the model-facing entry, or omit a one-shot child. */
+function project(agents, entry, position) {
+    const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth };
+    if ('kind' in entry && entry.kind === 'diagnostic') {
+        return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at };
+    }
+    // One-shot children cannot be continued by send_message, so the model
+    // never selects them; discovery still traversed them for descendants.
+    if (entry.mode !== 'continuable')
+        return undefined;
+    return {
+        kind: 'child',
+        id: entry.id,
+        label: entry.label,
+        status: statusOf(agents, entry.id),
+        ...at,
+    };
+}
+/**
+ * Register the `list_agents` tool.
+ * @param ctx - context carrying the tool registry, subagent service, and live Agent registry.
+ */
+export function apply(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'list_agents',
+        description: 'List subagents you started, with their ids, labels, and status. '
+            + 'running means it is working; inactive means it is not currently working. '
+            + 'You will be notified when a subagent finishes; there is no need to keep checking its status. '
+            + 'Use send_message to continue the conversation.',
+        parameters: {
+            scope: {
+                type: 'string',
+                enum: ['children', 'descendants'],
+                description: 'children (default) lists direct children, which accept send_message in any status. '
+                    + 'descendants lists the whole tree below you with each entry\'s parent session id and depth; entries deeper than 1 accept only interrupt_agent.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'array',
+                items: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                kind: { type: 'string', required: true, enum: ['child'] },
+                                id: { type: 'string', required: true },
+                                label: { type: 'string', required: true },
+                                status: { type: 'string', required: true, enum: ['running', 'inactive'] },
+                                parent: { type: 'string' },
+                                depth: { type: 'number' },
+                            },
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                kind: { type: 'string', required: true, enum: ['diagnostic'] },
+                                id: { type: 'string', required: true },
+                                reason: { type: 'string', required: true, enum: ['corrupt', 'unsupported', 'unavailable'] },
+                                parent: { type: 'string' },
+                                depth: { type: 'number' },
+                            },
+                        },
+                    ],
+                },
+            },
+            render: (args, entries) => {
+                const request = resolveListAgentsRequest(args);
+                return [{
+                        type: 'text',
+                        text: entries.length === 0
+                            ? '(no subagents)'
+                            : entries.map((entry) => {
+                                // A descendants row always carries its position; children rows
+                                // never render it. String() spans the schema-optional shape
+                                // without a dead fallback branch.
+                                const at = request.scope === 'descendants'
+                                    ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
+                                    : '';
+                                return entry.kind === 'child'
+                                    ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
+                                    : `${entry.id} [diagnostic: ${entry.reason}]${at}`;
+                            }).join('\n'),
+                    }];
+            },
+        },
+        async execute(args, exec) {
+            const parent = exec.agent;
+            if (!parent) {
+                // Non-agent callers have no session whose children could be listed.
+                throw new Error('list_agents requires a calling agent (exec.agent was undefined)');
+            }
+            const request = resolveListAgentsRequest(args);
+            switch (request.scope) {
+                case 'children': {
+                    const entries = await ctx.subagents.listChildren(parent.id, exec.signal);
+                    return entries
+                        .map(entry => project(ctx.agents, entry))
+                        .filter(entry => entry !== undefined);
+                }
+                case 'descendants': {
+                    const entries = await ctx.subagents.listDescendants(parent.id, exec.signal);
+                    return entries
+                        .map(entry => project(ctx.agents, entry, entry))
+                        .filter(entry => entry !== undefined);
+                }
+                /* v8 ignore next 2 -- the resolver normalizes the schema-validated closed scope before dispatch. */
+                default:
+                    return assertNever(request.scope, 'list_agents scope');
+            }
+        },
+    }));
+}
+//# sourceMappingURL=list-agents.js.map

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@qlzt/dsh-tool-subagent-control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zsping1989/deepseek-harness.git",
+    "directory": "packages/subagent/tool-subagent-control"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./list-agents": {
+      "types": "./lib/types/list-agents.d.ts",
+      "default": "./lib/types/list-agents.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@qlzt/dsh-llm": "0.2.1-alpha.3",
+    "@qlzt/dsh-session": "0.2.1-alpha.3",
+    "@qlzt/dsh-subagent": "0.2.1-alpha.3",
+    "@qlzt/dsh-tools": "0.2.1-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-query": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subagent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subagent-fork-in-process": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3"
+  },
+  "dependencies": {
+    "@qlzt/dsh-brand": "0.2.1-alpha.3",
+    "@qlzt/dsh-util-values": "0.2.1-alpha.3"
+  },
+  "dsh": {}
+}