fix(agents): stop raw tool output leaking into subagent completion announces

blaspat · blaspat · commit d43cb97054e1 · 2026-05-10T10:52:55.000+07:00
selectSubagentOutputText() was falling through to snapshot.latestRawText
when no assistant-produced text was available. Raw tool output is not
user-facing content and must not be delivered as completion text.

Fix: return undefined instead of snapshot.latestRawText so the caller
falls back to readLatestAssistantReply (post-compaction result) or
synthesizes a bounded failure summary.

Updated tests that expected raw tool output to be announced — they now
correctly expect '(no output)' since no assistant-composed text exists.

Signed-off-by: Blasius Patrick &lt;blasius.patrick@gmail.com&gt;
diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md
@@ -94,7 +94,7 @@ requester chat when the run finishes.
     The completion handoff to the requester session is runtime-generated
     internal context (not user-authored text) and includes:
 
-    - `Result` — latest visible `assistant` reply text, otherwise sanitized latest tool/toolResult text. Terminal failed runs do not reuse captured reply text.
+    - `Result` — latest visible `assistant` reply text, otherwise `(no output)`. Terminal failed runs do not reuse captured reply text.
     - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
     - Compact runtime/token stats.
     - A delivery instruction telling the requester agent to rewrite in normal assistant voice (not forward raw internal metadata).
@@ -432,7 +432,7 @@ Announce context is normalized to a stable internal event block:
 | Session ids    | Child session key/id                                                                                          |
 | Type           | Announce type + task label                                                                                    |
 | Status         | Derived from runtime outcome (`success`, `error`, `timeout`, or `unknown`) — **not** inferred from model text |
-| Result content | Latest visible assistant text, otherwise sanitized latest tool/toolResult text                                |
+| Result content | Latest visible assistant text; `(no output)` if no assistant text is available                                |
 | Follow-up      | Instruction describing when to reply vs stay silent                                                           |
 
 Terminal failed runs report failure status without replaying captured
diff --git a/src/agents/subagent-announce-output.ts b/src/agents/subagent-announce-output.ts
@@ -301,7 +301,12 @@ function selectSubagentOutputText(
   if (partialProgress) {
     return partialProgress;
   }
-  return snapshot.latestRawText;
+  // Do not fall through to snapshot.latestRawText — raw tool output is not
+  // user-facing content and must not be delivered as completion text.  If no
+  // assistant-produced text is available, the caller should fall back to
+  // readLatestAssistantReply (post-compaction result) or synthesize a bounded
+  // failure summary.
+  return undefined;
 }
 
 export async function readSubagentOutput(
diff --git a/src/agents/subagent-announce.format.e2e.test.ts b/src/agents/subagent-announce.format.e2e.test.ts
@@ -634,7 +634,7 @@ describe("subagent announce formatting", () => {
 
       const call = agentSpy.mock.calls[0]?.[0] as { params?: { message?: string } };
       const msg = call?.params?.message as string;
-      expect(msg).toContain(testCase.toolOutput);
+      expect(msg).toContain("(no output)");
     },
   );
 
@@ -2022,7 +2022,7 @@ describe("subagent announce formatting", () => {
     expect(agentSpy).toHaveBeenCalledTimes(1);
     const call = agentSpy.mock.calls[0]?.[0] as { params?: { message?: string } };
     const msg = call?.params?.message as string;
-    expect(msg).toContain("tool output only");
+    expect(msg).toContain("(no output)");
   });
 
   it("ignores user text when deriving fallback completion output", async () => {

Original file line number	Diff line number	Diff line change
`@@ -301,7 +301,12 @@ function selectSubagentOutputText(`
`301`	`301`	`if (partialProgress) {`
`302`	`302`	`return partialProgress;`
`303`	`303`	`}`
`304`		`- return snapshot.latestRawText;`
	`304`	`+ // Do not fall through to snapshot.latestRawText — raw tool output is not`
	`305`	`+ // user-facing content and must not be delivered as completion text. If no`
	`306`	`+ // assistant-produced text is available, the caller should fall back to`
	`307`	`+ // readLatestAssistantReply (post-compaction result) or synthesize a bounded`
	`308`	`+ // failure summary.`
	`309`	`+ return undefined;`
`305`	`310`	`}`
`306`	`311`
`307`	`312`	`export async function readSubagentOutput(`