@hydraharness/harness-tool-subagent-control 0.1.1-rc.6

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.md

@@ -0,0 +1,74 @@
+# @hydraharness/harness-tool-subagent-control
+
+The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@hydraharness/harness-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 [`@hydraharness/harness-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#hydraharness-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/lib/index.js

@@ -0,0 +1,101 @@
+import { defineTool } from "@hydraharness/harness-tools";
+import { SessionId } from "@hydraharness/harness-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
+* `@hydraharness/harness-tool-subagent` instances so multiple delegation tools share
+* one control API.
+* @module @hydraharness/harness-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 `@hydraharness/harness-tool-subagent-control`.
+* @module @hydraharness/harness-tool-subagent-control/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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
+ * `@hydraharness/harness-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @hydraharness/harness-tool-subagent-control
+ */
+import type { Context } from '@hydraharness/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
+ * `@hydraharness/harness-tool-subagent` instances so multiple delegation tools share
+ * one control API.
+ * @module @hydraharness/harness-tool-subagent-control
+ */
+import { defineTool } from '@hydraharness/harness-tools';
+import { SessionId } from '@hydraharness/harness-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 `@hydraharness/harness-tool-subagent-control`.
+ * @module @hydraharness/harness-tool-subagent-control/invariant
+ */
+import type { Context } from '@hydraharness/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 `@hydraharness/harness-tool-subagent-control`.
+ * @module @hydraharness/harness-tool-subagent-control/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-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 @hydraharness/harness-tool-subagent-control/list-agents
+ */
+import type { Context } from '@hydraharness/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 @hydraharness/harness-tool-subagent-control/list-agents
+ */
+import { defineTool } from '@hydraharness/harness-tools';
+import { assertNever } from '@hydraharness/harness-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,67 @@
+{
+  "name": "@hydraharness/harness-tool-subagent-control",
+  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent list child agents, send follow-up messages, or interrupt their work."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-persistence-jsonl": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent-spawn-in-process": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6"
+  }
+}