@x1a0f3n9/dsh-tool-subagent-control 0.1.5-rc.5 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,106 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# 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
-README.md: 99ca52dd4a7ea2629441c4d661632b8598c8171d
-README.zh.md: 1ff49a3179dbe61db1a9353e2fab131082cb29ae
+/:
+  en: 5413b8e52a0c8e3d
+  zh: 9b6d0385209ff9bb
+/x1a0f3n9-dsh-tool-subagent-control:
+  en: 455b7977c281c623
+  zh: 5ad1de3bab0ec299
+/x1a0f3n9-dsh-tool-subagent-control/summary:
+  en: 7464eb99b6f618eb
+  zh: 8c7628c8e9f163ca
+/x1a0f3n9-dsh-tool-subagent-control/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/x1a0f3n9-dsh-tool-subagent-control/use-this-package:
+  en: 27c5bbe682f0b72b
+  zh: b16aeb2c43f3692e
+/x1a0f3n9-dsh-tool-subagent-control/use-this-package/minimal-configuration:
+  en: 4a52c81317ec9001
+  zh: ebd9f1ba920da50a
+/x1a0f3n9-dsh-tool-subagent-control/use-this-package/send-message:
+  en: d80bb1df2eb740b7
+  zh: e3203d9868a82910
+/x1a0f3n9-dsh-tool-subagent-control/use-this-package/interrupt-agent:
+  en: 01dd41fe11f294d7
+  zh: f45a2e4073c0b206
+/x1a0f3n9-dsh-tool-subagent-control/use-this-package/list-agents:
+  en: b777ad75f0eb7a59
+  zh: 19275aba6573a917
+/x1a0f3n9-dsh-tool-subagent-control/understand-the-implementation:
+  en: c5cdf01a78c990f2
+  zh: 53c180d726ce4502
+/x1a0f3n9-dsh-tool-subagent-control/understand-the-implementation/design-concept:
+  en: 0af7238c690ee8d6
+  zh: 5049eea23770ffed
+/x1a0f3n9-dsh-tool-subagent-control/understand-the-implementation/delivery-and-signal-ownership:
+  en: 4c7698ccea49a60b
+  zh: fbf129ff583e6ab9
+/x1a0f3n9-dsh-tool-subagent-control/understand-the-implementation/listing-projection:
+  en: 70e344022e6e535e
+  zh: 355488590648a82e
+/x1a0f3n9-dsh-tool-subagent-control/understand-the-implementation/source-map:
+  en: a2a918cbad1a8313
+  zh: 5bcddba1b2bdd26e
+/x1a0f3n9-dsh-tool-subagent-control/further-exploration:
+  en: df2bf39d0ffffd43
+  zh: 4cd02551f7433c90
+/x1a0f3n9-dsh-tool-subagent-control/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/tool-schema/what-the-model-sees:
+  en: a63be096ee9c4873
+  zh: cd1bd116ccc66318
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/tool-schema/token-effect:
+  en: db207dc8d5860684
+  zh: ad2663b4967fbca9
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/tool-schema/kv-cache-effect:
+  en: 4b77d42b96b3519d
+  zh: dd393d8f0f6536c1
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/interrupt-result:
+  en: d64e936e83e89a2b
+  zh: b9905c33af6cca45
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/interrupt-result/what-the-model-sees:
+  en: 89305619897680ba
+  zh: e610a844fc09c53f
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/interrupt-result/token-effect:
+  en: 5d1bcef28b5f18da
+  zh: 027d67d93d660e76
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/interrupt-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/delivery-result:
+  en: ab964e307bd37dca
+  zh: 03f975252f838a42
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/delivery-result/what-the-model-sees:
+  en: 4a0a4955589012ae
+  zh: 2bbbb5196a8aa4fd
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/delivery-result/token-effect:
+  en: 0f134e37e4bd9965
+  zh: ceb858d01266e976
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/delivery-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/listing-result:
+  en: 094e55d258f2ec2e
+  zh: f364bc9046530bff
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/listing-result/what-the-model-sees:
+  en: efbbd1e36c7b2edd
+  zh: a8a95475666ed1dc
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/listing-result/token-effect:
+  en: 4688e849b3143dfc
+  zh: f22b5520c454f9e7
+/x1a0f3n9-dsh-tool-subagent-control/model-experience/listing-result/kv-cache-effect:
+  en: 4a629edb36a17e32
+  zh: 5a7539cfbf404c54
+/x1a0f3n9-dsh-tool-subagent-control/known-limitations-and-deferred-work:
+  en: 31cd8a1934cf0093
+  zh: 2fd07e05c8e58e9a
+/x1a0f3n9-dsh-tool-subagent-control/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -46,7 +46,7 @@ This package takes no configuration: the root plugin provides `send_message` and
 
 ### 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 idle target starts a turn, and a cold direct child resumes 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.
