@humwick/runner 0.0.0-stage → 0.130.0

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

@@ -0,0 +1,373 @@
+#!/usr/bin/env bash
+
+# POST a JSON body over stdin. A curl argv argument is capped by the kernel (~128 KiB), and a
+# prompt or assistant message can exceed it; curl then never starts and the report is lost (#2664).
+relay_post_json() {
+  local port="$1" path="$2" max_time="${3:-}"
+  curl -fsS ${max_time:+--max-time "$max_time"} -X POST "http://127.0.0.1:${port}${path}" \
+    -H 'Content-Type: application/json' --data-binary @-
+}
+
+relay_post_status() {
+  local status="${1:-}"
+  local reason="${2:-}"
+  local id="${3:-}"
+  local label="${4:-}"
+  local role="${5:-}"
+  local parent_id="${6:-}"
+  local clear_kind="${7:-}"
+  local timeline_status="${8:-}"
+  # Raw JSON object (e.g. '{"backgroundTasks":[...]}'), not a string field — the caller is
+  # responsible for producing valid JSON (see relay_background_task_metadata). Empty/unset
+  # omits the field entirely so ordinary status posts are unaffected.
+  local metadata_json="${9:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  [ -z "$status" ] && return 0
+  local body="{\"status\":\"$(relay_json_escape "$status")\""
+  [ -n "${AGENT_RELAY_PROVIDER_SESSION_ID:-}" ] && body="${body},\"providerSessionId\":\"$(relay_json_escape "$AGENT_RELAY_PROVIDER_SESSION_ID")\""
+  [ -n "$reason" ] && body="${body},\"reason\":\"$(relay_json_escape "$reason")\""
+  [ -n "$clear_kind" ] && body="${body},\"clear\":[\"$(relay_json_escape "$clear_kind")\"]"
+  [ -n "$timeline_status" ] && body="${body},\"timeline\":{\"status\":\"$(relay_json_escape "$timeline_status")\"}"
+  [ -n "$id" ] && body="${body},\"id\":\"$(relay_json_escape "$id")\""
+  [ -n "$label" ] && body="${body},\"label\":\"$(relay_json_escape "$label")\""
+  [ -n "$role" ] && body="${body},\"role\":\"$(relay_json_escape "$role")\""
+  [ -n "$parent_id" ] && body="${body},\"parentId\":\"$(relay_json_escape "$parent_id")\""
+  [ -n "$metadata_json" ] && body="${body},\"metadata\":${metadata_json}"
+  body="${body}}"
+  printf '%s' "$body" | relay_post_json "$port" /status >/dev/null || true
+}
+
+relay_post_status_clearing_subagents() {
+  relay_post_status "$1" "${2:-}" "${3:-}" "${4:-}" "${5:-}" "${6:-}" subagent
+}
+
+# #502/#539: count user background shells still running at turn end.
+# Claude's Stop payload carries a `background_tasks` array (CC v2.1.157+) listing
+# shells launched with run_in_background that have not yet finished. It can also
+# include the long-lived Humwick monitor; that monitor is notification
+# plumbing, not agent work, so exclude it before driving `background-script`
+# busy state. Older Claude builds omit the field → count 0 → graceful no-op.
+relay_background_task_count() {
+  local input="${1:-}"
+  [ -z "$input" ] && { printf '0'; return 0; }
+  if command -v jq >/dev/null 2>&1; then
+    local n
+    n="$(printf '%s' "$input" | jq -r '
+      (.background_tasks // [])
+      | map(select(
+          (.name // "") != "agent-relay-runner-monitor"
+          and ((.command // "") | contains("relay-monitor.ts") | not)
+          and ((.command // "") | contains("agent-relay-runner-monitor") | not)
+        ))
+      | length
+    ' 2>/dev/null)"
+    case "$n" in ''|*[!0-9]*) printf '0' ;; *) printf '%s' "$n" ;; esac
+    return 0
+  fi
+  # jq-less fallback: avoid a false busy for the common "only relay monitor" case.
+  local compact
+  compact="$(printf '%s' "$input" | tr -d '[:space:]')"
+  if printf '%s' "$compact" | grep -q '"background_tasks":\[{'; then
+    if printf '%s' "$compact" | grep -qE '("name":"agent-relay-runner-monitor"|relay-monitor\.ts)' \
+      && ! printf '%s' "$compact" | grep -q '},{'; then
+      printf '0'
+      return 0
+    fi
+    printf '1'
+  else
+    printf '0'
+  fi
+}
+
+# #2034 (#2031 L3): cap on the per-task detail list — bounds task count and per-command
+# length so a pathological Stop payload (a runaway number of concurrent background shells,
+# or an absurdly long command string) can never bloat the persisted work record.
+# relay_background_task_count above (the busy/label signal) stays uncapped; only this
+# richer detail list is bounded.
+RELAY_BACKGROUND_TASK_LIST_MAX=20
+RELAY_BACKGROUND_TASK_COMMAND_MAX=200
+
+# #2034 (#2031 L3): shape Claude's Stop-payload background_tasks[] into the compact
+# {id, command} detail list the runner keeps as the background-script work record's
+# `metadata.backgroundTasks` — the per-task identity a watchdog can name directly instead
+# of just a count. The runner (not this hook) stamps startedAt: each hook invocation is a
+# fresh process with no memory of when a task first appeared, so age tracking has to live
+# in the long-lived runner process, keyed by task id across turns.
+# Same monitor-exclusion as relay_background_task_count above — must stay in sync.
+# No jq -> "[]" (graceful degradation; the coarse count/busy path above is unaffected).
+relay_background_task_list() {
+  local input="${1:-}"
+  [ -z "$input" ] && { printf '[]'; return 0; }
+  command -v jq >/dev/null 2>&1 || { printf '[]'; return 0; }
+  printf '%s' "$input" | jq -c \
+    --argjson max "$RELAY_BACKGROUND_TASK_LIST_MAX" \
+    --argjson cmdmax "$RELAY_BACKGROUND_TASK_COMMAND_MAX" '
+    (.background_tasks // [])
+    | map(select(
+        (.name // "") != "agent-relay-runner-monitor"
+        and ((.command // "") | contains("relay-monitor.ts") | not)
+        and ((.command // "") | contains("agent-relay-runner-monitor") | not)
+      ))
+    | map({
+        id: ((.id // "") | tostring),
+        command: ((.command // "") | if length > $cmdmax then .[0:$cmdmax] + "…" else . end)
+      })
+    | map(select(.id != ""))
+    | .[0:$max]
+  ' 2>/dev/null || printf '[]'
+}
+
+# Wrap a capped task list into the `metadata` object relay_post_status expects, or print
+# nothing when there is nothing to report (no task list, empty list, or jq-less host) so an
+# ordinary background-script status post is byte-for-byte what it was before #2034.
+relay_background_task_metadata() {
+  local list_json="${1:-}"
+  case "$list_json" in
+    ''|'[]') printf '' ;;
+    *) printf '{"backgroundTasks":%s}' "$list_json" ;;
+  esac
+}
+
+# #502: end the provider turn (idle) clearing any stale subagent work — the
+# critical path (#199) — then report the live background-script snapshot so an
+# agent whose turn ended while a `run_in_background` shell keeps running stays
+# busy instead of falsely reading idle. A single full-snapshot post per turn-end:
+# >0 → busy(background-script); 0 → idle(background-script) which clears any prior.
+relay_post_turn_end_status() {
+  local bg_count="${1:-0}"
+  # #2034: the capped {id, command} detail list (see relay_background_task_list) — only
+  # relevant on the busy branch; a bg_count of 0 always resolves to idle regardless.
+  local bg_tasks_json="${2:-[]}"
+  local bg_metadata
+  bg_metadata="$(relay_background_task_metadata "$bg_tasks_json")"
+  relay_post_status_clearing_subagents idle
+  case "$bg_count" in
+    ''|0|*[!0-9]*) relay_post_status idle background-script background-tasks ;;
+    1) relay_post_status busy background-script background-tasks "1 background task" "" "" "" "" "$bg_metadata" ;;
+    *) relay_post_status busy background-script background-tasks "${bg_count} background tasks" "" "" "" "" "$bg_metadata" ;;
+  esac
+}
+
+# Report a provider usage/rate-limit hold to the runner (#286). The runner turns
+# this into a `providerState: blocked` (reason rate_limit), posts a chat notice,
+# and auto-resumes the agent once the window resets. reset_time (unix seconds,
+# only "if available" per CC StopFailure docs) drives the resume; the runner falls
+# back to a poll window when it is absent. Fire-and-forget like the other reports.
+relay_post_rate_limit() {
+  local error_type="${1:-}"
+  local reset_time="${2:-}"
+  local error_message="${3:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local body="{\"errorType\":\"$(relay_json_escape "$error_type")\""
+  case "$reset_time" in ''|*[!0-9]*) ;; *) body="${body},\"resetTime\":${reset_time}" ;; esac
+  [ -n "$error_message" ] && body="${body},\"errorMessage\":\"$(relay_json_escape "$error_message")\""
+  body="${body}}"
+  printf '%s' "$body" | relay_post_json "$port" /rate-limit >/dev/null 2>&1 || true
+}
+
+relay_post_timeline_status() {
+  relay_post_status "$1" "${2:-provider-turn}" "" "" "" "" "${3:-}" "$4"
+}
+
+relay_post_session_turn() {
+  # Phase 1 live-session lane: hand the transcript path to the runner so it can
+  # capture the assistant turn for the dashboard chat. Synchronous on purpose —
+  # the captured turn clears the reply obligation before the stop decision check
+  # below, so the agent is not nagged to /reply (and does not re-emit).
+  local transcript_path="${1:-}"
+  local last_assistant_message="${2:-}"
+  local prompt_id="${3:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  # transcript_path is the primary capture source, but the Stop payload can omit it
+  # (known CC edge case). last_assistant_message is the fallback for exactly that —
+  # POST with whichever we have; only bail when both are missing.
+  [ -z "$transcript_path" ] && [ -z "$last_assistant_message" ] && return 0
+  local body="{"
+  [ -n "$transcript_path" ] && body="${body}\"transcriptPath\":\"$(relay_json_escape "$transcript_path")\""
+  if [ -n "$last_assistant_message" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"lastAssistantMessage\":${last_assistant_message}"
+  fi
+  # prompt_id (#1086): Claude's native turn identifier — the stable id the runner
+  # uses instead of a minted random UUID, and the deterministic key it slices the
+  # transcript by for full-mode enrichment.
+  if [ -n "$prompt_id" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"promptId\":\"$(relay_json_escape "$prompt_id")\""
+  fi
+  body="${body}}"
+  printf '%s' "$body" | relay_post_json "$port" /session-turn >/dev/null 2>&1 || true
+}
+
+# Forward a hook's raw stdin JSON unchanged, stamped with when the hook ran (#2664). No jq: a
+# missing jq must not silence the prompt hook the runner confirms submits by.
+relay_forward_hook_payload() {
+  local path="${1:-}" payload="${2:-}" fired_at="${3:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  case "$fired_at" in ''|*[!0-9]*) fired_at="" ;; esac
+  printf '%s' "$payload" | relay_post_json "$port" "${path}${fired_at:+?firedAt=${fired_at}}" 3 >/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, and uses the stamp as submit evidence.
+  # Fire-and-forget; never blocks or fails the turn.
+  [ -z "${1:-}" ] && return 0
+  relay_forward_hook_payload /user-prompt "$1" "${2:-}"
+}
+
+relay_post_session_boundary() {
+  # Pre-destroy seam (#183): tell the runner a context reset or termination is imminent
+  # (compact/clear/logout/…) so it can run end-of-session work — the #184 context-gathering
+  # ratio capture — from the full transcript before the invasive op. Fire-and-forget; the
+  # transcript path is optional (the runner falls back to the last path it saw).
+  local transcript_path="${1:-}"
+  local reason="${2:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local body="{"
+  [ -n "$transcript_path" ] && body="${body}\"transcriptPath\":\"$(relay_json_escape "$transcript_path")\""
+  if [ -n "$reason" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"reason\":\"$(relay_json_escape "$reason")\""
+  fi
+  body="${body}}"
+  printf '%s' "$body" | relay_post_json "$port" /session-boundary 3 >/dev/null 2>&1 || true
+}
+
+# --- Hook FATAL surfacing (#198) -------------------------------------------
+# A hook that dies unexpectedly must never be silent. relay_install_hook_guard
+# arms an ERR trap that reports the failure FATAL to the runner control port,
+# which logs it to the dashboard-surfaced per-agent log. Best-effort and bounded
+# (--max-time 2) so the report itself can never blow the hook's timeout budget.
+relay_hook_fatal_report() {
+  local hook="${1:-unknown}" detail="${2:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local body="{\"hook\":\"$(relay_json_escape "$hook")\",\"error\":\"$(relay_json_escape "$detail")\"}"
+  printf '%s' "$body" | relay_post_json "$port" /hook-fatal 2 >/dev/null 2>&1 || true
+}
+
+relay_install_hook_guard() {
+  RELAY_HOOK_NAME="${1:-unknown}"
+  # The pipe adapter owns native turn boundaries and final-result reporting.
+  # Permission and safety hooks still run; TUI lifecycle hooks must not compete.
+  if [ "${AGENT_RELAY_CLAUDE_TRANSPORT:-}" = "stream-json" ]; then
+    case "$RELAY_HOOK_NAME" in
+      user-prompt-submit|stop|stop-failure|session-end|pre-compact|post-compact|subagent-start|subagent-stop) exit 0 ;;
+    esac
+  fi
+  # Fires on any unhandled failure under `set -e`/`set -u`/pipefail in the hook's
+  # main body, just before the shell exits. Reports, then lets the exit proceed.
+  # (ERR is not inherited into functions without `set -E`; this covers the top-level
+  # flow, which is where a silent death actually wedges a turn.)
+  trap 'relay_hook_err_rc=$?; relay_hook_fatal_report "${RELAY_HOOK_NAME:-unknown}" "exit ${relay_hook_err_rc}: ${BASH_COMMAND}"' ERR
+}
+
+relay_pending_reply_stop_decision() {
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local response
+  # --max-time guards the Claude Stop hook's 5s budget: a slow runner/server (e.g. an
+  # un-indexed obligation query) must never block past the timeout, or Claude SIGKILLs
+  # the hook before it clears the turn -> stuck "busy" (#199). On timeout: no block.
+  response="$(curl -fsS --max-time 2 "http://127.0.0.1:${port}/reply-obligations/claude-stop" 2>/dev/null || true)"
+  case "$response" in
+    *'"decision":"block"'*|*'"decision": "block"'*) ;;
+    *) return 0 ;;
+  esac
+  printf '%s' "$response"
+}
+
+relay_json_string_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' | head -1
+}
+
+relay_json_number_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' | head -1
+}
+
+relay_json_bool_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*(true|false).*/\1/p' | head -1
+}
+
+# Wall-clock epoch milliseconds, or nothing when no source can tell (never whole seconds).
+relay_now_ms() {
+  local ms=""
+  if [ -n "${EPOCHREALTIME:-}" ]; then
+    local t="${EPOCHREALTIME/,/.}"
+    local frac="${t#*.}000"
+    ms="${t%.*}${frac:0:3}"
+  fi
+  case "$ms" in [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]) ;; *) ms="$(date +%s%3N 2>/dev/null || true)" ;; esac
+  case "$ms" in [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]) ;; *) ms="$(perl -MTime::HiRes=time -e 'printf "%d", time() * 1000' 2>/dev/null || true)" ;; esac
+  case "$ms" in [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]) printf '%s' "$ms" ;; esac
+}
+
+relay_json_escape() {
+  local text="${1:-}" code octal char escaped
+  text="${text//\\/\\\\}"
+  text="${text//\"/\\\"}"
+  # Bash strings cannot hold NUL. Escape every other JSON control byte, with no subprocesses.
+  for ((code = 1; code < 32; code++)); do
+    printf -v octal '%03o' "$code"
+    printf -v char '%b' "\\$octal"
+    printf -v escaped '\\u%04x' "$code"
+    text="${text//"$char"/$escaped}"
+  done
+  printf '%s' "$text"
+}
+
+# Print a short "request-review when done" reminder to stdout IFF this agent owns
+# an isolated workspace whose branch has committed work not yet integrated into
+# base. Prints nothing otherwise — so plain chat, shared-mode, and no-change
+# sessions never pay context/token cost. Reads the workspace from
+# AGENT_RELAY_WORKSPACE_JSON (set by the orchestrator at spawn) and does a local,
+# network-free git count. Always returns 0 (never aborts its caller).
+relay_review_reminder_text() {
+  local ws="${AGENT_RELAY_WORKSPACE_JSON:-}"
+  [ -z "$ws" ] && return 0
+  local mode worktree base id branch ahead
+  mode="$(relay_json_string_field mode "$ws")"
+  [ "$mode" = "isolated" ] || return 0
+  worktree="$(relay_json_string_field worktreePath "$ws")"
+  base="$(relay_json_string_field baseSha "$ws")"
+  [ -z "$base" ] && base="$(relay_json_string_field baseRef "$ws")"
+  id="$(relay_json_string_field id "$ws")"
+  branch="$(relay_json_string_field branch "$ws")"
+  [ -n "$worktree" ] || return 0
+  [ -n "$base" ] || return 0
+  [ -n "$id" ] || return 0
+  ahead="$(git -C "$worktree" rev-list --count "${base}..HEAD" 2>/dev/null || echo 0)"
+  case "$ahead" in ''|*[!0-9]*) ahead=0 ;; esac
+  [ "$ahead" -gt 0 ] || return 0
+  printf '[agent-relay] You have %s committed change(s) on `%s` that are not yet integrated into base. If your task is complete, request review so Humwick can auto-land it: POST /api/workspaces/%s/actions with {"action":"request-review"}. If you are still working, ignore this — it only appears while there is unmerged committed work.' \
+    "$ahead" "${branch:-this branch}" "$id"
+  return 0
+}
+
+# Wrap reminder text in the Claude Code additionalContext envelope for a given
+# hook event. Emits nothing when the text is empty.
+relay_emit_additional_context() {
+  local event="${1:-}" text="${2:-}"
+  [ -z "$event" ] && return 0
+  [ -z "$text" ] && return 0
+  printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}' \
+    "$event" "$(relay_json_escape "$text")"
+  return 0
+}

