agent-relay-runner 0.127.4 → 0.127.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.127.4",
+  "version": "0.127.6",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.4",
-    "agent-relay-sdk": "0.2.119",
+    "agent-relay-sdk": "0.2.121",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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.127.4",
+  "version": "0.127.6",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
+import type { AgentProfile, InteractivePrompt, 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";
@@ -48,12 +48,15 @@ export interface ProviderSessionEvent {
   body: string;
   origin?: "chat" | "terminal" | "provider";
   turnId?: string;
+  occurredAt?: number;
   /** 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;
+  /** Whether this response may clear a direct user obligation; Codex keeps this false. */
+  replyToUserObligation?: boolean;
   label?: string;
   status?: "running" | "completed" | "failed";
   streaming?: boolean;
@@ -63,6 +66,66 @@ export interface ProviderSessionEvent {
   stepId?: string;
 }
 
+export type ProviderSessionEventBatch = ProviderSessionEvent[];
+
+export interface ProviderSessionTurnInput {
+  transcriptPath: string;
+  lastAssistantMessage?: unknown;
+  promptId?: string;
+  isPreFlush?: boolean;
+  toolName?: string;
+  toolInput?: unknown;
+}
+
+export interface ProviderSessionTurnContext {
+  turnId?: string;
+  turnStartedAt?: number;
+  chatCaptureMode: ProviderConfig["chatCaptureMode"];
+  reasoningCapture?: boolean;
+  settlePollIntervalMs: number;
+  settlePollTimeoutMs: number;
+  flushSessionEvents(timeoutMs: number): Promise<boolean>;
+  pendingSessionEventCount(): number;
+  log(message: string): void;
+  debug(message: string): void;
+}
+
+export interface ProviderSessionTurnResult {
+  reasoningSettled?: boolean;
+}
+
+export interface ProviderUserPromptInput {
+  prompt: string;
+  transcriptPath?: string;
+  promptId?: string;
+}
+
+export interface ProviderPermissionResolvedPrompt {
+  provider: "claude";
+  kind: "questions" | "plan" | "command" | "tool";
+  title: string;
+  body: string;
+  promptBody?: string;
+  toolName: string;
+  hookEventName: string;
+  approvalId: string;
+  decision: ProviderPermissionDecisionInput["decision"];
+  decisionLabel: string;
+  occurredAt: number;
+  resolvedAt: number;
+  decisionReason: ProviderPermissionDecisionReason;
+  questions?: unknown[];
+  answers?: Record<string, string>;
+}
+
+export interface ProviderPermissionPromptHandler {
+  source: string;
+  resolvedLabel: string;
+  buildView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt;
+  buildHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown>;
+  buildResolvedPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt;
+}
+
 export interface ProviderConfig {
   command: string;
   defaultArgs: string[];
@@ -146,13 +209,22 @@ export interface ProviderPermissionDecisionInput {
   approvalId: string;
   decision: ProviderPermissionDecision;
   reason?: string;
+  decisionReason?: ProviderPermissionDecisionReason;
   // For "answer" decisions (Claude AskUserQuestion): maps each question's text
   // to the chosen option label(s). Multi-select labels are comma-joined.
   answers?: Record<string, string>;
 }
 
+export interface ProviderPermissionDecisionReason {
+  kind: "timeout" | "dismissed" | "answered";
+  message?: string;
+}
+
 export interface ProviderAdapter {
   provider: string;
+  statusSourceId?: string;
+  stopObligationPath?: string;
+  permissionPromptHandler?: ProviderPermissionPromptHandler;
   spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
   compact?(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown> | void>;
@@ -187,6 +259,12 @@ export interface ProviderAdapter {
   probePaneBusy?(process: ManagedProcess): Promise<boolean>;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
   respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
+  captureSessionTurn?(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void>;
+  handleUserPrompt?(input: ProviderUserPromptInput, ctx: ProviderSessionTurnContext): Promise<void>;
+  drainSessionTrace?(ctx: ProviderSessionTurnContext): Promise<void>;
+  settleSessionTraceForToolUse?(transcriptPath: string, toolName: string | undefined, toolInput: unknown, ctx: ProviderSessionTurnContext): Promise<{ settled: boolean; jsonl?: string }>;
+  stopSessionTrace?(): void;
+  publishPassiveTelemetry?(): Promise<void>;
   // `options.readyTimeoutMs` lets the runner widen the provider-ready wait for the
   // first (cold-start) delivery vs. a fast re-attempt after a ready signal (#329).
   deliverInitialPrompt?(process: ManagedProcess, prompt: string, options?: { readyTimeoutMs?: number }): Promise<void>;
@@ -199,10 +277,10 @@ export interface ProviderAdapter {
   seedsInitialPromptAtLaunch?: boolean;
   deliver(process: ManagedProcess, messages: Message[]): Promise<void>;
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
-  // Subscribe to session-mirror events from providers that emit them directly
-  // (Codex app-server item events). Claude mirrors via hooks/transcript instead,
-  // so it leaves this unimplemented.
+  // Subscribe to session-mirror events from providers. Batch callbacks preserve
+  // shared idempotency for multiple trace steps discovered in one provider poll.
   onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
+  onSessionEvents?(cb: (events: ProviderSessionEventBatch) => void): void;
   // §4.1 of the Runner↔provider contract (#725 / #746): fold the runner-tracked raw
   // transport/timeline/token/work-kind signals into ONE normalized LivenessSignal the
   // server reads instead of six raw `meta` fields. Each adapter owns what counts as

package/src/adapters/claude-permission.ts

@@ -0,0 +1,191 @@
+import type { InteractivePrompt } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
+import type { ProviderPermissionDecisionInput, ProviderPermissionPromptHandler, ProviderPermissionResolvedPrompt } from "../adapter";
+
+function decisionReasonMessage(decision: ProviderPermissionDecisionInput, fallback: string): string {
+  return decision.reason || decision.decisionReason?.message || fallback;
+}
+
+export const claudePermissionPromptHandler: ProviderPermissionPromptHandler = {
+  source: "claude",
+  resolvedLabel: "Claude approval resolved",
+  buildView: claudePermissionApprovalView,
+  buildHookResponse: claudePermissionHookResponse,
+  buildResolvedPrompt: claudeResolvedPermissionPrompt,
+};
+
+function claudePermissionApprovalView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  if (toolName === "AskUserQuestion" && Array.isArray(toolInput.questions) && toolInput.questions.length) {
+    const count = toolInput.questions.length;
+    return {
+      id,
+      kind: "questions",
+      title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
+      body: "",
+      questions: toolInput.questions as InteractivePrompt["questions"],
+      choices: [],
+      reasoningSettled,
+    };
+  }
+  if (toolName === "ExitPlanMode") {
+    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
+      ? toolInput.plan
+      : JSON.stringify(toolInput);
+    return {
+      id,
+      kind: "plan",
+      title: "Claude is ready to code",
+      body: plan,
+      choices: [
+        { id: "approve", label: "Approve plan" },
+        { id: "deny", label: "Keep planning" },
+      ],
+      reasoningSettled,
+    };
+  }
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const description = typeof toolInput.description === "string" ? toolInput.description : "";
+  const bodyText = [
+    command || description || JSON.stringify(toolInput),
+    typeof body.cwd === "string" ? `CWD: ${body.cwd}` : "",
+    typeof body.permission_mode === "string" ? `Mode: ${body.permission_mode}` : "",
+  ].filter(Boolean).join("\n");
+  return {
+    id,
+    kind: toolName.toLowerCase() === "bash" ? "command" : "tool",
+    title: `Approve ${toolName}`,
+    body: bodyText,
+    choices: [
+      { id: "approve", label: "Approve" },
+      { id: "approve-session", label: "Approve session" },
+      { id: "deny", label: "Deny" },
+      { id: "abort", label: "Abort" },
+    ],
+    reasoningSettled,
+  };
+}
+
+function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
+  if (body.hook_event_name === "PreToolUse") {
+    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+    if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+          updatedInput: { ...toolInput, answers: decision.answers },
+        },
+      };
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: decisionReasonMessage(decision, "Dismissed from Agent Relay dashboard"),
+      },
+    };
+  }
+  const hookEventName = "PermissionRequest";
+  if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
+    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+    return {
+      hookSpecificOutput: {
+        hookEventName,
+        decision: {
+          behavior: "allow",
+          updatedInput: { ...toolInput, answers: decision.answers },
+        },
+      },
+    };
+  }
+  if (decision.decision === "approve" || decision.decision === "approve-session") {
+    const suggestions = Array.isArray(body.permission_suggestions) ? body.permission_suggestions : [];
+    return {
+      hookSpecificOutput: {
+        hookEventName,
+        decision: {
+          behavior: "allow",
+          ...(decision.decision === "approve-session" && suggestions.length ? { updatedPermissions: suggestions } : {}),
+        },
+      },
+    };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName,
+      decision: {
+        behavior: "deny",
+        message: decisionReasonMessage(decision, "Denied from Agent Relay dashboard"),
+        interrupt: decision.decision === "abort",
+      },
+    },
+  };
+}
+
+function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const kind: ProviderPermissionResolvedPrompt["kind"] = view.kind === "questions" || view.kind === "plan" || view.kind === "command" || view.kind === "tool"
+    ? view.kind
+    : toolName.toLowerCase() === "bash" ? "command" : "tool";
+  const questions = Array.isArray(view.questions)
+    ? view.questions
+    : Array.isArray(toolInput.questions) ? toolInput.questions : undefined;
+  const promptBody = typeof view.body === "string" ? view.body : "";
+  const title = typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`;
+  const decisionLabel = claudePermissionDecisionLabel(kind, decision.decision);
+  return {
+    provider: "claude",
+    kind,
+    title,
+    body: claudeResolvedPermissionBody({ kind, title, toolName, promptBody, decisionLabel, questions, answers: decision.answers }),
+    ...(promptBody ? { promptBody } : {}),
+    toolName,
+    hookEventName: typeof body.hook_event_name === "string" ? body.hook_event_name : "PermissionRequest",
+    approvalId: decision.approvalId,
+    decision: decision.decision,
+    decisionLabel,
+    decisionReason: decision.decisionReason ?? { kind: decision.decision === "deny" || decision.decision === "abort" ? "dismissed" : "answered", ...(decision.reason ? { message: decision.reason } : {}) },
+    occurredAt,
+    resolvedAt: Date.now(),
+    ...(questions ? { questions } : {}),
+    ...(decision.answers ? { answers: decision.answers } : {}),
+  };
+}
+
+function claudeResolvedPermissionBody(input: { kind: string; title: string; toolName: string; promptBody: string; decisionLabel: string; questions?: unknown[]; answers?: Record<string, string> }): string {
+  if (input.kind === "questions") {
+    return [
+      input.title,
+      input.decisionLabel,
+      ...resolvedQuestionRows(input.questions, input.answers, input.decisionLabel).map((row) => `Q: ${row.question}\nA: ${row.answer}`),
+    ].filter(Boolean).join("\n\n");
+  }
+  const subject = input.kind === "plan" ? "Plan prompt resolved" : `${input.toolName} permission resolved`;
+  return [subject, `Decision: ${input.decisionLabel}`, input.promptBody.trim()].filter(Boolean).join("\n\n");
+}
+
+function resolvedQuestionRows(questions: unknown[] | undefined, answers: Record<string, string> | undefined, fallback: string): Array<{ question: string; answer: string }> {
+  const answerMap = answers ?? {};
+  const rows = (questions ?? []).map((question, index) => {
+    const record = question && typeof question === "object" && !Array.isArray(question) ? question as Record<string, unknown> : {};
+    const label = typeof record.question === "string" && record.question.trim()
+      ? record.question.trim()
+      : typeof record.header === "string" && record.header.trim() ? record.header.trim() : `Question ${index + 1}`;
+    const rawAnswer = answerMap[label] ?? answerMap[String(record.question ?? "")] ?? answerMap[String(record.header ?? "")];
+    return { question: label, answer: typeof rawAnswer === "string" && rawAnswer.trim() ? rawAnswer.trim() : fallback };
+  });
+  return rows.length ? rows : Object.entries(answerMap).map(([question, answer]) => ({ question, answer }));
+}
+
+function claudePermissionDecisionLabel(kind: string, decision: ProviderPermissionDecisionInput["decision"]): string {
+  if (kind === "questions") return decision === "answer" ? "Answered" : "Dismissed";
+  if (kind === "plan") return decision === "approve" || decision === "approve-session" ? "Approved plan" : "Kept planning";
+  if (decision === "approve-session") return "Approved for session";
+  if (decision === "approve") return "Approved";
+  if (decision === "abort") return "Aborted";
+  if (decision === "answer") return "Answered";
+  return "Denied";
+}

package/src/{claude-prompt-gates.ts → adapters/claude-prompt-gates.ts}

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { isRecord, type ProviderState } from "agent-relay-sdk";
-import type { ProviderStatusUpdate, RunnerSpawnConfig } from "./adapter";
-import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "./rate-limit";
+import type { ProviderStatusUpdate, RunnerSpawnConfig } from "../adapter";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 
 export interface ClaudeConfigPromptGatePrevention {
   id: string;
@@ -37,6 +37,7 @@ export interface ClaudePromptGatePaneContext {
   sessionName?: string;
   busy?: boolean;
   nowMs?: number;
+  sourceId?: string;
 }
 
 export interface ClaudePromptGateAction {
@@ -44,7 +45,7 @@ export interface ClaudePromptGateAction {
   label: string;
   policy: string;
   keystroke: string;
-  source: "claude-pane";
+  source: string;
 }
 
 export interface ClaudePromptGatePaneResult {
@@ -113,7 +114,7 @@ const panePromptGates: ClaudePanePromptGate[] = [
         kind: match.kind ?? "usage_limit",
         ...(match.resetAt ? { resetAt: match.resetAt } : {}),
         message: match.message,
-        source: context.sessionName ? `claude-pane:${context.sessionName}` : "claude-pane",
+        source: paneSource(context),
       });
     },
   },
@@ -217,7 +218,7 @@ export function evaluateClaudePromptGatePane(
     label: detected.entry.label,
     policy: detected.entry.policy,
     keystroke: detected.entry.keystroke,
-    source: "claude-pane",
+    source: paneSource(context),
   };
   return {
     action,
@@ -226,6 +227,11 @@ export function evaluateClaudePromptGatePane(
   };
 }
 
+function paneSource(context: ClaudePromptGatePaneContext): string {
+  const source = context.sourceId ?? "claude-pane";
+  return context.sessionName ? `${source}:${context.sessionName}` : source;
+}
+
 function firstDetectedPaneGate(text: string, nowMs?: number): { entry: ClaudePanePromptGate; match: PaneGateMatch } | null {
   for (const entry of panePromptGates) {
     const match = entry.match(text, nowMs);

package/src/adapters/claude-session-capture.ts

@@ -0,0 +1,235 @@
+import { readFile } from "node:fs/promises";
+import { errMessage, type MessageSessionMeta } from "agent-relay-sdk";
+import type { ManagedProcess, ProviderSessionEvent, ProviderSessionEventBatch, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderSessionTurnResult, ProviderUserPromptInput } from "../adapter";
+import type { SessionEvent } from "../session-insights";
+import {
+  collectClaudeSessionEvents,
+  countTranscriptEntries,
+  extractAssistantTurnForPrompt,
+  extractHookAssistantMessage,
+  extractLastAssistantTurn,
+  extractLastAssistantTurnAfterEntry,
+  extractLatestTurnSteps,
+  stepDedupKeys,
+  transcriptHasToolUseAnchor,
+  transcriptLooksComplete,
+} from "./claude-transcript";
+import { IncrementalClaudeTranscriptTail } from "./claude-transcript-tail";
+
+interface ReasoningTailState {
+  timer: ReturnType<typeof setInterval>;
+  emittedNarrationKeys: Set<string>;
+  poll(): Promise<void>;
+}
+
+const REASONING_POLL_MS = 1_200;
+
+export class ClaudeSessionCapture {
+  private narrativeFlushEntryCount = 0;
+  private reasoningTail?: ReasoningTailState;
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
+  private sessionEventsCb: (events: ProviderSessionEventBatch) => void = (events) => { for (const event of events) this.sessionEventCb(event); };
+
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  onSessionEvents(cb: (events: ProviderSessionEventBatch) => void): void {
+    this.sessionEventsCb = cb;
+  }
+
+  async captureSessionTurn(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void> {
+    if (input.isPreFlush) {
+      if (!input.transcriptPath) return { reasoningSettled: true };
+      const settled = await this.settlePollForToolUse(input.transcriptPath, input.toolName, input.toolInput, ctx);
+      const jsonl = settled.jsonl;
+      if (jsonl === undefined) return { reasoningSettled: false };
+      const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
+      await this.drainReasoningTail(ctx);
+      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
+      if (body && !this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, body)) {
+        ctx.log(`pre-flush narrative for turn ${ctx.turnId ?? "?"} (${body.length} chars)`);
+        this.emit({ type: "response", origin: "provider", body, final: false, ...(ctx.turnId ? { turnId: ctx.turnId } : {}) });
+      }
+      await ctx.flushSessionEvents(2_000).then(
+        (ok) => { if (!ok) ctx.log(`pre-flush session outbox incomplete before blocking control (${ctx.pendingSessionEventCount()} pending)`); },
+        (error) => ctx.log(`pre-flush session outbox failed before blocking control: ${errMessage(error)}`),
+      );
+      return { reasoningSettled: settled.settled };
+    }
+
+    const turnId = input.promptId ?? ctx.turnId;
+    await this.drainReasoningTail(ctx);
+    this.stopSessionTrace();
+    const flushCount = this.narrativeFlushEntryCount;
+    this.narrativeFlushEntryCount = 0;
+
+    let body = extractHookAssistantMessage(input.lastAssistantMessage);
+    if (ctx.chatCaptureMode === "full" && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined && transcriptLooksComplete(jsonl)) {
+        let full = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        if (!full) full = flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl);
+        if (full) body = full;
+      }
+    }
+    if (!body && ctx.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));
+      }
+    }
+    if (!body) {
+      ctx.log(`response capture: no closing text for turn ${turnId ?? "?"} (skipped)`);
+      return;
+    }
+
+    ctx.log(`response captured for turn ${turnId ?? "?"} (${body.length} chars)`);
+    this.emit({
+      type: "response",
+      origin: "provider",
+      body,
+      final: true,
+      confidence: "definitive",
+      endedBy: "completed",
+      replyToUserObligation: true,
+      ...(turnId ? { turnId } : {}),
+    });
+  }
+
+  async handleUserPrompt(input: ProviderUserPromptInput, ctx: ProviderSessionTurnContext): Promise<void> {
+    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath, ctx);
+  }
+
+  async drainReasoningTail(ctx: ProviderSessionTurnContext): Promise<void> {
+    if (ctx.reasoningCapture === false) return;
+    await this.reasoningTail?.poll();
+  }
+
+  stopSessionTrace(): void {
+    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
+    this.reasoningTail = undefined;
+  }
+
+  async settlePollForToolUse(transcriptPath: string, toolName: string | undefined, toolInput: unknown, ctx: ProviderSessionTurnContext): Promise<{ settled: boolean; jsonl?: string }> {
+    const deadline = Date.now() + ctx.settlePollTimeoutMs;
+    for (;;) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (!toolName) return { settled: Boolean(jsonl), jsonl };
+      if (jsonl !== undefined && transcriptHasToolUseAnchor(jsonl, toolName, toolInput)) return { settled: true, jsonl };
+      if (Date.now() >= deadline) return { settled: false, jsonl };
+      await Bun.sleep(ctx.settlePollIntervalMs);
+    }
+  }
+
+  private startReasoningTail(transcriptPath: string, ctx: ProviderSessionTurnContext): void {
+    if (ctx.reasoningCapture === false) return;
+    this.stopSessionTrace();
+    const seen = new Set<string>();
+    const emittedNarrationKeys = new Set<string>();
+    const transcriptTail = new IncrementalClaudeTranscriptTail();
+    const turnIdAtStart = ctx.turnId;
+    let seeded = false;
+    let pendingPoll = Promise.resolve();
+    const pollBody = async (): Promise<void> => {
+      const result = await transcriptTail.poll(transcriptPath);
+      if (!result.available) return;
+      if (result.reset) { seen.clear(); emittedNarrationKeys.clear(); seeded = false; }
+      if (!result.changed && (seeded || (!result.steps.length && !result.transcriptLooksComplete))) return;
+      const keyed = stepDedupKeys(result.steps).map((sig, i) => ({ sig, step: result.steps[i]! }));
+      if (!seeded) {
+        seeded = true;
+        if (result.transcriptLooksComplete) {
+          for (const { sig } of keyed) seen.add(sig);
+        }
+      }
+      const turnId = ctx.turnId ?? turnIdAtStart;
+      let emitted = 0;
+      const events: ProviderSessionEvent[] = [];
+      for (const { sig, step } of keyed) {
+        if (seen.has(sig)) continue;
+        seen.add(sig);
+        emitted += 1;
+        events.push({
+          type: step.type,
+          origin: "provider",
+          body: step.text,
+          ...(step.occurredAt ? { occurredAt: step.occurredAt } : {}),
+          ...(turnId ? { turnId } : {}),
+          ...(step.label ? { label: step.label } : {}),
+        });
+        if (step.type === "narration") emittedNarrationKeys.add(sig);
+      }
+      if (events.length) this.emitBatch(events);
+      if (emitted) ctx.debug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
+    };
+    const poll = (): Promise<void> => {
+      const next = pendingPoll.then(pollBody, pollBody);
+      pendingPoll = next.catch(() => {});
+      return next;
+    };
+    this.reasoningTail = { emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
+    ctx.log(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
+    void poll();
+  }
+
+  private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
+    const tail = this.reasoningTail;
+    if (!tail || !tail.emittedNarrationKeys.size) return false;
+    const steps = extractLatestTurnSteps(jsonl);
+    const keys = stepDedupKeys(steps);
+    const mirrored = steps
+      .map((step, index) => ({ step, key: keys[index]! }))
+      .filter(({ step, key }) => step.type === "narration" && tail.emittedNarrationKeys.has(key))
+      .map(({ step }) => step.text)
+      .join("\n\n")
+      .trim();
+    const trimmed = body.trim();
+    return mirrored === trimmed || mirrored.endsWith(`\n\n${trimmed}`);
+  }
+
+  private emit(event: ProviderSessionEvent): void {
+    this.sessionEventCb(event);
+  }
+
+  private emitBatch(events: ProviderSessionEventBatch): void {
+    this.sessionEventsCb(events);
+  }
+}
+
+export function providerSessionEventToMessageSession(event: ProviderSessionEvent): MessageSessionMeta {
+  return {
+    type: event.type,
+    origin: event.origin ?? "provider",
+    ...(event.turnId ? { turnId: event.turnId } : {}),
+    ...(event.label ? { label: event.label } : {}),
+    ...(event.status ? { status: event.status } : {}),
+    ...(event.streaming !== undefined ? { streaming: event.streaming } : {}),
+    ...(event.stepId ? { stepId: event.stepId } : {}),
+    ...(event.final ? { final: true } : {}),
+  };
+}
+
+export async function collectClaudeTranscriptSessionEvents(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null> {
+  if (!ctx.transcriptPath) return null;
+  let jsonl: string;
+  try {
+    jsonl = await readFile(ctx.transcriptPath, "utf8");
+  } catch {
+    return null;
+  }
+  return collectClaudeSessionEvents(jsonl);
+}
+
+export async function collectClaudeTranscriptArchiveSegment(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null> {
+  if (!ctx.transcriptPath) return null;
+  try {
+    return await readFile(ctx.transcriptPath, "utf8");
+  } catch {
+    return null;
+  }
+}