@stigmer/runner 3.14.0 → 3.15.0

package/src/activities/execute-cursor/message-translator.ts

@@ -30,13 +30,14 @@
  * - approvalMessage: from the policy, with placeholder resolution
  */
 
-import { create } from "@bufbuild/protobuf";
+import { clone, create } from "@bufbuild/protobuf";
 import type { JsonObject } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
-import { ApprovalPolicySource, MessageType, ToolCallStatus, SubAgentStatus, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ApprovalPolicySource, MessageType, ToolCallStatus, SubAgentStatus, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { SDKMessage } from "@cursor/sdk";
 import type { MergedToolPolicy } from "./approval-policy.js";
 import { lookupMcpToolPolicy, resolveApprovalMessage, builtInRequiresApproval, getBuiltInApprovalMessage, SALIENT_ARG_FIELDS } from "./approval-policy.js";
@@ -55,6 +56,7 @@ import {
   type DeniedLedgerEntry,
 } from "./approval-state.js";
 import { utcTimestamp } from "../../shared/status.js";
+import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
 import { hideToolCallRow, isToolCallRowHidden } from "../../shared/tool-row.js";
 import { classifyTool, toolApprovalCategory, type ToolApprovalCategory } from "../../shared/tool-kind.js";
 import { resolveWorkspacePath } from "../../shared/file-change.js";
@@ -192,7 +194,7 @@ function translateToolCall(event: Extract<SDKMessage, { type: "tool_call" }>): A
  */
 export function buildToolCallProto(
   event: Extract<SDKMessage, { type: "tool_call" }>,
-  mergedPolicies?: Map<string, MergedToolPolicy>,
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>,
   provenance?: ApprovalProvenanceContext,
 ): ToolCall {
   const status = mapToolCallStatus(event.status);
@@ -714,7 +716,7 @@ function interpretSubAgentToolResult(result: unknown): {
  * Options for creating a MessageAccumulator with policy awareness.
  */
 export interface MessageAccumulatorOptions {
-  mergedPolicies?: Map<string, MergedToolPolicy>;
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>;
   /**
    * Run-scoped approval context (global bypass + active leases) so reconstructed
    * tool calls carry their authorization provenance. Omitted in unit tests that
@@ -729,13 +731,28 @@ export interface MessageAccumulatorOptions {
   workspaceRoot?: string;
   /**
    * Sub-agent executions carried over from the persisted transcript on a
-   * durable resume (see seedCursorTranscriptFromExecution in index.ts). The
-   * accumulator re-registers them so a sub-agent's resumed lifecycle updates
-   * merge onto the seeded row instead of producing a duplicate, and so the row
-   * survives the round-trip rather than being dropped from the rebuilt status.
-   * Empty on a first run.
+   * durable resume ({@link seededSubAgentsOf}). The accumulator re-registers
+   * them so a sub-agent's resumed lifecycle updates merge onto the seeded row
+   * instead of producing a duplicate, and so the row survives the round-trip
+   * rather than being dropped from the rebuilt status. Empty on a first run.
    */
-  seededSubAgents?: SubAgentExecution[];
+  seededSubAgents?: readonly SubAgentExecution[];
+}
+
+/**
+ * The sub-agent rows a resumed turn re-registers, cloned from the persisted
+ * execution so the input stays immutable. This accumulator OWNS
+ * `status.subAgentExecutions` and overwrites it on every flush, which is why
+ * the runtime's transcript seeding (`harness/turn-context.ts`
+ * `seedTranscriptFromExecution`) leaves the sub-agents to this harness: they
+ * are re-registered here, never pushed onto the status. Same "left a
+ * transcript" test as the seeding, so a resume that seeded messages always
+ * seeds their sub-agents too.
+ */
+export function seededSubAgentsOf(execution: AgentExecution): SubAgentExecution[] {
+  const persisted = execution.status;
+  if (!persisted || persisted.messages.length === 0) return [];
+  return persisted.subAgentExecutions.map((sub) => clone(SubAgentExecutionSchema, sub));
 }
 
 /**
@@ -765,31 +782,6 @@ export interface MessageAccumulatorOptions {
  * Task (sub-agent) tool calls additionally produce SubAgentExecution
  * protos, accessible via the subAgentExecutions getter.
  */
-/**
- * Transition any non-terminal sub-agent (IN_PROGRESS or PENDING) in the given
- * proto array to CANCELLED with a completion timestamp, in place.
- *
- * Operates directly on the status array (not the accumulator) because the
- * Cursor cancellation exception unwinds out of the streaming loop into the
- * activity's catch block, where the MessageAccumulator is out of scope. Returns
- * true if any sub-agent changed.
- */
-export function cancelInProgressSubAgentProtos(
-  subAgents: SubAgentExecution[],
-): boolean {
-  let changed = false;
-  for (const sub of subAgents) {
-    if (
-      sub.status === SubAgentStatus.SUB_AGENT_IN_PROGRESS ||
-      sub.status === SubAgentStatus.SUB_AGENT_PENDING
-    ) {
-      sub.status = SubAgentStatus.SUB_AGENT_CANCELLED;
-      sub.completedAt = utcTimestamp();
-      changed = true;
-    }
-  }
-  return changed;
-}
 
 export class MessageAccumulator {
   private readonly messages: AgentMessage[];
@@ -797,7 +789,7 @@ export class MessageAccumulator {
   private activeThinkingByRunId = new Map<string, AgentMessage>();
   private readonly _subAgentExecutions: SubAgentExecution[] = [];
   private readonly subAgentMap = new Map<string, SubAgentExecution>();
-  private readonly mergedPolicies?: Map<string, MergedToolPolicy>;
+  private readonly mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>;
   private readonly provenance?: ApprovalProvenanceContext;
   private readonly workspaceRoot?: string;
   private readonly toolCallIndex = new Map<string, ToolCall>();
@@ -974,12 +966,21 @@ export class MessageAccumulator {
    * pending call with the same identity naturally reconciles onto the next one.
    * Tool calls created during this turn are not WAITING_APPROVAL until the
    * post-stream denial reconciliation runs, so they can never be matched here.
+   *
+   * Only a row whose decision EXECUTES is resumable: the re-issue after an
+   * APPROVE is the approved act itself, landing on its row. A row the user
+   * declined (SKIP / REJECT) is a closed gate — a later same-identity call is a
+   * NEW act the model was told not to perform, and it gets its own row so the
+   * hook's denial gates it afresh instead of landing on the declined row and
+   * inheriting its decision (S2 M4 finding F9, the accumulator's half; the
+   * denial overlay's half is {@link isAdjudicatedRow}).
    */
   private findResumableSeededToolCall(candidate: ToolCall): ToolCall | undefined {
     const wanted = toolCallIdentityToken(candidate);
     for (const tc of this.toolCallIndex.values()) {
       if (
         tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL &&
+        !isDeclinedRow(tc) &&
         toolCallIdentityToken(tc) === wanted
       ) {
         return tc;
@@ -1241,7 +1242,7 @@ export class MessageAccumulator {
 export async function reconcileDeniedToolCalls(
   messages: AgentMessage[],
   ledger: DeniedLedgerEntry[],
-  mergedPolicies?: Map<string, MergedToolPolicy>,
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>,
   workspaceBackend?: WorkspaceBackend,
 ): Promise<ToolCall[]> {
   // Defense-in-depth: only APPROVAL-kind denials may become approval gates.
@@ -1281,10 +1282,13 @@ export async function reconcileDeniedToolCalls(
   //    byte-for-byte (the path form agreed on both sides). The anchor resource
   //    re-attempted within the turn shares one token and collapses to a single
   //    approval (the first match is the keeper; same-identity twins are blanked
-  //    by collapseRedundantToolCallTwins below).
+  //    by collapseRedundantToolCallTwins below). A row an earlier invocation's
+  //    gate already settled is never the home of THIS turn's denial
+  //    (isAdjudicatedRow) — the search moves past it to this turn's attempt.
   for (const msg of messages) {
     if (anchorMatched) break;
     for (const tc of msg.toolCalls) {
+      if (isAdjudicatedRow(tc)) continue;
       if (toolCallIdentityToken(tc) !== anchorToken) continue;
       overlayDeniedStreamCall(tc, anchorInput, mergedPolicies);
       matchedCalls.add(tc);
@@ -1415,7 +1419,7 @@ export async function reconcileDeniedToolCalls(
 function overlayDeniedStreamCall(
   tc: ToolCall,
   input: Record<string, unknown> | undefined,
-  mergedPolicies: Map<string, MergedToolPolicy> | undefined,
+  mergedPolicies: ReadonlyMap<string, MergedToolPolicy> | undefined,
 ): void {
   markWaitingApproval(tc, mergedPolicies);
   applyGateInput(tc, input);
@@ -1466,6 +1470,42 @@ function isAlreadyCollapsed(tc: ToolCall): boolean {
   );
 }
 
+/**
+ * Whether the server has already adjudicated this row — the user decided its
+ * gate (`approval_action`, the server's field; the runner never writes it).
+ *
+ * Such a row belongs to a gate that is CLOSED: approved and executed, or
+ * declined, in an earlier invocation of this execution. No reconciliation of
+ * the CURRENT turn may rewrite it — not the denial overlay (a new denial of the
+ * same identity is a NEW act and gets its own row), not the twin collapse (the
+ * executed row is the transcript's record). Before this rule the overlay matched
+ * a denial to the FIRST same-identity row in the whole transcript, flipped a
+ * completed, approved row back to WAITING_APPROVAL with its APPROVE still on
+ * it, and the next invocation read that as the decision for the new, undecided
+ * proposal — an approval bleeding to a later identical act (S2 M4 finding F9,
+ * found by the harness contract kit's invariant 3 against this adapter).
+ */
+function isAdjudicatedRow(tc: ToolCall): boolean {
+  return tc.approvalAction !== ApprovalAction.UNSPECIFIED;
+}
+
+/** Adjudicated with a decision that does NOT execute: the user declined this gate. */
+function isDeclinedRow(tc: ToolCall): boolean {
+  switch (tc.approvalAction) {
+    case ApprovalAction.SKIP:
+    case ApprovalAction.REJECT:
+      return true;
+    case ApprovalAction.UNSPECIFIED:
+    case ApprovalAction.APPROVE:
+    case ApprovalAction.APPROVE_ALL:
+      return false;
+    default: {
+      const exhaustive: never = tc.approvalAction;
+      throw new Error(`isDeclinedRow: unknown approval action ${String(exhaustive)}`);
+    }
+  }
+}
+
 /**
  * Whether a tool call carries a change/output of its own — the signal that it is
  * authoritative for its resource rather than a redundant denial/cancel twin.
@@ -1556,8 +1596,11 @@ export function collapseRedundantToolCallTwins(messages: AgentMessage[]): number
     if (group.length < 2) continue; // a lone call is never a twin
 
     // Keepers carry authoritative state: a change/output of their own
-    // (carriesOwnChange) or the approval gate itself. For a file mutation the gate
-    // is the sole authoritative row (the row carries no diff — review lives in the
+    // (carriesOwnChange), the approval gate itself, or a gate an earlier
+    // invocation already settled (isAdjudicatedRow — the transcript's record of
+    // what the user decided and what ran; a same-identity act in a later turn
+    // is a new act, never this row's twin). For a file mutation the gate is the
+    // sole authoritative row (the row carries no diff — review lives in the
     // ledger, or the row IS the no-storage deny-gate), so a denied write's
     // same-identity siblings collapse onto it; a shell/MCP twin keeps every
     // distinct run with output.
@@ -1565,6 +1608,7 @@ export function collapseRedundantToolCallTwins(messages: AgentMessage[]): number
       group.filter(
         (tc) =>
           carriesOwnChange(tc) ||
+          isAdjudicatedRow(tc) ||
           tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
       ),
     );
@@ -1613,6 +1657,7 @@ function collapseNonAnchorDenials(
   let collapsed = 0;
   for (const msg of messages) {
     for (const tc of msg.toolCalls) {
+      if (isAdjudicatedRow(tc)) continue;
       const token = toolCallIdentityToken(tc);
       if (token === anchorToken) continue;
       if (!deniedTokens.has(token)) continue;
@@ -1714,7 +1759,7 @@ function findUnmatchedStreamCallByNormalizedSalient(
 ): ToolCall | undefined {
   for (const msg of messages) {
     for (const tc of msg.toolCalls) {
-      if (matchedCalls.has(tc)) continue;
+      if (matchedCalls.has(tc) || isAdjudicatedRow(tc)) continue;
       const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
       if (normalizedFileSalient(id.key, id.salient, workspaceRoot) === wanted) {
         return tc;
@@ -2189,7 +2234,7 @@ function toolCallArgs(tc: ToolCall): Record<string, unknown> {
  */
 function markWaitingApproval(
   tc: ToolCall,
-  mergedPolicies?: Map<string, MergedToolPolicy>,
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>,
 ): void {
   tc.status = ToolCallStatus.TOOL_CALL_WAITING_APPROVAL;
   tc.requiresApproval = true;
@@ -2209,7 +2254,7 @@ function synthesizeWaitingApprovalToolCall(
   salient: string,
   digest: string,
   token: string,
-  mergedPolicies?: Map<string, MergedToolPolicy>,
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>,
 ): ToolCall {
   const tc = create(ToolCallSchema, {
     id: `approval:${token}`,
@@ -2255,7 +2300,7 @@ function resolveDeniedApprovalMessage(
   name: string,
   mcpServerSlug: string,
   args: Record<string, unknown>,
-  mergedPolicies?: Map<string, MergedToolPolicy>,
+  mergedPolicies?: ReadonlyMap<string, MergedToolPolicy>,
 ): string {
   if (mergedPolicies && mcpServerSlug) {
     const policy = lookupMcpToolPolicy(name, mcpServerSlug, mergedPolicies);

package/src/activities/execute-cursor/prompt-builder.ts

@@ -48,6 +48,8 @@ import {
   type DownloadUrlKind,
 } from "../../shared/attachment-download-urls.js";
 import { formatTurnRecoveryText } from "./turn-recovery.js";
+import type { SkillMetadata } from "../../shared/skill-resolver.js";
+import type { AgentResolution, AgentResolutionReason } from "./session-lifecycle.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -66,12 +68,6 @@ const RUNNER_PATH_MARKERS = [
   "/dist/main.js",
 ] as const;
 
-export interface SkillMetadata {
-  name: string;
-  description: string;
-  path: string;
-}
-
 /**
  * Vision facts about this turn's attachments, rendered inside the
  * input-files section: which images the model can see inline (in send
@@ -80,7 +76,7 @@ export interface SkillMetadata {
  */
 export interface VisionPromptInfo {
   inlineFilenames: string[];
-  notViewable: NotViewableEntry[];
+  notViewable: readonly NotViewableEntry[];
 }
 
 /**
@@ -104,13 +100,13 @@ export interface AttachmentPromptEntry {
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
-  skills: SkillMetadata[];
+  skills: readonly SkillMetadata[];
   /**
    * Serving proactive channels + their approved templates — rendered as
    * the `<available_channel_templates>` section (proactive-messaging
    * DD-003 D5) beside the synthesized send_channel_message tool.
    */
-  channelMessaging?: ChannelMessagingInfo[];
+  channelMessaging?: readonly ChannelMessagingInfo[];
   subAgents: SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
@@ -326,7 +322,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
  */
 export function buildReinvocationPrompt(
   pendingApprovals: PendingApproval[],
-  approvalDecisions: Map<string, ApprovalAction>,
+  approvalDecisions: ReadonlyMap<string, ApprovalAction>,
   appliedToolCallIds: ReadonlySet<string> = new Set(),
 ): string {
   const approved: string[] = [];
@@ -415,7 +411,7 @@ export function buildHitlRecoveryPrompt(
   recovery: {
     turnDigest: string | undefined;
     pendingApprovals: PendingApproval[];
-    approvalDecisions: Map<string, ApprovalAction>;
+    approvalDecisions: ReadonlyMap<string, ApprovalAction>;
     appliedToolCallIds?: ReadonlySet<string>;
   },
 ): string {
@@ -508,7 +504,7 @@ export function formatConversationCatchupSection(digest: string): string {
   return `<conversation_catchup>\n${formatConversationCatchupText(digest)}\n</conversation_catchup>`;
 }
 
-export function formatSkillsSection(skills: SkillMetadata[]): string {
+export function formatSkillsSection(skills: readonly SkillMetadata[]): string {
   const entries = skills.map(
     (s) => `- **${s.name}**: ${s.description}\n  Path: \`${s.path}\``,
   );
@@ -810,3 +806,322 @@ export function buildToolApprovalRuleFile(): string {
     "",
   ].join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// Prompt selection — which of the four shapes a turn sends, from how the
+// agent resolved and whether the turn carries adjudicated approvals. Moved
+// from `index.ts` at S2 M3b, body unchanged; `__tests__/build-prompt.test.ts`
+// pins every branch.
+// ---------------------------------------------------------------------------
+
+export interface BuildPromptInput {
+  resolution: AgentResolution;
+  /** Empty when the turn carries no adjudicated approvals (see isHitlReinvocation). */
+  approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+  instructions: string;
+  userMessage: string;
+  skills: readonly SkillMetadata[];
+  /**
+   * Serving proactive channels + their templates (the DD-006 D2
+   * discovery read) — the `<available_channel_templates>` section.
+   */
+  channelMessaging?: readonly ChannelMessagingInfo[];
+  subAgents: SubAgent[];
+  workspaceDirs: string[];
+  workspaceFileRefs: string[];
+  /**
+   * This turn's resolved attachments for the `<input_files>` section —
+   * final paths plus duplicate-rename disclosure (attachment-resolver.ts).
+   */
+  attachments: AttachmentPromptEntry[];
+  /**
+   * Vision facts for the input-files section (T04): which attachments the
+   * model sees inline and which degraded to path-only. PER-TURN like the
+   * catchup — it rides both the enhanced prompt and a resumed turn's prefix.
+   */
+  vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — keys
+   * the input-files hand-off wording. Sourced from the resolved
+   * artifactStorage's self-description; absent when no storage resolved.
+   */
+  downloadUrlKind?: DownloadUrlKind;
+  pendingApprovals: PendingApproval[];
+  /**
+   * Approved whole-file writes the runner already applied itself (exact-apply).
+   * The reinvocation prompt marks these as done so the model does not redo them;
+   * the remaining approved actions are the ones it must still carry out.
+   */
+  appliedToolCallIds?: ReadonlySet<string>;
+  interactionMode?: InteractionMode;
+  /**
+   * The execution is a Build-from-plan turn (spec.execution_config
+   * .build_from_plan): both prompt paths carry the implement-plan directive.
+   */
+  buildFromPlan?: boolean;
+  /**
+   * Rollover context bridge from `SessionSpec.metadata` (cloud DD-013).
+   * Only the enhanced-prompt path consumes it — a resumed agent's native
+   * context IS the previous conversation, so it needs no bridge.
+   */
+  contextBridge?: string;
+  /**
+   * Channel sender identity from `SessionSpec.metadata`. Like the bridge,
+   * only the enhanced-prompt path consumes it — a resumed agent's native
+   * context already carries it from the session's first turn.
+   */
+  senderIdentity?: SenderIdentity;
+  /**
+   * Embedder-supplied session context from `SessionSpec.metadata`. Like
+   * the bridge, only the enhanced-prompt path consumes it — a resumed
+   * agent's native context already carries it from the session's first
+   * turn.
+   */
+  sessionContext?: string;
+  /**
+   * Platform-declared standing preferences from the execution spec's
+   * `declared_preferences` (stigmer/stigmer#293). Like the bridge, only
+   * the enhanced-prompt path consumes it — deliberately frozen per Cursor
+   * session (DD-002 D3): the first turn delivers it into the agent's own
+   * conversation store, and repeating it on resumed turns would bloat the
+   * store with identical content.
+   */
+  declaredPreferences?: DeclaredPreferencesContent;
+  /**
+   * The subject's confirmed memories from the execution spec's
+   * `recalled_memories` (stigmer/stigmer#293 Phase 2, DD-006). Like the
+   * preferences, only the enhanced-prompt path consumes it — deliberately
+   * frozen per Cursor session (DD-002 D3, inherited by DD-006 D4): the
+   * first turn delivers it into the agent's own conversation store, and
+   * repeating it on resumed turns would bloat the store with identical
+   * content.
+   */
+  recalledMemories?: RecalledMemoriesContent;
+  /**
+   * Conversation catchup from the execution spec's `conversation_catchup`
+   * (cloud DD-006): what happened on the channel conversation that the
+   * agent has not seen. PER-TURN, so unlike the standing values
+   * above it rides BOTH prompt paths — the enhanced prompt and a resumed
+   * turn's prefix (the `interaction_mode` shape). Handback lands
+   * mid-session on a resumed agent: the resumed path is the one that
+   * matters. Once delivered, the digest persists in the agent's own
+   * conversation store; the next turn's field is composed fresh and is
+   * usually blank.
+   */
+  conversationCatchup?: string;
+  /**
+   * The turn's recorded transcript rendered as digest lines
+   * (turn-recovery.ts), composed from `status.messages` at the call site.
+   * Consumed ONLY by the HITL-recovery shape — a fresh agent that replaced
+   * a lost one mid-HITL needs the story of the work it no longer remembers
+   * (issue #366); every other shape either has native context or no prior
+   * work to tell.
+   */
+  turnRecoveryDigest?: string;
+}
+
+/**
+ * Select and build the appropriate prompt based on resolution reason and
+ * HITL state.
+ *
+ * Conversation continuation is carried entirely by the Cursor SDK's native
+ * agent state (the local SQLite store persisted on the durable workspace
+ * volume, or cloud server-side state) — there is no separate continuation
+ * store. The prompt therefore depends only on how the agent was resolved:
+ *
+ * 1. HITL reinvocation,        -> buildReinvocationPrompt (approval decisions
+ *    resumed agent                 only; the resumed agent's native context
+ *                                  carries the prior conversation)
+ * 2. HITL reinvocation,        -> buildHitlRecoveryPrompt (full context +
+ *    fresh agent after            the turn's recorded transcript + decisions;
+ *    resume failure               the replacement agent's conversation is
+ *                                 empty, and both fresh-agent crossings —
+ *                                 resolution-time resume failure and mid-send
+ *                                 poisoned-handle recovery — land here by
+ *                                 keying on the reason, issue #366)
+ * 3. resumed_successfully      -> raw userMessage (native context carries it)
+ * 4. first execution / fresh   -> buildEnhancedPrompt (full instructions +
+ *    agent after resume failure   skills; no prior conversation to inherit)
+ */
+/**
+ * Whether this activity invocation is a HITL re-invocation — the turn resumes
+ * an agent purely to convey approval decisions, carrying NO user message.
+ * Discriminates the two surfaces that depend on the agent already holding
+ * this turn's content natively — the prompt shape (below) and the primary
+ * send's vision payload — but never alone: both pair it with
+ * `resolution.reason`, because a FRESH agent mid-HITL holds nothing and
+ * needs the full re-delivery (issue #366).
+ */
+export function isHitlReinvocation(
+  approvalDecisions: ReadonlyMap<string, ApprovalAction>,
+): boolean {
+  return approvalDecisions.size > 0;
+}
+
+/**
+ * Whether the PRIMARY send delivers the turn's vision payload. The invariant
+ * is "images accompany the user's turn message, wherever the conversation
+ * does not already hold them" — so the only send that skips them is a HITL
+ * re-invocation of a successfully RESUMED agent, whose native conversation
+ * carries the images from the original send. A fresh agent mid-HITL
+ * (resolution-time resume failure — issue #366's vision corollary) holds
+ * nothing and needs the re-delivery. The mid-send recovery retries always
+ * run on a fresh agent, so their send sites carry the payload
+ * unconditionally rather than consulting this.
+ */
+export function primarySendCarriesImages(
+  approvalDecisions: ReadonlyMap<string, ApprovalAction>,
+  reason: AgentResolutionReason,
+): boolean {
+  return !(isHitlReinvocation(approvalDecisions) && reason === "resumed_successfully");
+}
+
+/**
+ * Whether a prompt built for this resolution carries the STANDING context —
+ * instructions, skills, declared preferences, recalled memories, session
+ * context. Exactly one resolution shape does not: a successfully RESUMED
+ * agent, whose native conversation already holds the first message's
+ * context (both its prompt shapes — the raw follow-up and the
+ * decisions-only HITL reinvocation — send no standing sections).
+ *
+ * The named authority for that routing property (the
+ * primarySendCarriesImages idiom): buildPrompt's internal routing and the
+ * activity's standing-context preparation (e.g. the memory selection gate)
+ * both consult THIS predicate, so the two can never drift.
+ */
+export function promptCarriesStandingContext(reason: AgentResolutionReason): boolean {
+  return reason !== "resumed_successfully";
+}
+
+/**
+ * Append the structured-output contract to a prompt when the execution
+ * requests one. A per-turn directive (the buildFromPlan rule): it must ride
+ * every prompt this turn sends — the primary send AND the poisoned-handle
+ * recovery rebuild, which previously lost it (issue #366 ride-along).
+ */
+export function appendStructuredOutputDirective(
+  basePrompt: string,
+  schema: Record<string, unknown> | undefined,
+): string {
+  if (!schema) return basePrompt;
+  const schemaStr = JSON.stringify(schema, null, 2);
+  return basePrompt + `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
+}
+
+export function buildPrompt(input: BuildPromptInput): string {
+  const {
+    resolution,
+    approvalDecisions,
+    instructions,
+    userMessage,
+    skills,
+    subAgents,
+    workspaceDirs,
+    workspaceFileRefs,
+    attachments,
+    interactionMode,
+    buildFromPlan,
+    conversationCatchup,
+  } = input;
+
+  // HITL reinvocation: the decisions-only prompt is correct ONLY while the
+  // agent's native context still carries the prior conversation — which only
+  // resumed_successfully guarantees. Any other reason means a fresh agent
+  // mid-HITL (in practice created_after_resume_failure: the stored handle
+  // failed to resume, or a poisoned handle was replaced mid-send), which
+  // gets the full recovery shape instead — enhanced context + the turn's
+  // recorded transcript + the same decisions — because the bare decisions on
+  // an empty conversation strand the agent with instructions and no story,
+  // and the session inherits that amnesia permanently (issue #366).
+  if (isHitlReinvocation(approvalDecisions)) {
+    if (promptCarriesStandingContext(resolution.reason)) {
+      return buildHitlRecoveryPrompt(
+        {
+          instructions,
+          userMessage,
+          skills,
+          channelMessaging: input.channelMessaging ?? [],
+          subAgents,
+          workspaceDirs,
+          workspaceFileRefs,
+          attachments,
+          vision: input.vision,
+          downloadUrlKind: input.downloadUrlKind,
+          interactionMode,
+          buildFromPlan,
+          contextBridge: input.contextBridge,
+          senderIdentity: input.senderIdentity,
+          sessionContext: input.sessionContext,
+          declaredPreferences: input.declaredPreferences,
+          recalledMemories: input.recalledMemories,
+          conversationCatchup,
+        },
+        {
+          turnDigest: input.turnRecoveryDigest,
+          pendingApprovals: input.pendingApprovals,
+          approvalDecisions,
+          appliedToolCallIds: input.appliedToolCallIds,
+        },
+      );
+    }
+    return buildReinvocationPrompt(
+      input.pendingApprovals,
+      approvalDecisions,
+      input.appliedToolCallIds,
+    );
+  }
+
+  // A successfully resumed agent carries its own conversation context via the
+  // SDK's native store — send the raw user message with no preamble. The
+  // exceptions are the per-EXECUTION values, which never inherit from the
+  // session's first turn: the interaction-mode prefix (a follow-up can switch
+  // Agent→Plan mid-session, and for Cursor the prompt is the only plan-mode
+  // enforcement), the implement-plan directive (the build turn is usually a
+  // follow-up on a resumed agent), THIS turn's attachments (spec.attachments
+  // is per-execution — a file sent on a follow-up turn materializes for this
+  // turn and would otherwise never be announced at all), and the conversation
+  // catchup (handback ALWAYS lands mid-session on a resumed agent — this
+  // prefix is the property the metadata lane structurally cannot deliver,
+  // cloud DD-006). Catchup last: it is context, and context sits closest to
+  // the task (the enhanced prompt's own ordering doctrine); the input files
+  // precede it because they are this turn's payload, not background.
+  if (!promptCarriesStandingContext(resolution.reason)) {
+    const prefixes = [
+      formatInteractionModePrefix(interactionMode),
+      formatImplementPlanSection(buildFromPlan, attachments),
+      attachments.length > 0
+        ? formatInputFiles(attachments, input.vision, input.downloadUrlKind)
+        : undefined,
+      conversationCatchup !== undefined
+        ? formatConversationCatchupSection(conversationCatchup)
+        : undefined,
+    ].filter((p): p is string => p !== undefined);
+    return prefixes.length > 0
+      ? [...prefixes, userMessage].join("\n\n")
+      : userMessage;
+  }
+
+  // First execution, or a fresh agent created after a resume failure: there is
+  // no prior conversation to inherit, so start a new turn with full context —
+  // including the rollover bridge, when the session carries one.
+  return buildEnhancedPrompt({
+    instructions,
+    userMessage,
+    skills,
+    channelMessaging: input.channelMessaging ?? [],
+    subAgents,
+    workspaceDirs,
+    workspaceFileRefs,
+    attachments,
+    vision: input.vision,
+    downloadUrlKind: input.downloadUrlKind,
+    interactionMode,
+    buildFromPlan,
+    contextBridge: input.contextBridge,
+    senderIdentity: input.senderIdentity,
+    sessionContext: input.sessionContext,
+    declaredPreferences: input.declaredPreferences,
+    recalledMemories: input.recalledMemories,
+    conversationCatchup,
+  });
+}