package/plugins/claude/hooks/session-end.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard session-end
+
+payload="$(cat || true)"
+reason="$(relay_json_string_field reason "$payload")"
+transcript_path="$(relay_json_string_field transcript_path "$payload")"
+
+case "$reason" in
+  clear)
+    relay_post_timeline_status idle provider-turn subagent clearing-context
+    # /clear wipes the context — the most common work boundary for a long-lived agent.
+    # Capture this segment's Insights (#183/#184) before it's gone.
+    relay_post_session_boundary "$transcript_path" clear
+    ;;
+  resume)
+    relay_post_status_clearing_subagents idle
+    ;;
+  logout|prompt_input_exit|bypass_permissions_disabled|other|*)
+    relay_post_status_clearing_subagents offline
+    # Real session termination: capture end-of-session Insights (#183/#184). Order after the
+    # status post is arbitrary — the runner reads the transcript file regardless.
+    relay_post_session_boundary "$transcript_path" "$reason"
+    ;;
+esac

package/plugins/claude/hooks/session-start.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard session-start
+# #2664 — a stamped check-in proves the hook path works before the first prompt is submitted.
+relay_forward_hook_payload /hook-check "{}" "$(relay_now_ms)"
+
+payload="$(cat || true)"
+source_kind="$(relay_json_string_field source "$payload")"
+continuation=""
+
+case "$source_kind" in
+  clear)
+    # A queued /clear can commit after the runner's confirmation timed out. Restore
+    # its continuation in THIS fresh context, even if the backstop hit the old one.
+    if [ -n "${AGENT_RELAY_RUNNER_PORT:-}" ]; then
+      continuation="$(printf '{"source":"clear","providerSessionId":"%s"}' "$(relay_json_escape "${AGENT_RELAY_PROVIDER_SESSION_ID:-}")" | relay_post_json "$AGENT_RELAY_RUNNER_PORT" /session-start 3 || true)"
+    fi
+    relay_post_timeline_status idle provider-turn subagent context-cleared
+    ;;
+  *)
+    ;;
+esac
+
+# Re-prime the request-review reminder when a session (re)starts — crucially on
+# source=="compact", which is how it survives a context compaction (PreCompact
+# cannot inject post-compact context; SessionStart can). No-op on a fresh startup
+# with no committed work, and silent for non-isolated/no-change sessions.
+reminder="$(relay_review_reminder_text || true)"
+if [ -n "$continuation" ]; then reminder="${reminder:0:1000}"; fi
+relay_emit_additional_context SessionStart "${continuation}${continuation:+${reminder:+$'\n\n'}}${reminder}"