+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
 
@@ -54,7 +54,7 @@ Stops only the target's current turn: queued messages stay parked until a later
 
 ### list_agents
 
-Lists the continuable children below the calling agent: `children` (default) shows direct children, `descendants` walks the whole tree in stable pre-order, annotating each entry with its durable direct-parent session id and depth. Status comes from the live Agent registry — `running`, `idle`, or `ready`. One-shot children are intentionally absent because they cannot accept `send_message`, and unreadable candidates appear as diagnostics.
+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`. 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.
 
 -----
 
@@ -76,7 +76,7 @@ The tool forwards its execution signal, which owns admission only until inbox ac
 
 ### 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`. Diagnostics keep their positions in the descendants scope and never expose descriptor contents.
+`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
 
@@ -150,11 +150,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = active driver, `idle` = resident between turns, `ready` = storage only, resumable rather than terminal), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read. The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection.
+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 — the whole tree under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
+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
 
@@ -169,7 +169,7 @@ These limits define what the control tools cannot observe or steer; they are cur
 
 - **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 `ready`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
+- **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>

package/README.zh.md

@@ -46,7 +46,7 @@ kind: "package-reference"
 
 ### send_message
 
-向 `agent_id` 指定的 Agent 发送消息：任何确切在线 Agent 都可以向自己的直接可继续子级发送消息，驻留的可继续子级还可以向自己的直接父级发送消息。正在工作的目标通过 Steer 在最近的步骤边界接收消息；空闲目标会启动一个轮次，冷状态的直接子级会通过继续执行生命周期恢复。调用只返回接受结果（被接受消息的稳定 `messageId`），绝不返回回复。失败——不受支持的目标、不可用的父级、未知子级、缺少描述符而无法恢复的子级，或准入被拒——会明确说明消息未送达。
+向 `agent_id` 指定的 Agent 发送消息：任何确切在线 Agent 都可以向自己的直接可继续子级发送消息，驻留的可继续子级还可以向自己的直接父级发送消息。正在工作的目标通过 Steer 在最近的步骤边界接收消息；非活跃目标会通过继续执行生命周期启动或恢复一个轮次。调用只返回接受结果（被接受消息的稳定 `messageId`），绝不返回回复。失败——不受支持的目标、不可用的父级、未知子级、缺少描述符而无法恢复的子级，或准入被拒——会明确说明消息未送达。
 
 ### interrupt_agent
 
@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### list_agents
 
-列出调用方 agent 下方的可继续子级：`children`（默认）只显示直接子级，`descendants` 按稳定前序遍历整棵树，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running`、`idle` 或 `ready`。一次性子级因无法接受 `send_message` 而被有意排除，无法读取的候选项以诊断信息呈现。
+列出调用方 agent 下方的可继续子级：`children`（默认）从父目录读取直接子级，不打开子日志；`descendants` 按稳定前序递归读取子级目录，并为每个条目标注其持久化直接父级会话 ID 与深度。状态来自在线 Agent 注册表——`running` 或 `inactive`。可读取的一次性子级不出现在输出中，但其目录仍是遍历节点。未知模式与无法读取的子级目录（包括一次性子级）仅在 `descendants` 作用域中以诊断信息呈现。普通 Session fork 不是目录条目，因此从源 Session 列表中既无法发现这些 fork，也无法发现其后代。
 
 -----
 
@@ -76,7 +76,7 @@ kind: "package-reference"
 
 ### 列表投影
 
