agent-relay-runner 0.11.9 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.11.9",
+  "version": "0.12.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.5"
+    "agent-relay-sdk": "0.2.6"
   },
   "devDependencies": {
     "@types/bun": "latest",

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

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

@@ -53,6 +53,25 @@ relay_post_session_turn() {
     -d "$body" >/dev/null 2>&1 || true
 }
 
+relay_post_user_prompt() {
+  # Mirror a prompt the human typed directly into this Claude session (web
+  # terminal / TUI) into the dashboard chat, and hand over the transcript path so
+  # the runner can tail reasoning/tool steps for the turn. The runner dedups
+  # prompts it injected itself. Fire-and-forget; never blocks or fails the turn.
+  local payload="${1:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  [ -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)"
+  [ -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" \
+    -H 'Content-Type: application/json' \
+    -d "$body" >/dev/null 2>&1 || true
+}
+
 relay_pending_reply_stop_decision() {
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0

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

@@ -1,7 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+payload="$(cat || true)"
 relay_post_status busy
+# 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"
 # Re-surface the request-review reminder each turn while there is unmerged
 # committed work — so a long session can't "forget" to land it. Silent otherwise.
 relay_emit_additional_context UserPromptSubmit "$(relay_review_reminder_text || true)"

package/src/adapter.ts

@@ -27,6 +27,20 @@ export interface ProviderStatusEvent {
 
 export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
 
+/**
+ * A session-mirror event surfaced by an adapter that learns about session
+ * activity through provider events rather than hooks/transcripts (e.g. the Codex
+ * app-server). The runner turns these into `kind: "session"` chat messages, the
+ * same lane Claude's transcript capture uses. Provider-independent boundary.
+ */
+export interface ProviderSessionEvent {
+  type: "prompt" | "response" | "reasoning" | "tool";
+  body: string;
+  origin?: "chat" | "terminal" | "provider";
+  turnId?: string;
+  label?: string;
+}
+
 export interface ProviderConfig {
   command: string;
   defaultArgs: string[];
@@ -36,6 +50,9 @@ export interface ProviderConfig {
   defaultApprovalMode: string;
   defaultTags: string[];
   chatCaptureMode: "final" | "full";
+  // When false, the runner does not stream reasoning/tool steps into chat. Defaults
+  // to enabled (steps render discreetly, never as chat bubbles).
+  reasoningCapture?: boolean;
   headless: {
     tmuxPrefix: string;
     shutdownTimeoutMs: number;
@@ -110,11 +127,24 @@ export interface ProviderAdapter {
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
   compact?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Interrupt the in-flight turn without ending the session (ESC for Claude's
+  // tmux pane, turn/interrupt for the Codex app-server). Provider-independent at
+  // the runner boundary; each adapter does what its provider actually supports.
+  interrupt?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Out-of-band activity probe for the busy-state reconciler: returns the real
+  // provider activity when the runner's claim state may have gone stale (e.g. the
+  // turn was interrupted from the web terminal so no Stop hook fired). "unknown"
+  // means the provider can't be cheaply probed and the reconciler should defer.
+  probeActivity?(process: ManagedProcess): Promise<"busy" | "idle" | "unknown">;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
   respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
   deliverInitialPrompt?(process: ManagedProcess, prompt: string): Promise<void>;
   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.
+  onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
   // Headless providers with no tmux session (e.g. the Codex app-server) still
   // warrant an automatic restart on unexpected exit. Returning true opts the
   // provider into the runner's restart-with-backoff path.

package/src/adapters/claude-transcript.ts

@@ -13,6 +13,15 @@
 interface TranscriptBlock {
   type?: string;
   text?: string;
+  thinking?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+export interface TurnStep {
+  type: "reasoning" | "tool";
+  text: string;
+  label?: string;
 }
 
 interface TranscriptMessage {
@@ -134,6 +143,49 @@ export function extractFinalAssistantMessage(jsonl: string): string {
  * string or an array of content blocks (same shape as transcript entries).
  * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
  */
+/**
+ * Extract the ordered reasoning and tool steps for the most recent turn (since
+ * the last real user prompt). Used by the reasoning tailer to stream discreet
+ * progress into chat while a turn is in flight. Returns steps in transcript order
+ * so the tailer can emit only the ones it hasn't seen yet by index.
+ */
+export function extractLatestTurnSteps(jsonl: string): TurnStep[] {
+  const lines = jsonl.split("\n");
+  let steps: TurnStep[] = [];
+  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 (isRealUserPrompt(entry)) {
+      steps = [];
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    for (const b of blocks(entry.message)) {
+      if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
+        steps.push({ type: "reasoning", text: b.thinking.trim() });
+      } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
+        steps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
+      }
+    }
+  }
+  return steps;
+}
+
+/** Compact one-line summary of a tool invocation for the discreet activity row. */
+export function summarizeToolUse(name: string, input: Record<string, unknown> | undefined): string {
+  const str = (key: string): string | undefined => (input && typeof input[key] === "string" ? (input[key] as string) : undefined);
+  const candidate = str("command") ?? str("file_path") ?? str("path") ?? str("pattern") ?? str("query") ?? str("url") ?? str("description") ?? str("prompt");
+  const summary = candidate ? candidate.replace(/\s+/g, " ").trim() : "";
+  if (!summary) return name;
+  return summary.length > 200 ? `${summary.slice(0, 197)}…` : summary;
+}
+
 export function extractHookAssistantMessage(content: unknown): string {
   if (typeof content === "string") return content.trim();
   if (!Array.isArray(content)) return "";

package/src/adapters/claude.ts

@@ -60,6 +60,33 @@ export class ClaudeAdapter implements ProviderAdapter {
     return { method: "tmux-inject", command: "/clear" };
   }
 
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session to interrupt");
+    // The same ESC the web terminal's aux key sends: cancels the in-flight turn
+    // and drops Claude back to its input box without ending the session.
+    const result = Bun.spawnSync(tmuxCommand(socket, "send-keys", "-t", session, "Escape"), {
+      stdin: "ignore", stdout: "ignore", stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(`tmux interrupt failed: ${stderr || `exit code ${result.exitCode}`}`);
+    }
+    return { method: "tmux-escape" };
+  }
+
+  async probeActivity(process: ManagedProcess): Promise<"busy" | "idle" | "unknown"> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) return "unknown";
+    let pane: string;
+    try { pane = captureTmuxPane(session, socket); } catch { return "unknown"; }
+    if (claudePaneIsBusy(pane)) return "busy";
+    if (claudePaneLooksReady(pane)) return "idle";
+    return "unknown";
+  }
+
   async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
     const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
     // A monitor object always exists for headless claude (it proxies to the runner

package/src/adapters/codex.ts

@@ -2,7 +2,7 @@ import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirS
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
-import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 
 /** Relay context prepended to a Codex agent's first turn: the standard relay
@@ -24,13 +24,42 @@ type PendingCodexApproval = {
 export class CodexAdapter implements ProviderAdapter {
   readonly provider = "codex";
   private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
   private readonly subagentThreads = new Map<string, { label?: string; role?: string; parentId?: string }>();
   private readonly pendingApprovals = new Map<string, PendingCodexApproval>();
+  // Active turn id for the main thread, captured from turn/started so an interrupt
+  // can target the in-flight turn. Cleared on turn/completed.
+  private activeTurnId?: string;
+  // Assistant message text accumulated across the current turn's agentMessage items,
+  // flushed as one session response on turn/completed (mirrors Claude's chatCaptureMode).
+  private turnMessages: string[] = [];
+  private captureMode: "final" | "full" = "final";
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
   }
 
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    if (!this.activeTurnId) throw new Error("no active Codex turn to interrupt");
+    await client.turnInterrupt(threadId, this.activeTurnId);
+    return { method: "turn-interrupt", turnId: this.activeTurnId };
+  }
+
+  // Codex streams thread/status continuously, so the runner's claim state never
+  // goes stale the way Claude's can after an out-of-band interrupt. No cheap probe
+  // is needed — defer to the live status stream.
+  async probeActivity(): Promise<"busy" | "idle" | "unknown"> {
+    return "unknown";
+  }
+
   // The Codex app-server is headless and has no tmux session, but an unexpected
   // exit should still be restarted with backoff rather than resolved as a final exit.
   supportsUnexpectedExitRestart(): boolean {
@@ -38,6 +67,7 @@ export class CodexAdapter implements ProviderAdapter {
   }
 
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    this.captureMode = (config.providerConfig as ProviderConfig).chatCaptureMode ?? "final";
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
     const appServer = Bun.spawn([args.command, ...args.args], {
       cwd: args.cwd,
@@ -295,16 +325,25 @@ export class CodexAdapter implements ProviderAdapter {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.statusCb({ status: "busy", reason: "provider-turn" });
+        const turn = isRecord(params?.turn) ? params.turn : undefined;
+        this.activeTurnId = stringValue(turn?.id);
+        this.turnMessages = [];
+        this.statusCb({ status: "busy", reason: "provider-turn", id: this.activeTurnId });
       }
     }
     if (method.includes("turn/completed") || method.includes("turn.completed")) {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.statusCb({ status: "idle", reason: "provider-turn" });
+        this.flushTurnResponse();
+        const completedTurnId = this.activeTurnId;
+        this.activeTurnId = undefined;
+        this.statusCb({ status: "idle", reason: "provider-turn", id: completedTurnId });
       }
     }
+    if ((method.includes("item/completed") || method.includes("item.completed")) && !isSubagent) {
+      this.handleCodexItem(isRecord(params?.item) ? params.item : undefined);
+    }
     if (method.includes("thread/status")) {
       const status = statusType(params?.status);
       if (threadId && this.subagentThreads.has(threadId)) {
@@ -317,6 +356,40 @@ export class CodexAdapter implements ProviderAdapter {
     }
   }
 
+  // Turn one completed Codex thread item into a session-mirror event. agentMessage
+  // text is accumulated and flushed as a single response on turn/completed; 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);
+    const turnId = this.activeTurnId;
+    if (type === "agentMessage") {
+      const text = stringValue(item.text)?.trim();
+      if (text) this.turnMessages.push(text);
+      return;
+    }
+    if (type === "userMessage") {
+      const text = codexUserMessageText(item.content);
+      if (text) this.sessionEventCb({ type: "prompt", origin: "terminal", body: text, ...(turnId ? { turnId } : {}) });
+      return;
+    }
+    if (type === "reasoning") {
+      const text = codexReasoningText(item);
+      if (text) this.sessionEventCb({ type: "reasoning", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
+      return;
+    }
+    const tool = codexToolSummary(type, item);
+    if (tool) this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, ...(turnId ? { turnId } : {}) });
+  }
+
+  private flushTurnResponse(): void {
+    if (!this.turnMessages.length) return;
+    const joined = this.captureMode === "full" ? this.turnMessages.join("\n\n") : this.turnMessages[this.turnMessages.length - 1]!;
+    this.turnMessages = [];
+    const text = joined.trim();
+    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
   private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): Record<string, unknown> | undefined {
     const state = codexProviderStateFromThreadStatus(status, params);
     if (state?.state !== "blocked" || state.reason !== "waitingOnApproval" || state.pendingApproval) return state;
@@ -337,6 +410,52 @@ function codexApprovalFromServerRequest(message: { id: string | number; method:
   };
 }
 
+/** Extract the human text from a Codex userMessage item's content (UserInput[]). */
+export function codexUserMessageText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(isRecord)
+    .filter((part) => part.type === "text" || part.type === "input_text" || part.type === "output_text")
+    .map((part) => (typeof part.text === "string" ? part.text : ""))
+    .filter(Boolean)
+    .join("")
+    .trim();
+}
+
+/** Extract reasoning text from a Codex reasoning item (content[] preferred, summary[] fallback). */
+export function codexReasoningText(item: Record<string, unknown>): string {
+  const stringsOf = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((v): v is string => typeof v === "string" && v.trim().length > 0) : [];
+  const content = stringsOf(item.content);
+  const text = (content.length ? content : stringsOf(item.summary)).join("\n\n").trim();
+  return text;
+}
+
+/** Build a compact { label, body } activity summary for a Codex tool item. */
+export function codexToolSummary(type: string | undefined, item: Record<string, unknown>): { label: string; body: string } | null {
+  const oneLine = (value: unknown): string => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+  const clip = (text: string): string => (text.length > 200 ? `${text.slice(0, 197)}…` : text);
+  if (type === "commandExecution") {
+    const command = oneLine(item.command);
+    return { label: "Shell", body: clip(command || "command") };
+  }
+  if (type === "fileChange") {
+    const changes = Array.isArray(item.changes) ? item.changes.filter(isRecord) : [];
+    const files = changes.map((c) => stringValue(c.path) ?? stringValue(c.file) ?? "").filter(Boolean);
+    return { label: "Edit", body: clip(files.length ? files.join(", ") : "file changes") };
+  }
+  if (type === "mcpToolCall" || type === "dynamicToolCall") {
+    const tool = stringValue(item.tool) ?? "tool";
+    const server = stringValue(item.server) ?? stringValue(item.namespace);
+    return { label: server ? `${server}/${tool}` : tool, body: clip(oneLine(JSON.stringify(item.arguments ?? {})) || tool) };
+  }
+  if (type === "webSearch") {
+    return { label: "Search", body: clip(oneLine(item.query) || "web search") };
+  }
+  return null;
+}
+
 function codexApprovalMethod(method: string): boolean {
   return method === "execCommandApproval" ||
     method === "applyPatchApproval" ||

package/src/control-server.ts

@@ -24,6 +24,10 @@ interface ControlServerOptions {
   // path so the runner can capture the assistant turn and surface it in the
   // dashboard chat without the agent re-emitting it via /reply.
   onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown }): Promise<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>;
 }
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
@@ -66,6 +70,9 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/session-turn" && req.method === "POST") {
         return handleSessionTurn(req, options);
       }
+      if (url.pathname === "/user-prompt" && req.method === "POST") {
+        return handleUserPrompt(req, options);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -216,6 +223,27 @@ export function claudePermissionApprovalView(id: string, body: Record<string, un
       choices: [],
     };
   }
+  // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
+  // match the AskUserQuestion matcher), which used to render the raw tool_input
+  // JSON with generic Approve/Deny buttons. Surface the plan as markdown with the
+  // real plan-mode choices instead. approve → allow (exit plan mode and proceed);
+  // deny → keep planning.
+  if (toolName === "ExitPlanMode") {
+    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
+      ? toolInput.plan
+      : JSON.stringify(toolInput);
+    return {
+      id,
+      provider: "claude",
+      kind: "plan",
+      title: "Claude is ready to code",
+      body: plan,
+      choices: [
+        { id: "approve", label: "Approve plan" },
+        { id: "deny", label: "Keep planning" },
+      ],
+    };
+  }
   const command = typeof toolInput.command === "string" ? toolInput.command : "";
   const description = typeof toolInput.description === "string" ? toolInput.description : "";
   const bodyText = [
@@ -304,6 +332,17 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   }
 }
 
+async function handleUserPrompt(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onUserPrompt) return Response.json({ ok: false, reason: "prompt echo unavailable" });
+  const body = await req.json().catch(() => null);
+  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;
+  // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  return Response.json({ ok: true });
+}
+
 async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
   const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
   const status = body?.status;

package/src/runner.ts

@@ -2,14 +2,14 @@ import { hostname } from "node:os";
 import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import type { AgentProfile, ContextState, Message, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
+import type { AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
-import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
-import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
 import { runtimeMetadata } from "./version";
@@ -68,6 +68,20 @@ const RAPID_EXIT_MS = 30 * 1000;
 const MAX_RAPID_UNEXPECTED_EXITS = 3;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const LOG_TAIL_BYTES = 128 * 1024;
+// A UserPromptSubmit echo matching a runner-injected prompt within this window is
+// the same prompt arriving back from the provider — drop it to avoid a duplicate.
+const PROMPT_ECHO_DEDUP_MS = 30_000;
+// Busy reconciler: how often to probe real provider activity, and how many
+// consecutive idle probes confirm a stuck-busy state should be cleared.
+const BUSY_RECONCILE_POLL_MS = 4_000;
+const BUSY_RECONCILE_IDLE_CONFIRM = 3;
+// Relay-injected content (delivered messages, memory context) is wrapped with
+// these markers; a UserPromptSubmit echo starting with one is a runner injection,
+// not a human typing into the terminal, so it must not be mirrored as a prompt.
+const RELAY_INJECTION_MARKERS = ["[relay message #", "[agent-relay"];
+// Reasoning tailer poll cadence (item 5). Coarse on purpose — reasoning is a
+// discreet progress signal, not a token stream, so ~1.2s keeps it light.
+const REASONING_POLL_MS = 1_200;
 const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
 
 interface RunnerTimelineEvent {
@@ -115,6 +129,22 @@ export class AgentRunner {
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
   private pendingTimelineEvent?: RunnerTimelineEvent;
   private pendingPromptMessageId?: number;
+  // Session-mirror: a synthesized id grouping a turn's reasoning/tool steps and
+  // its final response. Set when a provider-turn starts, cleared when it ends.
+  private currentTurnId?: string;
+  // Prompt-echo dedup: the last prompt the runner itself injected (chat box or
+  // initial prompt). A UserPromptSubmit hook echo matching this within the window
+  // is the same prompt arriving back from the provider and must not double-post.
+  private lastInjectedPrompt?: { text: string; at: number };
+  // Busy reconciler: consecutive idle probes observed while claims still say busy.
+  private busyReconcileIdleStreak = 0;
+  private busyReconcileTimer?: ReturnType<typeof setInterval>;
+  // Tracks whether the provider is in a legitimate blocked/approval state, so the
+  // busy reconciler doesn't mistake a permission prompt for a stuck-busy turn.
+  private providerBlocked = false;
+  // Reasoning tailer (item 5): streams the in-flight turn's reasoning/tool steps
+  // from the Claude transcript into chat as discreet session events.
+  private reasoningTail?: { timer: ReturnType<typeof setInterval>; emitted: number };
   private scratch?: SessionScratchLayout;
 
   constructor(private readonly options: RunnerOptions) {
@@ -195,6 +225,7 @@ export class AgentRunner {
       onTerminalAttachSpec: () => this.terminalAttachSpec(),
       onReplyObligations: () => this.http.listReplyObligations(this.agentId),
       onSessionTurn: (input) => this.publishSessionTurn(input),
+      onUserPrompt: (input) => this.handleUserPrompt(input),
     });
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
@@ -207,6 +238,7 @@ export class AgentRunner {
       this.setProviderStatus(status);
       if (runnerShouldResolveProviderExit(semanticStatus, this.exitCommandInProgress)) this.options.onProviderExit?.(semanticStatus === "offline" ? 0 : 1);
     });
+    this.options.adapter.onSessionEvent?.((event) => { void this.publishProviderSessionEvent(event); });
     this.bus.on("message.new", (message) => this.enqueueMessage(message as Message));
     this.bus.on("command", (type, params, commandId, command) => {
       void this.handleCommand(type, params, commandId, command);
@@ -250,6 +282,8 @@ export class AgentRunner {
     this.httpLivenessTimer = undefined;
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
+    this.disarmBusyReconciler();
+    this.stopReasoningTail();
     this.control?.stop();
     await this.bus.close();
   }
@@ -428,7 +462,7 @@ export class AgentRunner {
   private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): Promise<void> {
     const target = typeof command?.target === "string" ? command.target : this.agentId;
     if (target !== this.agentId && target !== this.options.runnerId) return;
-    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "prompt.inject") return;
+    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "agent.interrupt" && type !== "prompt.inject") return;
 
     const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
     if (exitAfterCommand) {
@@ -451,6 +485,9 @@ export class AgentRunner {
       } else if (type === "agent.clearContext") {
         if (!this.options.adapter.clearContext || !this.process) throw new Error("provider does not support clearContext");
         providerResult = await this.options.adapter.clearContext(this.process);
+      } else if (type === "agent.interrupt") {
+        if (!this.options.adapter.interrupt || !this.process) throw new Error("provider does not support interrupt");
+        providerResult = await this.options.adapter.interrupt(this.process);
       } else if (type === "agent.injectContext") {
         if (!this.process) throw new Error("provider process is unavailable");
         providerResult = await this.injectContext(params);
@@ -546,6 +583,9 @@ export class AgentRunner {
     if (!this.options.adapter.deliverInitialPrompt) throw new Error("provider does not support prompt injection");
     const messageId = typeof params.messageId === "number" ? params.messageId : undefined;
     if (messageId) this.pendingPromptMessageId = messageId;
+    // Mark so the matching UserPromptSubmit echo isn't double-posted: a chat-box
+    // prompt already created its own session message shown in the dashboard.
+    this.lastInjectedPrompt = { text: body.trim(), at: Date.now() };
     await this.options.adapter.deliverInitialPrompt(this.process, body);
     return { injected: true, messageId };
   }
@@ -785,6 +825,20 @@ export class AgentRunner {
         ...(update.timeline.metadata ? { metadata: update.timeline.metadata } : {}),
       };
     }
+    if (typeof update !== "string" && update.providerState) {
+      const state = (update.providerState as { state?: unknown }).state;
+      this.providerBlocked = state === "blocked";
+    } else if (status === "idle") {
+      this.providerBlocked = false;
+    }
+    if (status === "busy" && reason === "provider-turn") {
+      if (!this.currentTurnId) this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
+      this.armBusyReconciler();
+    } else if (status === "idle" && reason === "provider-turn") {
+      this.currentTurnId = undefined;
+      this.disarmBusyReconciler();
+      this.stopReasoningTail();
+    }
     if (status === "busy") {
       this.claims.clearTerminalStatus();
       this.claims.startWork(reason, id, typeof update === "string" ? {} : {
@@ -811,14 +865,16 @@ export class AgentRunner {
     this.publishStatus();
   }
 
-  // Phase 1 live-session lane: capture the assistant turn from the Claude
-  // transcript and post it as an observed "session" message so it shows in the
-  // dashboard chat with zero agent tokens. Posting it as a reply to the
-  // triggering message also clears the reply obligation, so the Stop hook no
-  // longer nags the agent to /reply — which is what made it re-emit before.
+  // Session-mirror lane: capture the assistant turn from the Claude transcript and
+  // post it as a "session" message so it shows in the dashboard chat with zero
+  // agent tokens. Capture is UNCONDITIONAL — it no longer depends on a triggering
+  // relay message existing, so turns started from the web terminal (which create
+  // no relay message) are mirrored too. A reply obligation, when present, is still
+  // used as replyTo so the Stop hook stops nagging the agent to /reply.
   private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown }): Promise<void> {
-    // Find the triggering message to reply to: either a pending prompt injection
-    // (Phase 2 direct lane) or a reply obligation from the dashboard human.
+    const turnId = this.currentTurnId;
+    this.stopReasoningTail();
+    // Optional correlation for threading + obligation clearing — never a capture gate.
     let replyToMessageId: number | undefined;
     const pendingPrompt = this.pendingPromptMessageId;
     if (pendingPrompt) {
@@ -830,52 +886,216 @@ export class AgentRunner {
         const obligation = [...obligations].reverse().find((o) => o.from === "user");
         replyToMessageId = obligation?.messageId;
       } catch {
-        return;
+        // fall through and capture without correlation
       }
     }
-    if (!replyToMessageId) return;
 
-    let jsonl: string;
-    try {
-      jsonl = await readFile(input.transcriptPath, "utf8");
-    } catch {
-      return;
-    }
-    // The Stop hook can fire before the final assistant entry is flushed to
-    // disk. Claude Code 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 the
-    // extraction yields non-empty text.
+    // 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 = "";
-    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 { return; }
+    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;
+        const extract = this.options.providerConfig.chatCaptureMode === "full" ? extractLastAssistantTurn : extractFinalAssistantMessage;
+        body = extract(jsonl);
+        if (body) break;
       }
-      if (!transcriptLooksComplete(jsonl)) continue;
-      const extract = this.options.providerConfig.chatCaptureMode === "full" ? extractLastAssistantTurn : extractFinalAssistantMessage;
-      body = extract(jsonl);
-      if (body) break;
     }
-    // Fallback: use last_assistant_message from the Stop hook payload directly.
-    // This bypasses the transcript file race entirely — Claude Code provides the
-    // content in-memory before the hook even fires.
+    // Fallback: last_assistant_message from the Stop hook payload, which bypasses
+    // the transcript file race entirely.
     if (!body && input.lastAssistantMessage) {
       body = extractHookAssistantMessage(input.lastAssistantMessage);
     }
+    // A pure tool-use turn with no closing text is fine to skip — its reasoning and
+    // tool steps already carried the visibility into chat.
     if (!body) return;
 
+    await this.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body,
+      ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+      session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
+    });
+  }
+
+  // Post one session-mirror event (prompt echo, assistant response, reasoning or
+  // tool step) as a `kind: "session"` relay message tagged with payload.session so
+  // the dashboard can render the live provider session faithfully. Display-only:
+  // session messages are never delivered back into a provider.
+  private async publishSessionEvent(input: {
+    from: string;
+    to: string;
+    body: string;
+    session: MessageSessionMeta;
+    replyTo?: number;
+  }): Promise<void> {
     try {
       await this.http.sendMessage({
+        from: input.from,
+        to: input.to,
+        ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+        kind: "session",
+        body: input.body,
+        payload: { session: { provider: this.options.provider, ...input.session } },
+      });
+    } catch (error) {
+      this.logRunnerDiagnostic(`session ${input.session.type} capture failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  // A human typed a prompt directly into the provider (web terminal / TUI). Mirror
+  // 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> {
+    if (!this.currentTurnId) this.currentTurnId = crypto.randomUUID();
+    const text = input.prompt.trim();
+    if (text && !this.isRunnerInjectedPrompt(text)) {
+      await this.publishSessionEvent({
+        from: "user",
+        to: this.agentId,
+        body: text,
+        session: { type: "prompt", origin: "terminal", turnId: this.currentTurnId },
+      });
+    }
+    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath);
+  }
+
+  // Route a provider-emitted session event (Codex app-server) into the chat mirror.
+  // Mirrors the same semantics as the Claude lane: prompts are echoed with dedup,
+  // and a response is only auto-captured when the agent won't separately reply to a
+  // relay obligation (so relay-triggered turns aren't double-posted).
+  private async publishProviderSessionEvent(event: ProviderSessionEvent): Promise<void> {
+    const body = event.body.trim();
+    if (!body) return;
+    const turnId = event.turnId ?? this.currentTurnId;
+    if (event.type === "prompt") {
+      if (this.isRunnerInjectedPrompt(body)) return;
+      await this.publishSessionEvent({
+        from: "user",
+        to: this.agentId,
+        body,
+        session: { type: "prompt", origin: event.origin ?? "terminal", ...(turnId ? { turnId } : {}) },
+      });
+      return;
+    }
+    if (event.type === "response") {
+      // If a relay message is awaiting the agent's own reply, let the agent answer
+      // it (Codex agents reply via their relay skills) instead of double-posting.
+      let replyToMessageId: number | undefined;
+      const pendingPrompt = this.pendingPromptMessageId;
+      if (pendingPrompt) {
+        replyToMessageId = pendingPrompt;
+        this.pendingPromptMessageId = undefined;
+      } else {
+        try {
+          const obligations = await this.http.listReplyObligations(this.agentId);
+          if (obligations.some((o) => o.from === "user")) return;
+        } catch {
+          // capture anyway on lookup failure
+        }
+      }
+      await this.publishSessionEvent({
         from: this.agentId,
         to: "user",
-        replyTo: replyToMessageId,
-        kind: "session",
         body,
+        ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+        session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) },
       });
-    } catch (error) {
-      this.logRunnerDiagnostic(`session turn capture failed: ${error instanceof Error ? error.message : String(error)}`);
+      return;
     }
+    if (this.options.providerConfig.reasoningCapture === false) return;
+    await this.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body,
+      session: { type: event.type, origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.label ? { label: event.label } : {}) },
+    });
+  }
+
+  private isRunnerInjectedPrompt(text: string): boolean {
+    if (RELAY_INJECTION_MARKERS.some((marker) => text.startsWith(marker))) return true;
+    const recent = this.lastInjectedPrompt;
+    if (recent && recent.text === text && Date.now() - recent.at < PROMPT_ECHO_DEDUP_MS) {
+      this.lastInjectedPrompt = undefined;
+      return true;
+    }
+    return false;
+  }
+
+  // --- Busy-state reconciler (item 2) -------------------------------------------------
+  // A safety net for turns that end out of band (interrupted from the web terminal,
+  // a hook that never fired) where the runner would otherwise stay stuck "busy".
+  private armBusyReconciler(): void {
+    if (this.busyReconcileTimer || !this.options.adapter.probeActivity) return;
+    this.busyReconcileIdleStreak = 0;
+    this.busyReconcileTimer = setInterval(() => { void this.runBusyReconcile(); }, BUSY_RECONCILE_POLL_MS);
+  }
+
+  private disarmBusyReconciler(): void {
+    if (this.busyReconcileTimer) clearInterval(this.busyReconcileTimer);
+    this.busyReconcileTimer = undefined;
+    this.busyReconcileIdleStreak = 0;
+  }
+
+  private async runBusyReconcile(): Promise<void> {
+    if (this.stopped || !this.process || !this.options.adapter.probeActivity) { this.disarmBusyReconciler(); return; }
+    // Only act while the runner still believes a provider turn is in flight, and
+    // never override a legitimate approval/blocked state.
+    if (this.claims.currentStatus() !== "busy" || this.providerBlocked) { this.busyReconcileIdleStreak = 0; return; }
+    if (!this.claims.activeWork().some((w) => w.kind === "provider-turn")) { this.disarmBusyReconciler(); return; }
+    let activity: "busy" | "idle" | "unknown";
+    try { activity = await this.options.adapter.probeActivity(this.process); } catch { return; }
+    if (activity !== "idle") { this.busyReconcileIdleStreak = 0; return; }
+    this.busyReconcileIdleStreak += 1;
+    if (this.busyReconcileIdleStreak < BUSY_RECONCILE_IDLE_CONFIRM) return;
+    this.logRunnerDiagnostic(`busy reconciler cleared a stuck provider-turn (idle confirmed ${this.busyReconcileIdleStreak}x)`);
+    const turnId = this.currentTurnId;
+    this.disarmBusyReconciler();
+    this.setProviderStatus({ status: "idle", reason: "provider-turn", id: turnId ?? "provider-turn" });
+  }
+
+  // --- Reasoning tailer (item 5) ------------------------------------------------------
+  // Tail the in-flight turn's Claude transcript and surface new reasoning/tool steps
+  // as discreet session events. Coalesced and coarse; the final response still comes
+  // through publishSessionTurn.
+  private startReasoningTail(transcriptPath: string): void {
+    if (this.options.providerConfig.reasoningCapture === false) return;
+    this.stopReasoningTail();
+    const state = { emitted: 0, timer: undefined as unknown as ReturnType<typeof setInterval> };
+    const poll = async (): Promise<void> => {
+      let jsonl: string;
+      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { return; }
+      const steps = extractLatestTurnSteps(jsonl);
+      const turnId = this.currentTurnId;
+      for (let i = state.emitted; i < steps.length; i++) {
+        const step = steps[i]!;
+        void this.publishSessionEvent({
+          from: this.agentId,
+          to: "user",
+          body: step.text,
+          session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
+        });
+      }
+      if (steps.length > state.emitted) state.emitted = steps.length;
+    };
+    state.timer = setInterval(() => { void poll(); }, REASONING_POLL_MS);
+    this.reasoningTail = state;
+    void poll();
+  }
+
+  private stopReasoningTail(): void {
+    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
+    this.reasoningTail = undefined;
   }
 
   private publishStatus(): void {
@@ -1451,6 +1671,13 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { so
     liveSession: {
       capture: true,
       inject: Boolean(options.adapter.deliverInitialPrompt),
+      interrupt: Boolean(options.adapter.interrupt),
+      // Both providers mirror directly-typed prompts and stream reasoning/tool
+      // activity into chat (Claude via hooks + transcript tail, Codex via
+      // app-server item events).
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: options.provider === "claude" || options.provider === "codex",
     },
     source: "runtime",
     confidence: "reported",