dsh-subagent-control 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.0.2
+
+- New optional `extras` component (`dsh-subagent-control/extras`), shipped **disabled**:
+  `relay_subagent_message`, `wait_subagents`, `drain_subagents`, `subagent_budget`.
+- The default install is unchanged: still exactly the three original tools while extras stays off.
+- New companion bundle `dsh-team-limits`, published separately, for raising the Agent Team
+  member/task/message limits by overriding the `agent-team` row.
+
+## 1.0.1
+
+- Documentation: bilingual README (English + 简体中文) with usage examples, the
+  security model, and the name-collision note.
+- Release: publishing now runs on GitHub Actions with npm trusted publishing
+  (OIDC) and provenance. No npm token is stored in the repository.
+- No runtime change: the three tools and their JSON Schemas are identical to
+  1.0.0.
+
 ## 1.0.0
 
 First release.

package/README.md

@@ -1,5 +1,7 @@
 # dsh-subagent-control
 
+**English** · [简体中文](#简体中文)
+
 Three tools that let any DSH agent — **including a team member** — list, steer and stop the subagents it started.
 
 `list_subagents` · `send_subagent_message` · `interrupt_subagent`
@@ -10,112 +12,184 @@ Three tools that let any DSH agent — **including a team member** — list, ste
 
 ### The problem
 
-The Harness ships `list_agents`, `send_message` and `interrupt_agent`. When the Agent Team bundle is active it registers tools with **those same three names** in every team member's exact Agent scope, and the more specific registration wins. Inside a teammate scope the team versions take over: they resolve `target` against the team roster only, and interrupting is a Lead-only operation.
+The Harness ships `list_agents`, `send_message` and `interrupt_agent`. When the Agent Team bundle is active, it registers tools with **those same three names** in every team member's exact Agent scope, and the more specific registration wins. Inside a teammate scope the team versions take over: they resolve `target` against the team roster only, and interrupting is a Lead-only operation.
 
-The result: a teammate can start a subagent with `subagent`, but cannot list it, follow up with it, or stop it — even though `ctx.subagents` (the subagent service) has supported all three for any live agent all along, and the authority rules already allow an ancestor to manage its own descendants.
+The result: a teammate can start a subagent with `subagent`, but cannot list it, follow up with it, or stop it — even though the subagent service (`ctx.subagents`) has supported all three for any live agent all along, and its authority rules already allow an ancestor to manage its own descendants.
 
-This bundle does not fight over the taken names. It registers three **new** names, globally, so the Lead and every teammate get them at once. Authority is still enforced by the service: a caller can message its own direct children and interrupt its own descendants.
+This bundle does not fight over the taken names. It registers three **new** names, globally, so the Lead and every teammate get them at once.
 
 ### Tools
 
-| Tool | Parameters | Calls |
+| Tool | Parameters | Underlying call |
 | --- | --- | --- |
 | `list_subagents` | `scope?`: `"children"` \| `"descendants"` (default `children`) | `ctx.subagents.listChildren()` / `listDescendants()` |
 | `send_subagent_message` | `subagent_id`, `message` (both required) | `ctx.subagents.sendMessage()` |
 | `interrupt_subagent` | `subagent_id` (required) | `ctx.subagents.interrupt()` with ancestor authority |
 
-`list_subagents` returns one line per subagent: `id  status  "label"  depth=`. `status` is `running` or `inactive` — `inactive` means no turn is executing, not that the subagent is gone.
+### Usage
+
+```
+list_subagents
+→ 3b0f9c1e  running  "review the patch"  depth=1
+
+list_subagents scope=descendants
+→ 3b0f9c1e  running  "review the patch"  depth=1
+  7d2a44b0  inactive "check the tests"    depth=2
+
+send_subagent_message subagent_id=3b0f9c1e message="also look at locale/zh.json"
+→ messageId=...
+
+interrupt_subagent subagent_id=3b0f9c1e
+→ accepted=true
+```
+
+Each listing line is `id  status  "label"  depth=`. `status` is `running` or `inactive` — **inactive means no turn is executing, not that the subagent is gone**. Use `send_subagent_message` to wake it.
 
 ### Behaviour and limits
 
-- One-shot subagents are not listed. They cannot accept a follow-up message, so showing them would only invite a call that is guaranteed to fail.
-- A child whose record cannot be read comes back as a diagnostic entry (`corrupt` / `unsupported` / `unavailable`) instead of turning the whole listing into an error.
-- `send_subagent_message` reaches a direct child only. This is the service's rule, not an extra restriction here.
-- `interrupt_subagent` reaches the caller's descendants, so a team Lead can also stop a grandchild.
-- Every failure is a normal error result that names the cause: no calling agent, unknown id, or an id that is not yours.
+- **One-shot subagents are hidden.** They cannot accept a follow-up message, so listing them would only invite a call that is guaranteed to fail.
+- **A broken record is reported, not thrown.** A child whose state cannot be read comes back as a diagnostic entry (`corrupt` / `unsupported` / `unavailable`) instead of turning the whole listing into an error.
+- **`send_subagent_message` reaches direct children only.** That is the service's own rule; the plugin does not widen it.
+- **`interrupt_subagent` reaches descendants**, so a team Lead can also stop a grandchild.
+- **Every failure names its cause**: no calling agent, unknown id, or an id that is not yours.
+- **No config, no storage.** The bundle writes nothing and reads nothing outside the three services.
 
 ### Install
 
-Through the plugin manager / market, or by asking the agent:
+Through the plugin panel / market, or by asking the agent:
 
 ```
 plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
 ```
 
-From a checkout, pass the directory path instead of the npm spec. The bundle applies immediately — no restart. Verify the three tool names appear and the plugin row is enabled.
+From a checkout, pass the **directory path** instead of the npm spec. The bundle applies immediately — no restart needed. Afterwards the three tool names are visible and the plugin row is enabled.
 
 ### Compatibility
 
 - DSH with the `tools`, `subagents` and `agents` services (0.2.x and later).
 - Node `^22.19.0 || >=24.0.0`.
-- No runtime dependencies, no peer dependencies: the module imports nothing. A plain tool table with explicit JSON Schemas installs the same way from npm or from a linked checkout.
+- **Zero dependencies** — no runtime dependency, no peer dependency, not a single `import`. The tools are plain tool-table objects with explicit JSON Schemas, so they install and behave identically from npm or from a linked checkout.
+
+### Name collisions
 
-### Known name conflict
+`dsh-subagent-library` also registers a global `list_subagents` tool. Two global registrations of one name cannot both win: install one of them, or remember that the other may shadow this one.
 
-`dsh-subagent-library` also registers a global `list_subagents` tool. Two global registrations of one name cannot both win — install one of them, or remember that the other may shadow this one.
+The three new names were chosen precisely because they do **not** collide with the built-in `list_agents` / `send_message` / `interrupt_agent`.
 
 ### Uninstall
 
-Remove or disable the bundle in the plugin panel. Nothing else is written: no config, no storage.
+Remove or disable the bundle in the plugin panel. Nothing is left behind.
+
+### Optional extras (off by default)
+
+The package also ships a second, **disabled-by-default** row: `subagent-control-extras`
+(`dsh-subagent-control/extras`). Nothing changes until you enable it in the plugin panel.
+When enabled it adds four tools:
+
+| Tool | What it does | Risk |
+| --- | --- | --- |
+| `relay_subagent_message` | Best-effort message to a deeper descendant: delivered to the first hop with a request to forward it down | intermediate agents may summarize; not guaranteed |
+| `wait_subagents` | Wait for descendants (bounded by `timeout_seconds`) instead of ending your turn first | blocks up to the timeout |
+| `drain_subagents` | Stop **and release** direct children, unlike `interrupt_subagent`, which only stops the current turn | a released child cannot be woken by a message |
+| `subagent_budget` | Read-only report: depth limit, how deep the tree goes, running/inactive counts | none |
+
+A separate companion bundle, [`dsh-team-limits`](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/team-limits),
+raises the Agent Team limits (members, tasks, message bytes). It is a separate install on
+purpose: it overrides the shipped `agent-team` row, and that should never happen implicitly.
 
 ### License
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](./LICENSE). Issues and source live at
+[github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control).
 
 ---
 