-`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。diagnostic 在 descendants scope 中保留其位置，且绝不暴露描述符内容。
+`list_agents` 从调用 agent 推导根 id，不使用 cursor 读取服务目录，通过在线 Agent 注册表细化每个候选的状态，并省略无法接受 `send_message` 的一次性子级。后代遍历保留每个父目录的事件顺序。未知模式产生诊断，但其目录仍可遍历；无法读取的目录产生诊断，并停止该分支。可达目录中不存在的后代无法被发现。
 
 ### 源码地图
 
@@ -150,11 +150,11 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示驱动器活跃，`idle` 表示驻留但处于轮次之间，`ready` 表示仅存于存储，可恢复而非终态），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。一次性子级会被有意排除；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
+按稳定目录顺序，每个可继续子级占一行：`<id> [<status>] — <label>`（`running` 表示正在执行轮次；`inactive` 表示没有轮次在执行，包括已加载和仅存于存储的情况；两种状态均不表示任务完成或结果）。仅 `descendants` 作用域会为未知模式或无法读取的子级目录添加 `<id> [diagnostic: <reason>]`，包括无法读取的一次性子级。`descendants` 作用域会在每行标签的破折号之前按前序插入 ` parent=<id> depth=<n>`。可读取的一次性子级会被省略；`(no subagents)` 表示投影后没有留下可继续子级或诊断信息。
 
 #### Token 影响
 
-随所列可继续子级数量线性增长——`descendants` 作用域下为整棵树；没有游标或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。
+随所列可继续子级和诊断数量线性增长——`descendants` 作用域下为目录可达后代；没有游标或上限，因此长期存活且有许多持久化子级的父级每次调用都会承担完整列表成本。
 
 #### KV Cache 影响
 
@@ -169,7 +169,7 @@ kind: "package-reference"
 
 - **已投递消息没有独立结果**——接受时只返回其 inbox `messageId`；目标后续工作会落入该目标的持久化会话，绝不会通过本工具收集。回复是另一条显式指定地址的 `send_message`，而非本次调用的结果。
 - **只有受支持的相邻 Agent 可以通信**——每个发送方都可以向直接可继续子级发送消息；只有具备驻留可继续 Activation 的发送方可以向自己的直接父级发送消息，且该父级必须仍在线；同级与更深的后代不能作为消息目标，只有向直接子级投递才支持冷激活。
-- **列表是快照，而非投递承诺**——它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `ready` 的子级；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
+- **列表是快照，而非投递承诺**——它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `inactive` 的子级；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
 - **没有分页或删除**——系统返回完整且稳定排序的集合；只要子级会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -21,7 +21,7 @@ const inject = ["tools", "subagents"];
 function apply(ctx) {
 	ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
 		name: "send_message",
-		description: "Send a message to a direct continuable child by its agent id. If you are a resident continuable child, you may also target your direct parent. If the target is still working, the message steers its nearest step; if it is idle, the message starts a turn. This call returns no answer from the agent — only confirmation that the message was delivered. A failure means the message was NOT delivered.",
+		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",
@@ -60,11 +60,11 @@ function apply(ctx) {
 	})));
 	ctx.tools.register(defineTool({
 		name: "interrupt_agent",
-		description: "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
+		description: "Ask a subagent to stop its current work. This call returns without waiting for it to stop. You can continue a direct child's conversation later with send_message. Subagents it started will keep running.",
 		parameters: { agent_id: {
 			type: "string",
 			required: true,
-			description: "The agent id of the running agent to interrupt."
+			description: "The id of an agent created under you: your direct child or a deeper descendant."
 		} },
 		output: {
 			schema: {

package/lib/types/index.js

@@ -20,10 +20,8 @@ export const inject = ['tools', 'subagents'];
 export function apply(ctx) {
     ctx.tools.register(markAdjacentAgentSendMessageTool(defineTool({
         name: 'send_message',
-        description: 'Send a message to a direct continuable child by its agent id. If you are a resident continuable child, '
-            + 'you may also target your direct parent. If the target is still working, the message steers its nearest step; '
-            + 'if it is idle, the message starts a turn. This call returns no answer from the agent — only confirmation '
-            + 'that the message was delivered. A failure means the message was NOT delivered.',
+        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',
@@ -61,17 +59,14 @@ export function apply(ctx) {
     })));
     ctx.tools.register(defineTool({
         name: 'interrupt_agent',
-        description: 'Request cancellation of a background agent\'s current turn by its agent id. The target may be your '
-            + 'direct child or a deeper agent created under you. Only the current turn stops: messages already '
-            + 'queued for the agent stay parked until a later send_message, agents it started keep running, and '
-            + 'the agent itself stays available for follow-ups. This call returns as soon as the stop request is '
-            + 'accepted, so the target may keep running briefly; interrupting an agent that already finished is '
-            + 'an accepted no-op.',
+        description: 'Ask a subagent to stop its current work. This call returns without waiting for it to stop. '
+            + 'You can continue a direct child\'s conversation later with send_message. '
+            + 'Subagents it started will keep running.',
         parameters: {
             agent_id: {
                 type: 'string',
                 required: true,
-                description: 'The agent id of the running agent to interrupt.',
+                description: 'The id of an agent created under you: your direct child or a deeper descendant.',
             },
         },
         output: {

package/lib/types/list-agents.js

@@ -14,23 +14,14 @@ export const inject = ['tools', 'subagents', 'agents'];
 function resolveListAgentsRequest(request) {
     return { scope: request.scope ?? 'children' };
 }
-/**
- * Refine one candidate's status through the live Agent registry: `running`
- * for an active driver, `idle` for a resident Agent between turns (possibly
- * waiting on agents it started), and `ready` when no live Agent remains.
- * `ready` preserves resumability without presenting an inactive conversation
- * as a terminal result to collect.
- */
+/** Report turn activity without exposing whether the child is loaded. */
 function statusOf(agents, id) {
-    const agent = agents.get(id);
-    if (agent === undefined)
-        return 'ready';
-    return agent.status === 'running' ? 'running' : 'idle';
+    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 (entry.kind === 'diagnostic') {
+    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
@@ -52,23 +43,16 @@ function project(agents, entry, position) {
 export function apply(ctx) {
     ctx.tools.register(defineTool({
         name: 'list_agents',
-        description: 'List your continuable background subagents by durable id and label. Use it to recall which ones '
-            + 'you started, not to poll for completion — you are told when one finishes. Status comes from the live '
-            + 'registry: running means the agent is working right now, idle means it is loaded but between turns '
-            + '(it may be waiting on agents it started), and ready means it exists only in storage — resumable, not '
-            + 'terminal, and not a result waiting to be collected; a `send_message` steers a running child at its nearest '
-            + 'step boundary or starts a turn for an idle or ready child, and a direct child remains a `send_message` '
-            + 'candidate in every status. The snapshot is not a delivery '
-            + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
-            + 'not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` '
-            + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
-            + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
-            + 'candidates for `interrupt_agent` only.',
+        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 only; descendants walks the complete tree below you.',
+                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: {
@@ -83,7 +67,7 @@ export function apply(ctx) {
                                 kind: { type: 'string', required: true, enum: ['child'] },
                                 id: { type: 'string', required: true },
                                 label: { type: 'string', required: true },
-                                status: { type: 'string', required: true, enum: ['running', 'idle', 'ready'] },
+                                status: { type: 'string', required: true, enum: ['running', 'inactive'] },
                                 parent: { type: 'string' },
                                 depth: { type: 'number' },
                             },
@@ -129,8 +113,6 @@ export function apply(ctx) {
                 throw new Error('list_agents requires a calling agent (exec.agent was undefined)');
             }
             const request = resolveListAgentsRequest(args);
-            // The registry drains started tool bodies, so the scan must observe the
-            // call's signal rather than finish a slow catalog after cancellation.
             switch (request.scope) {
                 case 'children': {
                     const entries = await ctx.subagents.listChildren(parent.id, exec.signal);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x1a0f3n9/dsh-tool-subagent-control",
   "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
-  "version": "0.1.5-rc.5",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,30 +32,30 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-subagent": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.5"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-subagent": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tools": "0.1.7-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-agent-loop": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-agent-loop-testkit": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-persistence": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-persistence-jsonl": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-query": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-subagent": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-subagent-fork-in-process": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-subagent-spawn-in-process": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.5"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@x1a0f3n9/dsh-agent-loop": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-agent-loop-testkit": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-agent": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-persistence": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-persistence-jsonl": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-projection": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-subagent-fork-in-process": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-query": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-subagent-spawn-in-process": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tools": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-subagent": "0.1.7-rc.2"
   },
   "dependencies": {
-    "@x1a0f3n9/dsh-brand": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-util-values": "^0.1.5-rc.5"
+    "@x1a0f3n9/dsh-brand": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-util-values": "0.1.7-rc.2"
   }
 }