agent-relay-runner 0.124.0 → 0.125.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.124.0",
+  "version": "0.125.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.124.0",
+  "version": "0.125.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/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/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/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/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/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/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/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/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/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: {

package/src/runner-core.ts

@@ -16,7 +16,7 @@ import { readRunnerContextProbeState } from "./context-probe-state";
 import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractFinalAssistantMessageAfterEntry, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, extractAssistantTurnForPrompt, countTranscriptEntries, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { IncrementalClaudeTranscriptTail } from "./adapters/claude-transcript-tail";
 import { getManifest } from "agent-relay-providers";
 import { profileUsesProviderHostGlobals } from "./profile-home";
@@ -1291,6 +1291,10 @@ export class AgentRunner {
     }
     if (status === "busy" && reason === "provider-turn") {
       if (!this.currentTurnId) {
+        // For Claude, `update.id` carries the native prompt_id the UserPromptSubmit
+        // hook reported (relay-status.sh → /status) — the same id the Stop hook and
+        // transcript use for this turn. Falls back to a random mint only when no
+        // native id was supplied (e.g. a provider/path that doesn't report one).
         this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
         this.currentTurnStartedAt = Date.now();
         this.compactionMidTurn = false;
@@ -1423,7 +1427,7 @@ export class AgentRunner {
   // isPreFlush: true (#435/#499) — mid-turn PreToolUse boundary. Drain the live
   // tail and force-flush session messages before showing the blocking control;
   // the entry cursor lets Stop capture skip already-emitted text.
-  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void> {
+  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
 
     if (input.isPreFlush) {
@@ -1443,7 +1447,13 @@ export class AgentRunner {
       return;
     }
 
-    const turnId = this.currentTurnId;
+    // Claude's Stop hook reports its own native `prompt_id` — the same UUID the
+    // transcript stamps on every entry of this turn (extractAssistantTurnForPrompt /
+    // resolveEntryPromptId in claude-transcript.ts). It's the authoritative turn
+    // identifier; currentTurnId should already equal it (seeded from the same
+    // prompt_id at turn start — see setProviderStatus / handleUserPrompt), but this
+    // prefers the freshest source so finalization is correct even if the two drift.
+    const turnId = input.promptId ?? this.currentTurnId;
     this.stopReasoningTail();
     // Optional correlation for threading + obligation clearing — never a capture gate.
     let replyToMessageId: number | undefined, replyTarget = "user";
@@ -1464,32 +1474,41 @@ export class AgentRunner {
     const flushCount = this.narrativeFlushEntryCount;
     this.narrativeFlushEntryCount = 0;
 
-    // The Stop hook can fire before the final assistant entry is flushed to disk.
-    // Claude writes thinking and text as separate entries (both with end_turn), so
-    // the transcript can "look complete" while the text entry is still pending.
-    // Retry until both the transcript has an end_turn AND extraction yields text.
-    let body = "";
-    let jsonl: string | undefined;
-    try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
-    if (jsonl !== undefined) {
-      for (let attempt = 0; attempt < 5; attempt++) {
-        if (attempt > 0) {
-          await new Promise((r) => setTimeout(r, 100));
-          try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { break; }
-        }
-        if (!transcriptLooksComplete(jsonl)) continue;
-        // If a pre-flush already emitted entries 1..flushCount, resume after that mark to avoid double-emit (#435/#499).
-        const extract = this.options.providerConfig.chatCaptureMode === "full"
-          ? (j: string) => (flushCount > 0 ? extractLastAssistantTurnAfterEntry(j, flushCount) : extractLastAssistantTurn(j))
-          : (j: string) => (flushCount > 0 ? extractFinalAssistantMessageAfterEntry(j, flushCount) : extractFinalAssistantMessage(j));
-        body = extract(jsonl);
-        if (body) break;
+    // PRIMARY capture source: the Stop hook's own last_assistant_message. Claude
+    // reports it synchronously in the hook payload itself, so there is no
+    // transcript file-read race to retry against — this text is authoritative and
+    // complete the moment the hook fires. The transcript is read at most ONCE
+    // (never retried/looped) and only to enrich "full" mode with the turn's
+    // intermediate narration; if that single read comes up empty (the file simply
+    // hasn't caught up yet) the hook payload text still carries the turn.
+    let body = extractHookAssistantMessage(input.lastAssistantMessage);
+    if (this.options.providerConfig.chatCaptureMode === "full" && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined && transcriptLooksComplete(jsonl)) {
+        // Deterministic slicing via prompt_id→parentUuid chaining when the native id is
+        // known; only fall back to the legacy "last real user prompt" heuristic when that
+        // deterministic slice comes up EMPTY, not merely when turnId is falsy — an old
+        // Claude (<2.1.196) mints a truthy random turnId that never resolves via promptId
+        // chaining, so branching on truthiness alone left this fallback unreachable and
+        // silently dropped intermediate narration in full mode (#1086 review, Finding F1).
+        let full = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        if (!full) full = flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl);
+        if (full) body = full;
       }
     }
-    // Fallback: last_assistant_message from the Stop hook payload, which bypasses
-    // the transcript file race entirely.
-    if (!body && input.lastAssistantMessage) {
-      body = extractHookAssistantMessage(input.lastAssistantMessage);
+    // Last-resort safety net for the default "final" mode (#1086 review, Finding F2):
+    // last_assistant_message is an undocumented Claude hook field. If a future Claude
+    // version renames or drops it, do ONE (never retried — same one-shot discipline as the
+    // "full" mode enrichment above) transcript read rather than silently losing every
+    // capture in the mode nearly every provider config runs in.
+    if (!body && this.options.providerConfig.chatCaptureMode === "final" && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined) {
+        const fallback = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        body = fallback || (flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl));
+      }
     }
     // A pure tool-use turn with no closing text is fine to skip — its reasoning and
     // tool steps already carried the visibility into chat.
@@ -1499,7 +1518,18 @@ export class AgentRunner {
     }
 
     this.sessionLog(`response captured for turn ${turnId ?? "?"} (${body.length} chars${replyToMessageId ? `, replyTo #${replyToMessageId}` : ", no replyTo"})`);
-    await publishCapturedResponse({ publishSessionEvent: (event) => this.publishSessionEvent(event), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: "provider", final: true, ...(turnId ? { turnId } : {}) } });
+    await publishCapturedResponse({
+      publishSessionEvent: (event) => this.publishSessionEvent(event),
+      outbox: this.sessionOutbox,
+      provider: this.options.provider,
+      from: this.agentId,
+      to: replyTarget,
+      body,
+      replyTo: replyToMessageId,
+      // A Stop-hook-driven capture is by construction a definitive, provider-native
+      // turn completion — Claude's own lifecycle hook fired, not a reconstructed guess.
+      session: { type: "response", origin: "provider", final: true, confidence: "definitive", endedBy: "completed", ...(turnId ? { turnId } : {}) },
+    });
     // The agent's reply may have cleared an obligation — refresh the snapshot so the next
     // turn-end doesn't re-prompt for a message already answered (#196).
     if (replyToMessageId) this.obligationCache.markDirty();
@@ -1609,10 +1639,15 @@ export class AgentRunner {
   // it into the dashboard chat so both surfaces stay in sync, and kick off reasoning
   // tailing for the turn. Skips prompts the runner itself injected (chat box, relay
   // deliveries) so those aren't double-posted.
-  private async handleUserPrompt(input: { prompt: string; transcriptPath?: string }): Promise<void> {
+  private async handleUserPrompt(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
     if (!this.currentTurnId) {
-      this.currentTurnId = crypto.randomUUID();
+      // Claude's own prompt_id (from the UserPromptSubmit hook payload) is the
+      // native, stable turn identifier — the same id the Stop hook reports and the
+      // transcript stamps on every entry of this turn. Falls back to a random mint
+      // only for the rare case prompt_id wasn't available (see the ZS base schema
+      // note: absent until the very first user input of the process lifetime).
+      this.currentTurnId = input.promptId ?? crypto.randomUUID();
       this.currentTurnStartedAt = Date.now();
     }
     const text = input.prompt.trim();
@@ -1739,6 +1774,14 @@ export class AgentRunner {
       // Dashboard prompt injection is already answered by this captured App Server
       // response. User obligations still belong to the session mirror; spawner
       // obligations (#413) route to the spawn-parent with replyTo to clear the debt.
+      // #1083: a turn-final capture is ALWAYS mirrored, regardless of reply route — an
+      // autonomous Codex turn with no pending prompt and no eligible obligation used to
+      // hit `if (!route) return` here and vanish before ever reaching publishCapturedResponse,
+      // so it was neither shown in the dashboard nor eligible for report-up. The route only
+      // decides whether an explicit reply/obligation-clear also happens; when there's none,
+      // replyToMessageId stays undefined and the capture still lands as a plain session-mirror
+      // response (enqueueCapturedResponseReport's own `!replyTo` gate then correctly skips
+      // report-up — there's no spawner obligation to report up against).
       let replyToMessageId: number | undefined, replyTarget = "user";
       const pendingPrompt = this.pendingPromptMessageId;
       if (pendingPrompt) {
@@ -1746,10 +1789,9 @@ export class AgentRunner {
         this.pendingPromptMessageId = undefined;
       } else {
         const route = responseCaptureReplyRoute(this.obligationCache.get(), this.currentTurnStartedAt, { suppressUser: true });
-        if (!route) return; // The session mirror will satisfy the user obligation; don't double-post (#196).
-        replyToMessageId = route.replyToMessageId; replyTarget = route.to;
+        if (route) { replyToMessageId = route.replyToMessageId; replyTarget = route.to; }
       }
-      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent(sessionEvent), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) } });
+      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent(sessionEvent), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.confidence ? { confidence: event.confidence } : {}), ...(event.endedBy ? { endedBy: event.endedBy } : {}) } });
       if (replyToMessageId) this.obligationCache.markDirty();
       return;
     }