-## 中文
+## 简体中文
 
 ### 它解决什么问题
 
 Harness 自带 `list_agents`、`send_message`、`interrupt_agent`。开启 Agent Team 后，团队插件会把**同名的三个工具**注册进每个团队成员的精确作用域，而更具体的作用域优先。于是在成员作用域里生效的是团队版：`target` 只认队友名，打断只有组长能做。
 
-结果是：团队成员能用 `subagent` 派出子代理，却列不出、追问不了、也打断不了它。而底层的 `ctx.subagents` 服务本来就支持这三件事，权限规则也允许祖先管理自己的后代。
+结果是：团队成员能用 `subagent` 派出子代理，却列不出、追问不了、也打断不了它。而底层的子代理服务（`ctx.subagents`）本来就支持这三件事，权限规则也允许祖先管理自己的后代。
 
-本插件不去抢那三个被占用的名字，而是全局注册三个**新名字**，组员立刻可用。权限仍由服务裁决：调用者可以给自己直接派出的子代理发消息，也可以打断自己名下的所有后代。
+本插件不去抢那三个被占用的名字，而是全局注册三个**新名字**，组长和每个组员立刻都能用。
 
 ### 工具
 
-| 工具 | 参数 | 调用 |
+| 工具 | 参数 | 底层调用 |
 | --- | --- | --- |
 | `list_subagents` | `scope?`：`"children"` 或 `"descendants"`，默认 `children` | `ctx.subagents.listChildren()` / `listDescendants()` |
