agent-relay-runner 0.62.2 → 0.62.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.62.2",
+  "version": "0.62.3",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.39"
+    "agent-relay-sdk": "0.2.40"
   },
   "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.62.2",
+  "version": "0.62.3",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/hooks.json

@@ -12,6 +12,16 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/read-only-bash-guard.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "matcher": "AskUserQuestion",
         "hooks": [

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

@@ -0,0 +1,689 @@
+#!/usr/bin/env bash
+# BEST-EFFORT GUARDRAIL / defense-in-depth only. This hook denies common
+# mutating Bash patterns for read-only Claude sessions, but it is not a sandbox.
+# 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"
+relay_install_hook_guard read-only-bash-guard
+
+payload="$(cat)"
+
+emit_deny() {
+  local reason="${1:-Read-only Claude sessions may only run inspection commands.}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' \
+    "$(relay_json_escape "$reason")"
+}
+
+case "${AGENT_RELAY_APPROVAL:-}" in
+  open|guarded)
+    exit 0
+    ;;
+  read-only)
+    ;;
+  *)
+    # Unknown approval values fail closed so typos such as "readonly" or
+    # casing drift do not silently disable the read-only boundary.
+    ;;
+esac
+
+if ! command -v jq >/dev/null 2>&1; 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
+    *'$('*|*'`'*)
+      printf '%s' "Read-only Bash guard denied command substitution."
+      return 0
+      ;;
+    *'<('*|*'>('*)
+      printf '%s' "Read-only Bash guard denied process substitution."
+      return 0
+      ;;
+  esac
+
+  local i len ch next quote="" escaped=0
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      fi
+      continue
+    fi
+
+    case "$ch" in
+      "'"|'"')
+        quote="$ch"
+        ;;
+      "\\")
+        escaped=1
+        ;;
+      ">")
+        printf '%s' "Read-only Bash guard denied shell output redirection."
+        return 0
+        ;;
+      "<")
+        next="${text:i+1:1}"
+        if [ "$next" = ">" ]; then
+          printf '%s' "Read-only Bash guard denied shell output redirection."
+          return 0
+        fi
+        ;;
+    esac
+  done
+
+  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
+    arg="${WORDS[i]}"
+    case "$arg" in
+      --list|--all|--remotes|--show-current|-a|-r|-v|-vv)
+        ;;
+      *)
+        deny_segment "Read-only Bash guard denied a git branch mutation or unsupported branch option."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_git_read_args() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      --output|--output=*)
+        deny_segment "Read-only Bash guard denied git output-to-file options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_git() {
+  local i="$1" arg sub
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    case "$arg" in
+      -C)
+        ((i += 1))
+        if (( i >= ${#WORDS[@]} )); then
+          deny_segment "Read-only Bash guard denied git -C without a path."
+          return 1
+        fi
+        ((i += 1))
+        ;;
+      --no-pager)
+        ((i += 1))
+        ;;
+      -c|--config-env|--config-env=*)
+        deny_segment "Read-only Bash guard denied git configuration or alias injection."
+        return 1
+        ;;
+      --)
+        ((i += 1))
+        break
+        ;;
+      -*)
+        deny_segment "Read-only Bash guard denied an unsupported git global option."
+        return 1
+        ;;
+      *)
+        break
+        ;;
+    esac
+  done
+
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied git without an explicit read-only subcommand."
+    return 1
+  fi
+
+  sub="${WORDS[i],,}"
+  ((i += 1))
+  case "$sub" in
+    diff|log|status|show|blame|grep|rev-parse|describe)
+      validate_git_read_args "$i"
+      return $?
+      ;;
+    branch)
+      validate_git_branch "$i"
+      return $?
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a git subcommand that is not in the read-only allow-list."
+      return 1
+      ;;
+  esac
+}
+
+find_arg_takes_operand() {
+  local arg="$1"
+  case "$arg" in
+    -name|-iname|-path|-ipath|-wholename|-iwholename|-regex|-iregex|-type|-xtype|-user|-group|-newer|-samefile|-size|-perm|-mtime|-mmin|-atime|-amin|-ctime|-cmin|-maxdepth|-mindepth|-printf|-printf0)
+      return 0
+      ;;
+    -newer??)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+validate_find() {
+  local i="$1" arg skip_next=0
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if (( skip_next )); then
+      skip_next=0
+      ((i += 1))
+      continue
+    fi
+    case "$arg" in
+      -exec|-execdir|-ok|-okdir|-delete|-fls|-fprint|-fprintf|-fprint0)
+        deny_segment "Read-only Bash guard denied find mutating action predicates."
+        return 1
+        ;;
+    esac
+    if find_arg_takes_operand "$arg"; then
+      skip_next=1
+    fi
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_fd() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -x|-X|--exec|--exec-batch)
+        deny_segment "Read-only Bash guard denied fd exec action options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_rg() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      --pre|--pre=*)
+        deny_segment "Read-only Bash guard denied rg preprocessor execution options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_sort() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -o|-o?*|--output|--output=*)
+        deny_segment "Read-only Bash guard denied sort output-to-file options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+uniq_arg_takes_operand() {
+  local arg="$1"
+  case "$arg" in
+    -f|-s|-w|--skip-fields|--skip-chars|--check-chars)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+validate_uniq() {
+  local i="$1" arg operands=0 after_options=0 skip_next=0
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if (( skip_next )); then
+      skip_next=0
+      ((i += 1))
+      continue
+    fi
+    if (( ! after_options )) && [ "$arg" = "--" ]; then
+      after_options=1
+      ((i += 1))
+      continue
+    fi
+    if (( ! after_options )) && [ "$arg" != "-" ] && [[ "$arg" == -* ]]; then
+      if uniq_arg_takes_operand "$arg"; then
+        skip_next=1
+      fi
+      ((i += 1))
+      continue
+    fi
+
+    ((operands += 1))
+    if (( operands > 1 )); then
+      deny_segment "Read-only Bash guard denied uniq output-file operands."
+      return 1
+    fi
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_yq() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -i|-i?*|--inplace|--inplace=*)
+        deny_segment "Read-only Bash guard denied yq in-place edit options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_bun() {
+  local i="$1" sub next
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied bun without an explicit test/typecheck command."
+    return 1
+  fi
+  sub="${WORDS[i],,}"
+  case "$sub" in
+    test)
+      return 0
+      ;;
+    run)
+      next="${WORDS[i+1]:-}"
+      if [ "$next" = "typecheck" ]; then
+        return 0
+      fi
+      deny_segment "Read-only Bash guard only allows bun run typecheck in read-only sessions."
+      return 1
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a bun command outside the test/typecheck allow-list."
+      return 1
+      ;;
+  esac
+}
+
+validate_agent_relay() {
+  local i="$1" sub next
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied agent-relay without an allowed read/message subcommand."
+    return 1
+  fi
+  sub="${WORDS[i]}"
+  next="${WORDS[i+1]:-}"
+  case "$sub" in
+    /reply|/react|/message|/status|/read-message|/tags|/whoami|/guide)
+      return 0
+      ;;
+    get-message|status|whoami|guide|tags)
+      return 0
+      ;;
+    workspace)
+      if [ "$next" = "status" ]; then
+        return 0
+      fi
+      deny_segment "Read-only Bash guard denied a mutating agent-relay workspace command."
+      return 1
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied an agent-relay command outside the read/message allow-list."
+      return 1
+      ;;
+  esac
+}
+
+validate_leading_assignment() {
+  local assignment="$1" name value
+  name="${assignment%%=*}"
+  value="${assignment#*=}"
+
+  case "$name" in
+    LANG|LANGUAGE|LC_*)
+      if [[ "$value" =~ ^[A-Za-z0-9_.:@+-]+$ ]]; then
+        return 0
+      fi
+      ;;
+    TZ)
+      if [[ "$value" =~ ^[A-Za-z0-9_+:-]+(/[A-Za-z0-9_+:-]+)*$ ]]; then
+        return 0
+      fi
+      ;;
+    PAGER|GIT_PAGER)
+      if [ "$value" = "cat" ]; then
+        return 0
+      fi
+      ;;
+  esac
+
+  deny_segment "Read-only Bash guard denied unsafe leading environment assignment."
+  return 1
+}
+
+validate_segment() {
+  local raw="$1" segment i=0 saw_assignment=0 command_name base
+  segment="$(trim_shell_text "$raw")"
+  if [ -z "$segment" ]; then
+    return 0
+  fi
+  if ! shell_words "$segment"; then
+    deny_segment "Read-only Bash guard denied shell syntax it could not parse."
+    return 1
+  fi
+  if (( ${#WORDS[@]} == 0 )); then
+    return 0
+  fi
+
+  while (( i < ${#WORDS[@]} )) && [[ "${WORDS[i]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do
+    if ! validate_leading_assignment "${WORDS[i]}"; then
+      return 1
+    fi
+    saw_assignment=1
+    ((i += 1))
+  done
+
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied an assignment-only shell segment."
+    return 1
+  fi
+
+  command_name="${WORDS[i]}"
+  if [[ "$command_name" == \$* ]]; then
+    deny_segment "Read-only Bash guard denied an indirect command name."
+    return 1
+  fi
+
+  base="${command_name##*/}"
+  base="${base,,}"
+  if [ -z "$base" ]; then
+    deny_segment "Read-only Bash guard denied an empty command name."
+    return 1
+  fi
+
+  case "$base" in
+    bash|sh|zsh|dash|env|python*|node|ruby|perl|php|awk|eval|exec|source|.)
+      deny_segment "Read-only Bash guard denied a nested shell, interpreter, or shell re-entry command."
+      return 1
+      ;;
+  esac
+
+  if (( saw_assignment )) && [[ "$command_name" == *'$'* ]]; then
+    deny_segment "Read-only Bash guard denied assignment-based command indirection."
+    return 1
+  fi
+
+  case "$base" in
+    git)
+      validate_git "$((i + 1))"
+      return $?
+      ;;
+    find)
+      validate_find "$((i + 1))"
+      return $?
+      ;;
+    fd)
+      validate_fd "$((i + 1))"
+      return $?
+      ;;
+    rg)
+      validate_rg "$((i + 1))"
+      return $?
+      ;;
+    sort)
+      validate_sort "$((i + 1))"
+      return $?
+      ;;
+    uniq)
+      validate_uniq "$((i + 1))"
+      return $?
+      ;;
+    yq)
+      validate_yq "$((i + 1))"
+      return $?
+      ;;
+    grep|cat|ls|head|tail|wc|pwd|jq|nl|cut)
+      return 0
+      ;;
+    bun)
+      validate_bun "$((i + 1))"
+      return $?
+      ;;
+    agent-relay)
+      validate_agent_relay "$((i + 1))"
+      return $?
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a command outside the read-only allow-list."
+      return 1
+      ;;
+  esac
+}
+
+if reason="$(hard_deny_reason "$command_text")"; then
+  emit_deny "$reason"
+  exit 0
+fi
+
+if ! split_segments "$command_text"; then
+  emit_deny "Read-only Bash guard denied shell syntax it could not parse."
+  exit 0
+fi
+
+for segment in "${SEGMENTS[@]}"; do
+  if ! validate_segment "$segment"; then
+    emit_deny "${DENY_REASON:-Read-only Claude sessions may only run explicit inspection commands.}"
+    exit 0
+  fi
+done
+
+exit 0

