Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(tasks): send the agent's report with the finish tool (#126478)

Harley Alexander422d2a64ded0
diff --git a/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts b/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts
index 5b493934fa42..a4f3d1d28373 100644
--- a/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts
@@ -33,6 +33,7 @@ const API_CONFIG: PostHogAPIConfig = {
type RequestFinish = (
status: "completed" | "failed",
message?: string,
+ report?: string,
) => Promise<void>;
function buildRequestFinish(
@@ -93,6 +94,16 @@ describe("ClaudeAcpAgent.buildRequestFinish", () => {
});
});
+ it("saves the report as the run's final message", async () => {
+ const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
+ await requestFinish?.("completed", undefined, "Opened 2 draft PRs");
+
+ expect(mocks.updateTaskRun).toHaveBeenCalledWith("task-1", "run-1", {
+ status: "completed",
+ output: { final_message: "Opened 2 draft PRs" },
+ });
+ });
+
it("marks the run failed with the message as error_message", async () => {
const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
await requestFinish?.("failed", "blocked on missing credentials");
diff --git a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
index 3b135e60f068..4193c630acc9 100644
--- a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
@@ -53,7 +53,9 @@ import {
type FileEnrichmentDeps,
} from "@posthog/harness/extensions/enrichment";
import {
+ buildFinishRunUpdate,
isCloudRun,
+ isFinishReportRequired,
LOCAL_TOOLS_MCP_NAME,
type LocalToolCtx,
resolveGithubToken,
@@ -3082,13 +3084,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
if (!config || !taskId || !taskRunId) {
return undefined;
}
- return async (status, message) => {
+ return async (status, message, report) => {
try {
- await new PostHogAPIClient(config).updateTaskRun(taskId, taskRunId, {
- status,
- ...(status === "failed" && message ? { error_message: message } : {}),
- ...(status === "failed" ? { error_type: "agent_declined" } : {}),
- });
+ await new PostHogAPIClient(config).updateTaskRun(
+ taskId,
+ taskRunId,
+ buildFinishRunUpdate(status, message, report),
+ );
} catch (error) {
this.logger.error("finish tool failed to mark run terminal", error);
throw error;
@@ -3191,6 +3193,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
taskRunId: meta?.taskRunId,
baseBranch,
requestFinish,
+ finishReportRequired: isFinishReportRequired({
+ taskOriginProduct,
+ endRunWhenDone,
+ }),
},
{
environment,
diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts
index 3a577b2cf711..b01b25085211 100644
--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts
+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts
@@ -42,6 +42,7 @@ let parsed: {
taskRunId?: string;
token?: string;
baseBranch?: string;
+ finishReportRequired?: boolean;
};
try {
parsed = JSON.parse(Buffer.from(ctxEnv, "base64").toString("utf-8"));
@@ -59,6 +60,7 @@ const ctx: LocalToolCtx = {
taskId: parsed.taskId,
taskRunId: parsed.taskRunId,
baseBranch: parsed.baseBranch,
+ finishReportRequired: parsed.finishReportRequired,
};
const enabledNames = (process.env.POSTHOG_LOCAL_TOOLS_ENABLED ?? "")
diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts
index a48fd8cedc3a..3c8a6a3db6f8 100644
--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts
+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts
@@ -62,6 +62,8 @@ describe("buildLocalToolsServer", () => {
taskId: "task-1",
taskRunId: "run-1",
baseBranch: "master",
+ taskOriginProduct: "workflow",
+ endRunWhenDone: true,
},
);
@@ -96,6 +98,7 @@ describe("buildLocalToolsServer", () => {
expect(ctx.taskId).toBe("task-1");
expect(ctx.taskRunId).toBe("run-1");
expect(ctx.baseBranch).toBe("master");
+ expect(ctx.finishReportRequired).toBe(true);
});
it("returns a server but omits token env vars when no token is present", () => {
diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts
index 70afcfd64142..876dd59828bc 100644
--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts
+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts
@@ -9,6 +9,7 @@ import type { McpServerStdio } from "@agentclientprotocol/sdk";
import { ghTokenEnv } from "@posthog/git/signed-commit";
import {
enabledLocalTools,
+ isFinishReportRequired,
LOCAL_TOOLS_MCP_NAME,
type LocalToolCtx,
type LocalToolGateMeta,
@@ -83,6 +84,7 @@ export function buildLocalToolsServer(
taskId: resolveTaskId(meta),
taskRunId: meta?.taskRunId,
baseBranch: meta?.baseBranch,
+ finishReportRequired: isFinishReportRequired(meta),
};
const names = enabledLocalTools(toolCtx, meta).map((tool) => tool.name);
if (isTaskRunSandbox(process.env)) names.push(MEMORY_KILL_HOOK_TOOL_NAME);
diff --git a/packages/agent/packages/harness/src/extensions/local-tools/index.ts b/packages/agent/packages/harness/src/extensions/local-tools/index.ts
index 2ce7560546d2..ec530182d097 100644
--- a/packages/agent/packages/harness/src/extensions/local-tools/index.ts
+++ b/packages/agent/packages/harness/src/extensions/local-tools/index.ts
@@ -38,7 +38,11 @@ export {
type SignedCommitToolResult,
} from "./signed-commit-shared";
export { TaskToolsApiClient, TaskToolsApiError } from "./task-tools-client";
-export { FINISH_TOOL_NAME } from "./tools/finish";
+export {
+ buildFinishRunUpdate,
+ FINISH_TOOL_NAME,
+ isFinishReportRequired,
+} from "./tools/finish";
export { GH_STACK_QUALIFIED_TOOL_NAME } from "./tools/gh-stack";
export { SHOW_ACTIONS_TOOL_NAME } from "./tools/show-actions";
export { SPEAK_TOOL_NAME } from "./tools/speak";
diff --git a/packages/agent/packages/harness/src/extensions/local-tools/registry.ts b/packages/agent/packages/harness/src/extensions/local-tools/registry.ts
index dde09ad3efbb..e339fcf2b085 100644
--- a/packages/agent/packages/harness/src/extensions/local-tools/registry.ts
+++ b/packages/agent/packages/harness/src/extensions/local-tools/registry.ts
@@ -30,7 +30,13 @@ export interface LocalToolCtx {
requestFinish?: (
status: "completed" | "failed",
message?: string,
+ report?: string,
) => Promise<void>;
+ /**
+ * A later workflow step reads this run's final message, so `finish` refuses to
+ * end the run without a report. Set from `isFinishReportRequired(meta)`.
+ */
+ finishReportRequired?: boolean;
}
/** Minimal session-meta shape needed to gate tools (e.g. cloud-only). */
diff --git a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts
index a74fce385aa1..825e1e445be2 100644
--- a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts
+++ b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts
@@ -9,7 +9,13 @@ vi.mock("../signed-commit-artefacts", async (importOriginal) => ({
import { enabledLocalTools } from "../index";
import type { LocalToolCtx, LocalToolGateMeta } from "../registry";
-import { FINISH_TOOL_NAME, finishSchema, finishTool } from "./finish";
+import {
+ buildFinishRunUpdate,
+ FINISH_REPORT_MAX_CHARS,
+ FINISH_TOOL_NAME,
+ finishSchema,
+ finishTool,
+} from "./finish";
describe("finish tool", () => {
const requestFinish = async (): Promise<void> => {};
@@ -174,9 +180,17 @@ describe("finish tool", () => {
const spy = vi.fn(async () => {});
const result = await finishTool.handler(
{ cwd: "/repo", requestFinish: spy },
- { status: "failed", reason: "ran out of quota" },
+ {
+ status: "failed",
+ reason: "ran out of quota",
+ report: "Partial report",
+ },
+ );
+ expect(spy).toHaveBeenCalledWith(
+ "failed",
+ "ran out of quota",
+ "Partial report",
);
- expect(spy).toHaveBeenCalledWith("failed", "ran out of quota");
expect(result.isError).toBeUndefined();
});
@@ -199,6 +213,57 @@ describe("finish tool", () => {
expect(result.isError).toBeUndefined();
});
+ it.each(["", " "])(
+ "keeps a report-required run open when the report is %j",
+ async (report) => {
+ const spy = vi.fn(async () => {});
+ const result = await finishTool.handler(
+ { cwd: "/repo", requestFinish: spy, finishReportRequired: true },
+ { status: "completed", report },
+ );
+ expect(spy).not.toHaveBeenCalled();
+ expect(result.isError).toBe(true);
+ },
+ );
+
+ const rejectOnce = (status: number) =>
+ vi
+ .fn<NonNullable<LocalToolCtx["requestFinish"]>>()
+ .mockRejectedValueOnce(Object.assign(new Error("rejected"), { status }))
+ .mockResolvedValue(undefined);
+
+ it.each([400, 403])(
+ "ends the run without the report when the backend rejects it (%i)",
+ async (status) => {
+ const spy = rejectOnce(status);
+ const result = await finishTool.handler(
+ { cwd: "/repo", requestFinish: spy },
+ { status: "completed", report: "Full report" },
+ );
+ expect(result.isError).toBeUndefined();
+ expect(spy).toHaveBeenLastCalledWith("completed", undefined);
+ },
+ );
+
+ it("keeps the report when the finish fails for another reason", async () => {
+ const spy = rejectOnce(500);
+ await expect(
+ finishTool.handler(
+ { cwd: "/repo", requestFinish: spy },
+ { status: "completed", report: "Full report" },
+ ),
+ ).rejects.toThrow("rejected");
+ expect(spy).toHaveBeenCalledTimes(1);
+ });
+
+ it("cuts a long report without splitting a surrogate pair", () => {
+ const report = `${"a".repeat(FINISH_REPORT_MAX_CHARS - 1)}😀😀`;
+ const finalMessage = buildFinishRunUpdate("completed", undefined, report)
+ .output?.final_message as string;
+ expect(finalMessage).toBe(`${"a".repeat(FINISH_REPORT_MAX_CHARS - 1)}😀`);
+ expect(finalMessage.isWellFormed()).toBe(true);
+ });
+
it("errors when requestFinish is unavailable", async () => {
const result = await finishTool.handler(
{ cwd: "/repo" },
diff --git a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts
index a9fd597c93c3..594fda80fb0b 100644
--- a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts
+++ b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts
@@ -2,12 +2,14 @@ import { z } from "zod";
import {
defineLocalTool,
type LocalToolCtx,
+ type LocalToolGateMeta,
type LocalToolResult,
} from "../registry";
import {
createSandboxPosthogClient,
withReportDeadline,
} from "../signed-commit-artefacts";
+import type { TaskRunUpdate } from "../task-tools-client";
export const FINISH_TOOL_NAME = "finish";
@@ -28,8 +30,60 @@ export const finishSchema = {
"Short note on why you're stopping — recorded on the run. Required-in- " +
"spirit for 'failed': say what blocked you so a human can pick it up.",
),
+ report: z
+ .string()
+ .optional()
+ .describe(
+ "Your final report: the full answer your instructions asked for. " +
+ "Workflow steps after this run read it, so put the complete report " +
+ "here, not a pointer to an earlier message.",
+ ),
};
+// Kept equal to FINAL_MESSAGE_MAX_CHARS in products/tasks/backend/constants.py.
+export const FINISH_REPORT_MAX_CHARS = 20_000;
+
+/** The task run PATCH that the `finish` tool sends. */
+export function buildFinishRunUpdate(
+ status: "completed" | "failed",
+ message?: string,
+ report?: string,
+): TaskRunUpdate {
+ return {
+ status,
+ ...(status === "failed" && message ? { error_message: message } : {}),
+ ...(status === "failed" ? { error_type: "agent_declined" } : {}),
+ // The relay saves the final message only when the turn ends, and `finish`
+ // ends the run before that, so the report travels with the status change.
+ ...(report
+ ? {
+ output: {
+ // Cut by code point: a split surrogate pair makes Postgres reject the JSONB write.
+ final_message: Array.from(report)
+ .slice(0, FINISH_REPORT_MAX_CHARS)
+ .join(""),
+ },
+ }
+ : {}),
+ };
+}
+
+/** A workflow run that opts into `finish` hands its report to the next step. */
+export function isFinishReportRequired(
+ meta: LocalToolGateMeta | undefined,
+): boolean {
+ return (
+ meta?.taskOriginProduct === "workflow" && meta?.endRunWhenDone === true
+ );
+}
+
+// A backend without finish-report support rejects the `output` field: 400 from
+// the run serializer, 403 for a scout trial token.
+function isReportRejected(error: unknown): boolean {
+ const status = (error as { status?: unknown } | null)?.status;
+ return status === 400 || status === 403;
+}
+
const FINISH_TOOL_DESCRIPTION =
"End this run and release the sandbox. This is an unattended background run: " +
"nothing else will stop it promptly, so calling `finish` is how the machine " +
@@ -38,7 +92,8 @@ const FINISH_TOOL_DESCRIPTION =
"or checks you were waiting on have settled, and you've delivered whatever " +
"your instructions asked for (or deliberately skipped delivery per those " +
"instructions). Do NOT call it while you're still working or still waiting on " +
- "something to finish. After it returns, stop — the run is over.";
+ "something to finish. Pass your final report in `report`. After it returns, " +
+ "stop — the run is over.";
/**
* Lets the model end its own background run. The handler calls back into the
@@ -64,19 +119,13 @@ function resolveRequestFinish(
if (!client) {
return undefined;
}
- return async (status, message) => {
+ return async (status, message, report) => {
await withReportDeadline(
(signal) =>
client.updateTaskRun(
taskId,
taskRunId,
- {
- status,
- ...(status === "failed" && message
- ? { error_message: message }
- : {}),
- ...(status === "failed" ? { error_type: "agent_declined" } : {}),
- },
+ buildFinishRunUpdate(status, message, report),
signal,
),
"run finish",
@@ -120,7 +169,34 @@ export const finishTool = defineLocalTool({
isError: true,
};
}
- await requestFinish(args.status, args.reason);
+ if (ctx.finishReportRequired && !args.report?.trim()) {
+ return {
+ content: [
+ {
+ type: "text",
+ text: "The run is still open. A workflow step reads this run's report, so call `finish` again with your full final report in `report`.",
+ },
+ ],
+ isError: true,
+ };
+ }
+ try {
+ await requestFinish(args.status, args.reason, args.report);
+ } catch (error) {
+ if (!args.report || !isReportRejected(error)) {
+ throw error;
+ }
+ // Ending the run without its report beats leaving it active until the idle timeout.
+ await requestFinish(args.status, args.reason);
+ return {
+ content: [
+ {
+ type: "text",
+ text: `Run marked ${args.status}, but the backend did not accept the report. Stop here.`,
+ },
+ ],
+ };
+ }
return {
content: [
{