From 24096e6191490385a28db3d80e593bbc78ec082e Mon Sep 17 00:00:00 2001
From: Robbie Coomber <robbie.coomber@gmail.com>
Date: Wed, 20 May 2026 22:21:47 +0100
Subject: [PATCH 1/2] feat(agent): add long-running task loop with LLM-planned
 proposals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an auto-continuing turn loop that the agent enters when the user
approves a proposal block. While active, the harness pushes a continuation
user message after each end_turn until the agent emits a configured marker,
hits a max-iteration cap, or the user steers/stops.

The /long-running-task slash command sends a brief planning prompt with
hidden context — the agent explores the codebase, asks clarifying questions
via AskUserQuestion when intent is ambiguous, then emits the config as a
<long-running-task-config> JSON block. The renderer parses that block,
shows an inline confirmation card (editable goal/criterion/marker/max), and
on Start sets the server-side state via a new tRPC mutation + sends the
kickoff prompt.

While a task is active, a pill above the prompt input shows iterations
N/M + goal + a Stop button. Mid-loop user messages pause auto-continuation
for that turn so the user can steer.

Generated-By: PostHog Code
Task-Id: c1333c34-d768-47e2-9dda-d2e456ab701a
---
 apps/code/src/main/services/agent/schemas.ts  |  19 ++
 apps/code/src/main/services/agent/service.ts  |  36 +++
 apps/code/src/main/trpc/routers/agent.ts      |  10 +
 .../long-running-task/LongRunningTaskPill.tsx |  64 +++++
 .../LongRunningTaskProposalCard.tsx           | 225 ++++++++++++++++++
 .../features/message-editor/commands.ts       |  42 +++-
 .../sessions/components/SessionView.tsx       |  22 ++
 .../features/sessions/service/service.ts      |  62 +++++
 .../renderer/stores/longRunningTaskStore.ts   |  87 +++++++
 packages/agent/src/acp-extensions.ts          |  28 +++
 .../agent/src/adapters/claude/claude-agent.ts |  69 ++++++
 .../claude/long-running-task/utils.test.ts    |  64 +++++
 .../claude/long-running-task/utils.ts         | 187 +++++++++++++++
 .../adapters/claude/session/instructions.ts   |  53 ++++-
 packages/agent/src/adapters/claude/types.ts   |  10 +
 packages/agent/src/index.ts                   |   7 +-
 16 files changed, 982 insertions(+), 3 deletions(-)
 create mode 100644 apps/code/src/renderer/components/long-running-task/LongRunningTaskPill.tsx
 create mode 100644 apps/code/src/renderer/components/long-running-task/LongRunningTaskProposalCard.tsx
 create mode 100644 apps/code/src/renderer/stores/longRunningTaskStore.ts
 create mode 100644 packages/agent/src/adapters/claude/long-running-task/utils.test.ts
 create mode 100644 packages/agent/src/adapters/claude/long-running-task/utils.ts

diff --git a/apps/code/src/main/services/agent/schemas.ts b/apps/code/src/main/services/agent/schemas.ts
index 3ead6cf15b..ff1db8bfc1 100644
--- a/apps/code/src/main/services/agent/schemas.ts
+++ b/apps/code/src/main/services/agent/schemas.ts
@@ -159,6 +159,25 @@ export const cancelPromptInput = z.object({
   reason: interruptReasonSchema.optional(),
 });
 