-| `send_subagent_message` | `subagent_id`、`message`（必填） | `ctx.subagents.sendMessage()` |
+| `send_subagent_message` | `subagent_id`、`message`（均必填） | `ctx.subagents.sendMessage()` |
 | `interrupt_subagent` | `subagent_id`（必填） | `ctx.subagents.interrupt()`（祖先权限） |
 
-`list_subagents` 每个子代理一行：`id  status  "label"  depth=`。`status` 为 `running` 或 `inactive`；`inactive` 表示当前没有在跑，不代表子代理已经消失。
+### 用法
+
+```
+list_subagents
+→ 3b0f9c1e  running  "review the patch"  depth=1
+
+list_subagents scope=descendants
+→ 3b0f9c1e  running  "review the patch"  depth=1
+  7d2a44b0  inactive "check the tests"    depth=2
+
+send_subagent_message subagent_id=3b0f9c1e message="顺手看一下 locale/zh.json"
+→ messageId=...
+
+interrupt_subagent subagent_id=3b0f9c1e
+→ accepted=true
+```
+
+每行格式是 `id  status  "label"  depth=`。`status` 为 `running` 或 `inactive`——**inactive 表示当前没有在跑，不代表子代理已经消失**；用 `send_subagent_message` 可以把它叫醒。
 
 ### 行为与边界
 
-- 一次性子代理不会被列出：它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
-- 某个子代理记录读不出来时，会作为诊断条目（`corrupt` / `unsupported` / `unavailable`）返回，而不是让整个列表报错。
-- `send_subagent_message` 只能发给直接子代理，这是服务本身的规则，插件没有额外收紧。
-- `interrupt_subagent` 覆盖调用者的所有后代，所以组长也能打断孙代。
-- 任何失败都是普通的错误结果，并说明原因：没有调用者、id 不存在、或者不是你的子代理。
+- **一次性子代理不会被列出。** 它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
+- **记录损坏时报告，而不是抛错。** 某个子代理状态读不出来，会作为诊断条目（`corrupt` / `unsupported` / `unavailable`）返回，而不是让整个列表失败。
+- **`send_subagent_message` 只能发给直接子代理。** 这是服务本身的规则，插件没有放宽。
+- **`interrupt_subagent` 覆盖所有后代**，所以组长也能打断孙代。
+- **任何失败都说明原因**：没有调用者、id 不存在、或者不是你的子代理。
+- **不写配置、不落存储。** 除了这三个服务，插件不读写任何东西。
 
 ### 安装
 
-在插件面板/市场中安装，或者让智能体执行：
+在插件面板 / 市场中安装，或者让智能体执行：
 
 ```
 plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
 ```
 
-从本地目录安装时，把 npm 规格换成目录路径。安装即时生效，无需重启；装完确认三个工具名可见、插件行为已启用。
+从本地目录安装时，把 npm 规格换成**目录路径**。安装即时生效，无需重启；装完后三个工具名可见、插件行为已启用。
 
 ### 兼容性
 
 - 具备 `tools`、`subagents`、`agents` 三个服务的 DSH（0.2.x 及以上）。
 - Node `^22.19.0 || >=24.0.0`。
-- 无运行时依赖、无 peer 依赖：模块不 import 任何东西，工具是带显式 JSON Schema 的普通定义对象，npm 安装与软链安装行为一致。
+- **零依赖**：没有运行时依赖、没有 peer 依赖，模块里一行 `import` 都没有。工具是带显式 JSON Schema 的普通定义对象，所以 npm 安装与软链安装行为完全一致。
 