package/plugins/claude/hooks/shell-trust.ts

@@ -0,0 +1,28 @@
+// Shared "is this plain simple commands?" pre-filter for the PreToolUse guards (#2834, #2993).
+// Heredocs, comments, functions, control-flow keywords, continuations, substitutions and
+// per-line unbalanced quotes (a string spanning lines) all mean "unsure": the caller allows.
+// `do`/`done` are deliberately not keywords here: they never appear without a header keyword
+// (`for`/`while`/`until`/`select`), and `echo done` tripped the filter.
+const SYNTAX = String.raw`<<|\\$|(^|\s)#|\$\(|` + "`" + String.raw`|\(\)|^\s*[{}]|\{\s*$`;
+export const CONTROL_KEYWORDS = ["if", "then", "elif", "else", "fi", "for", "while", "until", "case", "esac", "select", "function"] as const;
+
+const patterns = new Map<string, RegExp>();
+function unsurePattern(keywords: readonly string[]): RegExp {
+  const key = keywords.join("|");
+  let pattern = patterns.get(key);
+  if (!pattern) {
+    pattern = new RegExp(`${SYNTAX}|(^|[\\s;&|(])(${key})\\b`, "m");
+    patterns.set(key, pattern);
+  }
+  return pattern;
+}
+const countOf = (line: string, char: string): number => line.split(char).length - 1;
+
+/** `;`-joined non-blank lines, or null when the text is not plainly simple commands. `keywords` are the control
+ *  words that mean "unsure"; a caller that parses a construct itself (a `while` loop) drops it from the list. */
+export function trustedFlatCommand(command: string, keywords: readonly string[] = CONTROL_KEYWORDS): string | null {
+  if (unsurePattern(keywords).test(command)) return null;
+  const lines = command.split(/\r?\n/);
+  if (lines.some((line) => countOf(line, "'") % 2 === 1 || countOf(line, '"') % 2 === 1)) return null;
+  return lines.filter((line) => line.trim()).join("; ");
+}