+// Long-running task start/stop
+export const startLongRunningTaskInput = z.object({
+  sessionId: z.string(),
+  goal: z.string().min(1).max(2000),
+  successCriterion: z.string().min(1).max(1000),
+  marker: z.string().min(1).max(200).optional(),
+  maxIterations: z.number().int().positive().max(200).optional(),
+});
+
+export type StartLongRunningTaskInput = z.infer<
+  typeof startLongRunningTaskInput
+>;
+
+export const stopLongRunningTaskInput = z.object({
+  sessionId: z.string(),
+});
+
+export type StopLongRunningTaskInput = z.infer<typeof stopLongRunningTaskInput>;
+
 // Reconnect session input
 export const reconnectSessionInput = z.object({
   taskId: z.string(),
diff --git a/apps/code/src/main/services/agent/service.ts b/apps/code/src/main/services/agent/service.ts
index 4c3eecb07f..0c09b9d364 100644
--- a/apps/code/src/main/services/agent/service.ts
+++ b/apps/code/src/main/services/agent/service.ts
@@ -15,6 +15,7 @@ import {
 import {
   isMcpToolReadOnly,
   isNotification,
+  POSTHOG_METHODS,
   POSTHOG_NOTIFICATIONS,
 } from "@posthog/agent";
 import type { McpToolApprovals } from "@posthog/agent/adapters/claude/mcp/tool-metadata";
@@ -937,6 +938,41 @@ When creating pull requests, add the following footer at the end of the PR descr
     }
   }
 
+  async startLongRunningTask(input: {
+    sessionId: string;
+    goal: string;
+    successCriterion: string;
+    marker?: string;
+    maxIterations?: number;
+  }): Promise<void> {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${input.sessionId}`);
+    }
+    await session.clientSideConnection.extMethod(
+      POSTHOG_METHODS.START_LONG_RUNNING_TASK,
+      {
+        goal: input.goal,
+        successCriterion: input.successCriterion,
+        marker: input.marker,
+        maxIterations: input.maxIterations,
+      },
+    );
+  }
+
+  async stopLongRunningTask(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    try {
+      await session.clientSideConnection.extMethod(
+        POSTHOG_METHODS.STOP_LONG_RUNNING_TASK,
+        {},
+      );
+    } catch (err) {
+      log.error("Failed to stop long-running task", { sessionId, err });
+    }
+  }
+
   getSession(taskRunId: string): ManagedSession | undefined {
     return this.sessions.get(taskRunId);
   }
diff --git a/apps/code/src/main/trpc/routers/agent.ts b/apps/code/src/main/trpc/routers/agent.ts
index 98c20a8ce6..3f0f4b09c3 100644
--- a/apps/code/src/main/trpc/routers/agent.ts
+++ b/apps/code/src/main/trpc/routers/agent.ts
@@ -20,7 +20,9 @@ import {
   respondToPermissionInput,
   sessionResponseSchema,
   setConfigOptionInput,
+  startLongRunningTaskInput,
   startSessionInput,
+  stopLongRunningTaskInput,
   subscribeSessionInput,
 } from "../../services/agent/schemas";
 import type { AgentService } from "../../services/agent/service";
@@ -57,6 +59,14 @@ export const agentRouter = router({
       getService().cancelPrompt(input.sessionId, input.reason),
     ),
 
+  startLongRunningTask: publicProcedure
+    .input(startLongRunningTaskInput)
+    .mutation(({ input }) => getService().startLongRunningTask(input)),
+
+  stopLongRunningTask: publicProcedure
+    .input(stopLongRunningTaskInput)
+    .mutation(({ input }) => getService().stopLongRunningTask(input.sessionId)),
+
   reconnect: publicProcedure
     .input(reconnectSessionInput)
     .output(sessionResponseSchema.nullable())
diff --git a/apps/code/src/renderer/components/long-running-task/LongRunningTaskPill.tsx b/apps/code/src/renderer/components/long-running-task/LongRunningTaskPill.tsx
new file mode 100644
index 0000000000..899a824466
--- /dev/null
+++ b/apps/code/src/renderer/components/long-running-task/LongRunningTaskPill.tsx
@@ -0,0 +1,64 @@
+import { StopCircleIcon } from "@phosphor-icons/react";
+import { Box, Flex, IconButton, Text, Tooltip } from "@radix-ui/themes";
+import { trpcClient } from "@renderer/trpc/client";
+import { useLongRunningTaskStore } from "@stores/longRunningTaskStore";
+import { logger } from "@utils/logger";
+import { toast } from "@utils/toast";
+import { useCallback } from "react";
+
+const log = logger.scope("long-running-task-pill");
+
+interface LongRunningTaskPillProps {
+  taskRunId: string;
+}
+
+export function LongRunningTaskPill({ taskRunId }: LongRunningTaskPillProps) {
+  const task = useLongRunningTaskStore((s) => s.byTaskRunId[taskRunId]);
+
+  const stopLoop = useCallback(async () => {
+    try {
+      await trpcClient.agent.stopLongRunningTask.mutate({
+        sessionId: taskRunId,
+      });
+      toast.success("Long-running task stopped");
+    } catch (err) {
+      log.error("Failed to stop long-running task", { err });
+      toast.error("Failed to stop long-running task");
+    }
+  }, [taskRunId]);
+
+  if (!task?.active) return null;
+
+  return (
+    <Box className="rounded-md border border-iris-6 bg-iris-2 px-3 py-2">
+      <Flex align="center" gap="3" justify="between">
+        <Flex align="center" gap="2" className="min-w-0">
+          <Text size="1" weight="medium" className="shrink-0 text-iris-11">
+            Long-running task
+          </Text>
+          <Text size="1" className="shrink-0 text-iris-11">
+            • {task.iterations}/{task.maxIterations}
+          </Text>
+          {task.goal && (
+            <Tooltip content={task.goal}>
+              <Text size="1" truncate className="min-w-0 text-iris-12">
+                • {task.goal}
+              </Text>
+            </Tooltip>
+          )}
+        </Flex>
+        <Tooltip content="Stop the auto-continuation loop. Current turn finishes normally.">
+          <IconButton
+            size="1"
+            variant="ghost"
+            color="iris"
+            onClick={stopLoop}
+            aria-label="Stop long-running task"
+          >
+            <StopCircleIcon size={16} />
+          </IconButton>
+        </Tooltip>
+      </Flex>
+    </Box>
+  );
+}
diff --git a/apps/code/src/renderer/components/long-running-task/LongRunningTaskProposalCard.tsx b/apps/code/src/renderer/components/long-running-task/LongRunningTaskProposalCard.tsx
new file mode 100644
index 0000000000..6dc5aca6a0
--- /dev/null
+++ b/apps/code/src/renderer/components/long-running-task/LongRunningTaskProposalCard.tsx
@@ -0,0 +1,225 @@
+import { getSessionService } from "@features/sessions/service/service";
+import { Button, Flex, Text, TextArea, TextField } from "@radix-ui/themes";
+import { trpcClient } from "@renderer/trpc/client";
+import { useLongRunningTaskStore } from "@stores/longRunningTaskStore";
+import { logger } from "@utils/logger";
+import { toast } from "@utils/toast";
+import { useCallback, useEffect, useState } from "react";
+
+const log = logger.scope("long-running-task-proposal");
+
+interface LongRunningTaskProposalCardProps {
+  taskId: string;
+  taskRunId: string;
+}
+
+export function LongRunningTaskProposalCard({
+  taskId,
+  taskRunId,
+}: LongRunningTaskProposalCardProps) {
+  const proposal = useLongRunningTaskStore(
+    (s) => s.proposalsByTaskRunId[taskRunId],
+  );
+  const clearProposal = useLongRunningTaskStore((s) => s.clearProposal);
+
+  const [goal, setGoal] = useState("");
+  const [successCriterion, setSuccessCriterion] = useState("");
+  const [maxIterations, setMaxIterations] = useState(20);
+  const [marker, setMarker] = useState("<TASK_COMPLETE>");
+  const [editing, setEditing] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+
+  useEffect(() => {
+    if (!proposal) return;
+    setGoal(proposal.goal);
+    setSuccessCriterion(proposal.successCriterion);
+    setMaxIterations(proposal.maxIterations);
+    setMarker(proposal.marker);
+    setEditing(false);
+  }, [proposal]);
+
+  const start = useCallback(async () => {
+    if (!proposal) return;
+    setSubmitting(true);
+    try {
+      await trpcClient.agent.startLongRunningTask.mutate({
+        sessionId: taskRunId,
+        goal: goal.trim(),
+        successCriterion: successCriterion.trim(),
+        marker: marker.trim(),
+        maxIterations,
+      });
+      clearProposal(taskRunId);
+      const kickoff =
+        "Configuration approved. Begin work toward the goal now. " +
+        `Run the verification command(s) for the success criterion after each meaningful change. ` +
+        `Output \`${marker.trim()}\` on its own line only after you have actually observed the criterion satisfied.`;
+      await getSessionService().sendPrompt(taskId, kickoff);
+    } catch (err) {
+      log.error("Failed to start long-running task", { err });
+      toast.error("Failed to start long-running task");
+    } finally {
+      setSubmitting(false);
+    }
+  }, [
+    proposal,
+    taskRunId,
+    taskId,
+    goal,
+    successCriterion,
+    marker,
+    maxIterations,
+    clearProposal,
+  ]);
+
+  const dismiss = useCallback(() => {
+    clearProposal(taskRunId);
+  }, [taskRunId, clearProposal]);
+
+  if (!proposal) return null;
+
+  const canStart =
+    goal.trim().length > 0 &&
+    successCriterion.trim().length > 0 &&
+    marker.trim().length > 0 &&
+    maxIterations > 0;
+
+  return (
+    <Flex
+      direction="column"
+      gap="3"
+      className="rounded-md border-2 border-iris-6 bg-iris-2 p-4"
+    >
+      <Flex align="center" justify="between">
+        <Text size="2" weight="medium" className="text-iris-12">
+          Start long-running task?
+        </Text>
+        <Text size="1" className="text-iris-11">
+          Auto-continues until verification passes or {maxIterations}{" "}
+          iterations.
+        </Text>
+      </Flex>
+
+      {editing ? (
+        <Flex direction="column" gap="2">
+          <FieldLabel>Goal</FieldLabel>
+          <TextArea
+            value={goal}
+            onChange={(e) => setGoal(e.target.value)}
+            rows={2}
+          />
+          <FieldLabel>Success criterion (objectively measurable)</FieldLabel>
+          <TextArea
+            value={successCriterion}
+            onChange={(e) => setSuccessCriterion(e.target.value)}
+            rows={2}
+          />
+          <Flex gap="3">
+            <Flex direction="column" gap="1" className="flex-1">
+              <FieldLabel>Completion marker</FieldLabel>
+              <TextField.Root
+                value={marker}
+                onChange={(e) => setMarker(e.target.value)}
+              />
+            </Flex>
+            <Flex direction="column" gap="1" style={{ width: 120 }}>
+              <FieldLabel>Max iterations</FieldLabel>
+              <TextField.Root
+                type="number"
+                min={1}
+                max={200}
+                value={maxIterations}
+                onChange={(e) =>
+                  setMaxIterations(
+                    Math.max(1, Math.min(200, Number(e.target.value) || 0)),
+                  )
+                }
+              />
+            </Flex>
+          </Flex>
+        </Flex>
+      ) : (
+        <Flex direction="column" gap="2">
+          <FieldRow label="Goal" value={goal} />
+          <FieldRow label="Success criterion" value={successCriterion} />
+          {proposal.approach && (
+            <FieldRow label="Approach" value={proposal.approach} />
+          )}
+          <FieldRow label="Marker" value={marker} mono />
+          <FieldRow label="Max iterations" value={String(maxIterations)} mono />
+        </Flex>
+      )}
+
+      <Flex gap="2" justify="end">
+        <Button
+          size="2"
+          variant="soft"
+          color="gray"
+          onClick={dismiss}
+          disabled={submitting}
+        >
+          Cancel
+        </Button>
+        {editing ? (
+          <Button
+            size="2"
+            variant="soft"
+            onClick={() => setEditing(false)}
+            disabled={submitting}
+          >
+            Done editing
+          </Button>
+        ) : (
+          <Button
+            size="2"
+            variant="soft"
+            onClick={() => setEditing(true)}
+            disabled={submitting}
+          >
+            Edit
+          </Button>
+        )}
+        <Button
+          size="2"
+          onClick={start}
+          disabled={submitting || !canStart}
+          loading={submitting}
+        >
+          Start
+        </Button>
+      </Flex>
+    </Flex>
+  );
+}
+
+function FieldLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <Text size="1" className="text-iris-11">
+      {children}
+    </Text>
+  );
+}
+
+function FieldRow({
+  label,
+  value,
+  mono,
+}: {
+  label: string;
+  value: string;
+  mono?: boolean;
+}) {
+  return (
+    <Flex direction="column" gap="1">
+      <Text size="1" className="text-iris-11">
+        {label}
+      </Text>
+      <Text
+        size="2"
+        className={mono ? "font-mono text-iris-12" : "text-iris-12"}
+      >
+        {value}
+      </Text>
+    </Flex>
+  );
+}
diff --git a/apps/code/src/renderer/features/message-editor/commands.ts b/apps/code/src/renderer/features/message-editor/commands.ts
index 3cacc20f64..7f6fe4358a 100644
--- a/apps/code/src/renderer/features/message-editor/commands.ts
+++ b/apps/code/src/renderer/features/message-editor/commands.ts
@@ -1,8 +1,13 @@
-import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { AvailableCommand, ContentBlock } from "@agentclientprotocol/sdk";
+import { getSessionService } from "@features/sessions/service/service";
+import { sessionStoreSetters } from "@features/sessions/stores/sessionStore";
 import { ANALYTICS_EVENTS, type FeedbackType } from "@shared/types/analytics";
 import { track } from "@utils/analytics";
+import { logger } from "@utils/logger";
 import { toast } from "@utils/toast";
 
+const log = logger.scope("code-commands");
+
 interface CommandContext {
   taskId: string;
   repoPath: string | null | undefined;
@@ -47,10 +52,45 @@ function makeFeedbackCommand(
   };
 }
 
