fix(subagents): avoid unnecessary result reads

Author: ALX99

home/.pi/agent/extensions/subagents/bootstrap.ts

@@ -6,7 +6,7 @@ import { CleanupAggregateError, type AgentQuestion, type AgentSummary } from "./
 import { loadProfiles, type ProfilesConfig } from "./profiles.ts";
 import type { RunUsage } from "./run-state.ts";
 import { SpawnAdmissionController } from "./spawn-admission.ts";
-import { activateForSubagentState, requiresExactResultRead } from "./tool-activation.ts";
+import { activateForSubagentState, activateSubagentTools, requiresExactResultRead } from "./tool-activation.ts";
 import { bindRegistryUi, notifyCompletion, type RegistryUiBinding } from "./ui/widget.ts";
 
 export const BACKGROUND_COMPLETION_DEBOUNCE_MS = 50;
@@ -161,6 +161,7 @@ export function registerSubagentLifecycle(pi: ExtensionAPI, runtime: DefaultSuba
 }
 
 function sendCompletions(pi: ExtensionAPI, summaries: readonly AgentSummary[]): void {
+	if (backgroundCompletionsNeedExactRead(summaries)) activateSubagentTools(pi, ["read_agent_result"]);
 	pi.sendMessage(
 		{
 			customType: "subagent-completion",
@@ -177,7 +178,24 @@ const BACKGROUND_COMPLETION_NOTICE =
 const BACKGROUND_RESULT_MAX_BYTES = 2 * 1024;
 const BACKGROUND_BATCH_MAX_BYTES = 16 * 1024;
 
+export function backgroundCompletionsNeedExactRead(summaries: readonly AgentSummary[]): boolean {
+	if (summaries.some((summary) => requiresExactResultRead(summary, BACKGROUND_RESULT_MAX_BYTES))) return true;
+	return (
+		summaries.some((summary) => summary.result !== undefined) &&
+		Buffer.byteLength(formatBackgroundCompletionContent(summaries), "utf8") > BACKGROUND_BATCH_MAX_BYTES
+	);
+}
+
 export function formatBackgroundCompletions(summaries: readonly AgentSummary[]): string {
+	const content = formatBackgroundCompletionContent(summaries);
+	const exactResultGuidance = backgroundCompletionsNeedExactRead(summaries)
+		? "\nUse read_agent_result with agent_id and generation when exact reconstruction is needed.\n"
+		: "";
+	const boundedContent = truncateHead(content, { maxBytes: BACKGROUND_BATCH_MAX_BYTES }).content;
+	return `${BACKGROUND_COMPLETION_NOTICE}${exactResultGuidance}\n${boundedContent}`;
+}
+
+function formatBackgroundCompletionContent(summaries: readonly AgentSummary[]): string {
 	const results = summaries.map((summary) => {
 		const output = escapeXml(
 			truncateHead(summary.final_text || summary.error || "(no output)", {
@@ -191,13 +209,7 @@ export function formatBackgroundCompletions(summaries: readonly AgentSummary[]):
 			: "";
 		return `<subagent_result agent_id="${escapeXmlAttribute(summary.agent_id)}" task_name="${escapeXmlAttribute(summary.task_name)}" generation="${summary.generation}" status="${escapeXmlAttribute(summary.status)}" profile="${escapeXmlAttribute(summary.profile)}" model="${escapeXmlAttribute(summary.model)}"${timing}>\n  <output>${output}</output>${usage}${resultReference}\n</subagent_result>`;
 	});
-	const content =
-		results.length === 1 ? (results[0] ?? "") : `<subagent_results>\n${results.join("\n")}\n</subagent_results>`;
-	const exactResultGuidance = summaries.some(requiresExactResultRead)
-		? "\nUse read_agent_result with agent_id and generation when exact reconstruction is needed.\n"
-		: "";
-	const boundedContent = truncateHead(content, { maxBytes: BACKGROUND_BATCH_MAX_BYTES }).content;
-	return `${BACKGROUND_COMPLETION_NOTICE}${exactResultGuidance}\n${boundedContent}`;
+	return results.length === 1 ? (results[0] ?? "") : `<subagent_results>\n${results.join("\n")}\n</subagent_results>`;
 }
 
 export function formatSubagentQuestion(summary: AgentSummary, question: AgentQuestion): string {

home/.pi/agent/extensions/subagents/result-store.ts

@@ -14,6 +14,7 @@ export const RESULT_READ_DEFAULT_BYTES = 6 * 1024;
 export const RESULT_READ_MAX_BYTES = 6 * 1024;
 export const RESULT_PREVIEW_MAX_BYTES = 4 * 1024;
 export const RESULT_PREVIEW_MAX_LINES = 100;
+export const RESULT_PREVIEW_TRUNCATION_NOTICE = "\n[Result preview truncated; use read_agent_result for exact output.]";
 
 const RESULT_ID_PATTERN = /^[0-9a-f]{64}$/;
 const ResultPageDataSchema = z.strictObject({
@@ -95,8 +96,7 @@ export interface ResultPage {
 
 /** Presentation-only text; the persisted result remains available by locator. */
 export function resultPreview(text: string): string {
-	const notice = "\n[Result preview truncated; use read_agent_result for exact output.]";
-	const maxContentBytes = RESULT_PREVIEW_MAX_BYTES - Buffer.byteLength(notice, "utf8");
+	const maxContentBytes = RESULT_PREVIEW_MAX_BYTES - Buffer.byteLength(RESULT_PREVIEW_TRUNCATION_NOTICE, "utf8");
 	let end = 0;
 	let bytes = 0;
 	let lines = 1;
@@ -110,7 +110,11 @@ export function resultPreview(text: string): string {
 		if (character === "\n") lines++;
 	}
 	if (end === text.length) return text;
-	return `${text.slice(0, end)}${notice}`;
+	return `${text.slice(0, end)}${RESULT_PREVIEW_TRUNCATION_NOTICE}`;
+}
+
+export function isTruncatedResultPreview(text: string): boolean {
+	return text.endsWith(RESULT_PREVIEW_TRUNCATION_NOTICE);
 }
 
 export interface ChildRunStats {

home/.pi/agent/extensions/subagents/tests/completion.test.ts

@@ -7,6 +7,7 @@ import type { AgentSummary } from "../agent-types.ts";
 import {
 	BACKGROUND_COMPLETION_DEBOUNCE_MS,
 	DefaultSubagentRuntime,
+	backgroundCompletionsNeedExactRead,
 	formatBackgroundCompletions,
 	formatSubagentQuestion,
 	isCompletionSuperseded,
@@ -79,6 +80,42 @@ test("background completions keep previews bounded and direct exact reads", () =
 	assert.ok(Buffer.byteLength(content, "utf8") < 3 * 1024);
 	assert.match(content, /read_agent_result/);
 	assert.match(content, /result_ref/);
+	assert.equal(
+		backgroundCompletionsNeedExactRead([
+			{
+				...summary(1),
+				final_text: "x".repeat(50 * 1024),
+				result: {
+					generation: 1,
+					result_id: "a".repeat(64),
+					pages: 9,
+					complete: true,
+					total_bytes: 50 * 1024,
+					sha256: "b".repeat(64),
+					source: "assistant",
+				},
+			},
+		]),
+		true,
+	);
+});
+
+test("complete background results do not direct exact reads", () => {
+	const result = {
+		...summary(1),
+		final_text: "complete result",
+		result: {
+			generation: 1,
+			result_id: "a".repeat(64),
+			pages: 1,
+			complete: true,
+			total_bytes: 15,
+			sha256: "b".repeat(64),
+			source: "assistant" as const,
+		},
+	};
+	assert.equal(backgroundCompletionsNeedExactRead([result]), false);
+	assert.doesNotMatch(formatBackgroundCompletions([result]), /read_agent_result/);
 });
 
 test("subagent questions serialize their routing fields as safe XML", () => {

home/.pi/agent/extensions/subagents/tests/tool-activation.test.ts

@@ -9,6 +9,7 @@ import {
 	requiresExactResultRead,
 	SUBAGENT_TOOL_NAMES,
 } from "../tool-activation.ts";
+import { resultPreview } from "../result-store.ts";
 
 function summary(overrides: Partial<AgentSummary> = {}): AgentSummary {
 	return {
@@ -130,14 +131,15 @@ test("routed questions and oversized results activate their matching tool", () =
 		"send_agent",
 	]);
 
+	const oversizedText = "x".repeat(50 * 1024);
 	const oversized = summary({
-		final_text: "x".repeat(50 * 1024),
+		final_text: resultPreview(oversizedText),
 		result: {
 			generation: 1,
 			result_id: "a".repeat(64),
 			pages: 1,
 			complete: true,
-			total_bytes: 50 * 1024,
+			total_bytes: Buffer.byteLength(oversizedText, "utf8"),
 			sha256: "a".repeat(64),
 			source: "pages",
 		},
@@ -148,7 +150,7 @@ test("routed questions and oversized results activate their matching tool", () =
 	assert.deepEqual(result.active(), ["spawn_agent", "read_agent_result"]);
 });
 
-test("every settled result activates exact reading, including small results", () => {
+test("complete small results do not activate exact reading", () => {
 	const result = toolApi(["spawn_agent"]);
 	activateForSubagentState(
 		result as never,
@@ -166,5 +168,22 @@ test("every settled result activates exact reading, including small results", ()
 		}),
 		false,
 	);
-	assert.deepEqual(result.active(), ["spawn_agent", "read_agent_result"]);
+	assert.equal(
+		requiresExactResultRead(
+			summary({
+				final_text: "small result",
+				result: {
+					generation: 1,
+					result_id: "a".repeat(64),
+					pages: 1,
+					complete: true,
+					total_bytes: 12,
+					sha256: "b".repeat(64),
+					source: "assistant",
+				},
+			}),
+		),
+		false,
+	);
+	assert.deepEqual(result.active(), ["spawn_agent"]);
 });

home/.pi/agent/extensions/subagents/tool-activation.ts

@@ -1,5 +1,6 @@
 import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentSummary } from "./agent-types.ts";
+import { isTruncatedResultPreview } from "./result-store.ts";
 
 export const SUBAGENT_TOOL_NAMES = [
 	"spawn_agent",
@@ -57,9 +58,12 @@ export function activateForSubagentState(
 	return activateSubagentTools(pi, names);
 }
 
-/** Native tool-output bounds may still require exact retrieval of an otherwise complete result. */
-export function requiresExactResultRead(summary: AgentSummary): boolean {
-	// Summaries intentionally contain only a preview, even for small results.
-	// The persisted terminal text is always reconstructed through the reader.
-	return summary.result !== undefined;
+/** The delivered terminal result is incomplete and must be reconstructed from storage. */
+export function requiresExactResultRead(summary: AgentSummary, maximumDisplayedBytes?: number): boolean {
+	if (summary.result === undefined) return false;
+	const text = summary.final_text ?? "";
+	return (
+		isTruncatedResultPreview(text) ||
+		(maximumDisplayedBytes !== undefined && Buffer.byteLength(text, "utf8") > maximumDisplayedBytes)
+	);
 }