package/plugins/claude/hooks/stop-failure.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard stop-failure
+
+payload="$(cat || true)"
+# CC sends the error class as `error_type` (StopFailure docs, verified 2026-06);
+# fall back to legacy `error` so older payloads / tests still match.
+error="$(relay_json_string_field error_type "$payload")"
+[ -z "$error" ] && error="$(relay_json_string_field error "$payload")"
+reset_time="$(relay_json_number_field reset_time "$payload")"
+error_message="$(relay_json_string_field error_message "$payload")"
+[ -z "$error_message" ] && error_message="$(relay_json_string_field error_details "$payload")"
+[ -z "$error_message" ] && error_message="$(relay_json_string_field last_assistant_message "$payload")"
+
+# #286: a usage/rate-limit stall is transient and time-bounded — hold the agent
+# (providerState blocked) and auto-resume at reset, instead of silently going idle.
+# The disambiguator for billing_error is reset_time: a subscription rolling-window
+# limit carries one (and is auto-resumable); true credit exhaustion does not (fatal).
+# #3577: a refused proxy credential (ERR_PROXY_TUNNEL) also posts here; the runner classifies it.
+case "$error" in
+  rate_limit|overloaded|server_error|api_error)
+    relay_post_rate_limit "$error" "$reset_time" "$error_message"
+    ;;
+  unknown)
+    case "$error_message" in
+      *"529"*|*"Overloaded"*|*"overloaded"*|*"temporar"*|*"server-side"*|*"server error"*|*"ERR_PROXY_TUNNEL"*)
+        relay_post_rate_limit "$error" "$reset_time" "$error_message"
+        ;;
+      *)
+        relay_post_status_clearing_subagents idle
+        ;;
+    esac
+    ;;
+  billing_error)
+    case "$reset_time" in
+      ''|*[!0-9]*) relay_post_status_clearing_subagents error ;;
+      *) relay_post_rate_limit "$error" "$reset_time" "$error_message" ;;
+    esac
+    ;;
+  authentication_failed|oauth_org_not_allowed|model_not_found)
+    relay_post_status_clearing_subagents error
+    ;;
+  *)
+    relay_post_status_clearing_subagents idle
+    ;;
+esac