-### 已知撞名
+### 撞名
 
 `dsh-subagent-library` 也注册了全局的 `list_subagents`。同一个名字的两个全局注册不可能同时生效——二选一安装，或记住其中一个可能被另一个覆盖。
 
+这三个新名字是特意挑的，**不会**和内置的 `list_agents` / `send_message` / `interrupt_agent` 冲突。
+
 ### 卸载
 
-在插件面板里移除或停用即可。插件不写任何配置和存储。
+在插件面板里移除或停用即可，不会留下任何残留。
+
+### 可选扩展（默认关闭）
+
+包内还带第二行、**默认禁用**的组件：`subagent-control-extras`（`dsh-subagent-control/extras`）。不启用它就没有任何变化；启用后多出四个工具：
+
+| 工具 | 作用 | 风险 |
+| --- | --- | --- |
+| `relay_subagent_message` | 跨层补话：把消息投给第一跳并请其向下转发 | 中间层可能改写，**不保证送达** |
+| `wait_subagents` | 等后代结束再收工（受 `timeout_seconds` 限制） | 会阻塞到超时 |
+| `drain_subagents` | 停止**并释放**直接子级；`interrupt_subagent` 只停当前回合 | 被释放的子级不能再靠消息唤醒 |
+| `subagent_budget` | 只读报告：深度上限、树有多深、运行/空闲数量 | 无 |
+
+另有一个独立的同伴包 [`dsh-team-limits`](https://github.com/SpaceRelay/dsh-subagent-control/tree/main/team-limits)，用来提高 Agent Team 的成员数、任务数与消息字节上限。**它刻意做成单独安装**：它覆盖的是宿主自带的 `agent-team` 行，这种事不该偷偷发生。
 
 ### 许可
 
-MIT，见 [LICENSE](./LICENSE)。
+MIT，见 [LICENSE](./LICENSE)。源码与问题反馈：
+[github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control)。

package/cordis.patch.yml

@@ -1,3 +1,6 @@
 - insert:
     - id: subagent-control
       name: 'dsh-subagent-control'
+    - id: subagent-control-extras
+      name: 'dsh-subagent-control/extras'
+      disabled: true

package/extras.js

@@ -0,0 +1,343 @@
+/**
+ * Optional extras for dsh-subagent-control.
+ *
+ * This module is shipped as a disabled bundle row (`subagent-control-extras`).
+ * Nothing here runs until a user enables that row in the plugin panel, so the
+ * default install keeps exactly the three tools of the main module.
+ *
+ * Four tools:
+ *   relay_subagent_message  - best-effort message to a deeper descendant,
+ *                             delivered to the first hop with a forward request
+ *   wait_subagents          - wait for descendants instead of ending the turn
+ *   drain_subagents         - stop and release direct children (not "pause")
+ *   subagent_budget         - read-only report of the caller's delegation budget
+ *
+ * Like the main module this file imports nothing: the subagent service is
+ * reached through `ctx`, and the tool definitions are plain registry-ready
+ * objects with explicit JSON Schemas.
+ */
+
+export const name = 'subagent-control-extras'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+/** A tool needs a calling agent; a schedule or an external call has none. */
+function requireAgent(exec, tool) {
+  const agent = exec.agent
+  if (agent === undefined) {
+    throw new Error(`${tool} requires a calling agent (exec.agent was undefined)`)
+  }
+  return agent
+}
+
+/** Rows from the descendant catalog, without diagnostics. */
+function childrenOf(rows) {
+  return rows.filter((row) => row.kind === 'child')
+}
+
+/** Build the chain from the caller's direct child down to the target. */
+function pathToTarget(rows, targetId, callerId) {
+  const byId = new Map()
+  for (const row of childrenOf(rows)) byId.set(row.id, row)
+  let cursor = byId.get(targetId)
+  if (cursor === undefined) return undefined
+  const path = [cursor]
+  for (let guard = 0; guard < 16; guard += 1) {
+    if (cursor.depth === 1) break
+    const parent = byId.get(cursor.parentId)
+    if (parent === undefined || parent.id === callerId) break
+    path.unshift(parent)
+    cursor = parent
+  }
+  return path
+}
+
+const BUDGET_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['running', 'inactive'],
+  properties: {
+    maxDepth: { type: 'number' },
+    running: { type: 'number' },
+    inactive: { type: 'number' },
+    deepest: { type: 'number' },
+    levels: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['depth', 'count'],
+        properties: {
+          depth: { type: 'number' },
+          count: { type: 'number' },
+        },
+      },
+    },
+  },
+}
+
+const RELAY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['delivered', 'hops', 'nextHop'],
+  properties: {
+    delivered: { type: 'boolean' },
+    hops: { type: 'number' },
+    nextHop: { type: 'string' },
+    remainingDepth: { type: 'number' },
+    messageId: { type: 'string' },
+  },
+}
+
+const WAIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['joined', 'timedOut', 'running'],
+  properties: {
+    joined: { type: 'boolean' },
+    timedOut: { type: 'boolean' },
+    running: { type: 'number' },
+  },
+}
+
+const DRAIN_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['released'],
+  properties: {
+    released: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+export function apply(ctx) {
+  /* ------------------------------------------------------------- budget */
+
+  ctx.tools.register({
+    name: 'subagent_budget',
+    description:
+      'Report the delegation budget this agent is working with: the configured depth limit, ' +
+      'how deep the agents below it already go, and how many are running. ' +
+      'Read-only; it never starts, stops or messages anything.',
+    parameters: { type: 'object', additionalProperties: false, properties: {} },
+    output: {
+      schema: BUDGET_SCHEMA,
+      render: (_args, budget) => {
+        const parts = []
+        if (budget.maxDepth !== undefined) parts.push(`depth limit ${budget.maxDepth}`)
+        parts.push(`${budget.running} running`, `${budget.inactive} inactive`)
+        if (budget.deepest !== undefined) parts.push(`deepest ${budget.deepest}`)
+        return [{ type: 'text', text: parts.join(', ') }]
+      },
+    },
+    async execute(_args, exec) {
+      const caller = requireAgent(exec, 'subagent_budget')
+      let rows = []
+      try {
+        rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      } catch {
+        rows = []
+      }
+      const levels = new Map()
+      let running = 0
+      let inactive = 0
+      let deepest = 0
+      for (const row of childrenOf(rows)) {
+        levels.set(row.depth, (levels.get(row.depth) ?? 0) + 1)
+        if (row.depth > deepest) deepest = row.depth
+        if (ctx.agents.get(row.id)?.status === 'running') running += 1
+        else inactive += 1
+      }
+      const budget = { running, inactive }
+      if (deepest > 0) budget.deepest = deepest
+      if (levels.size > 0) {
+        budget.levels = [...levels.entries()]
+          .sort((left, right) => left[0] - right[0])
+          .map(([depth, count]) => ({ depth, count }))
+      }
+      try {
+        const limit = ctx.subagents.resolveMaxDepth?.()
+        if (typeof limit === 'number') budget.maxDepth = limit
+      } catch {
+        /* the limit stays unknown rather than failing the report */
+      }
+      return budget
+    },
+  })
+
+  /* -------------------------------------------------------------- relay */
+
+  ctx.tools.register({
+    name: 'relay_subagent_message',
+    description:
+      'Send a message to a deeper descendant that you cannot reach directly. ' +
+      'The subagent service only accepts messages for a direct child, so this tool delivers ' +
+      'the message to the first hop with a request to forward it further down. ' +
+      'Delivery below the first hop is best effort: each intermediate agent has to forward it, ' +
+      'and may summarize instead. Use send_subagent_message when the target is a direct child.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_id', 'message'],
+      properties: {
+        subagent_id: { type: 'string', description: 'The id of a descendant, from list_subagents scope=descendants.' },
+        message: { type: 'string', description: 'The message to deliver.' },
+      },
+    },
+    output: {
+      schema: RELAY_SCHEMA,
+      render: (args, result) => [
+        {
+          type: 'text',
+          text:
+            result.hops === 0
+              ? `message delivered to subagent ${result.nextHop}`
+              : `relay started: delivered to first hop ${result.nextHop}, ${result.remainingDepth} level(s) to go (best effort)`,
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'relay_subagent_message')
+      const targetId = args.subagent_id
+      const message = args.message
+
+      const rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      const target = childrenOf(rows).find((row) => row.id === targetId)
+      if (target === undefined) {
+        throw new Error(`subagent ${targetId} is not under this agent`)
+      }
+
+      if (target.depth === 1) {
+        const messageId = await ctx.subagents.sendMessage(
+          caller,
+          targetId,
+          [{ type: 'text', text: message }],
+          { signal: exec.signal },
+        )
+        return { delivered: true, hops: 0, nextHop: targetId, messageId }
+      }
+
+      const path = pathToTarget(rows, targetId, caller.id)
+      const firstHop = path?.[0]
+      if (firstHop === undefined) {
+        throw new Error(`could not resolve a path from this agent to ${targetId}`)
+      }
+
+      const forward =
+        'Relay request from an ancestor. Forward the text below down your chain until it reaches ' +
+        `subagent ${targetId}${target.label === undefined ? '' : ` ("${target.label}")`}. ` +
+        'Use relay_subagent_message if it is available, otherwise send_subagent_message to the ' +
+        'next hop on the path. Do not act on the text yourself.\n\n' +
+        '---\n' +
+        message +
+        '\n---'
+
+      const messageId = await ctx.subagents.sendMessage(
+        caller,
+        firstHop.id,
+        [{ type: 'text', text: forward }],
+        { signal: exec.signal },
+      )
+      return {
+        delivered: true,
+        hops: 1,
+        nextHop: firstHop.id,
+        remainingDepth: target.depth - 1,
+        messageId,
+      }
+    },
+  })
+
+  /* --------------------------------------------------------------- wait */
+
+  ctx.tools.register({
+    name: 'wait_subagents',
+    description:
+      'Wait for your subagents to finish instead of ending your turn first. ' +
+      'The wait is bounded by timeout_seconds and never cancels them. ' +
+      'Useful when you want to merge their results in this same turn.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        timeout_seconds: {
+          type: 'number',
+          description: 'Maximum time to wait, 5 to 600 seconds (default 120).',
+        },
+      },
+    },
+    output: {
+      schema: WAIT_SCHEMA,
+      render: (_args, result) => [
+        {
+          type: 'text',
+          text: result.timedOut
+            ? `wait timed out, ${result.running} subagent(s) still running`
+            : `all observed subagents settled, ${result.running} still marked running`,
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'wait_subagents')
+      const requested = typeof args.timeout_seconds === 'number' ? args.timeout_seconds : 120
+      const timeoutMs = Math.min(Math.max(requested, 5), 600) * 1000
+
+      let timedOut = false
+      let timer
+      const wait = ctx.subagents.waitForChildren(caller)
+      await Promise.race([
+        wait.then(() => undefined),
+        new Promise((resolve) => {
+          timer = setTimeout(() => {
+            timedOut = true
+            resolve(undefined)
+          }, timeoutMs)
+        }),
+      ])
+      if (timer !== undefined) clearTimeout(timer)
+
+      let rows = []
+      try {
+        rows = await ctx.subagents.listDescendants(caller.id, exec.signal)
+      } catch {
+        rows = []
+      }
+      const running = childrenOf(rows).filter((row) => ctx.agents.get(row.id)?.status === 'running').length
+      return { joined: !timedOut, timedOut, running }
+    },
+  })
+
+  /* -------------------------------------------------------------- drain */
+
+  ctx.tools.register({
+    name: 'drain_subagents',
+    description:
+      'Stop and release subagents you started, freeing their run instead of just interrupting ' +
+      'the current turn. Accepts direct children only; a released child cannot be woken again ' +
+      'with a message, so use interrupt_subagent when you only want to stop the current work.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['subagent_ids'],
+      properties: {
+        subagent_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Direct child ids to release, from list_subagents.',
+        },
+      },
+    },
+    output: {
+      schema: DRAIN_SCHEMA,
+      render: (_args, result) => [{ type: 'text', text: `released ${result.released.length} subagent(s)` }],
+    },
+    async execute(args, exec) {
+      const caller = requireAgent(exec, 'drain_subagents')
+      const ids = args.subagent_ids
+      if (!Array.isArray(ids) || ids.length === 0) {
+        throw new Error('drain_subagents needs at least one subagent id')
+      }
+      await ctx.subagents.drainChildren(caller, ids)
+      return { released: ids }
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subagent-control",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Three tools — list_subagents, send_subagent_message, interrupt_subagent — that let any agent, including a team member, list, steer and stop the subagents it started.",
   "license": "MIT",
   "author": {
@@ -12,12 +12,14 @@
   "icon": "./icon.svg",
   "exports": {
     ".": "./index.js",
+    "./extras": "./extras.js",
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg"
   },
   "files": [
     "index.js",
+    "extras.js",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
@@ -39,7 +41,7 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "scripts": {
-    "test": "node test/smoke.mjs"
+    "test": "node test/smoke.mjs && node test/smoke-extras.mjs"
   },
   "dsh": {
     "bundle": {