package/src/adapters/claude-transcript.ts

@@ -126,6 +126,50 @@ export function extractLastAssistantTurn(jsonl: string): string {
   return collected.join("\n\n").trim();
 }
 
+/**
+ * Like extractLastAssistantTurn but skips the first `afterEntry` valid JSON entries.
+ * Used when a partial transcript flush already emitted entries 1..afterEntry so the
+ * Stop-hook full-mode capture doesn't re-emit the already-published text.
+ */
+export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: number): string {
+  const lines = jsonl.split("\n");
+  const collected: string[] = [];
+  let entryIndex = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    entryIndex++;
+    if (isSidechainEntry(entry)) continue;
+    if (isRealUserPrompt(entry)) {
+      collected.length = 0;
+      continue;
+    }
+    if (entryIndex <= afterEntry) continue;
+    const text = assistantText(entry);
+    if (text) collected.push(text);
+  }
+  return collected.join("\n\n").trim();
+}
+
+/**
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
 /**
  * Returns only the text from the LAST assistant entry in the current turn.
  * Unlike extractLastAssistantTurn which collects all intermediate text between

package/src/adapters/claude.ts

@@ -450,25 +450,21 @@ export function sessionStatusLineSettingsArgs(...argLists: string[][]): string[]
 }
 
 export function claudeLaunchArgs(defaultArgs: string[], providerArgs: string[], approvalMode?: string): string[] {
+  const stripToolArgs = approvalMode === "read-only";
   return [
-    ...stripClaudePermissionArgs(defaultArgs),
-    ...stripClaudePermissionArgs(providerArgs),
+    ...stripClaudePermissionArgs(defaultArgs, stripToolArgs),
+    ...stripClaudePermissionArgs(providerArgs, stripToolArgs),
     ...claudePermissionModeArgs(approvalMode),
   ];
 }
 
 export function claudePermissionModeArgs(approvalMode?: string): string[] {
   if (approvalMode === "open") return ["--dangerously-skip-permissions"];
-  if (approvalMode === "read-only") return [
-    "--permission-mode",
-    "dontAsk",
-    "--allowedTools",
-    "Read,Grep,Glob,LS,Bash(agent-relay *)",
-  ];
+  if (approvalMode === "read-only") return ["--permission-mode", "dontAsk", "--tools", "Read,Grep,Glob,LS,Bash"];
   return ["--permission-mode", "default"];
 }
 
-function stripClaudePermissionArgs(args: string[]): string[] {
+function stripClaudePermissionArgs(args: string[], stripToolArgs = false): string[] {
   const result: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -484,6 +480,10 @@ function stripClaudePermissionArgs(args: string[]): string[] {
       i++;
       continue;
     }
+    if (stripToolArgs && /^--(?:tools|allowedTools|allowed-tools|disallowedTools|disallowed-tools)(?:=|$)/.test(arg)) {
+      if (!arg.includes("=")) i++;
+      continue;
+    }
     result.push(arg);
   }
   return result;

package/src/control-server.ts

@@ -36,7 +36,9 @@ interface ControlServerOptions {
   // Phase 1 live-session lane: a provider Stop hook hands over its transcript
   // 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>;
+  // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
+  // un-mirrored narrative before the interactive form appears in chat (#435).
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void>;
   // 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.
@@ -221,6 +223,14 @@ async function handlePermissionRequest(
 ): Promise<Response> {
   const body = await req.json().catch(() => null);
   if (!isRecord(body)) return Response.json({});
+  // #435: flush any un-mirrored narrative from the transcript before the form
+  // appears in chat — the transcript already has the assistant text block at
+  // PreToolUse time, but the Stop hook (which normally captures it) won't fire
+  // until after the user answers, so the form would otherwise arrive first.
+  const transcriptPath = typeof body.transcript_path === "string" ? body.transcript_path : "";
+  if (transcriptPath && options.onSessionTurn) {
+    await options.onSessionTurn({ transcriptPath, isPreFlush: true }).catch(() => {});
+  }
   const approvalId = crypto.randomUUID();
   const view = claudePermissionApprovalView(approvalId, body);
   options.onStatus({

package/src/runner.ts

@@ -13,7 +13,7 @@ import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { computeContextRatio } from "./session-insights";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
@@ -254,6 +254,10 @@ export class AgentRunner {
   // its final response. Set when a provider-turn starts, cleared when it ends.
   private currentTurnId?: string;
   private currentTurnStartedAt?: number;
+  // #435: high-water-mark for the pre-turn narrative flush. Counts how many
+  // valid JSONL entries were in the transcript at last pre-flush time so the
+  // Stop-hook capture (full mode) can skip what was already emitted.
+  private narrativeFlushEntryCount = 0;
   // True while a turn that was already in flight is being compacted. Claude's PostCompact
   // hook posts a single `idle`, but a mid-turn compaction RESUMES the turn afterward — so
   // treating that idle as a turn end (flip idle, kill the reasoning tail) makes chat go dark
@@ -1283,8 +1287,33 @@ export class AgentRunner {
   // 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> {
+  //
+  // isPreFlush: true (#435) — mid-turn call from a PreToolUse hook (AskUserQuestion /
+  // ExitPlanMode / permission). Emits any un-mirrored narrative from the transcript
+  // tail immediately, before the interactive form appears in chat, then updates the
+  // entry-count cursor so the eventual Stop-hook call (full mode) skips it.
+  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
+
+    if (input.isPreFlush) {
+      if (!input.transcriptPath) return;
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { return; }
+      if (!jsonl) return;
+      const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
+      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
+      if (!body) return;
+      const turnId = this.currentTurnId;
+      this.sessionLog(`pre-flush narrative for turn ${turnId ?? "?"} (${body.length} chars)`);
+      await this.publishSessionEvent({
+        from: this.agentId,
+        to: "user",
+        body,
+        session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
+      });
+      return;
+    }
+
     const turnId = this.currentTurnId;
     this.stopReasoningTail();
     // Optional correlation for threading + obligation clearing — never a capture gate.
@@ -1300,6 +1329,12 @@ export class AgentRunner {
       replyToMessageId = obligation?.messageId;
     }
 
+    // Grab and reset the pre-flush cursor before extraction: the cursor may be
+    // non-zero when a PreToolUse hook flushed narrative earlier this turn (#435).
+    // In "full" mode, skip those already-emitted entries so they don't duplicate.
+    const flushCount = this.narrativeFlushEntryCount;
+    this.narrativeFlushEntryCount = 0;
+
     // The Stop hook can fire before the final assistant entry is flushed to disk.
     // Claude writes thinking and text as separate entries (both with end_turn), so
     // the transcript can "look complete" while the text entry is still pending.
@@ -1314,7 +1349,11 @@ export class AgentRunner {
           try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { break; }
         }
         if (!transcriptLooksComplete(jsonl)) continue;
-        const extract = this.options.providerConfig.chatCaptureMode === "full" ? extractLastAssistantTurn : extractFinalAssistantMessage;
+        // Full mode: if a pre-flush already emitted entries 1..flushCount, only
+        // collect text from entries after that mark to avoid double-emit (#435).
+        const extract = this.options.providerConfig.chatCaptureMode === "full"
+          ? (j: string) => (flushCount > 0 ? extractLastAssistantTurnAfterEntry(j, flushCount) : extractLastAssistantTurn(j))
+          : extractFinalAssistantMessage;
         body = extract(jsonl);
         if (body) break;
       }
@@ -2466,6 +2505,7 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextState?: Cont
   const model = options.model ?? probeModel?.model;
   const effort = options.effort ?? probeModel?.effort;
   const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
+  const shellMode = runtimeShellMode(options);
   return {
     lifecycle: {
       managed: true,
@@ -2487,7 +2527,8 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextState?: Cont
       approvalMode: options.approvalMode,
       fileRead: true,
       fileWrite: options.approvalMode !== "read-only",
-      shell: options.approvalMode !== "read-only",
+      shell: shellMode !== "none",
+      shellMode,
       source: "runtime",
       confidence: "reported",
       lastUpdatedAt: options.startedAt,
@@ -2511,6 +2552,13 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextState?: Cont
   };
 }
 
+function runtimeShellMode(options: RunnerOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
+  if (options.approvalMode === "read-only") {
+    return options.provider === "claude" ? "read-only-guarded" : "none";
+  }
+  return options.approvalMode === "open" ? "unrestricted" : "guarded";
+}
+
 function runtimeProviderTerminalCapabilities(options: RunnerOptions): Pick<ProviderCapabilities, "terminal"> {
   if (options.provider === "claude" && options.headless) {
     return {