@hydraharness/harness-tool-subagent-report 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,64 @@
+# @hydraharness/harness-tool-subagent-report
+
+The optional child-scoped `report` tool is a thin adapter over `ctx.subagents.reportFrom()`. It gives every continuable in-process child a return channel to the Agent that started it, and installs the prompt section that instructs the child to use it. The package registers a continuable-child setup contribution instead of a global tool, so the tool and its guidance exist only inside those children. Roots, one-shot subagents, remote subagent providers, sibling scopes, and agentless tool execution never present or execute it. Installing this package grants only that child-scoped capability; the parent-to-child direction remains the independent [`@hydraharness/harness-tool-subagent-control`](../tool-subagent-control/README.md), and continuable mode depends on neither package.
+
+The child-scoped `tool:report` prompt section instructs the child to call `report` once before finishing, with a self-contained answer, and earlier whenever a partial finding changes what the parent should do next. The instruction is guidance, not enforcement: the mechanism still accepts zero or many calls in one turn, and no runtime path rejects a child that never reports. A successful call neither concludes the turn, settles the Activation, nor prevents later parent follow-ups, and finishing a turn never reports automatically. The tool accepts no recipient: `exec.agent` is the sender's exact live Agent and the authority credential, and the service derives the sole recipient from that child's durable `parentSession`. Success returns the stable `MessageId` of the parent-accepted message, not a read receipt, an inbox-occurrence id, a parent-log acknowledgement, a turn-completion receipt, or a persistence flush. A parent absent from the registry fails the call with `direct parent is not live; report was not delivered` — registry presence governs parent resolution, and a registered parent already in host-owned disposal still accepts while its log admits appends. The service performs no injection, parent cold resume, or offline mailbox write; the durable child transcript remains the recovery source, and a failed tool call does not prove non-delivery (a later `tools/post-execute` veto can fail a call whose report was already accepted).
+
+`reportDelivery` selects parent scheduling for every accepted report. `next-step` (the default) uses `parent.steer()`: a running parent receives the report at its nearest safe step boundary, while an idle parent starts a turn. Reports accepted in sequence share the next-step FIFO, including the later manager-authored settlement notice, so the parent cannot observe settlement before an earlier report; reports waiting together enter one claimed batch. `quiet` uses `parent.inject()`, adding the same next-step context without waking a parked parent. This is deployment scheduling policy, so the model-facing schema cannot select or override it per call.
+
+Scope-local registration deliberately survives the child's global `toolFilter`, so a delegation allow-list cannot remove the only return channel. A deployment that requires a child with no return channel omits this package.
+
+The contribution body is exported as `installReportTool(childCtx, ctx, delivery)` so inspection consumers can install `report` and its guidance into a minted child scope, and returns the one disposer revoking both. The generated tool catalog uses that path because the global registry cannot expose a scope-local schema. Production composition still enters through `apply()`; the subagent seam's contribution registry remains private.
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [`report` schema](../../../docs/tool-catalog.md#hydraharness-tool-subagent-report): one required `output` string. Its description states that the child must report once before finishing, that reporting reaches only the Agent that started the child, and that it does not end the turn. It carries no recipient or delivery-mode parameter. The separate `tool:report` prompt section repeats the obligation outside the schema, where a child that ignores tool descriptions still reads it.
+
+#### Token effect
+
+Fixed schema and prompt-section cost per continuable-child request, and none in any other Agent's requests.
+
+#### KV Cache effect
+
+Prefix-stable within a child; neither the schema nor the section changes at runtime. Removing the package revokes both from resident children, which changes their next request prefix.
+
+### Report result
+
+#### What the model sees
+
+`report accepted by the agent that started you as message <messageId>` on acceptance; the canonical output carries the stable `messageId`. A failure from an unauthorized sender, an unavailable parent, or a closing lifecycle is an errored result. The description says a failed call may still have arrived because a later `tools/post-execute` failure can replace the result after `reportFrom()` accepted the message.
+
+#### Token effect
+
+One short acknowledgement per call in the reporting child. The reported content is additionally billed to the parent: next-step delivery joins the next request in an open parent turn or starts a turn for an idle parent, while quiet delivery waits for another input to wake the parent.
+
+#### KV Cache effect
+
+Append-only in the child. In the parent, the framed report follows existing history and preserves the reusable prefix.
+
+### Parent-visible report
+
+#### What the model sees
+
+One user-role parent message framed as `Background subagent <child-id> reported:` followed by the child's exact `output`, with a durable source `{ kind: 'subagent-report', senderSessionId: <child-id> }` that names the child.
+
+#### Token effect
+
+The child's complete `output` plus the one-line frame, uncapped by this package.
+
+#### KV Cache effect
+
+Append-only; the report follows the parent's reusable request prefix. Next-step delivery wakes the parent and may extend its open turn, while quiet delivery does not wake it.
+
+## Known Limitations and Deferred Work
+
+- **A parent whose host-owned disposal already started can still accept** — `AgentHandle.dispose()` cancels, awaits quiescence, and only then unwinds the scope and leaves the registry; it exposes no signal for "disposal started." A report accepted in that window is appended to the parent's transcript, but that parent will not act on it in this process. A continuation-manager-owned parent rejects forest teardown through the manager's admission boundary.
+- **Acceptance is weaker than durable delivery** — there is no durable mailbox, idempotency key, delivery receipt, retry protocol, or exactly-once claim. A process failure after one side recorded acceptance leaves the outcome ambiguous, and an external retry may duplicate the report.
+- **A staged quiet report is not immediately reconstructable** — acceptance returns its stable `MessageId`, but the parent Session reconstructs the framed content only after pending context reaches its ordinary log boundary.
+- **Granting waits for the next Activation; revocation is immediate** — installing this package after a child becomes resident grants `report` and its guidance only on that child's next Activation, while removing the package revokes both from resident children immediately.
+- **Nested reporting reaches exactly one edge upward** — a grandchild reports to its direct child parent, never to the top-level coordinator, which must explicitly report a derived update later.
+- **No rate limiting** — the default `next-step` mode can amplify model work when nested children report frequently, although reports waiting together share one step; a deployment that accepts unread reports over that amplification selects `quiet`.

package/lib/index.js

@@ -0,0 +1,98 @@
+import z from "@hydraharness/schemastery";
+import { defineTool } from "@hydraharness/harness-tools";
+//#region lib/types/index.js
+/**
+* The child-scoped `report` tool and its usage guidance, installed into every
+* continuable in-process child's unpublished context. Roots, one-shot children,
+* remote providers, and agentless executions never see the registration.
+*
+* @module @hydraharness/harness-tool-subagent-report
+*/
+const name = "tool-subagent-report";
+const inject = [
+	"subagents",
+	"tools",
+	"systemPrompt"
+];
+/** Guidance order after every per-tool section a continuable child can carry. */
+const REPORT_SECTION_ORDER = 117;
+const Config = z.object({ reportDelivery: z.union(["quiet", "next-step"]).default("next-step") });
+/**
+* Install `report` and its usage guidance into one continuable child's scope.
+* Both registrations are owned by that scope and are therefore invisible to the
+* child's parent and siblings.
+* @param childCtx - child-scoped context receiving the tool and the guidance.
+* @param ctx - service context used for delivery.
+* @param delivery - resolved deployment scheduling policy.
+* @returns disposer that attempts both child registrations before reporting cleanup failures.
+*/
+function installReportTool(childCtx, ctx, delivery) {
+	const disposeSection = childCtx.systemPrompt.section({
+		name: "tool:report",
+		order: REPORT_SECTION_ORDER,
+		text: "Deliver your result with the report tool before you finish: call it once with a self-contained answer. The agent that started you shares your workspace but does not automatically receive your transcript, tool output, or reasoning, so a closing remark such as \"done\" leaves it nothing it can use. Report earlier as well whenever a partial finding changes what that agent should do next; reporting never ends your turn."
+	});
+	let disposeTool;
+	try {
+		disposeTool = childCtx.tools.register(defineTool({
+			name: "report",
+			description: "Report selected content to the agent that started you. Call this once before you finish, with a self-contained final result, and earlier for progress or findings that change what that agent does next. That agent shares your workspace but does not automatically receive your transcript, tool output, or reasoning, so finishing your work is not itself a result. Reporting does not end your turn or finish your work, and only your direct parent receives it. A failed call may still have arrived, so do not blindly repeat it.",
+			parameters: { output: {
+				type: "string",
+				required: true,
+				description: "Actionable content for your parent; summarize conclusions and reference relevant shared paths."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { messageId: {
+						type: "string",
+						required: true
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `report accepted by the agent that started you as message ${value.messageId}`
+				}]
+			},
+			async execute(args, exec) {
+				const content = [{
+					type: "text",
+					text: args.output
+				}];
+				return { messageId: await ctx.subagents.reportFrom(exec.agent, content, {
+					delivery,
+					signal: exec.signal
+				}) };
+			}
+		}));
+	} catch (error) {
+		try {
+			disposeSection();
+		} catch (rollbackError) {
+			throw new AggregateError([error, rollbackError], "failed to register the report tool and roll back its prompt guidance");
+		}
+		throw error;
+	}
+	return () => {
+		const failures = [];
+		for (const dispose of [disposeTool, disposeSection]) try {
+			dispose();
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures.length > 0) throw new AggregateError(failures, "failed to revoke report tool and prompt registrations");
+	};
+}
+/**
+* Register the continuable-child contribution.
+* @param ctx - context carrying tools, the system prompt, and the subagent service.
+* @param config - deployment scheduling policy.
+*/
+function apply(ctx, config = {}) {
+	const { reportDelivery } = Config(config);
+	ctx.subagents.registerContinuableSetup((childCtx) => installReportTool(childCtx, ctx, reportDelivery));
+}
+//#endregion
+export { Config, apply, inject, installReportTool, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-tool-subagent-report`.
+* @module @hydraharness/harness-tool-subagent-report/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-subagent-report";
+/** Cordis companion plugin name. */
+const name = "tool-subagent-report-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this adapter has no independent lifecycle stream;
+* sender authorization and delivery relations belong to the subagent service.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - context carrying the invariant service.
+* @returns the registration 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,39 @@
+/**
+ * The child-scoped `report` tool and its usage guidance, installed into every
+ * continuable in-process child's unpublished context. Roots, one-shot children,
+ * remote providers, and agentless executions never see the registration.
+ *
+ * @module @hydraharness/harness-tool-subagent-report
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { SubagentReportDelivery } from '@hydraharness/harness-subagent';
+export declare const name = "tool-subagent-report";
+export declare const inject: string[];
+/** Config: how accepted reports are scheduled on the parent. */
+export interface Config {
+    /**
+     * Parent scheduling (default `next-step`). `next-step` wakes the parent and
+     * enters at its nearest step boundary; `quiet` adds the same context without
+     * waking, so a parked parent waits for another waking input.
+     */
+    reportDelivery?: SubagentReportDelivery;
+}
+export declare const Config: z<Config>;
+/**
+ * Install `report` and its usage guidance into one continuable child's scope.
+ * Both registrations are owned by that scope and are therefore invisible to the
+ * child's parent and siblings.
+ * @param childCtx - child-scoped context receiving the tool and the guidance.
+ * @param ctx - service context used for delivery.
+ * @param delivery - resolved deployment scheduling policy.
+ * @returns disposer that attempts both child registrations before reporting cleanup failures.
+ */
+export declare function installReportTool(childCtx: Context, ctx: Context, delivery: SubagentReportDelivery): () => void;
+/**
+ * Register the continuable-child contribution.
+ * @param ctx - context carrying tools, the system prompt, and the subagent service.
+ * @param config - deployment scheduling policy.
+ */
+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-report`.
+ * @module @hydraharness/harness-tool-subagent-report/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-subagent-report-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - context carrying the invariant service.
+ * @returns the registration disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@hydraharness/harness-tool-subagent-report",
+  "description": "Child-scoped report tool over ctx.subagents continuations",
+  "hydra": {
+    "plugin": {
+      "application": "Let a child agent report its progress or findings to its parent."
+    }
+  },
+  "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-report"
+  },
+  "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-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop-testkit": "^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-session-persistence-jsonl": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-tool-subagent-control": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}