@hydraharness/harness-tool-subagent 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,80 @@
+# @hydraharness/harness-tool-subagent
+
+The model-facing delegation tool over one configured `ctx.subagents` provider. Changing the provider changes transport without changing the execution contract.
+
+## Provider selection and lifecycle
+
+Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
+
+A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns the canonical `{ kind: 'foreground', runId, output: JsonValue[] }`, rendered as the same final text. Abort, refusal, token limit, and other failures become errored tool results whose message contains the stop-reason headline, an optional provider-authored `SubagentResult.diagnostic`, and then any preserved partial assistant text. The diagnostic remains separate from `SubagentResult.output`, so a truncated answer is never reported as success or confused with infrastructure detail. If result collection and disposal both reject, the errored result preserves both failures.
+
+`backgroundMode` selects both the background route and the omitted `run_in_background` default. `one-shot` waits in the foreground by default; an explicit `true` registers a plain parent-owned Task and returns canonical `{ kind: 'background', jobId }`, rendered as `started background subagent job <id>`, even when the provider supports continuable children. Generic task tools own its later status, collection, cancellation, and notices; a failed Task keeps the stop reason and the same optional provider diagnostic in its detail. `continuable` runs in the background when the argument is omitted or `true`; an explicit `false` waits for the result in the foreground. Its background route requires a provider with the `prepareContinuable` capability, calls `ctx.subagents.startContinuable()`, and returns `{ kind: 'continuable', subagentId }`, rendered as `started continuable subagent <childId>; not a background job — wait for the runtime notice, do not call job_output or job_kill`. The child id is never valid for `job_output` or `job_kill`; the route resolves at inbox acceptance, so it neither waits for nor collects a result. The continuation service delivers one settlement notice whenever the child's Activation ends, containing its outcome and any final assistant message independently of `report`; use that notice instead of starting a duplicate delegation. The optional global `send_message` tool starts later work in the same child conversation. Starting continuable work does not require `send_message` to be loaded. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), and the [background-first delegation Agent Note](../../../.agents/notes/implemented/feature/2026-08-11-background-first-continuable-delegation.md).
+
+`toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `provider` (required) | Provider name (`spawn`, `fork`, `acp`, ...). |
+| `toolName` | Model-facing name, default `subagent`; distinct for every loaded instance. |
+| `enableRunInBackground` | Exposes background mode, default `true`; disabling also rejects forced background calls. |
+| `backgroundMode` | Background lifecycle policy, default `one-shot`. `one-shot` defaults calls to foreground; `continuable` defaults them to background, requires the provider's `prepareContinuable` capability, and returns a durable child id without requiring the follow-up tool. |
+| `agentOptions` | Provider-specific child `provider`, `model`, and positive `maxTokens`; the in-process provider treats explicit values as overrides of inherited parent options. |
+| `persona` | Per-child persona; requires provider `persona` capability. |
+| `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
+| `maxDepth` | Absolute delegation-depth cap, default `3` (`0` forbids delegation); a numeric cap requires the `depthLimit` capability and fails the mount without it. `'provider-managed'` sends no cap for an out-of-process provider whose budget belongs to the child harness. The tool stays visible at the cap; each attempted start checks the calling agent's current depth and returns an errored tool result when rejected. |
+
+## Concurrency
+
+Foreground and background calls are concurrency-safe: sibling delegations in one assistant message overlap under the loop's rolling pool (`maxParallelToolCalls`), and results still commit in model order. Children work in their own sessions and a run never mutates the parent session; the one-shot background form's one parent-owned write — registering a Task — is a synchronous, commutative insertion that tolerates concurrent dispatch, so overlapping background calls acquire their job ids in dispatch-race order. Coordinating sibling workspace effects belongs to the model, exactly as it already does for background and continuable children. See the [parallel subagent Agent Note](../../../.agents/notes/implemented/feature/2026-08-09-parallel-subagent-delegations.md) and the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md).
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated default [`subagent` schema](../../../docs/tool-catalog.md#hydraharness-tool-subagent) under this instance's configured name while its provider exists. Provider context inheritance changes the tool and prompt descriptions. Enabled background mode adds `run_in_background`: continuable mode documents its `true` default, runtime settlement notice, explicit foreground override, and that its durable id is not accepted by `job_output` or `job_kill`; one-shot mode documents its `false` default and the job id collected with `job_output` or stopped with `job_kill`. While the tool is visible in an assembly's scope, a `tool:<toolName>` system-prompt section tells the model to start independent continuable delegations together, keep working while they run, use the settlement notice instead of duplicate work, and choose foreground only when its next action depends on the result; a tool restriction removes both its schema and this guidance.
+
+#### Token effect
+
+Fixed schema cost per parent request; each provider instance adds one schema, and each continuable instance adds one short system-prompt section.
+
+#### KV Cache effect
+
+Prefix-stable while provider instances, names, descriptions, and schemas are unchanged. Provider registration lifecycle may invalidate parent reuse from the first changed tool definition.
+
+### Foreground result
+
+#### What the model sees
+
+The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <stop reason>`, followed by a safe provider diagnostic when present and then any partial assistant text. Intermediate child steps stay out of the parent.
+
+#### Token effect
+
+The prompt and result remain in parent history until compaction; child working context remains in the child.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Background result
+
+#### What the model sees
+
+Start returns exactly `started continuable subagent <childId>; not a background job — wait for the runtime notice, do not call job_output or job_kill` in configured continuable mode, or `started background subagent job <id>` in configured one-shot mode. In one-shot mode the generic task surface provides later status, final output, cancellation responses, and notices; failed status detail includes the provider diagnostic when the result supplied one. In continuable mode this tool returns no result of its own; the child id is not accepted by generic job tools, its settlement reaches the parent as a [service-owned notice](../subagent/README.md#settlement-notice), and an independently loaded `send_message` tool delivers follow-ups.
+
+#### Token effect
+
+The acknowledgement is retained; a one-shot final output enters parent history only when collected or injected, while a continuable child's output never returns through this tool — its settlement notice arrives independently of any tool result.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Background runs expose no result through this tool** — a one-shot task's final output is collected through the generic task surface, and a continuable child's output stays in its own session, read by its subagent id. The settlement notice states how that child ended and carries any final assistant message, but it is not this call's return value and cannot be awaited here.
+- **Duplicate names across waiting one-shot instances are detected late** (`TODO(subagent-dup-toolname)`) — continuable instances reserve their prompt-section name during plugin application, but preventing provider-registration rollback for waiting one-shot instances requires a registry of intended names.
+- **Child policy is fixed per instance** — another model, persona, tool filter, or depth cap requires another distinctly named tool.

package/lib/index.js

@@ -0,0 +1,302 @@
+import z from "@hydraharness/schemastery";
+import { defineTool } from "@hydraharness/harness-tools";
+import { assertSubagentMaxDepth, settleRun } from "@hydraharness/harness-subagent";
+//#region lib/types/index.js
+/**
+* Model-facing delegation through one configured `ctx.subagents` provider.
+* Provider lifecycle controls tool registration and context-sensitive schema
+* wording. Foreground calls always dispose the run after collection.
+* Background policy is selected by this plugin's configuration: one-shot
+* calls own a plain Task, while continuable calls use
+* `ctx.subagents.startContinuable()`.
+* @module @hydraharness/harness-tool-subagent
+*/
+const name = "tool-subagent";
+const inject = [
+	"tools",
+	"subagents",
+	"systemPrompt"
+];
+/** Prompt order after bounded delegation policy and before child reporting. */
+const SUBAGENT_SECTION_ORDER = 116.5;
+const Config = z.object({
+	provider: z.string().required(),
+	toolName: z.string().default("subagent"),
+	enableRunInBackground: z.boolean().default(true),
+	backgroundMode: z.union(["one-shot", "continuable"]).default("one-shot"),
+	agentOptions: z.object({
+		provider: z.string(),
+		model: z.string(),
+		maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER)
+	}).default(void 0),
+	persona: z.string(),
+	toolFilter: z.object({
+		allow: z.array(z.string()).default(void 0),
+		deny: z.array(z.string()).default(void 0)
+	}).default(void 0),
+	maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const("provider-managed")]).default(3)
+});
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values) {
+	return values.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value) && value.type === "text" && typeof value.text === "string").map((value) => value.text).join("");
+}
+/** Settle pending startup without rejecting the task producer contract. */
+async function settleStart(start, signal) {
+	try {
+		return await settleRun(await start);
+	} catch (error) {
+		return signal.aborted && !(error instanceof AggregateError) ? { status: "killed" } : {
+			status: "failed",
+			detail: String(error)
+		};
+	}
+}
+/** A non-`completed` stop reason means the child did not finish cleanly. */
+function stopReasonError(result) {
+	switch (result.stopReason) {
+		case "completed": return;
+		case "aborted": return "subagent run was cancelled";
+		case "error": return "subagent run failed";
+		case "max-tokens": return "subagent run hit its token limit before finishing";
+		case "refusal": return "subagent declined the task";
+		default: return `subagent run ended abnormally (${String(result.stopReason)})`;
+	}
+}
+/**
+* Append provider-authored failure detail and the child's preserved partial
+* answer to a stop-reason error, keeping diagnostic text separate from the
+* child's assistant output.
+* @param error - the stop-reason headline.
+* @param result - the child's terminal result.
+* @returns the headline, diagnostic, and partial text that are present.
+*/
+function withDiagnosticAndPartialText(error, result) {
+	const diagnostic = result.diagnostic === void 0 ? "" : `\nDiagnostic: ${result.diagnostic}`;
+	const text = result.output.filter((block) => block.type === "text").map((block) => block.text).join("");
+	return `${error}${diagnostic}${text.length === 0 ? "" : `\nPartial output before the run ended:\n${text}`}`;
+}
+/**
+* Collect and release one foreground run without letting disposal replace an
+* independent result failure.
+*/
+async function settleForegroundRun(run) {
+	const [execution] = await Promise.allSettled([run.result.then((result) => {
+		const error = stopReasonError(result);
+		if (error !== void 0) throw new Error(withDiagnosticAndPartialText(error, result));
+		return {
+			kind: "foreground",
+			runId: run.id,
+			output: result.output
+		};
+	})]);
+	const [disposal] = await Promise.allSettled([Promise.resolve().then(() => run.dispose())]);
+	if (execution.status === "rejected") {
+		if (disposal.status === "rejected") throw new AggregateError([execution.reason, disposal.reason], `subagent run failed: ${String(execution.reason)}; dispose failed: ${String(disposal.reason)}`);
+		throw execution.reason;
+	}
+	if (disposal.status === "rejected") throw disposal.reason;
+	return execution.value;
+}
+/**
+* Model-facing wording from the provider's conversation-history descriptor
+* ({@link SubagentProvider.inheritsParentContext}).
+* A fresh child needs a standalone prompt; a forked child already sees the
+* conversation's completed turns — telling the model to restate everything
+* (or, worse, that the child "does not see this conversation") would be false
+* for a fork.
+* @param inheritsConversation - whether the child's conversation is seeded
+*   with the parent's completed turns; this says nothing about tool, service,
+*   scope, or authority inheritance.
+* @returns the tool `description` and the `prompt` parameter description.
+*/
+function providerWording(inheritsConversation) {
+	if (inheritsConversation) return {
+		description: "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn). Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive its result, not its intermediate steps.",
+		promptDescription: "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+	};
+	return {
+		description: "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.",
+		promptDescription: "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+	};
+}
+/** Resolve the model's optional scheduling request into one execution route. */
+function resolveDelegationRun(request, options) {
+	if (!options.backgroundEnabled) {
+		if (request.run_in_background === true) throw new Error("run_in_background is disabled for this tool instance (enableRunInBackground: false)");
+		return { runInBackground: false };
+	}
+	return { runInBackground: request.run_in_background ?? options.continuable };
+}
+function apply(ctx, config) {
+	if (config.maxDepth !== "provider-managed") assertSubagentMaxDepth(config.maxDepth);
+	if (config.toolFilter !== void 0 && config.toolFilter.allow === void 0 && config.toolFilter.deny === void 0) throw new Error("tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter");
+	const backgroundEnabled = config.enableRunInBackground !== false;
+	const continuable = (config.backgroundMode ?? "one-shot") === "continuable";
+	const toolName = config.toolName ?? "subagent";
+	let disposeTool;
+	const mount = (provider) => {
+		if (typeof config.maxDepth === "number" && !provider.capabilities.depthLimit) throw new Error(`tool-subagent: provider "${provider.name}" cannot enforce maxDepth (no depthLimit capability) — set maxDepth: 'provider-managed' to leave the recursion budget to the provider`);
+		const wording = providerWording(provider.inheritsParentContext);
+		if (continuable && provider.prepareContinuable === void 0) throw new Error(`tool-subagent: provider "${provider.name}" does not support \`backgroundMode: continuable\``);
+		disposeTool = ctx.tools.register(defineTool({
+			name: toolName,
+			description: wording.description + (backgroundEnabled ? continuable ? " This tool runs in the background by default and immediately returns a durable continuable subagent id, not a background job id. Do not pass that id to `job_output` or `job_kill`. When the run settles, the runtime sends the parent a notice containing its outcome and any final assistant message; wait for that notice rather than starting a duplicate delegation. `send_message` starts a later turn in the same child conversation. Set `run_in_background: false` only when your next action depends on receiving the result." : " This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`." : " This call waits for the subagent and returns its result."),
+			parameters: {
+				description: {
+					type: "string",
+					required: true,
+					description: "A short (3-5 word) description of the delegated task, for display."
+				},
+				prompt: {
+					type: "string",
+					required: true,
+					description: wording.promptDescription
+				},
+				...backgroundEnabled ? { run_in_background: {
+					type: "boolean",
+					description: continuable ? "Whether to run in the background and return a durable continuable subagent id immediately. Defaults to true. This id is not a background job id; do not pass it to `job_output` or `job_kill`. Set false to wait for the result when your next action depends on it." : "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
+				} } : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "background"
+							},
+							jobId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "continuable"
+							},
+							subagentId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "foreground"
+							},
+							runId: {
+								type: "string",
+								required: true
+							},
+							output: {
+								type: "array",
+								required: true,
+								items: { type: "json" }
+							}
+						}
+					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background subagent job ${value.jobId}` : value.kind === "continuable" ? `started continuable subagent ${value.subagentId}; not a background job — wait for the runtime notice, do not call job_output or job_kill` : outputValueText(value.output)
+				}]
+			},
+			isConcurrencySafe: () => true,
+			presentCall: (args) => ({
+				card: "generic",
+				title: args.description || "Subagent",
+				kind: "other",
+				rawInput: args.prompt
+			}),
+			async execute(args, exec) {
+				const parent = exec.agent;
+				if (!parent) throw new Error("subagent tool requires a calling agent (exec.agent was undefined)");
+				const maxDepth = typeof config.maxDepth === "number" ? config.maxDepth : void 0;
+				const request = {
+					label: args.description,
+					prompt: [{
+						type: "text",
+						text: args.prompt
+					}],
+					parent,
+					...config.agentOptions !== void 0 ? { agentOptions: config.agentOptions } : {},
+					...config.persona !== void 0 ? { persona: config.persona } : {},
+					...config.toolFilter !== void 0 ? { toolFilter: config.toolFilter } : {},
+					...maxDepth !== void 0 ? { maxDepth } : {}
+				};
+				if (resolveDelegationRun(args, {
+					backgroundEnabled,
+					continuable
+				}).runInBackground) {
+					if (continuable) return {
+						kind: "continuable",
+						subagentId: (await ctx.subagents.startContinuable({
+							provider: config.provider,
+							label: args.description,
+							request,
+							signal: exec.signal
+						})).childId
+					};
+					const jobs = ctx.get("jobs");
+					if (jobs === void 0) throw new Error("background jobs unavailable: load @hydraharness/harness-jobs and @hydraharness/harness-tool-jobs");
+					return {
+						kind: "background",
+						jobId: jobs.start({
+							kind: "subagent",
+							label: args.description,
+							owner: parent,
+							run: () => {
+								const controller = new AbortController();
+								return {
+									cancel: (reason) => {
+										controller.abort(reason ?? "background subagent task killed");
+									},
+									done: settleStart(ctx.subagents.start(config.provider, {
+										...request,
+										signal: controller.signal
+									}), controller.signal)
+								};
+							}
+						})
+					};
+				}
+				return settleForegroundRun(await ctx.subagents.start(config.provider, {
+					...request,
+					signal: exec.signal
+				}));
+			}
+		}));
+	};
+	ctx.on("subagent/provider-added", (provider) => {
+		if (provider.name === config.provider && disposeTool === void 0) mount(provider);
+	});
+	ctx.on("subagent/provider-removed", (name) => {
+		if (name !== config.provider || disposeTool === void 0) return;
+		disposeTool();
+		disposeTool = void 0;
+	});
+	const present = ctx.subagents.getProvider(config.provider);
+	if (present !== void 0) mount(present);
+	else ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? "subagent"}" tool will register when it appears`);
+	if (backgroundEnabled && continuable) ctx.systemPrompt.section({
+		name: `tool:${toolName}`,
+		order: SUBAGENT_SECTION_ORDER,
+		text: (context) => disposeTool === void 0 || ctx.tools.get(toolName, context.scope) === void 0 ? "" : `Use ${toolName} in the background by default. Its returned continuable id is not a background job id: do not pass it to job_output or job_kill. Start independent delegations together in one assistant message, continue useful work while they run, and wait for the runtime notice rather than starting a duplicate delegation. Set \`run_in_background: false\` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.`
+	});
+}
+//#endregion
+export { Config, 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`.
+* @module @hydraharness/harness-tool-subagent/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-subagent";
+/** Cordis companion plugin name. */
+const name = "tool-subagent-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; execution
+* relations are owned by the capability seam 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,69 @@
+/**
+ * Model-facing delegation through one configured `ctx.subagents` provider.
+ * Provider lifecycle controls tool registration and context-sensitive schema
+ * wording. Foreground calls always dispose the run after collection.
+ * Background policy is selected by this plugin's configuration: one-shot
+ * calls own a plain Task, while continuable calls use
+ * `ctx.subagents.startContinuable()`.
+ * @module @hydraharness/harness-tool-subagent
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { AgentOptions } from '@hydraharness/harness-agent';
+export declare const name = "tool-subagent";
+export declare const inject: string[];
+/** Config: which registered provider this tool delegates to, plus child defaults. */
+export interface Config {
+    /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
+    provider: string;
+    /**
+     * Model-facing tool name (default `subagent`). Each loaded instance must use
+     * a distinct name.
+     */
+    toolName?: string;
+    /**
+     * Expose `run_in_background` (default true). Disabled instances omit the
+     * parameter and reject forced background calls.
+     */
+    enableRunInBackground?: boolean;
+    /**
+     * Background execution policy (default `one-shot`). `one-shot` defaults calls
+     * to foreground; `continuable` defaults them to background, requires a provider
+     * with the `prepareContinuable` capability, and returns the durable child id.
+     * Follow-up adapters remain independently optional.
+     */
+    backgroundMode?: 'one-shot' | 'continuable';
+    /**
+     * Agent options applied to every child; omitted fields use child-loop defaults.
+     */
+    agentOptions?: AgentOptions;
+    /**
+     * Per-child persona that shadows `deployment:persona`. Requires the
+     * provider's `persona` capability; omission preserves the deployment persona.
+     */
+    persona?: string;
+    /**
+     * Tool filter applied to every child. Filtered tools disappear from its
+     * prompt and reject execution. Requires the provider's `toolFilter`
+     * capability; unknown names fail startup.
+     */
+    toolFilter?: {
+        /** Global tool names the child keeps; everything else is removed. */
+        allow?: string[];
+        /** Global tool names removed from the child. */
+        deny?: string[];
+    };
+    /**
+     * Maximum child depth: a non-negative safe integer (default `3`; `0` forbids
+     * delegation entirely), or `'provider-managed'` to send no cap. A numeric cap
+     * requires the provider's `depthLimit` capability (mount fails loud
+     * otherwise). The provider checks the calling agent's current depth at every
+     * start; the tool remains model-visible so runtime policy owns rejection.
+     * `'provider-managed'` is for an out-of-process provider whose recursion
+     * budget belongs to the child runtime or its own deployment.
+     */
+    maxDepth?: number | 'provider-managed';
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-tool-subagent`.
+ * @module @hydraharness/harness-tool-subagent/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-subagent-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/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@hydraharness/harness-tool-subagent",
+  "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent delegate a task to a child agent."
+    }
+  },
+  "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"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@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/harness-session-persistence": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent-spawn-in-process": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.6",
+    "@hydraharness/harness-tool-jobs": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-persistence-jsonl": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-jobs-local": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6"
+  }
+}