@hasna-internal/kai-tool-subagent-control 0.1.1-rc.2

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,6 @@
+# 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:
+#   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
+README.md: 91f8d23ac092049e5315418070cdaae025054860
+README.zh.md: ca63383e541ccb157f5ee8a6a7a7de7be84b9f5a

package/README.md

@@ -0,0 +1,76 @@
+# @hasna-internal/kai-tool-subagent-control
+
+English | [中文](README.zh.md)
+
+The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@hasna-internal/kai-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and `interrupt_agent` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents` and declares `subagents` plus `agents` as load-time dependencies. Its catalog reads additionally require the session store and projection registry at call time, but no query service. A deployment can keep the root tools while omitting the list tool. No tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@hasna-internal/kai-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
+
+The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and records every message source as `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
+
+`interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
+
+`list_agents` takes one optional `scope` argument, derives the root id from the calling agent, and projects the service catalog to continuable children without a cursor. The default `children` scope reads `ctx.subagents.listChildren()`; `descendants` reads `ctx.subagents.listDescendants()`, whose one-corpus walk crosses ordinary sessions and one-shot children and renders surviving rows in stable pre-order with `parent=<id> depth=<n>`. The `parent` annotation is the durable direct-parent session id and may name an ordinary session omitted from the output. For the calling agent, only depth-1 child entries are `send_message` candidates; deeper child entries are `interrupt_agent` candidates only. Status comes from the live Agent registry: `running` (active driver), `idle` (resident between turns, possibly waiting on agents it started), or `ready` (storage only and resumable rather than terminal). The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible, with positions in the descendants scope. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain the service's.
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `send_message` takes `subagent_id` and `message`, describing that the message becomes the subagent's next turn, that this call returns no answer from the subagent, and that a failure means the message was not delivered; `interrupt_agent` takes `agent_id`, describing that only the current turn stops, queued messages park, descendants keep running, and acceptance precedes the actual stop; `list_agents` takes the optional `scope` enum.
+
+#### 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 queued as the next turn for subagent <subagent_id>` on acceptance; the canonical output carries the accepted `messageId`. A failure — an unauthorized or unknown child, a 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 child's response never returns through this call. A separately granted `report` may 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` = active driver, `idle` = resident between turns, `ready` = storage only; resumable rather than terminal, not a result waiting to be collected — a direct child in that state can be resumed by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). 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. Diagnostics never expose descriptor contents.
+
+#### 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.
+
+#### KV Cache effect
+
+Append-only; each result follows the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- **A queued message has no independent result** — acceptance returns only its inbox `messageId`; the child's work lands in the durable child Session and is never collected through this tool. A child granted `report` may send selected content back separately, but that message is not this call's result.
+- **No steering of the current turn** — every message opens a later FIFO turn, so a message sent while the child is working runs only after its current turn finishes and cannot redirect it.
+- **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.
+- **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.

package/README.zh.md