package/plugins/claude/hooks/stop.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard stop
+
+# Clearing the turn's busy state is the critical path (#199). Register it on EXIT
+# so it runs even if a side-call below fails or times out under `set -e`. The one
+# exception is the reply-obligation block path, which deliberately keeps the agent
+# busy to answer — it opts out via the flag before exiting.
+_relay_clear_idle_on_exit=1
+# bg_count/bg_tasks_json are read from the payload below and consumed by the trap at exit
+# time (#502): the turn-end status carries the live background-script snapshot so an agent
+# whose turn ended while a run_in_background shell keeps running stays busy instead of
+# falsely reading idle. bg_tasks_json (#2034) is the per-task {id, command} detail behind
+# that snapshot — the ledger the runner enriches with startedAt and a watchdog can read.
+bg_count=0
+bg_tasks_json="[]"
+trap '[ "${_relay_clear_idle_on_exit:-0}" = "1" ] && relay_post_turn_end_status "${bg_count:-0}" "${bg_tasks_json:-[]}"' EXIT
+
+payload="$(cat || true)"
+stop_hook_active="$(relay_json_bool_field stop_hook_active "$payload")"
+bg_count="$(relay_background_task_count "$payload")"
+bg_tasks_json="$(relay_background_task_list "$payload")"
+
+# Session-mirror capture is orthogonal to reply-obligation gating (#332): a recursive Stop
+# (stop_hook_active=true) must NOT suppress capturing this turn's response, or the live mirror
+# silently drops frames. Always post the turn; only the reply-obligation decision is gated below.
+last_assistant_msg="$(echo "$payload" | jq -c '.last_assistant_message // empty' 2>/dev/null || true)"
+# prompt_id (#1086): Claude's own native turn identifier, correlating this Stop with
+# the same UUID stamped on every transcript entry of the turn (and the id the
+# UserPromptSubmit hook reported at turn start) — the stable replacement for a
+# runner-minted random UUID.
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg" "$prompt_id"
+
+if [ "$stop_hook_active" != "true" ]; then
+  # `|| true`: under `set -e`, a non-zero from the obligation check must never abort
+  # the hook before the idle-clear — clearing the turn is the critical path (#199).
+  stop_decision="$(relay_pending_reply_stop_decision || true)"
+  if [ -n "$stop_decision" ]; then
+    _relay_clear_idle_on_exit=0
+    printf '%s\n' "$stop_decision"
+    exit 0
+  fi
+fi
+
+# Normal turn end → the EXIT trap posts idle (always, even on an unexpected abort above).
+exit 0

