agent-relay-runner 0.99.1 → 0.101.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.99.1",
+  "version": "0.101.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.80"
+    "agent-relay-sdk": "0.2.82"
   },
   "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.99.1",
+  "version": "0.101.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/kill-guard.sh

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+# Shared "fleet fratricide" kill-pattern guard (issue #753).
+#
+# Every managed agent's runner runs as
+#   bun run .../agent-relay-runner/src/index.ts <provider> ...
+# so a broad process kill such as `pkill -f "src/index.ts"` (or `pkill bun`,
+# `killall node`, ...) matches EVERY sibling agent host-wide and silently SIGTERMs
+# the whole fleet. This is the structural guard so that can't happen again.
+#
+# It blocks broad process-kill commands (pkill / killall, and `kill` with a
+# pattern that leaks a fleet token) whose target would match sibling runners,
+# while still allowing the safe shapes: PID-scoped kills (kill 12345,
+# kill "$SERVER_PID") and pkill -f on a token that is unique to the caller's own
+# throwaway server (its exact test port, or "$PWD/public").
+#
+# DUAL MODE:
+#   - sourced: defines fratricide_deny_reason() / fratricide_raw_reason() plus the
+#     shell-parsing helpers (trim_shell_text / split_segments / shell_words). The
+#     Claude PreToolUse Bash guard sources this and is wired to it.
+#   - executed: `kill-guard.sh "<command text>"` prints the guidance + exits 0 when
+#     the command is a dangerous broad kill, and exits 1 (silent) when it is safe.
+#     This lets non-bash callers reuse the SAME matcher as a subprocess.
+#
+# TODO(#753 follow-up): wire the Codex runner/exec layer to invoke this guard.
+# Codex managed agents have no Claude PreToolUse hook, so the same broad pkill can
+# still fratricide the fleet from a Codex session until that wiring lands. The
+# matcher is intentionally factored here so the Codex side can call it directly
+# (e.g. `bash kill-guard.sh "$command"`) without duplicating the pattern list.
+
+shopt -s extglob
+
+# Guidance returned on a block — tells the caller how to clean up safely instead.
+FRATRICIDE_PATTERN_GUIDANCE='Blocked a broad process-kill (#753 fleet-fratricide guard): this pattern would match sibling agents'\'' runners, because every managed agent runs "bun run .../agent-relay-runner/src/index.ts". Kill only a PID you own — capture it when you spawn the server (SERVER_PID=$!; kill "$SERVER_PID") — or pkill -f a token that is unique to your own process (your exact test port, or "$PWD/public"). Never pkill/killall on bun, node, src/index.ts, agent-relay, or agent-relay-runner.'
+
+trim_shell_text() {
+  local value="$1"
+  value="${value##+([[:space:]])}"
+  value="${value%%+([[:space:]])}"
+  printf '%s' "$value"
+}
+
+split_segments() {
+  local text="$1"
+  local current="" i len ch next quote="" escaped=0
+  SEGMENTS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      current+="$ch"
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      current+="$ch"
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      fi
+      continue
+    fi
+
+    case "$ch" in
+      "'"|'"')
+        quote="$ch"
+        current+="$ch"
+        ;;
+      "\\")
+        escaped=1
+        current+="$ch"
+        ;;
+      $'\n'|";")
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "&")
+        next="${text:i+1:1}"
+        if [ "$next" = "&" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "|")
+        next="${text:i+1:1}"
+        if [ "$next" = "|" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      *)
+        current+="$ch"
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  SEGMENTS+=("$current")
+  return 0
+}
+
+shell_words() {
+  local text="$1"
+  local word="" i len ch quote="" escaped=0 in_word=0
+  WORDS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      word+="$ch"
+      in_word=1
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      else
+        word+="$ch"
+      fi
+      in_word=1
+      continue
+    fi
+
+    case "$ch" in
+      [[:space:]])
+        if (( in_word )); then
+          WORDS+=("$word")
+          word=""
+          in_word=0
+        fi
+        ;;
+      "'"|'"')
+        quote="$ch"
+        in_word=1
+        ;;
+      "\\")
+        escaped=1
+        in_word=1
+        ;;
+      *)
+        word+="$ch"
+        in_word=1
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  if (( in_word )); then
+    WORDS+=("$word")
+  fi
+  return 0
+}
+
+# True (0) when text mentions a process-kill verb (pkill / killall / kill).
+_looks_like_kill() {
+  if [[ "${1,,}" =~ (^|[^a-z])(pkill|killall|kill)([^a-z]|$) ]]; then
+    return 0
+  fi
+  return 1
+}
+
+# True (0) when a kill pattern/token would match sibling runners across the fleet.
+# Matches the runner path tokens, and the bare interpreter process names bun/node
+# even when wrapped in pgrep/regex metacharacters such as [b]un, ^node$, bun.* .
+_pattern_hits_fleet() {
+  local lower="${1,,}"
+  case "$lower" in
+    *index.ts*|*agent-relay*)
+      return 0
+      ;;
+  esac
+  local cleaned="$lower" mc
+  for mc in '[' ']' '(' ')' '{' '}' '^' '$' '*' '+' '?' '\' '|'; do
+    cleaned="${cleaned//"$mc"/}"
+  done
+  if [[ "$cleaned" =~ (^|[^a-z0-9])(bun|node)([^a-z0-9]|$) ]]; then
+    return 0
+  fi
+  return 1
+}
+
+# Inspect one shell segment. Prints guidance + returns 0 when it is a dangerous
+# broad kill; returns 1 when the segment is safe or not a kill.
+_fratricide_segment_reason() {
+  local raw="$1" segment base i=0 j arg
+  segment="$(trim_shell_text "$raw")"
+  if [ -z "$segment" ]; then
+    return 1
+  fi
+  if ! shell_words "$segment"; then
+    # Unparseable — only worry if it both looks like a kill and leaks a fleet token.
+    if _looks_like_kill "$segment" && _pattern_hits_fleet "$segment"; then
+      printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+      return 0
+    fi
+    return 1
+  fi
+  if (( ${#WORDS[@]} == 0 )); then
+    return 1
+  fi
+
+  # Skip any leading VAR=value assignments (e.g. SERVER_PID=$!; kill ...).
+  while (( i < ${#WORDS[@]} )) && [[ "${WORDS[i]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do
+    ((i += 1))
+  done
+  if (( i >= ${#WORDS[@]} )); then
+    return 1
+  fi
+
+  base="${WORDS[i]##*/}"
+  base="${base,,}"
+  case "$base" in
+    pkill|killall)
+      # Pattern-matching kills: block if ANY non-flag operand hits the fleet.
+      j=$((i + 1))
+      while (( j < ${#WORDS[@]} )); do
+        arg="${WORDS[j]}"
+        if [[ "$arg" == -* ]]; then
+          ((j += 1))
+          continue
+        fi
+        if _pattern_hits_fleet "$arg"; then
+          printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+          return 0
+        fi
+        ((j += 1))
+      done
+      return 1
+      ;;
+    kill)
+      # PID-scoped kills (kill 123, kill "$PID", kill -9 %1) are safe. Block only
+      # when an operand leaks a fleet token — e.g. kill $(pgrep -f src/index.ts).
+      j=$((i + 1))
+      while (( j < ${#WORDS[@]} )); do
+        arg="${WORDS[j]}"
+        if _pattern_hits_fleet "$arg"; then
+          printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+          return 0
+        fi
+        ((j += 1))
+      done
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+# Structured matcher: split a full command into segments and check each one.
+# Prints guidance + returns 0 on the first dangerous broad kill; returns 1 if safe.
+fratricide_deny_reason() {
+  local text="$1" segment reason
+  if ! split_segments "$text"; then
+    fratricide_raw_reason "$text"
+    return $?
+  fi
+  local -a segments=("${SEGMENTS[@]}")
+  for segment in "${segments[@]}"; do
+    if reason="$(_fratricide_segment_reason "$segment")"; then
+      printf '%s' "$reason"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Coarse raw-text fallback for when structured parsing is unavailable (no jq, or
+# unparseable shell). Prints guidance + returns 0 only when the text both looks
+# like a kill and leaks a fleet token.
+fratricide_raw_reason() {
+  local text="$1"
+  if _looks_like_kill "$text" && _pattern_hits_fleet "$text"; then
+    printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+    return 0
+  fi
+  return 1
+}
+
+# Executed directly (not sourced): argv[1] is the command text to inspect.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  if reason="$(fratricide_deny_reason "${1:-}")"; then
+    printf '%s\n' "$reason"
+    exit 0
+  fi
+  exit 1
+fi

package/plugins/claude/hooks/read-only-bash-guard.sh

@@ -4,8 +4,12 @@
 # Real boundaries are Relay token scope, unavailable write tools, and future
 # OS-level enforcement.
 set -euo pipefail
-source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+HOOK_DIR="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks"
+source "${HOOK_DIR}/relay-status.sh"
 relay_install_hook_guard read-only-bash-guard
+# Shared fleet-fratricide kill-pattern matcher (#753): trim_shell_text,
+# split_segments, shell_words and fratricide_deny_reason live here.
+source "${HOOK_DIR}/kill-guard.sh"
 
 payload="$(cat)"
 
@@ -15,6 +19,38 @@ emit_deny() {
     "$(relay_json_escape "$reason")"
 }
 
+shopt -s extglob
+
+# Extract the Bash command once. jq is strongly preferred; both the fleet-kill
+# guard (all modes) and the read-only allow-list (read-only mode) consume it.
+jq_available=0
+tool_name=""
+command_text=""
+if command -v jq >/dev/null 2>&1; then
+  jq_available=1
+  tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+  command_text="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+fi
+
+# --- Fleet-fratricide guard: ACTIVE IN ALL APPROVAL MODES (#753) ---
+# A broad pkill/killall/kill can SIGTERM every sibling agent's runner host-wide,
+# so this block runs before (and independent of) the read-only allow-list.
+if (( jq_available )); then
+  if [ "${tool_name,,}" = "bash" ] && [ -n "$command_text" ]; then
+    if fratricide_reason="$(fratricide_deny_reason "$command_text")"; then
+      emit_deny "$fratricide_reason"
+      exit 0
+    fi
+  fi
+else
+  # No jq: best-effort raw scan so the fleet guard still bites the obvious cases.
+  if fratricide_reason="$(fratricide_raw_reason "$payload")"; then
+    emit_deny "$fratricide_reason"
+    exit 0
+  fi
+fi
+
+# --- Read-only allow-list: only the read-only approval mode below this point ---
 case "${AGENT_RELAY_APPROVAL:-}" in
   open|guarded)
     exit 0
@@ -27,40 +63,27 @@ case "${AGENT_RELAY_APPROVAL:-}" in
     ;;
 esac
 
-if ! command -v jq >/dev/null 2>&1; then
+if (( ! jq_available )); then
   emit_deny "Read-only Bash guard could not inspect the command because jq is unavailable."
   exit 0
 fi
 
-tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
 if [ "${tool_name,,}" != "bash" ]; then
   exit 0
 fi
 
-command_text="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
 if [ -z "$command_text" ]; then
   emit_deny "Read-only Bash guard denied an empty Bash command."
   exit 0
 fi
 
-shopt -s extglob
-
 DENY_REASON=""
-SEGMENTS=()
-WORDS=()
 
 deny_segment() {
   DENY_REASON="$1"
   return 1
 }
 
-trim_shell_text() {
-  local value="$1"
-  value="${value##+([[:space:]])}"
-  value="${value%%+([[:space:]])}"
-  printf '%s' "$value"
-}
-
 hard_deny_reason() {
   local text="$1"
   case "$text" in
@@ -117,131 +140,6 @@ hard_deny_reason() {
   return 1
 }
 
-split_segments() {
-  local text="$1"
-  local current="" i len ch next quote="" escaped=0
-  SEGMENTS=()
-  len=${#text}
-  for ((i = 0; i < len; i++)); do
-    ch="${text:i:1}"
-    if (( escaped )); then
-      current+="$ch"
-      escaped=0
-      continue
-    fi
-    if [ -n "$quote" ]; then
-      current+="$ch"
-      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
-        escaped=1
-        continue
-      fi
-      if [ "$ch" = "$quote" ]; then
-        quote=""
-      fi
-      continue
-    fi
-
-    case "$ch" in
-      "'"|'"')
-        quote="$ch"
-        current+="$ch"
-        ;;
-      "\\")
-        escaped=1
-        current+="$ch"
-        ;;
-      $'\n'|";")
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      "&")
-        next="${text:i+1:1}"
-        if [ "$next" = "&" ]; then
-          ((i += 1))
-        fi
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      "|")
-        next="${text:i+1:1}"
-        if [ "$next" = "|" ]; then
-          ((i += 1))
-        fi
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      *)
-        current+="$ch"
-        ;;
-    esac
-  done
-
-  if [ -n "$quote" ] || (( escaped )); then
-    return 1
-  fi
-  SEGMENTS+=("$current")
-  return 0
-}
-
-shell_words() {
-  local text="$1"
-  local word="" i len ch quote="" escaped=0 in_word=0
-  WORDS=()
-  len=${#text}
-  for ((i = 0; i < len; i++)); do
-    ch="${text:i:1}"
-    if (( escaped )); then
-      word+="$ch"
-      in_word=1
-      escaped=0
-      continue
-    fi
-    if [ -n "$quote" ]; then
-      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
-        escaped=1
-        continue
-      fi
-      if [ "$ch" = "$quote" ]; then
-        quote=""
-      else
-        word+="$ch"
-      fi
-      in_word=1
-      continue
-    fi
-
-    case "$ch" in
-      [[:space:]])
-        if (( in_word )); then
-          WORDS+=("$word")
-          word=""
-          in_word=0
-        fi
-        ;;
-      "'"|'"')
-        quote="$ch"
-        in_word=1
-        ;;
-      "\\")
-        escaped=1
-        in_word=1
-        ;;
-      *)
-        word+="$ch"
-        in_word=1
-        ;;
-    esac
-  done
-
-  if [ -n "$quote" ] || (( escaped )); then
-    return 1
-  fi
-  if (( in_word )); then
-    WORDS+=("$word")
-  fi
-  return 0
-}
-
 validate_git_branch() {
   local i="$1" arg
   while (( i < ${#WORDS[@]} )); do

package/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
@@ -30,7 +30,7 @@ export interface ProviderStatusEvent {
   // runner reconciles them against actual liveness and clears the busy marker if
   // every pid is dead — recovering from a tracked process killed out-of-band.
   pids?: number[];
-  providerState?: Record<string, unknown>;
+  providerState?: ProviderState;
   metadata?: Record<string, unknown>;
 }
 

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, LivenessSignal, Message } from "agent-relay-sdk";
+import type { ContextState, InteractivePrompt, LivenessSignal, Message, 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, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
@@ -29,7 +29,7 @@ type PendingCodexApproval = {
   requestId: string | number;
   method: string;
   params: Record<string, unknown>;
-  view: Record<string, unknown>;
+  view: InteractivePrompt;
 };
 
 type PendingCodexCompact = {
@@ -420,6 +420,12 @@ export class CodexAdapter implements ProviderAdapter {
     if (event.type === "server-request" && process) {
       const approval = codexApprovalFromServerRequest(event.message);
       if (approval) {
+        // #435/#723 ordering invariant: mirror every reasoning/narrative step of the turn
+        // BEFORE the approval form surfaces — the same guarantee Claude makes by pre-flushing
+        // the transcript at its hook seam, here enforced from the Codex app-server mechanism.
+        // approval.view.reasoningSettled === true asserts this flush has run.
+        this.agentMessageCapture.closeSegment((body) => this.emitAgentNarration(body));
+        this.flushBufferedReasoning();
         this.pendingApprovals.set(approval.pending.id, approval.pending);
         this.statusCb({
           status: "busy",
@@ -728,7 +734,7 @@ export class CodexAdapter implements ProviderAdapter {
     pending.reject(error);
   }
 
-  private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): Record<string, unknown> | undefined {
+  private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): ProviderState | undefined {
     const state = codexProviderStateFromThreadStatus(status, params);
     if (state?.state !== "blocked" || state.reason !== "waitingOnApproval" || state.pendingApproval) return state;
     const pending = [...this.pendingApprovals.values()].at(-1);
@@ -779,7 +785,7 @@ export function codexHeadlessElicitationResponse(): Record<string, unknown> {
   return { action: "accept", content: {}, _meta: null };
 }
 
-function codexApprovalFromServerRequest(message: { id: string | number; method: string; params?: unknown }): { pending: PendingCodexApproval; view: Record<string, unknown> } | null {
+function codexApprovalFromServerRequest(message: { id: string | number; method: string; params?: unknown }): { pending: PendingCodexApproval; view: InteractivePrompt } | null {
   if (!isRecord(message.params)) return null;
   const method = message.method;
   if (!codexApprovalMethod(method)) return null;
@@ -882,7 +888,11 @@ function codexApprovalMethod(method: string): boolean {
     method === "item/permissions/requestApproval";
 }
 
-function codexApprovalView(id: string, method: string, params: Record<string, unknown>): Record<string, unknown> {
+// Build the normalized InteractivePrompt for a Codex app-server approval request.
+// reasoningSettled is stamped `true` because handleCodexEvent flushes buffered reasoning +
+// any open narration segment BEFORE this view is emitted as pendingApproval (#435/#723). No
+// `provider` tag — the server reads the typed contract, not provider identity.
+function codexApprovalView(id: string, method: string, params: Record<string, unknown>): InteractivePrompt {
   const command = typeof params.command === "string" ? params.command
     : Array.isArray(params.command) ? params.command.filter((v): v is string => typeof v === "string").join(" ")
     : "";
@@ -902,7 +912,6 @@ function codexApprovalView(id: string, method: string, params: Record<string, un
   const isSessionCapable = method !== "item/permissions/requestApproval";
   return {
     id,
-    provider: "codex",
     kind: method.includes("file") || method === "applyPatchApproval" ? "file-change" : method.includes("permission") ? "permission" : "command",
     title: method.includes("file") || method === "applyPatchApproval"
       ? "Approve file changes"
@@ -910,12 +919,12 @@ function codexApprovalView(id: string, method: string, params: Record<string, un
         ? "Approve extra permissions"
         : "Approve command",
     body: body || "Codex is requesting permission.",
-    method,
     choices: [
       { id: "approve", label: method.includes("permission") ? "Allow this turn" : "Approve" },
       ...(isSessionCapable ? [{ id: "approve-session", label: "Approve session" }] : [{ id: "approve-session", label: "Allow session" }]),
       { id: "deny", label: "Deny" },
     ],
+    reasoningSettled: true,
   };
 }
 
@@ -962,7 +971,7 @@ export function codexDeliveryNotice(messages: Message[], threadId: string): stri
   return `[agent-relay] received ${messages.length} relay message${messages.length === 1 ? "" : "s"} ${ids} from ${senders}; injecting into Codex thread ${threadId}`;
 }
 
-export function codexProviderStateFromThreadStatus(status: unknown, params?: Record<string, unknown>, now = Date.now()): Record<string, unknown> | undefined {
+export function codexProviderStateFromThreadStatus(status: unknown, params?: Record<string, unknown>, now = Date.now()): ProviderState | undefined {
   const type = statusType(status);
   const flags = activeFlags(status);
   const threadId = stringValue(params?.threadId) ?? (isRecord(params?.thread) ? stringValue(params.thread.id) : undefined);

package/src/claude-prompt-gates.ts

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { isRecord } from "agent-relay-sdk";
+import { isRecord, type ProviderState } from "agent-relay-sdk";
 import type { ProviderStatusUpdate, RunnerSpawnConfig } from "./adapter";
 import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "./rate-limit";
 
@@ -24,7 +24,7 @@ interface ClaudePanePromptGate {
   keystroke: string;
   minDetections: number;
   match(text: string, nowMs?: number): PaneGateMatch | null;
-  providerState?(match: PaneGateMatch, context: ClaudePromptGatePaneContext): Record<string, unknown>;
+  providerState?(match: PaneGateMatch, context: ClaudePromptGatePaneContext): ProviderState;
 }
 
 export interface ClaudePromptGatePaneState {

package/src/control-server.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import type { Message, ReplyObligation } from "agent-relay-sdk";
+import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
@@ -302,7 +302,12 @@ async function handlePermissionRequest(
   return Response.json(claudePermissionHookResponse(decision, body));
 }
 
-function claudePermissionApprovalView(id: string, body: Record<string, unknown>): Record<string, unknown> {
+// Build the normalized InteractivePrompt for a Claude PreToolUse permission/question hook.
+// reasoningSettled is stamped `true` because handlePermissionRequest pre-flushes the
+// transcript narrative (onSessionTurn isPreFlush) BEFORE this view is built and emitted, so
+// the turn's reasoning is already mirrored ahead of the form (#435/#723). No `provider` tag —
+// the server reads the typed contract, not provider identity.
+function claudePermissionApprovalView(id: string, body: Record<string, unknown>): InteractivePrompt {
   const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
   const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
   // AskUserQuestion is not a yes/no gate — it asks the user to pick answers.
@@ -313,12 +318,12 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
     const count = toolInput.questions.length;
     return {
       id,
-      provider: "claude",
       kind: "questions",
       title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
       body: "",
-      questions: toolInput.questions,
+      questions: toolInput.questions as InteractivePrompt["questions"],
       choices: [],
+      reasoningSettled: true,
     };
   }
   // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
@@ -332,7 +337,6 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
       : JSON.stringify(toolInput);
     return {
       id,
-      provider: "claude",
       kind: "plan",
       title: "Claude is ready to code",
       body: plan,
@@ -340,6 +344,7 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
         { id: "approve", label: "Approve plan" },
         { id: "deny", label: "Keep planning" },
       ],
+      reasoningSettled: true,
     };
   }
   const command = typeof toolInput.command === "string" ? toolInput.command : "";
@@ -351,7 +356,6 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
   ].filter(Boolean).join("\n");
   return {
     id,
-    provider: "claude",
     kind: toolName.toLowerCase() === "bash" ? "command" : "tool",
     title: `Approve ${toolName}`,
     body: bodyText,
@@ -361,6 +365,7 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
       { id: "deny", label: "Deny" },
       { id: "abort", label: "Abort" },
     ],
+    reasoningSettled: true,
   };
 }
 
@@ -429,7 +434,7 @@ function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput,
   };
 }
 
-function claudeResolvedPermissionPrompt(view: Record<string, unknown>, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): ResolvedPermissionPrompt {
+function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): ResolvedPermissionPrompt {
   const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
   const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
   const kind = view.kind === "questions" || view.kind === "plan" || view.kind === "command" || view.kind === "tool"

package/src/rate-limit.ts

@@ -7,6 +7,8 @@
 // Both build the hold here so the shape stays identical, and the relay's resume sweep
 // (services/rate-limit-resume.ts) lifts either once the window resets.
 
+import type { ProviderState } from "agent-relay-sdk";
+
 export const RATE_LIMIT_BLOCK_REASON = "rate_limit";
 
 // Reject a parsed reset that's in the past or implausibly far out — a bad parse would
@@ -24,7 +26,7 @@ interface RateLimitHoldInput {
 }
 
 /** The blocked providerState a rate-limit hold carries. Shared by both detection arms. */
-export function buildRateLimitProviderState(input: RateLimitHoldInput): Record<string, unknown> {
+export function buildRateLimitProviderState(input: RateLimitHoldInput): ProviderState {
   const now = Date.now();
   const resetAt = typeof input.resetAt === "number" && Number.isFinite(input.resetAt) ? input.resetAt : undefined;
   const kind = input.kind ?? rateLimitKindForError(input.errorType);

package/src/runner-core.ts

@@ -2,7 +2,7 @@ import { hostname } from "node:os";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
+import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, ProviderState, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "agent-relay-sdk/context-probe";
 import { isPidAlive } from "agent-relay-sdk/process-utils";
@@ -264,14 +264,14 @@ export class AgentRunner {
   // 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;
-  private terminalFailure?: { reason: string; message: string; providerState?: Record<string, unknown> };
+  private terminalFailure?: { reason: string; message: string; providerState?: ProviderState };
   // #286: a usage/rate-limit hold. The turn truly ended (idle), but the agent is
   // held until the limit resets, so this can't ride an active-work claim like the
   // permission-blocked state does. publishStatus surfaces it as the agent's
   // providerState; it clears when a new turn starts (the relay's resume message
   // wakes one) so the blocked badge lifts on its own.
-  private rateLimitHold?: Record<string, unknown>;
-  private pendingRateLimitHold?: Record<string, unknown>;
+  private rateLimitHold?: ProviderState;
+  private pendingRateLimitHold?: ProviderState;
   // 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?: ReasoningTailState;
@@ -1157,7 +1157,7 @@ export class AgentRunner {
     }
     let deferredRateLimitHold = false;
     if (typeof update !== "string" && update.providerState) {
-      const ps = update.providerState as { state?: unknown; reason?: unknown; source?: unknown };
+      const ps = update.providerState;
       // A rate-limit hold persists across the idle the turn ends on; any other
       // providerState supersedes it (clears a stale hold).
       if (ps.state === "blocked" && ps.reason === "rate_limit") {
@@ -1858,8 +1858,8 @@ export class AgentRunner {
   // (NOT an inbound message) so it shows in the dashboard chat WITHOUT waking a turn
   // — waking a still-limited agent would just re-fail. The relay sends the waking
   // resume message later, once the window has reset.
-  private publishRateLimitNotice(providerState: Record<string, unknown>): void {
-    const label = typeof providerState.label === "string" && providerState.label ? providerState.label : "usage limit reached";
+  private publishRateLimitNotice(providerState: ProviderState): void {
+    const label = providerState.label || "usage limit reached";
     this.publishSessionEvent({
       from: this.agentId,
       to: "user",

package/src/runner-helpers.ts

@@ -1,5 +1,5 @@
 import { closeSync, openSync, readSync, statSync } from "node:fs";
-import type { AgentProfile, ContextState, Message, ProviderCapabilities, QuotaState } from "agent-relay-sdk";
+import type { AgentProfile, ContextState, Message, ProviderCapabilities, ProviderState, QuotaState } from "agent-relay-sdk";
 import { errMessage } from "agent-relay-sdk";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
@@ -377,10 +377,12 @@ function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quota
   };
 }
 
-export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): Record<string, unknown> | null {
+export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): ProviderState | null {
   const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
   const state = providerTurn?.metadata?.providerState;
-  return state && typeof state === "object" && !Array.isArray(state) ? state as Record<string, unknown> : null;
+  return state && typeof state === "object" && !Array.isArray(state) && typeof (state as { state?: unknown }).state === "string"
+    ? state as ProviderState
+    : null;
 }
 
 export function isHttpAuthError(error: unknown): boolean {