@@ -0,0 +1,76 @@
+# @hasna-internal/kai-tool-subagent-control
+
+[English](README.md) | 中文
+
+可选的全局具名 `send_message`、`interrupt_agent` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@hasna-internal/kai-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message` 与 `interrupt_agent`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，并将 `subagents` 与 `agents` 声明为加载时依赖。其目录读取在调用时还要求会话存储与投影注册表，但不要求任何查询服务。部署可保留根插件工具并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@hasna-internal/kai-tool-subagent-report`](../tool-subagent-report/README.zh.md) 负责子到父的方向。
+
+本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源记录为 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为 subagent 的下一个 FIFO 轮次：如果子 agent（智能体）仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
+
+`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、陈旧与非 ancestor 调用方会成为出错结果。
+
+`list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）或 `ready`（仅存于存储，表示可恢复而非终态）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到的内容
+
+已生成的 [schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-subagent-control)：`send_message` 包含 `subagent_id` 和 `message`，说明消息会成为 subagent 的下一个轮次、本次调用不会返回 subagent 的回答，以及失败即表示消息未送达；`interrupt_agent` 包含 `agent_id`，说明只有当前轮次会停止、已排队消息保持暂停、后代继续运行，以及接受先于实际停止；`list_agents` 包含可选的 `scope` 枚举。
+
+#### Token 影响
+
+每个父级请求支付固定的 schema 成本。
+
+#### KV Cache 影响
+
+前缀保持稳定；schema 不会在运行时改变。
+
+### 中断结果
+
+#### 模型看到的内容
+
+接受时返回 `interrupt requested for agent <agent_id>`。未授权的调用方——self、sibling、陈旧或非 ancestor——会成为指明拒绝原因的出错结果；目标不存在或已结算仍渲染接受行。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；被中断轮次的中止只在 child 自己的 transcript 中可见。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
+### 投递结果
+
+#### 模型看到的内容
+
+接受时返回 `message queued as the next turn for subagent <subagent_id>`；规范输出携带被接受的 `messageId`。失败，包括未授权或未知的子 agent、缺少描述符而无法恢复的子 agent，或准入被拒绝，都会成为出错的结果，其消息说明该消息未送达。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；子 agent 的响应绝不会通过本次调用返回。单独授予的 `report` 可以把选定内容追加到父级历史中。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 列表结果
+
+#### 模型看到的内容
+
+按稳定目录顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`ready` 表示仅存于存储；可恢复而非终态，也不表示有结果等待收集——处于该状态的直接 child 可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。`descendants` scope 会在每行 label 破折号之前插入 ` parent=<id> depth=<n>`，按 pre-order 排列。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
+
+#### Token 影响
+
+随所列可继续 child 数量线性增长——`descendants` scope 下为整棵树；没有 cursor 或上限，因此长期存活且有许多持久化 child 的 parent 每次调用都会承担完整列表成本。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
+## 已知限制与暂缓事项
+
+- **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；subagent 的工作会落入持久化子 agent 会话，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
+- **不对当前轮次进行 steering（中途引导）**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
+- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `ready` 的 child；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
+- **没有分页或删除**：系统返回完整且稳定排序的集合；只要 child 会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。

package/lib/index.js