package/plugins/claude/hooks/subagent-guard.cjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+// Native model forcing exempts forks; resolve skills at execution, after lazy discovery.
+const fs = require('node:fs');
+(async () => {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const input = payload.tool_input || {};
+  const event = payload.hook_event_name;
+  let reason;
+  if (require('./subagent-skill-policy.cjs').harnessSubagentsDisabled() && ['Agent', 'Task', 'TeamCreate', 'TeamDelete', 'SendMessage'].includes(payload.tool_name)) {
+    reason = 'Harness sub-agents are disabled. Start a Relay workflow or ask your coordinator';
+  } else if (event === 'UserPromptSubmit') {
+    if (/^\s*\/(fork|subtask|remote|agents|team|teams|workflow|autocompact)(?:\s|$)/i.test(payload.prompt || '')) reason = 'native fork, remote, team and workflow commands are disabled';
+  } else if (event === 'UserPromptExpansion' || payload.tool_name === 'Skill') {
+    if (payload.expansion_type !== 'mcp_prompt') {
+      reason = await require('./subagent-skill-policy.cjs').skillDenial(payload, event === 'UserPromptExpansion' ? payload.command_name : input.skill);
+    }
+  } else if (['TeamCreate', 'TeamDelete', 'SendMessage', 'Workflow'].includes(payload.tool_name) || input.subagent_type === 'fork' || input.isolation === 'remote' || input.team_name || input.resume) {
+    reason = 'native forks, remote agents, teams, workflows and resumed children are disabled; use an ordinary Agent child or Relay spawn';
+  }
+  if (reason) {
+    reason = `Relay child policy denied execution: ${reason}. Start a Relay workflow or ask your coordinator.`;
+    console.log(JSON.stringify(event === 'PreToolUse'
+      ? { hookSpecificOutput: { hookEventName: event, permissionDecision: 'deny', permissionDecisionReason: reason } }
+      : { decision: 'block', reason }));
+  }
+})().catch((error) => { console.error(`Relay child policy cannot validate execution: ${error.message}`); process.exit(2); });