Expose subagent final metadata in ended hook

anyech · Clawsistant · commit 4f3665d4ac2f · 2026-05-04T06:53:15.000Z
Add privacy-minimal metadata to subagent_ended hook events when a frozen child final result is available. Include only availability, hash, byte length, and capture timestamp so hook consumers can correlate final-ready completion without receiving raw final text.

Document and test that the digest covers the exact UTF-8 bytes of frozenResultText for non-blank values.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -423,6 +423,7 @@ Docs: https://docs.openclaw.ai
 - Agents/runtime: reuse the startup-loaded plugin registry for request-time providers, tools, channel actions, web/capability/memory/migration helpers, and memoized provider extra-params so stable embedded-run inputs no longer repeat plugin registry resolution while model-specific transport hook patches stay isolated. Thanks @DmitryPogodaev.
 - Agents/runtime: memoize transcript replay-policy resolution for stable config and process-env runs while preserving custom-env provider hook behavior. Thanks @DmitryPogodaev.
 - Infra/path-guards: add a fast path for canonical absolute POSIX containment checks, avoiding repeated `path.resolve` and `path.relative` work in hot filesystem walkers. Refs #75895, #75575, and #68782. Thanks @Enderfga.
+- Subagents/hooks: expose privacy-minimal frozen final metadata on `subagent_ended` hook events so plugins can correlate final-ready completions without receiving raw final text. Thanks @anyech.
 - Tools: add a platform-level tool descriptor planner for descriptor-first visibility, generic availability checks, and executor references. Thanks @shakkernerd.
 - Plugins/tools: cache plugin tool descriptors captured from `api.registerTool(...)` so repeated prompt-time planning can skip plugin runtime loading while execution still loads the live plugin tool. (#76079) Thanks @shakkernerd.
 - Docs/Codex: clarify that ChatGPT/Codex subscription setups should use `openai/gpt-*` with `agentRuntime.id: "codex"` for native Codex runtime, while `openai-codex/*` remains the PI OAuth route. Thanks @pashpashpash.
diff --git a/src/agents/subagent-registry-completion.test.ts b/src/agents/subagent-registry-completion.test.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { SUBAGENT_ENDED_REASON_COMPLETE } from "./subagent-lifecycle-events.js";
 import type { SubagentRunRecord } from "./subagent-registry.types.js";
@@ -40,6 +41,24 @@ describe("emitSubagentEndedHookOnce", () => {
     };
   };
 
+  const readLastSubagentEndedEvent = () => {
+    const calls = lifecycleMocks.runSubagentEnded.mock.calls as unknown as Array<
+      [
+        {
+          final?: {
+            frozenResultTextAvailable: true;
+            textSha256: string;
+            byteLength: number;
+            capturedAt?: number;
+          };
+        },
+      ]
+    >;
+    const event = calls.at(-1)?.[0];
+    expect(event).toBeDefined();
+    return event!;
+  };
+
   beforeAll(async () => {
     mod = await import("./subagent-registry-completion.js");
   });
@@ -112,6 +131,82 @@ describe("emitSubagentEndedHookOnce", () => {
     expect(params.persist).toHaveBeenCalledTimes(1);
   });
 
+  it("includes privacy-minimal frozen final metadata on subagent_ended", async () => {
+    lifecycleMocks.getGlobalHookRunner.mockReturnValue({
+      hasHooks: () => true,
+      runSubagentEnded: lifecycleMocks.runSubagentEnded,
+    });
+
+    const finalText = "  child final answer 雪🚀  \n";
+    const capturedAt = Date.now() - 100;
+    const entry = {
+      ...createRunEntry(),
+      frozenResultText: finalText,
+      frozenResultCapturedAt: capturedAt,
+    };
+    const params = createEmitParams({ entry });
+    const emitted = await mod.emitSubagentEndedHookOnce(params);
+
+    expect(emitted).toBe(true);
+    expect(lifecycleMocks.runSubagentEnded).toHaveBeenCalledTimes(1);
+    const event = readLastSubagentEndedEvent();
+    expect(event).toMatchObject({
+      final: {
+        frozenResultTextAvailable: true,
+        textSha256: createHash("sha256").update(finalText, "utf8").digest("hex"),
+        byteLength: Buffer.byteLength(finalText, "utf8"),
+        capturedAt,
+      },
+    });
+    expect(event?.final?.textSha256).not.toBe(
+      createHash("sha256").update(finalText.trim(), "utf8").digest("hex"),
+    );
+    expect(JSON.stringify(event)).not.toContain(finalText);
+  });
+
+  it("includes frozen final metadata when capture timestamp is missing", async () => {
+    lifecycleMocks.getGlobalHookRunner.mockReturnValue({
+      hasHooks: () => true,
+      runSubagentEnded: lifecycleMocks.runSubagentEnded,
+    });
+
+    const finalText = "final without timestamp";
+    const entry = {
+      ...createRunEntry(),
+      frozenResultText: finalText,
+    };
+    const params = createEmitParams({ entry });
+    const emitted = await mod.emitSubagentEndedHookOnce(params);
+
+    expect(emitted).toBe(true);
+    const event = readLastSubagentEndedEvent();
+    expect(event.final).toEqual({
+      frozenResultTextAvailable: true,
+      textSha256: createHash("sha256").update(finalText, "utf8").digest("hex"),
+      byteLength: Buffer.byteLength(finalText, "utf8"),
+    });
+  });
+
+  it("omits frozen final metadata when no useful final text was captured", async () => {
+    lifecycleMocks.getGlobalHookRunner.mockReturnValue({
+      hasHooks: () => true,
+      runSubagentEnded: lifecycleMocks.runSubagentEnded,
+    });
+
+    const params = createEmitParams({
+      entry: {
+        ...createRunEntry(),
+        frozenResultText: "   ",
+        frozenResultCapturedAt: Date.now(),
+      },
+    });
+    const emitted = await mod.emitSubagentEndedHookOnce(params);
+
+    expect(emitted).toBe(true);
+    const event = readLastSubagentEndedEvent();
+    expect(event.final).toBeUndefined();
+  });
+
   it("returns false when the global hook runner is not initialized yet", async () => {
     lifecycleMocks.getGlobalHookRunner.mockReturnValue(null);
 
diff --git a/src/agents/subagent-registry-completion.ts b/src/agents/subagent-registry-completion.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
 import type { SubagentRunOutcome } from "./subagent-announce-output.js";
 import {
@@ -63,6 +64,29 @@ export function resolveLifecycleOutcomeFromRunOutcome(
   return SUBAGENT_ENDED_OUTCOME_OK;
 }
 
+/**
+ * Build privacy-minimal metadata for the exact frozen child final string.
+ *
+ * Blank/whitespace-only finals are omitted, but non-blank values are not
+ * trimmed or otherwise canonicalized before hashing. `textSha256` is SHA-256
+ * over the exact UTF-8 bytes of `entry.frozenResultText`, and `byteLength` is
+ * that same UTF-8 byte count.
+ */
+export function buildSubagentEndedFinalMetadata(entry: SubagentRunRecord) {
+  const text = typeof entry.frozenResultText === "string" ? entry.frozenResultText : undefined;
+  if (!text?.trim()) {
+    return undefined;
+  }
+  return {
+    frozenResultTextAvailable: true as const,
+    textSha256: createHash("sha256").update(text, "utf8").digest("hex"),
+    byteLength: Buffer.byteLength(text, "utf8"),
+    ...(entry.frozenResultCapturedAt === undefined
+      ? {}
+      : { capturedAt: entry.frozenResultCapturedAt }),
+  };
+}
+
 export async function emitSubagentEndedHookOnce(params: {
   entry: SubagentRunRecord;
   reason: SubagentLifecycleEndedReason;
@@ -102,6 +126,7 @@ export async function emitSubagentEndedHookOnce(params: {
           endedAt: params.entry.endedAt,
           outcome: params.outcome,
           error: params.error,
+          final: buildSubagentEndedFinalMetadata(params.entry),
         },
         {
           runId: params.entry.runId,
diff --git a/src/plugins/hook-types.ts b/src/plugins/hook-types.ts
@@ -582,6 +582,22 @@ export type PluginHookSubagentEndedEvent = {
   endedAt?: number;
   outcome?: "ok" | "error" | "timeout" | "killed" | "reset" | "deleted";
   error?: string;
+  /**
+   * Privacy-minimal metadata about the frozen child final result, when one was
+   * captured before the lifecycle hook emitted. Raw final text is intentionally
+   * not included; consumers that need content must resolve it from an
+   * explicitly authorized store/contract.
+   *
+   * The digest and byte length are computed from the exact UTF-8 bytes of the
+   * stored frozen final string. Non-blank values are not trimmed or otherwise
+   * canonicalized before hashing.
+   */
+  final?: {
+    frozenResultTextAvailable: true;
+    textSha256: string;
+    byteLength: number;
+    capturedAt?: number;
+  };
 };
 
 export type PluginHookGatewayContext = {