@@ -0,0 +1,101 @@
+import { defineTool } from "@hasna-internal/kai-tools";
+import { SessionId } from "@hasna-internal/kai-session";
+//#region lib/types/index.js
+/**
+* The globally named `send_message` and `interrupt_agent` tools: thin
+* model-facing adapters over `ctx.subagents.followup()` 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
+* `@hasna-internal/kai-tool-subagent` instances so multiple delegation tools share
+* one control API.
+* @module @hasna-internal/kai-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(defineTool({
+		name: "send_message",
+		description: "Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.",
+		parameters: {
+			subagent_id: {
+				type: "string",
+				required: true,
+				description: "The subagent id returned when the background subagent was started."
+			},
+			message: {
+				type: "string",
+				required: true,
+				description: "The message to deliver to the subagent."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { messageId: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (args, _value) => [{
+				type: "text",
+				text: `message queued as the next turn for subagent ${args.subagent_id}`
+			}]
+		},
+		async execute(args, exec) {
+			const parent = exec.agent;
+			if (!parent) 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.followup(parent, SessionId(args.subagent_id), message, {
+				source: {
+					kind: "coordinator",
+					form: "relay",
+					senderSessionId: parent.id
+				},
+				signal: exec.signal
+			}) };
+		}
+	}));
+	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.",
+		parameters: { agent_id: {
+			type: "string",
+			required: true,
+			description: "The agent id of the running agent to interrupt."
+		} },
+		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(SessionId(args.agent_id), {
+				kind: "ancestor",
+				agent: caller
+			});
+			return Promise.resolve({ accepted: true });
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-tool-subagent-control`.
+* @module @hasna-internal/kai-tool-subagent-control/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-tool-subagent-control";
+/** Cordis companion plugin name. */
+const name = "tool-subagent-control-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; delivery
+* and activation relations are owned by the subagent service it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#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.followup()` 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
+ * `@hasna-internal/kai-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @hasna-internal/kai-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,107 @@
+/**
+ * The globally named `send_message` and `interrupt_agent` tools: thin
+ * model-facing adapters over `ctx.subagents.followup()` 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
+ * `@hasna-internal/kai-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @hasna-internal/kai-tool-subagent-control
+ */
+import { defineTool } from '@hasna-internal/kai-tools';
+import { SessionId } from '@hasna-internal/kai-session';
+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(defineTool({
+        name: 'send_message',
+        description: 'Send a message to a background subagent by its subagent id, continuing the same conversation. It '
+            + 'becomes the subagent\'s next turn: if it is still working, the message waits until its current turn '
+            + 'finishes, so it cannot redirect work already underway. This call returns no answer from the '
+            + 'subagent — only confirmation that the message was delivered — so use it to give it more work. A '
+            + 'failure means the message was NOT delivered.',
+        parameters: {
+            subagent_id: {
+                type: 'string',
+                required: true,
+                description: 'The subagent id returned when the background subagent was started.',
+            },
+            message: {
+                type: 'string',
+                required: true,
+                description: 'The message to deliver to the subagent.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    messageId: { type: 'string', required: true },
+                },
+            },
+            render: (args, _value) => [{
+                    type: 'text',
+                    text: `message queued as the next turn for subagent ${args.subagent_id}`,
+                }],
+        },
+        async execute(args, exec) {
+            const parent = exec.agent;
+            if (!parent) {
+                // Parent authority requires an exact live calling agent.
+                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.followup(parent, SessionId(args.subagent_id), message, {
+                source: { kind: 'coordinator', form: 'relay', senderSessionId: parent.id },
+                signal: exec.signal,
+            });
+            return { messageId };
+        },
+    }));
+    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.',
+        parameters: {
+            agent_id: {
+                type: 'string',
+                required: true,
+                description: 'The agent id of the running agent to interrupt.',
+            },
+        },
+        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(SessionId(args.agent_id), { kind: 'ancestor', agent: caller });
+            return Promise.resolve({ accepted: true });
+        },
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-tool-subagent-control`.
+ * @module @hasna-internal/kai-tool-subagent-control/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-subagent-control-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-tool-subagent-control`.
+ * @module @hasna-internal/kai-tool-subagent-control/invariant
+ */
+const PACKAGE_NAME = '@hasna-internal/kai-tool-subagent-control';
+/** Cordis companion plugin name. */
+export const name = 'tool-subagent-control-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; delivery
+ * and activation relations are owned by the subagent service it calls.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.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 @hasna-internal/kai-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,153 @@
+/**
+ * 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 @hasna-internal/kai-tool-subagent-control/list-agents
+ */
+import { defineTool } from '@hasna-internal/kai-tools';
+import { assertNever } from '@hasna-internal/kai-llm';
+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' };
+}
+/**
+ * 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.
+ */
+function statusOf(agents, id) {
+    const agent = agents.get(id);
+    if (agent === undefined)
+        return 'ready';
+    return agent.status === 'running' ? 'running' : 'idle';
+}
+/** 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') {
+        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 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` starts a new turn on the same '
+            + 'conversation, 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.',
+        parameters: {
+            scope: {
+                type: 'string',
+                enum: ['children', 'descendants'],
+                description: 'children (default) lists direct children only; descendants walks the complete tree below you.',
+            },
+        },
+        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', 'idle', 'ready'] },
+                                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);
+            // 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);
+                    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

@@ -0,0 +1,62 @@
+{
+  "name": "@hasna-internal/kai-tool-subagent-control",
+  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/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"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.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/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-subagent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent-loop": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-persistence": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-projection": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-persistence-jsonl": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent-loop-testkit": "^0.1.1-rc.2",
+    "@hasna-internal/kai-subagent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-subagent-spawn-in-process": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}