+const longRunningTaskCommand: CodeCommand = {
+  name: "long-running-task",
+  description:
+    "Plan and run an auto-iterating task with a measurable success criterion",
+  input: { hint: "what should the agent work on?" },
+  async execute(args, ctx) {
+    const session = sessionStoreSetters.getSessionByTaskId(ctx.taskId);
+    if (session?.isCloud) {
+      toast.error(
+        "Long-running tasks aren't supported on cloud sessions yet — run locally.",
+      );
+      return;
+    }
+    const description = args?.trim() ?? "";
+    const visibleText = description
+      ? `Plan a long-running task: ${description}`
+      : "Plan a long-running task (please ask me what to work on).";
+    const blocks: ContentBlock[] = [
+      { type: "text", text: visibleText },
+      {
+        type: "text",
+        text: "Follow the long-running task workflow from your system prompt: explore the relevant code first, ask clarifying questions via AskUserQuestion only when intent is genuinely ambiguous, then emit the proposal as a single <long-running-task-config>{...}</long-running-task-config> block. Do NOT begin iterating until the user approves the proposal.",
+        _meta: { ui: { hidden: true } },
+      },
+    ];
+    try {
+      await getSessionService().sendPrompt(ctx.taskId, blocks);
+    } catch (err) {
+      log.error("Failed to start long-running task planning", { err });
+      toast.error("Failed to start long-running task planning");
+    }
+  },
+};
+
 const commands: CodeCommand[] = [
   makeFeedbackCommand("good", "good", "Positive"),
   makeFeedbackCommand("bad", "bad", "Negative"),
   makeFeedbackCommand("feedback", "general", "General"),
+  longRunningTaskCommand,
 ];
 
 export const CODE_COMMANDS: AvailableCommand[] = commands.map((cmd) => ({
diff --git a/apps/code/src/renderer/features/sessions/components/SessionView.tsx b/apps/code/src/renderer/features/sessions/components/SessionView.tsx
index b95675e7de..81f7704a11 100644
--- a/apps/code/src/renderer/features/sessions/components/SessionView.tsx
+++ b/apps/code/src/renderer/features/sessions/components/SessionView.tsx
@@ -1,4 +1,6 @@
 import { isOtherOption } from "@components/action-selector/constants";
+import { LongRunningTaskPill } from "@components/long-running-task/LongRunningTaskPill";
+import { LongRunningTaskProposalCard } from "@components/long-running-task/LongRunningTaskProposalCard";
 import { PermissionSelector } from "@components/permissions/PermissionSelector";
 import { showOfflineToast } from "@features/connectivity/connectivityToast";
 import {
@@ -13,6 +15,7 @@ import {
   useAdapterForTask,
   useModeConfigOptionForTask,
   usePendingPermissionsForTask,
+  useSessionStore,
   useThoughtLevelConfigOptionForTask,
 } from "@features/sessions/stores/sessionStore";
 import type { Plan } from "@features/sessions/types";
@@ -181,6 +184,9 @@ export function SessionView({
   );
 
   const sessionId = taskId ?? "default";
+  const taskRunId = useSessionStore((s) =>
+    taskId ? s.taskIdIndex[taskId] : undefined,
+  );
   const setContext = useDraftStore((s) => s.actions.setContext);
   const requestFocus = useDraftStore((s) => s.actions.requestFocus);
 
@@ -619,6 +625,22 @@ export function SessionView({
                           : "pointer-events-none translate-y-4 opacity-0"
                       }`}
                     >
+                      {taskRunId && taskId && (
+                        <Box
+                          className={compact ? "px-1 pt-1" : "mx-auto px-2 pt-2"}
+                          style={
+                            compact
+                              ? undefined
+                              : { maxWidth: CHAT_CONTENT_MAX_WIDTH }
+                          }
+                        >
+                          <LongRunningTaskProposalCard
+                            taskId={taskId}
+                            taskRunId={taskRunId}
+                          />
+                          <LongRunningTaskPill taskRunId={taskRunId} />
+                        </Box>
+                      )}
                       <Box
                         className={compact ? "p-1" : "mx-auto p-2"}
                         style={
diff --git a/apps/code/src/renderer/features/sessions/service/service.ts b/apps/code/src/renderer/features/sessions/service/service.ts
index efa33cc25a..8d204d5068 100644
--- a/apps/code/src/renderer/features/sessions/service/service.ts
+++ b/apps/code/src/renderer/features/sessions/service/service.ts
@@ -56,6 +56,7 @@ import type { AcpMessage, StoredLogEntry } from "@shared/types/session-events";
 import { isJsonRpcRequest } from "@shared/types/session-events";
 import { getBackoffDelay } from "@shared/utils/backoff";
 import { getCloudUrlFromRegion } from "@shared/utils/urls";
+import { useLongRunningTaskStore } from "@stores/longRunningTaskStore";
 import { buildPermissionToolMetadata, track } from "@utils/analytics";
 import { logger } from "@utils/logger";
 import {
@@ -1332,6 +1333,67 @@ export class SessionService {
 
       this.drainQueuedMessages(taskRunId, session);
     }
+
+    if (
+      "method" in msg &&
+      "params" in msg &&
+      isNotification(msg.method, POSTHOG_NOTIFICATIONS.LONG_RUNNING_TASK_UPDATE)
+    ) {
+      const params = msg.params as {
+        active?: boolean;
+        goal?: string | null;
+        successCriterion?: string | null;
+        marker?: string | null;
+        iterations?: number;
+        maxIterations?: number;
+      };
+      if (params.active) {
+        useLongRunningTaskStore.getState().setTask(taskRunId, {
+          active: true,
+          goal: params.goal ?? "",
+          successCriterion: params.successCriterion ?? "",
+          marker: params.marker ?? "",
+          iterations: params.iterations ?? 0,
+          maxIterations: params.maxIterations ?? 0,
+        });
+      } else {
+        useLongRunningTaskStore.getState().clearTask(taskRunId);
+      }
+    }
+
+    if (
+      "method" in msg &&
+      "params" in msg &&
+      isNotification(
+        msg.method,
+        POSTHOG_NOTIFICATIONS.LONG_RUNNING_TASK_PROPOSAL,
+      )
+    ) {
+      const params = msg.params as {
+        proposalId?: string;
+        goal?: string;
+        successCriterion?: string;
+        marker?: string;
+        maxIterations?: number;
+        approach?: string | null;
+      };
+      if (
+        typeof params.proposalId === "string" &&
+        typeof params.goal === "string" &&
+        typeof params.successCriterion === "string" &&
+        typeof params.marker === "string" &&
+        typeof params.maxIterations === "number"
+      ) {
+        useLongRunningTaskStore.getState().setProposal(taskRunId, {
+          proposalId: params.proposalId,
+          goal: params.goal,
+          successCriterion: params.successCriterion,
+          marker: params.marker,
+          maxIterations: params.maxIterations,
+          approach: params.approach ?? null,
+        });
+      }
+    }
   }
 
   private drainQueuedMessages(
diff --git a/apps/code/src/renderer/stores/longRunningTaskStore.ts b/apps/code/src/renderer/stores/longRunningTaskStore.ts
new file mode 100644
index 0000000000..e11b290e97
--- /dev/null
+++ b/apps/code/src/renderer/stores/longRunningTaskStore.ts
@@ -0,0 +1,87 @@
+import { create } from "zustand";
+
+export interface LongRunningTaskInfo {
+  active: boolean;
+  goal: string;
+  successCriterion: string;
+  marker: string;
+  iterations: number;
+  maxIterations: number;
+}
+
+export interface LongRunningTaskProposal {
+  proposalId: string;
+  goal: string;
+  successCriterion: string;
+  marker: string;
+  maxIterations: number;
+  approach: string | null;
+}
+
+interface LongRunningTaskStoreState {
+  byTaskRunId: Record<string, LongRunningTaskInfo>;
+  proposalsByTaskRunId: Record<string, LongRunningTaskProposal>;
+}
+
+interface LongRunningTaskStoreActions {
+  setTask: (taskRunId: string, info: LongRunningTaskInfo) => void;
+  clearTask: (taskRunId: string) => void;
+  setProposal: (taskRunId: string, proposal: LongRunningTaskProposal) => void;
+  clearProposal: (taskRunId: string) => void;
+}
+
+type LongRunningTaskStore = LongRunningTaskStoreState &
+  LongRunningTaskStoreActions;
+
+export const useLongRunningTaskStore = create<LongRunningTaskStore>((set) => ({
+  byTaskRunId: {},
+  proposalsByTaskRunId: {},
+  setTask: (taskRunId, info) =>
+    set((state) => ({
+      byTaskRunId: { ...state.byTaskRunId, [taskRunId]: info },
+      // A new active task supersedes any pending proposal for the same run.
+      proposalsByTaskRunId: info.active
+        ? omitKey(state.proposalsByTaskRunId, taskRunId)
+        : state.proposalsByTaskRunId,
+    })),
+  clearTask: (taskRunId) =>
+    set((state) => {
+      if (!state.byTaskRunId[taskRunId]) return state;
+      return { byTaskRunId: omitKey(state.byTaskRunId, taskRunId) };
+    }),
+  setProposal: (taskRunId, proposal) =>
+    set((state) => ({
+      proposalsByTaskRunId: {
+        ...state.proposalsByTaskRunId,
+        [taskRunId]: proposal,
+      },
+    })),
+  clearProposal: (taskRunId) =>
+    set((state) => {
+      if (!state.proposalsByTaskRunId[taskRunId]) return state;
+      return {
+        proposalsByTaskRunId: omitKey(state.proposalsByTaskRunId, taskRunId),
+      };
+    }),
+}));
+
+function omitKey<T>(record: Record<string, T>, key: string): Record<string, T> {
+  const { [key]: _, ...rest } = record;
+  return rest;
+}
+
+export function selectLongRunningTask(
+  taskRunId: string | null | undefined,
+): LongRunningTaskInfo | null {
+  if (!taskRunId) return null;
+  return useLongRunningTaskStore.getState().byTaskRunId[taskRunId] ?? null;
+}
+
+export function selectLongRunningTaskProposal(
+  taskRunId: string | null | undefined,
+): LongRunningTaskProposal | null {
+  if (!taskRunId) return null;
+  return (
+    useLongRunningTaskStore.getState().proposalsByTaskRunId[taskRunId] ?? null
+  );
+}
diff --git a/packages/agent/src/acp-extensions.ts b/packages/agent/src/acp-extensions.ts
index 759d778080..70ab6e875d 100644
--- a/packages/agent/src/acp-extensions.ts
+++ b/packages/agent/src/acp-extensions.ts
@@ -69,6 +69,20 @@ export const POSTHOG_NOTIFICATIONS = {
 
   /** Response to a relayed permission request (plan approval, question) */
   PERMISSION_RESPONSE: "_posthog/permission_response",
+
+  /**
+   * Long-running-task state changed (entered, iteration advanced, exited).
+   * Payload: { active, goal, successCriterion, marker, iterations, maxIterations }
+   */
+  LONG_RUNNING_TASK_UPDATE: "_posthog/long_running_task_update",
+
+  /**
+   * Agent emitted a long-running-task proposal in its end-of-turn message.
+   * Payload: { proposalId, goal, successCriterion, marker, maxIterations, approach }
+   * The client should render a confirmation card and call START_LONG_RUNNING_TASK
+   * (plus send a kickoff prompt) when the user approves.
+   */
+  LONG_RUNNING_TASK_PROPOSAL: "_posthog/long_running_task_proposal",
 } as const;
 
 /**
@@ -85,6 +99,20 @@ export const POSTHOG_METHODS = {
    * completed so the caller can safely send the next prompt.
    */
   REFRESH_SESSION: "_posthog/refresh_session",
+
+  /**
+   * Begin a long-running task on this session. The next prompt() call will
+   * loop after each end_turn until the agent emits `marker` in its last
+   * assistant text, the iteration cap is hit, or the user stops the loop.
+   * Payload: { goal, successCriterion, marker, maxIterations }
+   */
+  START_LONG_RUNNING_TASK: "_posthog/long_running_task/start",
+
+  /**
+   * Stop the active long-running task on this session. The current turn
+   * finishes naturally — no auto-continuation will be injected after it.
+   */
+  STOP_LONG_RUNNING_TASK: "_posthog/long_running_task/stop",
 } as const;
 
 type PosthogNotification =
diff --git a/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/src/adapters/claude/claude-agent.ts
index 2b516b72d8..cf78a27a71 100644
--- a/packages/agent/src/adapters/claude/claude-agent.ts
+++ b/packages/agent/src/adapters/claude/claude-agent.ts
@@ -69,6 +69,12 @@ import {
   handleUserAssistantMessage,
 } from "./conversion/sdk-to-acp";
 import type { EnrichedReadCache } from "./hooks";
+import {
+  broadcastLongRunningTaskUpdate,
+  decideLongRunningTaskStep,
+  maybeBroadcastProposal,
+  StartLongRunningTaskParamsSchema,
+} from "./long-running-task/utils";
 import {
   fetchMcpToolMetadata,
   getConnectedMcpServerNames,
@@ -604,6 +610,26 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
               });
             }
 
+            const lrtDecision = await decideLongRunningTaskStep(
+              this.session,
+              params.sessionId,
+              this.client,
+            );
+            if (lrtDecision.kind !== "exit") {
+              // Keep the while-loop alive — a continuation user message has
+              // been pushed into session.input, so the SDK will start a new
+              // turn instead of going idle.
+              promptReplayed = true;
+              break;
+            }
+
+            // No active task: see if the agent emitted a setup proposal.
+            await maybeBroadcastProposal(
+              this.session,
+              params.sessionId,
+              this.client,
+            );
+
             return { stopReason: result.stopReason ?? "end_turn", usage };
           }
 
@@ -822,6 +848,12 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     method: string,
     params: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
+    if (isMethod(method, POSTHOG_METHODS.START_LONG_RUNNING_TASK)) {
+      return this.handleStartLongRunningTask(params);
+    }
+    if (isMethod(method, POSTHOG_METHODS.STOP_LONG_RUNNING_TASK)) {
+      return this.handleStopLongRunningTask();
+    }
     if (!isMethod(method, POSTHOG_METHODS.REFRESH_SESSION)) {
       throw RequestError.methodNotFound(method);
     }
@@ -849,6 +881,42 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     return { refreshed: true };
   }
 
+  private async handleStartLongRunningTask(
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const parsed = StartLongRunningTaskParamsSchema.safeParse(params);
+    if (!parsed.success) {
+      throw new RequestError(
+        -32602,
+        `start_long_running_task: invalid params — ${parsed.error.issues
+          .map((i) => `${i.path.join(".")}: ${i.message}`)
+          .join("; ")}`,
+      );
+    }
+    this.session.longRunningTask = {
+      goal: parsed.data.goal,
+      successCriterion: parsed.data.successCriterion,
+      marker: parsed.data.marker,
+      iterations: 0,
+      maxIterations: parsed.data.maxIterations,
+    };
+    await broadcastLongRunningTaskUpdate(
+      this.client,
+      this.sessionId,
+      this.session.longRunningTask,
+    );
+    return { started: true };
+  }
+
+  private async handleStopLongRunningTask(): Promise<Record<string, unknown>> {
+    if (!this.session.longRunningTask) {
+      return { stopped: false };
+    }
+    this.session.longRunningTask = null;
+    await broadcastLongRunningTaskUpdate(this.client, this.sessionId, null);
+    return { stopped: true };
+  }
+
   private async refreshSession(
     mcpServers: Record<string, McpServerConfig>,
   ): Promise<void> {
@@ -1190,6 +1258,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       promptRunning: false,
       pendingMessages: new Map(),
       nextPendingOrder: 0,
+      longRunningTask: null,
       emitRawSDKMessages: meta?.claudeCode?.emitRawSDKMessages ?? false,
 
       // Custom properties
diff --git a/packages/agent/src/adapters/claude/long-running-task/utils.test.ts b/packages/agent/src/adapters/claude/long-running-task/utils.test.ts
new file mode 100644
index 0000000000..f8458d0296
--- /dev/null
+++ b/packages/agent/src/adapters/claude/long-running-task/utils.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { extractProposal } from "./utils";
+
+describe("extractProposal", () => {
+  it("parses a well-formed proposal block", () => {
+    const text = `I've explored the codebase. Here is the proposal:
+
+<long-running-task-config>
+{
+  "goal": "Reduce bundle size below 500KB",
+  "successCriterion": "du -b dist/main.js < 500000",
+  "marker": "<TASK_COMPLETE>",
+  "maxIterations": 20,
+  "approach": "Use source-map-explorer"
+}
+</long-running-task-config>
+
+Ready to start when you approve.`;
+
+    const result = extractProposal(text);
+    expect(result).toEqual({
+      goal: "Reduce bundle size below 500KB",
+      successCriterion: "du -b dist/main.js < 500000",
+      marker: "<TASK_COMPLETE>",
+      maxIterations: 20,
+      approach: "Use source-map-explorer",
+    });
+  });
+
+  it("applies defaults for marker and maxIterations", () => {
+    const text = `<long-running-task-config>
+{ "goal": "Fix tests", "successCriterion": "all tests pass" }
+</long-running-task-config>`;
+
+    const result = extractProposal(text);
+    expect(result?.marker).toBe("<TASK_COMPLETE>");
+    expect(result?.maxIterations).toBe(20);
+  });
+
+  it("returns null when block is missing", () => {
+    expect(extractProposal("just a regular message")).toBeNull();
+  });
+
+  it("returns null when JSON is malformed", () => {
+    const text = `<long-running-task-config>
+{ this is not json }
+</long-running-task-config>`;
+    expect(extractProposal(text)).toBeNull();
+  });
+
+  it("returns null when required fields are missing", () => {
+    const text = `<long-running-task-config>
+{ "goal": "fix something" }
+</long-running-task-config>`;
+    expect(extractProposal(text)).toBeNull();
+  });
+
+  it("rejects out-of-range maxIterations", () => {
+    const text = `<long-running-task-config>
+{ "goal": "x", "successCriterion": "y", "maxIterations": 9999 }
+</long-running-task-config>`;
+    expect(extractProposal(text)).toBeNull();
+  });
+});
diff --git a/packages/agent/src/adapters/claude/long-running-task/utils.ts b/packages/agent/src/adapters/claude/long-running-task/utils.ts
new file mode 100644
index 0000000000..40e1177997
--- /dev/null
+++ b/packages/agent/src/adapters/claude/long-running-task/utils.ts
@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { POSTHOG_NOTIFICATIONS } from "../../../acp-extensions";
+import { getLatestAssistantText } from "../plan/utils";
+import type { LongRunningTaskState, Session } from "../types";
+
+export const DEFAULT_MARKER = "<TASK_COMPLETE>";
+export const DEFAULT_MAX_ITERATIONS = 20;
+
+export const StartLongRunningTaskParamsSchema = z.object({
+  goal: z.string().min(1),
+  successCriterion: z.string().min(1),
+  marker: z.string().min(1).default(DEFAULT_MARKER),
+  maxIterations: z
+    .number()
+    .int()
+    .positive()
+    .max(200)
+    .default(DEFAULT_MAX_ITERATIONS),
+});
+
+export type StartLongRunningTaskParams = z.infer<
+  typeof StartLongRunningTaskParamsSchema
+>;
+
+function makeUserMessage(sessionId: string, text: string): SDKUserMessage {
+  return {
+    type: "user",
+    message: { role: "user", content: [{ type: "text", text }] },
+    session_id: sessionId,
+    parent_tool_use_id: null,
+    uuid: randomUUID(),
+  };
+}
+
+export function buildContinuationMessage(task: LongRunningTaskState): string {
+  return [
+    `Continue working toward the goal. Iterations used: ${task.iterations}/${task.maxIterations}.`,
+    `Goal: ${task.goal}`,
+    `Success criterion (must be objectively verified before stopping): ${task.successCriterion}`,
+    `When — and only when — you have actually run the verification and observed success, output the exact marker on its own line: ${task.marker}`,
+    `If the verification fails or is incomplete, keep iterating. Do NOT output the marker speculatively.`,
+  ].join("\n");
+}
+
+export function buildWrapUpMessage(task: LongRunningTaskState): string {
+  return [
+    `You have used all ${task.maxIterations} iterations without satisfying the success criterion (${task.successCriterion}).`,
+    `Stop iterating. In a single final response, summarize:`,
+    `- What you accomplished`,
+    `- What still remains`,
+    `- Any blockers or impossibilities you encountered`,
+    `Do NOT output the marker ${task.marker}.`,
+  ].join("\n");
+}
+
+export function pushSystemContinuation(
+  session: Session,
+  sessionId: string,
+  text: string,
+): void {
+  session.input.push(makeUserMessage(sessionId, text));
+}
+
+export async function broadcastLongRunningTaskUpdate(
+  client: AgentSideConnection,
+  sessionId: string,
+  task: LongRunningTaskState | null,
+): Promise<void> {
+  await client.extNotification(POSTHOG_NOTIFICATIONS.LONG_RUNNING_TASK_UPDATE, {
+    sessionId,
+    active: task !== null,
+    goal: task?.goal ?? null,
+    successCriterion: task?.successCriterion ?? null,
+    marker: task?.marker ?? null,
+    iterations: task?.iterations ?? 0,
+    maxIterations: task?.maxIterations ?? 0,
+  });
+}
+
+export type LoopDecision =
+  | { kind: "exit" }
+  | { kind: "continue" }
+  | { kind: "wrap_up" };
+
+/**
+ * Decide what to do after an end-of-turn signal when a long-running task is
+ * active. Mutates session state (iterations++, clearing on exit) and pushes
+ * the appropriate user message into session.input when continuing.
+ */
+export async function decideLongRunningTaskStep(
+  session: Session,
+  sessionId: string,
+  client: AgentSideConnection,
+): Promise<LoopDecision> {
+  const task = session.longRunningTask;
+  if (!task || session.cancelled) {
+    return { kind: "exit" };
+  }
+
+  const lastText = getLatestAssistantText(session.notificationHistory) ?? "";
+
+  // Marker observed — task done.
+  if (lastText.includes(task.marker)) {
+    session.longRunningTask = null;
+    await broadcastLongRunningTaskUpdate(client, sessionId, null);
+    return { kind: "exit" };
+  }
+
+  // Budget exhausted — let the agent do one wrap-up turn, then exit.
+  if (task.iterations >= task.maxIterations) {
+    const text = buildWrapUpMessage(task);
+    session.longRunningTask = null;
+    await broadcastLongRunningTaskUpdate(client, sessionId, null);
+    pushSystemContinuation(session, sessionId, text);
+    return { kind: "wrap_up" };
+  }
+
+  // User has steered: a concurrent prompt() has queued their input. Defer to
+  // it — the next prompt() will pick up the loop after its own end_turn.
+  if (session.pendingMessages.size > 0) {
+    return { kind: "exit" };
+  }
+
+  task.iterations += 1;
+  await broadcastLongRunningTaskUpdate(client, sessionId, task);
+  pushSystemContinuation(session, sessionId, buildContinuationMessage(task));
+  return { kind: "continue" };
+}
+
+const PROPOSAL_TAG_RE =
+  /<long-running-task-config>\s*([\s\S]*?)\s*<\/long-running-task-config>/i;
+
+export const ProposalSchema = z.object({
+  goal: z.string().min(1).max(2000),
+  successCriterion: z.string().min(1).max(2000),
+  marker: z.string().min(1).max(200).default(DEFAULT_MARKER),
+  maxIterations: z
+    .number()
+    .int()
+    .positive()
+    .max(200)
+    .default(DEFAULT_MAX_ITERATIONS),
+  approach: z.string().max(4000).optional(),
+});
+
+export type Proposal = z.infer<typeof ProposalSchema>;
+
+export function extractProposal(text: string): Proposal | null {
+  const match = text.match(PROPOSAL_TAG_RE);
+  if (!match) return null;
+  const raw = match[1].trim();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = ProposalSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}
+
+export async function maybeBroadcastProposal(
+  session: Session,
+  sessionId: string,
+  client: AgentSideConnection,
+): Promise<void> {
+  if (session.longRunningTask) return;
+  const lastText = getLatestAssistantText(session.notificationHistory);
+  if (!lastText) return;
+  const proposal = extractProposal(lastText);
+  if (!proposal) return;
+  await client.extNotification(
+    POSTHOG_NOTIFICATIONS.LONG_RUNNING_TASK_PROPOSAL,
+    {
+      sessionId,
+      proposalId: randomUUID(),
+      goal: proposal.goal,
+      successCriterion: proposal.successCriterion,
+      marker: proposal.marker,
+      maxIterations: proposal.maxIterations,
+      approach: proposal.approach ?? null,
+    },
+  );
+}
diff --git a/packages/agent/src/adapters/claude/session/instructions.ts b/packages/agent/src/adapters/claude/session/instructions.ts
index 792be41d04..7798a7ae1e 100644
--- a/packages/agent/src/adapters/claude/session/instructions.ts
+++ b/packages/agent/src/adapters/claude/session/instructions.ts
@@ -26,4 +26,55 @@ If an MCP tool call is explicitly denied with a message, relay that denial messa
 If an MCP tool call returns an error, treat it as a normal tool error — troubleshoot, retry, or inform the user about the specific error. Do NOT assume it is a permissions issue and do NOT direct the user to any settings page.
 `;
 
-export const APPENDED_INSTRUCTIONS = BRANCH_NAMING + PLAN_MODE + MCP_TOOLS;
+const LONG_RUNNING_TASK = `
+# Long-Running Tasks
+
+The harness supports a "long-running task" loop. While it is active, the harness auto-continues your turn after each end_turn by injecting a continuation message. You exit the loop by outputting the configured completion marker (default: \`<TASK_COMPLETE>\`) on its own line in your final response — or the harness force-exits when a max-iterations cap is hit. While the loop is active, treat continuation messages like "Continue working toward the goal. Iterations used: N/M. ..." as system reminders, not user input.
+
+## When a long-running task fits
+
+Suitable when ALL of these hold:
+
+1. **Measurable success** — a number or boolean state can be checked each cycle that moves monotonically toward done (tests passing, error count, bundle size, coverage %, lint warnings).
+2. **Objective** — no taste or design judgment is required to evaluate completion.
+3. **Walk-away suitable** — the user does not need to steer each iteration.
+4. **Scoped deliverable** — a well-defined end state.
+5. **Likely > ~5 cycles of work** — for shorter tasks the overhead isn't worth it.
+
+NOT a fit for: UI polish, copy editing, open-ended investigation, production debugging, anything needing human judgment per cycle.
+
+## Proposing a long-running task
+
+When the user invokes \`/long-running-task\` — or when you independently judge that their request fits the criteria above — DON'T jump straight into iterating. Instead:
+
+1. **Explore first.** Run the commands or read the files needed to understand the current state. Examples:
+   - For "reduce bundle size": measure current per-file sizes (e.g. \`du -b dist/*.js\` or \`source-map-explorer\`) to find what's actually heavy.
+   - For "fix failing tests": run the test suite once to see what's failing and group the failures.
+   - For "refactor N files": list the files matching the old pattern so the count is real.
+2. **Pick concrete tools/commands** you'll use to make progress and to verify each iteration.
+3. **Ask clarifying questions** via \`AskUserQuestion\` when the user's intent is genuinely ambiguous (e.g. "main bundle only or all chunks?"). Don't ask trivial questions you can answer from the codebase.
+4. **Propose the configuration** as a JSON block tagged \`<long-running-task-config>\` on its own lines:
+
+\`\`\`
+<long-running-task-config>
+{
+  "goal": "Reduce apps/code main bundle below 500KB",
+  "successCriterion": "\`du -b apps/code/dist/main.js\` reports < 500000",
+  "marker": "<TASK_COMPLETE>",
+  "maxIterations": 20,
+  "approach": "Use source-map-explorer to identify heaviest deps; tree-shake, lazy-load, or replace; verify with du -b after each change."
+}
+</long-running-task-config>
+\`\`\`
+
+Include nothing inside the tags except the JSON object. The user will see this rendered as a confirmation card. Do not begin iterating — wait for them to approve.
+
+## While the loop is active
+
+- Only output the completion marker after you have actually run the verification (test, measurement, check) and observed success. Never emit it speculatively.
+- If verification fails, keep iterating.
+- If the user sends a steering message mid-loop, the harness pauses auto-continuation for that turn — respond to them, then resume.
+`;
+
+export const APPENDED_INSTRUCTIONS =
+  BRANCH_NAMING + PLAN_MODE + MCP_TOOLS + LONG_RUNNING_TASK;
diff --git a/packages/agent/src/adapters/claude/types.ts b/packages/agent/src/adapters/claude/types.ts
index 1898a23609..e270db052a 100644
--- a/packages/agent/src/adapters/claude/types.ts
+++ b/packages/agent/src/adapters/claude/types.ts
@@ -39,6 +39,14 @@ export type PendingMessage = {
   order: number;
 };
 
+export type LongRunningTaskState = {
+  goal: string;
+  successCriterion: string;
+  marker: string;
+  iterations: number;
+  maxIterations: number;
+};
+
 export type Session = BaseSession & {
   query: Query;
   /** The Options object passed to query() — mutating it affects subsequent prompts */
@@ -65,6 +73,8 @@ export type Session = BaseSession & {
   pendingMessages: Map<string, PendingMessage>;
   nextPendingOrder: number;
   emitRawSDKMessages: boolean | SDKMessageFilter[];
+  /** Active long-running task — drives the auto-continuation loop. */
+  longRunningTask: LongRunningTaskState | null;
 };
 
 export type ToolUseCache = {
diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.ts
index 05dc8bae59..e3cec6b39e 100644
--- a/packages/agent/src/index.ts
+++ b/packages/agent/src/index.ts
@@ -1,4 +1,9 @@
-export { isNotification, POSTHOG_NOTIFICATIONS } from "./acp-extensions";
+export {
+  isMethod,
+  isNotification,
+  POSTHOG_METHODS,
+  POSTHOG_NOTIFICATIONS,
+} from "./acp-extensions";
 export {
   getMcpToolMetadata,
   isMcpToolReadOnly,

From fa85fa1b4d6bb5698ccfb3c13ce3772c24d49b95 Mon Sep 17 00:00:00 2001
From: Robbie Coomber <robbie.coomber@gmail.com>
Date: Wed, 20 May 2026 22:35:00 +0100
Subject: [PATCH 2/2] feat(agent): mirror long-running task loop in codex
 adapter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactors the long-running task helpers to be adapter-agnostic and adds
the same loop primitive to the codex adapter.

- decideLongRunningTaskStep now returns the continuation text instead of
  pushing it; caller routes it through the right turn mechanism
  (session.input push for claude, new PromptRequest for codex)
- LRT system-prompt instructions extracted to a shared module that both
  adapters append to their system prompt
- codex runPrompt wraps codexConnection.prompt() in a while loop —
  each iteration is a fresh ACP turn, no broadcast on continuations so
  the user only sees the original prompt in chat
- codex-client forwards every session notification to the session's
  notificationHistory so getLatestAssistantText finds the agent's text
  for marker + proposal detection
- codex extMethod handles START / STOP and emits the same update
  notifications the renderer already listens for
- codex spawn instructions get LRT instructions appended, mirroring the
  Claude APPENDED_INSTRUCTIONS path

Generated-By: PostHog Code
Task-Id: c1333c34-d768-47e2-9dda-d2e456ab701a
---
 .../agent/src/adapters/claude/claude-agent.ts |  10 +-
 .../claude/long-running-task/instructions.ts  |  54 +++++++++
 .../claude/long-running-task/utils.ts         |  55 ++++++---
 .../adapters/claude/session/instructions.ts   |  54 +--------
 .../agent/src/adapters/codex/codex-agent.ts   | 111 +++++++++++++++++-
 .../agent/src/adapters/codex/codex-client.ts  |   7 ++
 6 files changed, 213 insertions(+), 78 deletions(-)
 create mode 100644 packages/agent/src/adapters/claude/long-running-task/instructions.ts

diff --git a/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/src/adapters/claude/claude-agent.ts
index cf78a27a71..1357cbfe60 100644
--- a/packages/agent/src/adapters/claude/claude-agent.ts
+++ b/packages/agent/src/adapters/claude/claude-agent.ts
@@ -72,6 +72,7 @@ import type { EnrichedReadCache } from "./hooks";
 import {
   broadcastLongRunningTaskUpdate,
   decideLongRunningTaskStep,
+  makeContinuationUserMessage,
   maybeBroadcastProposal,
   StartLongRunningTaskParamsSchema,
 } from "./long-running-task/utils";
@@ -614,11 +615,14 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
               this.session,
               params.sessionId,
               this.client,
+              { pendingUserMessageCount: this.session.pendingMessages.size },
             );
             if (lrtDecision.kind !== "exit") {
-              // Keep the while-loop alive — a continuation user message has
-              // been pushed into session.input, so the SDK will start a new
-              // turn instead of going idle.
+              this.session.input.push(
+                makeContinuationUserMessage(params.sessionId, lrtDecision.text),
+              );
+              // Keep the while-loop alive — the SDK will start a new turn
+              // instead of going idle.
               promptReplayed = true;
               break;
             }
diff --git a/packages/agent/src/adapters/claude/long-running-task/instructions.ts b/packages/agent/src/adapters/claude/long-running-task/instructions.ts
new file mode 100644
index 0000000000..3674ece6bf
--- /dev/null
+++ b/packages/agent/src/adapters/claude/long-running-task/instructions.ts
@@ -0,0 +1,54 @@
+/**
+ * System-prompt instructions that teach the agent how to use the
+ * long-running task loop. Adapter-agnostic — both Claude and Codex append
+ * this to their system prompt.
+ */
+export const LONG_RUNNING_TASK_INSTRUCTIONS = `
+# Long-Running Tasks
+
+The harness supports a "long-running task" loop. While it is active, the harness auto-continues your turn after each end_turn by injecting a continuation message. You exit the loop by outputting the configured completion marker (default: \`<TASK_COMPLETE>\`) on its own line in your final response — or the harness force-exits when a max-iterations cap is hit. While the loop is active, treat continuation messages like "Continue working toward the goal. Iterations used: N/M. ..." as system reminders, not user input.
+
+## When a long-running task fits
+
+Suitable when ALL of these hold:
+
+1. **Measurable success** — a number or boolean state can be checked each cycle that moves monotonically toward done (tests passing, error count, bundle size, coverage %, lint warnings).
+2. **Objective** — no taste or design judgment is required to evaluate completion.
+3. **Walk-away suitable** — the user does not need to steer each iteration.
+4. **Scoped deliverable** — a well-defined end state.
+5. **Likely > ~5 cycles of work** — for shorter tasks the overhead isn't worth it.
+
+NOT a fit for: UI polish, copy editing, open-ended investigation, production debugging, anything needing human judgment per cycle.
+
+## Proposing a long-running task
+
+When the user invokes \`/long-running-task\` — or when you independently judge that their request fits the criteria above — DON'T jump straight into iterating. Instead:
+
+1. **Explore first.** Run the commands or read the files needed to understand the current state. Examples:
+   - For "reduce bundle size": measure current per-file sizes (e.g. \`du -b dist/*.js\` or \`source-map-explorer\`) to find what's actually heavy.
+   - For "fix failing tests": run the test suite once to see what's failing and group the failures.
+   - For "refactor N files": list the files matching the old pattern so the count is real.
+2. **Pick concrete tools/commands** you'll use to make progress and to verify each iteration.
+3. **Ask clarifying questions** via \`AskUserQuestion\` when the user's intent is genuinely ambiguous (e.g. "main bundle only or all chunks?"). Don't ask trivial questions you can answer from the codebase.
+4. **Propose the configuration** as a JSON block tagged \`<long-running-task-config>\` on its own lines:
+
+\`\`\`
+<long-running-task-config>
+{
+  "goal": "Reduce apps/code main bundle below 500KB",
+  "successCriterion": "\`du -b apps/code/dist/main.js\` reports < 500000",
+  "marker": "<TASK_COMPLETE>",
+  "maxIterations": 20,
+  "approach": "Use source-map-explorer to identify heaviest deps; tree-shake, lazy-load, or replace; verify with du -b after each change."
+}
+</long-running-task-config>
+\`\`\`
+
+Include nothing inside the tags except the JSON object. The user will see this rendered as a confirmation card. Do not begin iterating — wait for them to approve.
+
+## While the loop is active
+
+- Only output the completion marker after you have actually run the verification (test, measurement, check) and observed success. Never emit it speculatively.
+- If verification fails, keep iterating.
+- If the user sends a steering message mid-loop, the harness pauses auto-continuation for that turn — respond to them, then resume.
+`;
diff --git a/packages/agent/src/adapters/claude/long-running-task/utils.ts b/packages/agent/src/adapters/claude/long-running-task/utils.ts
index 40e1177997..22eaecf70c 100644
--- a/packages/agent/src/adapters/claude/long-running-task/utils.ts
+++ b/packages/agent/src/adapters/claude/long-running-task/utils.ts
@@ -56,12 +56,11 @@ export function buildWrapUpMessage(task: LongRunningTaskState): string {
   ].join("\n");
 }
 
-export function pushSystemContinuation(
-  session: Session,
+export function makeContinuationUserMessage(
   sessionId: string,
   text: string,
-): void {
-  session.input.push(makeUserMessage(sessionId, text));
+): SDKUserMessage {
+  return makeUserMessage(sessionId, text);
 }
 
 export async function broadcastLongRunningTaskUpdate(
@@ -82,18 +81,37 @@ export async function broadcastLongRunningTaskUpdate(
 
 export type LoopDecision =
   | { kind: "exit" }
-  | { kind: "continue" }
-  | { kind: "wrap_up" };
+  | { kind: "continue"; text: string }
+  | { kind: "wrap_up"; text: string };
+
+interface LongRunningTaskHostSession {
+  longRunningTask: LongRunningTaskState | null;
+  cancelled: boolean;
+  notificationHistory: Session["notificationHistory"];
+}
+
+interface DecideOptions {
+  /**
+   * Number of user-driven prompts queued behind the current turn. If > 0,
+   * the loop yields to the user instead of auto-continuing. Adapters that
+   * don't queue concurrent prompts (codex) pass 0.
+   */
+  pendingUserMessageCount: number;
+}
 
 /**
  * Decide what to do after an end-of-turn signal when a long-running task is
- * active. Mutates session state (iterations++, clearing on exit) and pushes
- * the appropriate user message into session.input when continuing.
+ * active. Mutates `session.longRunningTask` in place (iterations++, clearing
+ * on exit) and returns the next continuation text for continue/wrap_up.
+ * Caller is responsible for routing the text through whatever turn mechanism
+ * its adapter uses (pushing into session.input for claude, building a new
+ * PromptRequest for codex).
  */
 export async function decideLongRunningTaskStep(
-  session: Session,
+  session: LongRunningTaskHostSession,
   sessionId: string,
   client: AgentSideConnection,
+  options: DecideOptions,
 ): Promise<LoopDecision> {
   const task = session.longRunningTask;
   if (!task || session.cancelled) {
@@ -102,32 +120,26 @@ export async function decideLongRunningTaskStep(
 
   const lastText = getLatestAssistantText(session.notificationHistory) ?? "";
 
-  // Marker observed — task done.
   if (lastText.includes(task.marker)) {
     session.longRunningTask = null;
     await broadcastLongRunningTaskUpdate(client, sessionId, null);
     return { kind: "exit" };
   }
 
-  // Budget exhausted — let the agent do one wrap-up turn, then exit.
   if (task.iterations >= task.maxIterations) {
     const text = buildWrapUpMessage(task);
     session.longRunningTask = null;
     await broadcastLongRunningTaskUpdate(client, sessionId, null);
-    pushSystemContinuation(session, sessionId, text);
-    return { kind: "wrap_up" };
+    return { kind: "wrap_up", text };
   }
 
-  // User has steered: a concurrent prompt() has queued their input. Defer to
-  // it — the next prompt() will pick up the loop after its own end_turn.
-  if (session.pendingMessages.size > 0) {
+  if (options.pendingUserMessageCount > 0) {
     return { kind: "exit" };
   }
 
   task.iterations += 1;
   await broadcastLongRunningTaskUpdate(client, sessionId, task);
-  pushSystemContinuation(session, sessionId, buildContinuationMessage(task));
-  return { kind: "continue" };
+  return { kind: "continue", text: buildContinuationMessage(task) };
 }
 
 const PROPOSAL_TAG_RE =
@@ -162,8 +174,13 @@ export function extractProposal(text: string): Proposal | null {
   return result.success ? result.data : null;
 }
 
+interface ProposalSessionView {
+  longRunningTask: LongRunningTaskState | null;
+  notificationHistory: Session["notificationHistory"];
+}
+
 export async function maybeBroadcastProposal(
-  session: Session,
+  session: ProposalSessionView,
   sessionId: string,
   client: AgentSideConnection,
 ): Promise<void> {
diff --git a/packages/agent/src/adapters/claude/session/instructions.ts b/packages/agent/src/adapters/claude/session/instructions.ts
index 7798a7ae1e..225e29214f 100644
--- a/packages/agent/src/adapters/claude/session/instructions.ts
+++ b/packages/agent/src/adapters/claude/session/instructions.ts
@@ -1,3 +1,5 @@
+import { LONG_RUNNING_TASK_INSTRUCTIONS } from "../long-running-task/instructions";
+
 const BRANCH_NAMING = `
 # Branch Naming
 
@@ -26,55 +28,5 @@ If an MCP tool call is explicitly denied with a message, relay that denial messa
 If an MCP tool call returns an error, treat it as a normal tool error — troubleshoot, retry, or inform the user about the specific error. Do NOT assume it is a permissions issue and do NOT direct the user to any settings page.
 `;
 
-const LONG_RUNNING_TASK = `
-# Long-Running Tasks
-
-The harness supports a "long-running task" loop. While it is active, the harness auto-continues your turn after each end_turn by injecting a continuation message. You exit the loop by outputting the configured completion marker (default: \`<TASK_COMPLETE>\`) on its own line in your final response — or the harness force-exits when a max-iterations cap is hit. While the loop is active, treat continuation messages like "Continue working toward the goal. Iterations used: N/M. ..." as system reminders, not user input.
-
-## When a long-running task fits
-
-Suitable when ALL of these hold:
-
-1. **Measurable success** — a number or boolean state can be checked each cycle that moves monotonically toward done (tests passing, error count, bundle size, coverage %, lint warnings).
-2. **Objective** — no taste or design judgment is required to evaluate completion.
-3. **Walk-away suitable** — the user does not need to steer each iteration.
-4. **Scoped deliverable** — a well-defined end state.
-5. **Likely > ~5 cycles of work** — for shorter tasks the overhead isn't worth it.
-
-NOT a fit for: UI polish, copy editing, open-ended investigation, production debugging, anything needing human judgment per cycle.
-
-## Proposing a long-running task
-
-When the user invokes \`/long-running-task\` — or when you independently judge that their request fits the criteria above — DON'T jump straight into iterating. Instead:
-
-1. **Explore first.** Run the commands or read the files needed to understand the current state. Examples:
-   - For "reduce bundle size": measure current per-file sizes (e.g. \`du -b dist/*.js\` or \`source-map-explorer\`) to find what's actually heavy.
-   - For "fix failing tests": run the test suite once to see what's failing and group the failures.
-   - For "refactor N files": list the files matching the old pattern so the count is real.
-2. **Pick concrete tools/commands** you'll use to make progress and to verify each iteration.
-3. **Ask clarifying questions** via \`AskUserQuestion\` when the user's intent is genuinely ambiguous (e.g. "main bundle only or all chunks?"). Don't ask trivial questions you can answer from the codebase.
-4. **Propose the configuration** as a JSON block tagged \`<long-running-task-config>\` on its own lines:
-
-\`\`\`
-<long-running-task-config>
-{
-  "goal": "Reduce apps/code main bundle below 500KB",
-  "successCriterion": "\`du -b apps/code/dist/main.js\` reports < 500000",
-  "marker": "<TASK_COMPLETE>",
-  "maxIterations": 20,
-  "approach": "Use source-map-explorer to identify heaviest deps; tree-shake, lazy-load, or replace; verify with du -b after each change."
-}
-</long-running-task-config>
-\`\`\`
-
-Include nothing inside the tags except the JSON object. The user will see this rendered as a confirmation card. Do not begin iterating — wait for them to approve.
-
-## While the loop is active
-
-- Only output the completion marker after you have actually run the verification (test, measurement, check) and observed success. Never emit it speculatively.
-- If verification fails, keep iterating.
-- If the user sends a steering message mid-loop, the harness pauses auto-continuation for that turn — respond to them, then resume.
-`;
-
 export const APPENDED_INSTRUCTIONS =
-  BRANCH_NAMING + PLAN_MODE + MCP_TOOLS + LONG_RUNNING_TASK;
+  BRANCH_NAMING + PLAN_MODE + MCP_TOOLS + LONG_RUNNING_TASK_INSTRUCTIONS;
diff --git a/packages/agent/src/adapters/codex/codex-agent.ts b/packages/agent/src/adapters/codex/codex-agent.ts
index 4313d29c06..122e53e8cb 100644
--- a/packages/agent/src/adapters/codex/codex-agent.ts
+++ b/packages/agent/src/adapters/codex/codex-agent.ts
@@ -62,6 +62,14 @@ import {
   nodeWritableToWebWritable,
 } from "../../utils/streams";
 import { BaseAcpAgent, type BaseSession } from "../base-acp-agent";
+import { LONG_RUNNING_TASK_INSTRUCTIONS } from "../claude/long-running-task/instructions";
+import {
+  broadcastLongRunningTaskUpdate,
+  decideLongRunningTaskStep,
+  maybeBroadcastProposal,
+  StartLongRunningTaskParamsSchema,
+} from "../claude/long-running-task/utils";
+import type { LongRunningTaskState } from "../claude/types";
 import { classifyAgentError } from "../error-classification";
 import { createCodexClient } from "./codex-client";
 import { normalizeCodexConfigOptions } from "./models";
@@ -112,8 +120,16 @@ export interface CodexAcpAgentOptions {
 type CodexSession = BaseSession & {
   settingsManager: CodexSettingsManager;
   promptRunning: boolean;
+  longRunningTask: LongRunningTaskState | null;
 };
 
+function appendLongRunningTaskInstructions(
+  existing: string | undefined,
+): string {
+  if (!existing) return LONG_RUNNING_TASK_INSTRUCTIONS;
+  return `${existing}\n\n${LONG_RUNNING_TASK_INSTRUCTIONS}`;
+}
+
 function toCodexPermissionMode(mode?: string): PermissionMode {
   if (mode && (isCodexNativeMode(mode) || isCodeExecutionMode(mode))) {
     return mode;
@@ -257,13 +273,18 @@ export class CodexAcpAgent extends BaseAcpAgent {
     const cwd = options.codexProcessOptions.cwd ?? process.cwd();
     const settingsManager = new CodexSettingsManager(cwd);
 
-    this.codexProcessOptions = options.codexProcessOptions;
+    this.codexProcessOptions = {
+      ...options.codexProcessOptions,
+      instructions: appendLongRunningTaskInstructions(
+        options.codexProcessOptions.instructions,
+      ),
+    };
     this.processCallbacks = options.processCallbacks;
     this.onStructuredOutput = options.onStructuredOutput;
 
     // Spawn the codex-acp subprocess
     this.codexProcess = spawnCodexProcess({
-      ...options.codexProcessOptions,
+      ...this.codexProcessOptions,
       settings: settingsManager.getSettings(),
       logger: this.logger,
       processCallbacks: options.processCallbacks,
@@ -281,6 +302,7 @@ export class CodexAcpAgent extends BaseAcpAgent {
       notificationHistory: [],
       cancelled: false,
       promptRunning: false,
+      longRunningTask: null,
     };
 
     this.sessionState = createSessionState("", cwd);
@@ -295,6 +317,9 @@ export class CodexAcpAgent extends BaseAcpAgent {
         createCodexClient(this.client, this.logger, this.sessionState, {
           enrichmentDeps: this.enrichment?.deps,
           onStructuredOutput: this.onStructuredOutput,
+          onSessionNotification: (n) => {
+            this.session.notificationHistory.push(n);
+          },
         }),
       codexStream,
     );
@@ -589,10 +614,40 @@ export class CodexAcpAgent extends BaseAcpAgent {
 
     this.session.promptRunning = true;
     let response: PromptResponse;
+    let currentParams = params;
     try {
-      response = await this.codexConnection.prompt(prependPrContext(params));
-    } catch (error) {
-      throw classifyPromptError(error);
+      // Long-running task loop: after each inner prompt() resolves we may
+      // synthesize another continuation user message and call prompt() again,
+      // until the agent emits the marker, the cap is hit, or the user
+      // cancels.
+      while (true) {
+        try {
+          response = await this.codexConnection.prompt(
+            prependPrContext(currentParams),
+          );
+        } catch (error) {
+          throw classifyPromptError(error);
+        }
+
+        const lrtDecision = await decideLongRunningTaskStep(
+          this.session,
+          params.sessionId,
+          this.client,
+          { pendingUserMessageCount: 0 },
+        );
+        if (lrtDecision.kind === "exit") {
+          await maybeBroadcastProposal(
+            this.session,
+            params.sessionId,
+            this.client,
+          );
+          break;
+        }
+        currentParams = {
+          sessionId: params.sessionId,
+          prompt: [{ type: "text", text: lrtDecision.text }],
+        };
+      }
     } finally {
       this.session.promptRunning = false;
     }
@@ -676,6 +731,12 @@ export class CodexAcpAgent extends BaseAcpAgent {
     method: string,
     params: Record<string, unknown>,
   ): Promise<Record<string, unknown>> {
+    if (isMethod(method, POSTHOG_METHODS.START_LONG_RUNNING_TASK)) {
+      return this.handleStartLongRunningTask(params);
+    }
+    if (isMethod(method, POSTHOG_METHODS.STOP_LONG_RUNNING_TASK)) {
+      return this.handleStopLongRunningTask();
+    }
     if (!isMethod(method, POSTHOG_METHODS.REFRESH_SESSION)) {
       throw RequestError.methodNotFound(method);
     }
@@ -701,6 +762,42 @@ export class CodexAcpAgent extends BaseAcpAgent {
     return { refreshed: true };
   }
 
+  private async handleStartLongRunningTask(
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    const parsed = StartLongRunningTaskParamsSchema.safeParse(params);
+    if (!parsed.success) {
+      throw new RequestError(
+        -32602,
+        `start_long_running_task: invalid params — ${parsed.error.issues
+          .map((i) => `${i.path.join(".")}: ${i.message}`)
+          .join("; ")}`,
+      );
+    }
+    this.session.longRunningTask = {
+      goal: parsed.data.goal,
+      successCriterion: parsed.data.successCriterion,
+      marker: parsed.data.marker,
+      iterations: 0,
+      maxIterations: parsed.data.maxIterations,
+    };
+    await broadcastLongRunningTaskUpdate(
+      this.client,
+      this.sessionId,
+      this.session.longRunningTask,
+    );
+    return { started: true };
+  }
+
+  private async handleStopLongRunningTask(): Promise<Record<string, unknown>> {
+    if (!this.session.longRunningTask) {
+      return { stopped: false };
+    }
+    this.session.longRunningTask = null;
+    await broadcastLongRunningTaskUpdate(this.client, this.sessionId, null);
+    return { stopped: true };
+  }
+
   private async refreshSession(mcpServers: McpServer[]): Promise<void> {
     const prev = this.session;
     if (prev.promptRunning) {
@@ -750,7 +847,11 @@ export class CodexAcpAgent extends BaseAcpAgent {
     const newConnection = new ClientSideConnection(
       (_agent) =>
         createCodexClient(this.client, this.logger, this.sessionState, {
+          enrichmentDeps: this.enrichment?.deps,
           onStructuredOutput: this.onStructuredOutput,
+          onSessionNotification: (n) => {
+            this.session.notificationHistory.push(n);
+          },
         }),
       codexStream,
     );
diff --git a/packages/agent/src/adapters/codex/codex-client.ts b/packages/agent/src/adapters/codex/codex-client.ts
index ebe05a4fe2..7008f51d3d 100644
--- a/packages/agent/src/adapters/codex/codex-client.ts
+++ b/packages/agent/src/adapters/codex/codex-client.ts
@@ -44,6 +44,12 @@ import {
 export interface CodexClientCallbacks {
   /** Called when a usage_update session notification is received */
   onUsageUpdate?: (update: Record<string, unknown>) => void;
+  /**
+   * Called for every session notification before it is forwarded upstream.
+   * The long-running task loop uses this to populate notificationHistory
+   * with agent_message_chunk entries so marker / proposal detection works.
+   */
+  onSessionNotification?: (notification: SessionNotification) => void;
   /** When set, Read responses are annotated with PostHog enrichment before reaching codex-acp. */
   enrichmentDeps?: FileEnrichmentDeps;
   /**
@@ -165,6 +171,7 @@ export function createCodexClient(
     },
 
     async sessionUpdate(params: SessionNotification): Promise<void> {
+      callbacks?.onSessionNotification?.(params);
       const update = params.update as Record<string, unknown> | undefined;
 
       if (