agent-relay-server 0.124.0 → 0.125.0

package/runner/plugins/claude/hooks/relay-status.sh

@@ -115,6 +115,7 @@ relay_post_session_turn() {
   # below, so the agent is not nagged to /reply (and does not re-emit).
   local transcript_path="${1:-}"
   local last_assistant_message="${2:-}"
+  local prompt_id="${3:-}"
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0
   # transcript_path is the primary capture source, but the Stop payload can omit it
@@ -127,6 +128,13 @@ relay_post_session_turn() {
     [ "$body" != "{" ] && body="${body},"
     body="${body}\"lastAssistantMessage\":${last_assistant_message}"
   fi
+  # prompt_id (#1086): Claude's native turn identifier — the stable id the runner
+  # uses instead of a minted random UUID, and the deterministic key it slices the
+  # transcript by for full-mode enrichment.
+  if [ -n "$prompt_id" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"promptId\":\"$(relay_json_escape "$prompt_id")\""
+  fi
   body="${body}}"
   curl -fsS -X POST "http://127.0.0.1:${port}/session-turn" \
     -H 'Content-Type: application/json' \
@@ -144,7 +152,9 @@ relay_post_user_prompt() {
   [ -z "$payload" ] && return 0
   command -v jq >/dev/null 2>&1 || return 0
   local body
-  body="$(printf '%s' "$payload" | jq -c '{prompt: (.prompt // ""), transcriptPath: (.transcript_path // "")}' 2>/dev/null || true)"
+  # promptId (#1086): Claude's native prompt_id for the turn this prompt starts —
+  # the stable turn identifier the runner uses instead of minting a random UUID.
+  body="$(printf '%s' "$payload" | jq -c '{prompt: (.prompt // ""), transcriptPath: (.transcript_path // ""), promptId: (.prompt_id // "")}' 2>/dev/null || true)"
   [ -z "$body" ] && return 0
   case "$body" in *'"prompt":""'*) return 0 ;; esac
   curl -fsS --max-time 3 -X POST "http://127.0.0.1:${port}/user-prompt" \

package/runner/plugins/claude/hooks/stop.sh

@@ -23,7 +23,12 @@ bg_count="$(relay_background_task_count "$payload")"
 # (stop_hook_active=true) must NOT suppress capturing this turn's response, or the live mirror
 # silently drops frames. Always post the turn; only the reply-obligation decision is gated below.
 last_assistant_msg="$(echo "$payload" | jq -c '.last_assistant_message // empty' 2>/dev/null || true)"
-relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg"
+# prompt_id (#1086): Claude's own native turn identifier, correlating this Stop with
+# the same UUID stamped on every transcript entry of the turn (and the id the
+# UserPromptSubmit hook reported at turn start) — the stable replacement for a
+# runner-minted random UUID.
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg" "$prompt_id"
 
 if [ "$stop_hook_active" != "true" ]; then
   # `|| true`: under `set -e`, a non-zero from the obligation check must never abort

package/runner/plugins/claude/hooks/user-prompt-submit.sh

@@ -3,7 +3,12 @@ set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
 relay_install_hook_guard user-prompt-submit
 payload="$(cat || true)"
-relay_post_status busy
+# prompt_id (#1086): Claude's own native turn identifier for the prompt starting
+# now — the same UUID the Stop hook reports and the transcript stamps on every
+# entry of this turn. Passed as the busy report's `id` so the runner adopts it as
+# currentTurnId instead of minting a random UUID (runner-core.ts setProviderStatus).
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_status busy "" "$prompt_id"
 # Mirror a terminal/TUI-typed prompt into the dashboard chat and start reasoning
 # tailing for this turn. No-op for prompts the runner injected (chat box / relay).
 relay_post_user_prompt "$payload"

package/runner/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk/types/guards";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
@@ -50,6 +50,10 @@ export interface ProviderSessionEvent {
   turnId?: string;
   /** True only when this response is the completed provider turn, not an intermediate flush. */
   final?: boolean;
+  /** Whether the turn-final edge was provider-native or reconstructed. Set only alongside `final`. */
+  confidence?: MessageFinalityConfidence;
+  /** Why the provider turn ended. Set only alongside `final`. */
+  endedBy?: MessageTurnEndReason;
   label?: string;
   status?: "running" | "completed" | "failed";
   streaming?: boolean;

package/runner/src/adapters/claude-transcript.ts

@@ -46,6 +46,16 @@ interface TranscriptEntry {
   // Events/countSubstantiveTurns) intentionally do NOT filter — changing them
   // would shift the #184/#185 baselines, a separate concern.
   isSidechain?: boolean;
+  // Every entry carries its own `uuid` and its `parentUuid` (the entry it was
+  // appended after), forming a causal chain for the whole session. A `user`-type
+  // entry — whether the real prompt or a synthetic tool_result — is stamped with
+  // `promptId`: the same UUID Claude's Stop-hook payload reports as `prompt_id`,
+  // shared by every entry from that prompt until the next one. Assistant entries
+  // don't carry `promptId` directly; their turn is resolved by walking `parentUuid`
+  // back to the nearest ancestor that has one (see resolveEntryPromptId).
+  uuid?: string;
+  parentUuid?: string;
+  promptId?: string;
 }
 
 function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
@@ -147,59 +157,39 @@ export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: nu
 }
 
 /**
- * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
- * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ * Resolve the `promptId` (Stop hook's `prompt_id`) a transcript entry belongs to.
+ * A `user`-type entry (the real prompt, or a synthetic tool_result) carries its own
+ * `promptId`; an assistant entry doesn't, so its turn is resolved by walking
+ * `parentUuid` back through the causal chain until an ancestor with one is found.
+ * Returns undefined for an entry with no resolvable ancestor (e.g. the very first
+ * turn of a process, before any `promptId` has ever been stamped).
  */
-export function countTranscriptEntries(jsonl: string): number {
-  let count = 0;
-  for (const line of jsonl.split("\n")) {
-    if (!line.trim()) continue;
-    try { JSON.parse(line); count++; } catch {}
-  }
-  return count;
-}
-
-/**
- * Returns only the text from the LAST assistant entry in the current turn.
- * Unlike extractLastAssistantTurn which collects all intermediate text between
- * tool calls, this returns just the final response — what the user sees as the
- * concluding message.
- */
-export function extractFinalAssistantMessage(jsonl: string): string {
-  const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = false;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let entry: TranscriptEntry;
-    try {
-      entry = JSON.parse(trimmed) as TranscriptEntry;
-    } catch {
-      continue;
-    }
-    if (isSidechainEntry(entry)) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
-    const text = assistantText(entry);
-    if (text) lastText = text;
+function resolveEntryPromptId(entry: TranscriptEntry, byUuid: ReadonlyMap<string, TranscriptEntry>): string | undefined {
+  let current: TranscriptEntry | undefined = entry;
+  const visited = new Set<string>();
+  while (current) {
+    if (typeof current.promptId === "string" && current.promptId) return current.promptId;
+    const parentUuid = current.parentUuid;
+    if (!parentUuid || visited.has(parentUuid)) return undefined;
+    visited.add(parentUuid);
+    current = byUuid.get(parentUuid);
   }
-  return lastText.trim();
+  return undefined;
 }
 
 /**
- * Like extractFinalAssistantMessage but skips the first `afterEntry` valid JSON
- * entries. Used when a PreToolUse pre-flush already emitted the text before a
- * blocking control, so final-mode Stop capture only sees later assistant text.
+ * Deterministic replacement for extractLastAssistantTurnAfterEntry's "walk back to
+ * the last real user prompt" heuristic: collects assistant `text` blocks for entries
+ * whose resolved promptId (see resolveEntryPromptId) equals the Claude-native
+ * `promptId` the Stop hook reported for this turn. Skips the first `afterEntry`
+ * entries the same way, for pre-flush resume. Since entries never move once
+ * written, a turn's promptId membership is exact — no text-shape guessing about
+ * what counts as a "real" prompt.
  */
-export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry: number): string {
+export function extractAssistantTurnForPrompt(jsonl: string, promptId: string, afterEntry = 0): string {
   const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = afterEntry > 0;
+  const byUuid = new Map<string, TranscriptEntry>();
+  const collected: string[] = [];
   let entryIndex = 0;
   for (const line of lines) {
     const trimmed = line.trim();
@@ -211,26 +201,30 @@ export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry
       continue;
     }
     entryIndex++;
+    if (typeof entry.uuid === "string" && entry.uuid) byUuid.set(entry.uuid, entry);
     if (isSidechainEntry(entry)) continue;
     if (entryIndex <= afterEntry) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
+    if (entry.type !== "assistant") continue;
+    if (resolveEntryPromptId(entry, byUuid) !== promptId) continue;
     const text = assistantText(entry);
-    if (text) lastText = text;
+    if (text) collected.push(text);
   }
-  return lastText.trim();
+  return collected.join("\n\n").trim();
 }
 
 /**
- * Extract text from the `last_assistant_message` field in the Stop hook
- * payload. This is the content of the final assistant message — either a plain
- * string or an array of content blocks (same shape as transcript entries).
- * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
  */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
 /**
  * Extract the ordered narration, reasoning, and tool steps for the most recent
  * turn (since the last real user prompt). Used by the reasoning tailer to stream

package/runner/src/adapters/codex-agent-message-capture.ts

@@ -4,7 +4,6 @@ type CompleteItemOptions = { includeInResponse?: boolean; phase?: unknown };
 
 const MAX_CAPTURED_RESPONSE_CHARS = 16_000;
 const TRUNCATION_MARKER_PREFIX = "[truncated:";
-const TERSE_FINAL_MAX_CHARS = 280;
 
 export class CodexAgentMessageCapture {
   private segments: ResponseEntry[][] = [];
@@ -46,11 +45,17 @@ export class CodexAgentMessageCapture {
     this.currentSegment = [];
   }
 
+  // Deterministic turn-final response: the TRAILING agentMessage run only — all items after
+  // the LAST non-message item (tool call, file change, reasoning...) in the turn (design
+  // #1079 §3.2). Earlier agentMessage segments are mid-work narration, already mirrored live
+  // via `emit`, and must not be re-injected into the final (#1083 Finding 2). Codex's own
+  // phase:"commentary" tag (see completeItem above) still trims commentary items out of
+  // whichever segment they land in, but is not the sole guard against leading narration.
   finish(emit: EmitAgentMessage): string | undefined {
     this.closeSegment(emit);
-    const selectedSegments = selectResponseSegments(this.segments);
+    const trailingSegment = this.segments.at(-1);
     this.segments = [];
-    const text = selectedSegments.length ? selectedSegments.map(segmentBody).join("\n\n").trim() : undefined;
+    const text = trailingSegment ? segmentBody(trailingSegment) : undefined;
     return truncateCapturedResponse(text);
   }
 
@@ -96,43 +101,10 @@ export class CodexAgentMessageCapture {
   }
 }
 
-function selectResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] {
-  const nonEmptySegments = segments.filter((segment) => segment.length > 0);
-  const finalSegment = nonEmptySegments.at(-1);
-  if (!finalSegment) return [];
-  const finalBody = segmentBody(finalSegment);
-  if (!isTerseTerminalStatus(finalBody)) return [finalSegment];
-
-  // Codex often posts the real wrap-up across multiple assistant segments before a
-  // final workspace-ready/status line. Keep contiguous substantive segments after
-  // the last procedural assistant segment, then append the terminal status.
-  const selectedSegments: ResponseEntry[][] = [];
-  for (let index = nonEmptySegments.length - 2; index >= 0; index -= 1) {
-    const candidate = nonEmptySegments[index];
-    if (!candidate || !isSubstantiveResponseSegment(segmentBody(candidate))) break;
-    selectedSegments.unshift(candidate);
-  }
-  return [...selectedSegments, finalSegment];
-}
-
 function segmentBody(segment: ResponseEntry[]): string {
   return segment.map((entry) => entry.body).join("\n\n").trim();
 }
 
-function isTerseTerminalStatus(body: string): boolean {
-  if (body.length > TERSE_FINAL_MAX_CHARS) return false;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return false;
-  return /\b(?:landed|ready for review|handed off|no further action|done|complete|completed|committed|merged)\b/i.test(body);
-}
-
-function isSubstantiveResponseSegment(body: string): boolean {
-  if (body.length >= 120) return true;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return true;
-  if (/\*\*(?:what changed|changes?|tests?|gates?|verification|risks?|residual risk|summary)\b/i.test(body)) return true;
-  if (/^#{1,3}\s+\S/m.test(body)) return true;
-  return body.split(/\n{2,}/).length >= 2;
-}
-
 function truncateCapturedResponse(text: string | undefined): string | undefined {
   if (!text || text.length <= MAX_CAPTURED_RESPONSE_CHARS) return text;
   return `${text.slice(0, MAX_CAPTURED_RESPONSE_CHARS).trimEnd()}\n\n${TRUNCATION_MARKER_PREFIX} showing first ${MAX_CAPTURED_RESPONSE_CHARS} of ${text.length} chars]`;

package/runner/src/adapters/codex.ts

@@ -1,7 +1,7 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { ContextState, InteractivePrompt, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import type { ContextState, InteractivePrompt, LivenessSignal, Message, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
@@ -144,13 +144,13 @@ export class CodexAdapter implements ProviderAdapter {
       const turnStatus = isRecord(activeTurn) ? stringValue(activeTurn.status) : undefined;
       if (turnStatus === "inProgress") return "busy";
       if (turnStatus === "completed" || turnStatus === "interrupted" || turnStatus === "failed") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(turnStatus));
         return "idle";
       }
       const threadStatus = statusType(thread?.status);
       if (threadStatus === "active") return "busy";
       if (threadStatus === "idle" || threadStatus === "notLoaded" || threadStatus === "systemError") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(threadStatus));
         return "idle";
       }
     } catch {
@@ -508,7 +508,7 @@ export class CodexAdapter implements ProviderAdapter {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(method));
       }
     }
     if ((method.includes("thread/compacted") || method.includes("thread.compacted")) && threadId) {
@@ -527,15 +527,16 @@ export class CodexAdapter implements ProviderAdapter {
         if (status === "idle" || status === "notLoaded") this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
         if (status === "active") this.statusCb({ status: "busy", reason: "provider-turn", providerState: this.providerStateFromThreadStatus(params?.status, params) });
-        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn();
+        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn(codexEndedByFrom(status));
       }
     }
   }
 
   // Turn one completed Codex thread item into a session-mirror event. agentMessage text is
-  // mirrored as narration as it lands; the captured turn-final response repeats the substantive
-  // assistant answer, including a substantive wrap-up segment before a terse terminal status.
-  // The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  // mirrored as narration as it lands; the captured turn-final response repeats only the
+  // TRAILING agentMessage run — the segment after the last tool/file-change/reasoning
+  // boundary (design #1079 §3.2) — never earlier mid-work narration, which was already
+  // mirrored live. The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
   private handleCodexItem(item: Record<string, unknown> | undefined): void {
     if (!item) return;
     const type = stringValue(item.type);
@@ -676,14 +677,23 @@ export class CodexAdapter implements ProviderAdapter {
     if (method.includes("outputDelta") || method.includes("output_delta") || method.includes("progress")) return;
   }
 
-  private flushTurnResponse(): void {
+  // A turn-final capture is emitted ONLY for a genuine `completed` turn (design #1079 §3.2):
+  // failed/interrupted turns must never produce a turn-final. Every "response"-type
+  // ProviderSessionEvent is unconditionally dual-stamped turnFinal/final downstream
+  // (publishCapturedResponse's provider-agnostic stamp), so the only way to keep a
+  // failed/interrupted partial OUT of D's work-final ring is to never emit it as a
+  // "response" event at all (#1083 Finding 1). The partial text was already mirrored live
+  // as narration by the `emit` callback inside agentMessageCapture.finish(), so it's still
+  // visible in the dashboard.
+  private flushTurnResponse(endedBy: MessageTurnEndReason): void {
     const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
-    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+    if (!text || endedBy !== "completed") return;
+    this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, confidence: "definitive", endedBy, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
   }
 
-  private finishMainTurn(): void {
+  private finishMainTurn(endedBy: MessageTurnEndReason): void {
     this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
-    this.flushTurnResponse();
+    this.flushTurnResponse(endedBy);
     const turnId = this.activeTurnId;
     this.activeTurnId = undefined;
     this.pendingApprovals.clear();
@@ -1151,6 +1161,14 @@ function statusType(value: unknown): string | undefined {
   return isRecord(value) ? stringValue(value.type) : undefined;
 }
 
+// Maps any Codex turn-ending signal — a turn/failed|interrupted (dot-notation too) app-server
+// method name, a turn status ("completed"/"interrupted"/"failed"), or a thread status
+// ("idle"/"notLoaded"/"systemError") — to the Part A (#1082) turn-end reason. "completed" is
+// the default for every signal that isn't explicitly a failure or an interruption.
+function codexEndedByFrom(value: string | undefined): MessageTurnEndReason {
+  return value === "systemError" || value?.includes("failed") ? "failed" : value?.includes("interrupted") ? "interrupted" : "completed";
+}
+
 function activeFlags(value: unknown): string[] {
   if (!isRecord(value) || !Array.isArray(value.activeFlags)) return [];
   return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);

package/runner/src/control-server.ts

@@ -49,12 +49,15 @@ interface ControlServerOptions {
   // dashboard chat without the agent re-emitting it via /reply.
   // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
   // un-mirrored narrative before the interactive form appears in chat (#435).
-  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void>;
+  // promptId (#1086): Claude's native `prompt_id` from the Stop hook payload — the
+  // stable, provider-native turn identifier used instead of a minted random UUID.
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
   // A provider UserPromptSubmit hook hands over the prompt the human typed
   // directly into the session (web terminal / TUI) so the runner can mirror it
   // into the dashboard chat and start tailing the turn transcript for reasoning.
-  onUserPrompt?(input: { prompt: string; transcriptPath?: string }): Promise<void>;
+  // promptId (#1086): Claude's native `prompt_id` for the turn this prompt starts.
+  onUserPrompt?(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void>;
   // A provider session-boundary hook (Claude PreCompact / SessionEnd) signals an imminent
   // context reset or termination so the runner can run end-of-session work (#183 pre-destroy
   // seam: #184 context-ratio capture) before the invasive operation. `reason` is the raw
@@ -501,6 +504,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   const body = await req.json().catch(() => null);
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
   const lastAssistantMessage = isRecord(body) ? body.lastAssistantMessage : undefined;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
   // transcriptPath is the primary source, but it can be absent (known CC Stop edge case).
   // lastAssistantMessage is the fallback for exactly that — accept either; reject only when
   // both are missing so the turn still reaches the dashboard chat (#264).
@@ -511,7 +515,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   // reply-obligation check, so the captured turn must be persisted (and the
   // obligation cleared) before this response returns.
   try {
-    await options.onSessionTurn({ transcriptPath, lastAssistantMessage });
+    await options.onSessionTurn({ transcriptPath, lastAssistantMessage, ...(promptId ? { promptId } : {}) });
     return Response.json({ ok: true });
   } catch (error) {
     return Response.json({ ok: false, reason: errMessage(error) }, { status: 500 });
@@ -524,8 +528,9 @@ async function handleUserPrompt(req: Request, options: ControlServerOptions): Pr
   const prompt = isRecord(body) && typeof body.prompt === "string" ? body.prompt : "";
   if (!prompt.trim()) return Response.json({ ok: false, reason: "prompt required" }, { status: 400 });
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
   // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
-  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath, ...(promptId ? { promptId } : {}) })).catch(() => {});
   return Response.json({ ok: true });
 }
 

package/runner/src/response-capture-report.ts

@@ -12,8 +12,11 @@ type SessionPublisher = (input: {
   replyTo?: number;
 }) => void | Promise<void>;
 
+// #1086: dual-stamp the Part A (#1082) turn-finality field alongside the legacy
+// `final` alias so old consumers keep working while new ones can key off the
+// typed `turnFinal` flag directly instead of every writer's own `final: true`.
 function finalSession(session: MessageSessionMeta): MessageSessionMeta {
-  return { ...session, final: true };
+  return { ...session, turnFinal: true, final: true };
 }
 
 export async function publishCapturedResponse(input: {