fix(core): preserve single-tool user-facing output

Author: NubsCarson

packages/core/src/__tests__/planner-happy-path.test.ts

@@ -465,6 +465,65 @@ describe("v5 happy path — message handler → planner → executor → evaluat
 		expect(evalStage?.evaluation?.decision).toBe("FINISH");
 	});
 
+	it("prefers a single tool's verified user-facing text over evaluator paraphrase", async () => {
+		const inspectRuntime = makeMockAction({
+			name: "CHECK_RUNTIME",
+			parameters: [],
+			handler: async () => ({
+				success: true,
+				text: "raw shell output with exact paths and metrics",
+				userFacingText:
+					"Root disk: 65% used, 138G available. Biggest cleanup candidate: /home/milady/.bun (19G).",
+				data: { actionName: "CHECK_RUNTIME" },
+			}),
+		});
+
+		const runtime = makeRuntime({
+			actions: [inspectRuntime],
+			responses: [
+				{
+					expectModelType: ModelType.RESPONSE_HANDLER,
+					body: stage1Response({
+						contexts: ["general"],
+						candidateActionNames: ["CHECK_RUNTIME"],
+						thought: "Runtime inspection needs a tool.",
+					}),
+				},
+				{
+					expectModelType: ModelType.ACTION_PLANNER,
+					body: {
+						text: "Checking runtime state.",
+						toolCalls: [{ id: "call-1", name: "CHECK_RUNTIME", args: {} }],
+					},
+				},
+				{
+					expectModelType: ModelType.RESPONSE_HANDLER,
+					body: JSON.stringify({
+						success: true,
+						decision: "FINISH",
+						thought: "Tool result is enough.",
+						messageToUser:
+							"Root disk: 65% used, 138G available. Biggest cleanup candidate: /home/milody/.bun (19G).",
+					}),
+				},
+			],
+		});
+
+		const result = await runV5MessageRuntimeStage1({
+			runtime,
+			message: makeMessage("check disk space"),
+			state: makeState(),
+			responseId: RESPONSE_ID,
+		});
+
+		expect(result.kind).toBe("planned_reply");
+		if (result.kind === "planned_reply") {
+			expect(result.result.responseContent?.text).toBe(
+				"Root disk: 65% used, 138G available. Biggest cleanup candidate: /home/milady/.bun (19G).",
+			);
+		}
+	});
+
 	it("records terminal task failure separately from evaluator failures", async () => {
 		const brokenAction = makeMockAction({
 			name: "BROKEN_ACTION",

packages/core/src/runtime/planner-loop.ts

@@ -264,9 +264,10 @@ export async function runPlannerLoop(
 							trajectory,
 							evaluator,
 							finalMessage: userSafeFinalMessage(
-								evaluator.messageToUser ??
-									plannerOutput.messageToUser ??
-									latestToolResultText(trajectory),
+								preferredFinalMessageFromToolOrModel(
+									trajectory,
+									evaluator.messageToUser ?? plannerOutput.messageToUser,
+								),
 								trajectory,
 							),
 						};
@@ -518,7 +519,7 @@ export async function runPlannerLoop(
 				trajectory,
 				evaluator: gated,
 				finalMessage: userSafeFinalMessage(
-					gated.messageToUser ?? latestToolResultText(trajectory),
+					preferredFinalMessageFromToolOrModel(trajectory, gated.messageToUser),
 					trajectory,
 				),
 			};
@@ -550,11 +551,13 @@ export async function runPlannerLoop(
 				trajectory,
 				evaluator,
 				finalMessage: userSafeFinalMessage(
-					evaluator.messageToUser ??
-						latestToolResultText(trajectory) ??
-						(evaluator.success === false
+					preferredFinalMessageFromToolOrModel(
+						trajectory,
+						evaluator.messageToUser,
+						evaluator.success === false
 							? failedToolFallbackMessage(trajectory)
-							: undefined),
+							: undefined,
+					),
 					trajectory,
 				),
 			};
@@ -2175,6 +2178,32 @@ function latestToolResultText(
 	return undefined;
 }
 
+function singleSuccessfulUserFacingToolResultText(
+	trajectory: PlannerTrajectory,
+): string | undefined {
+	const toolResultSteps = trajectory.steps.filter(
+		(step) => step.toolCall && step.result,
+	);
+	if (toolResultSteps.length !== 1) return undefined;
+	const result = toolResultSteps[0]?.result;
+	if (result?.success !== true) return undefined;
+	const text = result.userFacingText?.trim();
+	return text || undefined;
+}
+
+function preferredFinalMessageFromToolOrModel(
+	trajectory: PlannerTrajectory,
+	modelMessage?: unknown,
+	fallback?: unknown,
+): string | undefined {
+	return (
+		singleSuccessfulUserFacingToolResultText(trajectory) ??
+		getNonEmptyString(modelMessage) ??
+		latestToolResultText(trajectory) ??
+		getNonEmptyString(fallback)
+	);
+}
+
 function latestFailedToolStep(
 	trajectory: PlannerTrajectory,
 ): PlannerStep | undefined {