@paths.design/caws-cli 11.0.0 → 11.1.1

package/templates/hook-packs/claude-code/dispatch/post_tool_use.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 8,16
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# PostToolUse dispatcher for Claude Code hooks.
+#
+# Single entry point invoked from settings.json's PostToolUse block. Reads
+# stdin ONCE, sanitizes via lib/parse-input.sh, then invokes every
+# registered handler with HOOK_* env vars inherited and the sanitized
+# JSON piped to each handler's stdin.
+#
+# Differences from pre_tool_use.sh:
+#   - HANDLERS entries may carry a positional argument (e.g. "audit.sh
+#     tool-use"). Entries are split on whitespace and passed to the
+#     handler as argv, so existing scripts that dispatch on $1 keep
+#     working without change.
+#   - Exit 2 is a no-op for PostToolUse semantically (the tool has
+#     already run) but we still honor it to short-circuit the chain and
+#     propagate the blocker's stderr, matching the pre-tool-use
+#     contract.
+#
+# Stdout: last non-empty handler buffer wins. Most PostToolUse handlers
+# write hookSpecificOutput JSON (quality-check, validate-spec, naming,
+# doc-frontmatter). Since each of those self-filters on file type, only
+# one of them emits stdout for any given Write/Edit. If two ever collide
+# (e.g., a YAML file that happens to match both the spec validator and
+# the naming check), the later-in-HANDLERS wins. Order below is set so
+# the more informative check runs last.
+#
+# Stderr: prefixed with "[<handler>]" so the source of any message is
+# visible to the agent.
+#
+# Fail-open: parser or lib failure returns exit 0 silently.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_DIR="$(dirname "$SCRIPT_DIR")"
+
+# shellcheck source=../lib/parse-input.sh
+source "$HOOKS_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+# shellcheck source=../lib/run-handlers.sh
+source "$HOOKS_DIR/lib/run-handlers.sh" 2>/dev/null || exit 0
+
+# Registered handlers in execution order. Mirrors the pre-registry
+# settings.json groups so ordering-sensitive behavior (stdout "last
+# wins" policy, audit log ordering) is preserved.
+HANDLERS=(
+  # "quality-check.sh"
+  # "validate-spec.sh"
+  # "naming-check.sh"
+  # "doc-frontmatter-check.sh"
+  # "audit.sh tool-use"
+  # "plan-transcript-snapshot.sh"
+  "session-log.sh"
+)
+
+run_handlers "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/dispatch/pre_tool_use.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 8,11,17
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# PreToolUse dispatcher for Claude Code hooks.
+#
+# Single entry point invoked from settings.json's PreToolUse block. Reads
+# stdin ONCE, sanitizes it via lib/parse-input.sh, then invokes every
+# registered handler with HOOK_* env vars inherited and the sanitized
+# JSON piped to each handler's stdin.
+#
+# Handlers self-filter via their own matcher predicate (a case statement
+# on $HOOK_TOOL_NAME at the top of the script).
+#
+# Exit-code aggregation:
+#   - First handler exiting 2 short-circuits the remaining handlers and
+#     the dispatcher returns 2 (blocking).
+#   - Non-zero non-2 exits are warnings; the dispatcher continues and
+#     returns the max non-2 code at the end.
+#
+# Fail-open: if the dispatcher itself errors before any handler runs
+# (parser crash, missing lib), it exits 0 rather than blocking the tool.
+# Guard infrastructure must not turn its own bugs into tool-call blocks.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_DIR="$(dirname "$SCRIPT_DIR")"
+
+# shellcheck source=../lib/parse-input.sh
+source "$HOOKS_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+# shellcheck source=../lib/run-handlers.sh
+source "$HOOKS_DIR/lib/run-handlers.sh" 2>/dev/null || exit 0
+
+# Registered handlers in execution order. Each handler self-filters
+# on $HOOK_TOOL_NAME; non-matching cases return exit 0 cheaply.
+HANDLERS=(
+  block-dangerous.sh
+  worktree-guard.sh
+  scope-guard.sh
+  worktree-write-guard.sh
+)
+
+run_handlers --short-circuit-on-block "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/dispatch/session_start.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 10,11
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# SessionStart dispatcher for Claude Code hooks.
+#
+# Fires once per session. Same fan-out semantics as pre_tool_use.sh and
+# post_tool_use.sh: reads stdin once, exports HOOK_* env vars, invokes
+# each registered handler with stdin piped and stderr prefixed.
+#
+# HANDLERS entries may carry a positional argument (e.g. "audit.sh
+# session-start" -- audit.sh's event type is an argv, not a field in
+# the stdin payload). Entries are split on whitespace and passed as argv.
+#
+# SessionStart semantics: these hooks inform the agent about session
+# state (CAWS briefing, audit log bootstrap, session-log meta file).
+# None should block. Exit 2 is treated the same as exit 1 here --
+# recorded as max_exit but does not short-circuit.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_DIR="$(dirname "$SCRIPT_DIR")"
+
+# shellcheck source=../lib/parse-input.sh
+source "$HOOKS_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+# shellcheck source=../lib/run-handlers.sh
+source "$HOOKS_DIR/lib/run-handlers.sh" 2>/dev/null || exit 0
+
+HANDLERS=(
+  "audit.sh session-start"
+  # "session-caws-status.sh session-start"
+  "session-log.sh"
+)
+
+run_handlers "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/dispatch/stop.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 10
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# Stop dispatcher for Claude Code hooks.
+#
+# Fires at end of session. Same fan-out semantics as the other dispatchers.
+# Handlers here finalize session artifacts: audit log closeout, worktree
+# cleanup reminder, plan-transcript finalize, session-log handoff.
+#
+# Stop semantics: none of these handlers should block the user -- the
+# session is already ending. All non-zero exits are treated as warnings;
+# max_exit is reported but no handler short-circuits the chain.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_DIR="$(dirname "$SCRIPT_DIR")"
+
+# shellcheck source=../lib/parse-input.sh
+source "$HOOKS_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+# shellcheck source=../lib/run-handlers.sh
+source "$HOOKS_DIR/lib/run-handlers.sh" 2>/dev/null || exit 0
+
+HANDLERS=(
+  # "audit.sh stop"
+  # "stop-worktree-check.sh"
+  "plan-transcript-finalize.sh"
+  "session-log.sh"
+)
+
+run_handlers "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/guard-strikes.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 8,16
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# Shared progressive strike handling for Claude pre-write guard hooks.
+#
+# If you are reading this because a guard blocked you, do not edit this file or
+# the generated guard-strikes JSON directly to bypass enforcement. The correct
+# recovery paths are:
+#   1. Switch into the right CAWS worktree.
+#   2. Bring the target file into the active spec's scope.in (if it legitimately
+#      belongs there), then ask the user to reset your strikes by running:
+#        bash .claude/hooks/reset-strikes.sh --current
+#      or the equivalent narrower reset (see --help).
+#   3. Ask the user to resolve the conflict explicitly.
+# Never edit guard-strikes-*.json files by hand — use reset-strikes.sh so the
+# reason is logged to .claude/logs/strike-resets.log.
+
+guard_worktree_state_dir() {
+  local cwd_hint="${1:-}"
+  local project_dir="${CLAUDE_PROJECT_DIR:-.}"
+  local worktree_dir=""
+
+  if [[ -n "$cwd_hint" ]] && [[ "$cwd_hint" =~ ^(.*\/\.caws\/worktrees\/[^/]+)($|/) ]]; then
+    worktree_dir="${BASH_REMATCH[1]}"
+  fi
+
+  if [[ -z "$worktree_dir" ]] && [[ "$project_dir" =~ ^(.*\/\.caws\/worktrees\/[^/]+)($|/) ]]; then
+    worktree_dir="${BASH_REMATCH[1]}"
+  fi
+
+  if [[ -n "$worktree_dir" ]] && [[ -d "$worktree_dir" ]]; then
+    mkdir -p "$worktree_dir/tmp"
+    printf '%s\n' "$worktree_dir/tmp"
+    return 0
+  fi
+
+  return 1
+}
+
+guard_strikes_file() {
+  local project_dir="${CLAUDE_PROJECT_DIR:-.}"
+  local cwd_hint="${2:-}"
+  local log_dir="$project_dir/.claude/logs"
+  local session_id="$1"
+  local safe_session
+
+  if guard_worktree_state_dir "$cwd_hint" >/dev/null 2>&1; then
+    log_dir=$(guard_worktree_state_dir "$cwd_hint")
+  else
+    mkdir -p "$log_dir"
+  fi
+
+  safe_session=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
+  printf '%s/guard-strikes-%s.json' "$log_dir" "$safe_session"
+}
+
+guard_record_strike() {
+  local session_id="$1"
+  local guard_name="$2"
+  local cwd_hint="${3:-}"
+  local state_file
+  local current_count
+
+  state_file=$(guard_strikes_file "$session_id" "$cwd_hint")
+  if [[ ! -f "$state_file" ]]; then
+    printf '{}\n' > "$state_file"
+  fi
+
+  current_count=$(jq -r --arg guard "$guard_name" '.[$guard] // 0' "$state_file" 2>/dev/null || printf '0')
+  if [[ ! "$current_count" =~ ^[0-9]+$ ]]; then
+    current_count=0
+  fi
+
+  current_count=$((current_count + 1))
+
+  jq --arg guard "$guard_name" --argjson count "$current_count" '.[$guard] = $count' "$state_file" > "$state_file.tmp"
+  mv "$state_file.tmp" "$state_file"
+
+  printf '%s\n' "$current_count"
+}
+
+guard_emit_warning_allow() {
+  local message="$1"
+
+  jq -n --arg msg "$message" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: $msg
+    }
+  }'
+}
+
+guard_emit_permission_ask() {
+  local message="$1"
+
+  jq -n --arg msg "$message" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: $msg
+    }
+  }'
+}
+
+guard_emit_block() {
+  local message="$1"
+
+  jq -n --arg msg "$message" '{
+    decision: "block",
+    reason: $msg
+  }'
+}
+
+guard_enforce_progressive_strikes() {
+  local session_id="$1"
+  local guard_name="$2"
+  local cwd_hint="$3"
+  local first_message="$4"
+  local second_message="$5"
+  local third_message="$6"
+  local strike
+
+  strike=$(guard_record_strike "$session_id" "$guard_name" "$cwd_hint")
+
+  case "$strike" in
+    1)
+      guard_emit_warning_allow "$first_message"
+      ;;
+    2)
+      guard_emit_permission_ask "$second_message"
+      ;;
+    *)
+      guard_emit_block "$third_message"
+      ;;
+  esac
+}

package/templates/hook-packs/claude-code/lib/parse-input.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 8,16
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# Shared hook input parser for Claude Code hooks.
+#
+# Handlers source this file and call `parse_hook_input` to get HOOK_* env
+# vars populated from the tool-call payload. This replaces the per-handler
+# pattern of `INPUT=$(read_hook_input_json)` followed by 3-5 `jq` calls.
+#
+# Two invocation modes:
+#   1. Standalone handler (legacy): reads stdin via read_hook_input_json,
+#      parses, exports HOOK_*.
+#   2. Via dispatcher (planned Phase 2): HOOK_INPUT_JSON already exported
+#      by the router; parse_hook_input just re-extracts scalar fields.
+#
+# Why one shared parser: before this lib, each of 17 handlers independently
+# ran read_hook_input_json + 3-5 jq calls on the same payload. A bug in the
+# parser (like the control-char failure fixed in runtime-paths.sh) ripples
+# to every handler. One parser, one bug surface, one fix.
+#
+# Idempotent source: safe to source multiple times.
+
+if [[ -n "${_HOOK_PARSE_INPUT_LOADED:-}" ]]; then
+  return 0 2>/dev/null || exit 0
+fi
+_HOOK_PARSE_INPUT_LOADED=1
+
+_hook_lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../runtime-paths.sh
+source "$_hook_lib_dir/../runtime-paths.sh"
+
+parse_hook_input() {
+  # Fast path: the dispatcher already parsed the input and exported
+  # HOOK_* env vars to the handler's environment. Re-extracting from
+  # HOOK_INPUT_JSON would be a wasted python subprocess. HOOK_TOOL_NAME
+  # is the canonical "parse completed" marker -- after a completed parse
+  # it's always defined (possibly empty for malformed input), so the
+  # `${HOOK_TOOL_NAME+set}` test distinguishes "parser ran" from
+  # "handler invoked standalone and parser hasn't run yet".
+  if [[ -n "${HOOK_TOOL_NAME+set}" ]]; then
+    return 0
+  fi
+
+  # If HOOK_INPUT_JSON is set but HOOK_TOOL_NAME is not, a caller staged
+  # the sanitized payload but didn't run the extractor. Extract now.
+  # Otherwise (standalone handler), read stdin via the sanitizer.
+  if [[ -z "${HOOK_INPUT_JSON:-}" ]]; then
+    HOOK_INPUT_JSON="$(read_hook_input_json)"
+    export HOOK_INPUT_JSON
+  fi
+
+  # Extract all common scalar fields in ONE python call, emitting
+  # shlex-quoted bash assignments. Compared to 3-5 separate `jq` calls,
+  # this is one subprocess per handler instead of many. Values are sh-safe
+  # via shlex.quote, so `eval` is not a code-injection hazard.
+  local assignments
+  assignments=$(printf '%s' "$HOOK_INPUT_JSON" | python3 -c '
+import json
+import shlex
+import sys
+
+try:
+    data = json.loads(sys.stdin.read() or "{}")
+except Exception:
+    data = {}
+if not isinstance(data, dict):
+    data = {}
+
+tool_input = data.get("tool_input")
+if not isinstance(tool_input, dict):
+    tool_input = {}
+
+tool_response = data.get("tool_response")
+if not isinstance(tool_response, dict):
+    tool_response = {}
+
+fields = {
+    "HOOK_TOOL_NAME": data.get("tool_name") or "",
+    "HOOK_FILE_PATH": tool_input.get("file_path") or "",
+    "HOOK_COMMAND": tool_input.get("command") or "",
+    "HOOK_CWD": data.get("cwd") or "",
+    "HOOK_SESSION_ID": data.get("session_id") or "unknown",
+    "HOOK_TRANSCRIPT_PATH": data.get("transcript_path") or "",
+    "HOOK_EVENT_NAME": data.get("hook_event_name") or "",
+    "HOOK_MODEL": data.get("model") or "",
+    "HOOK_SOURCE": data.get("source") or "",
+    "HOOK_PERMISSION_MODE": data.get("permission_mode") or "default",
+    "HOOK_TOOL_USE_ID": data.get("tool_use_id") or "",
+    "HOOK_STOP_HOOK_ACTIVE": "1" if data.get("stop_hook_active") else "0",
+    # Whole objects as JSON strings -- consumed by audit.sh for log payloads.
+    # Always valid JSON ("{}" at minimum) so `jq --argjson` works without
+    # a defensive check in every caller.
+    "HOOK_TOOL_INPUT_JSON": json.dumps(tool_input),
+    "HOOK_TOOL_RESPONSE_JSON": json.dumps(tool_response),
+}
+
+for k, v in fields.items():
+    print(f"{k}={shlex.quote(str(v))}")
+' 2>/dev/null || true)
+
+  # Fail-open: if the python subprocess failed for any reason, leave
+  # HOOK_* vars unset/empty. Handlers will see empty tool_name and
+  # short-circuit on their own matcher predicate. Guard infrastructure
+  # must never block a tool call because its parser crashed.
+  if [[ -n "$assignments" ]]; then
+    eval "$assignments"
+  fi
+
+  export HOOK_TOOL_NAME="${HOOK_TOOL_NAME:-}" \
+         HOOK_FILE_PATH="${HOOK_FILE_PATH:-}" \
+         HOOK_COMMAND="${HOOK_COMMAND:-}" \
+         HOOK_CWD="${HOOK_CWD:-}" \
+         HOOK_SESSION_ID="${HOOK_SESSION_ID:-unknown}" \
+         HOOK_TRANSCRIPT_PATH="${HOOK_TRANSCRIPT_PATH:-}" \
+         HOOK_EVENT_NAME="${HOOK_EVENT_NAME:-}" \
+         HOOK_MODEL="${HOOK_MODEL:-}" \
+         HOOK_SOURCE="${HOOK_SOURCE:-}" \
+         HOOK_PERMISSION_MODE="${HOOK_PERMISSION_MODE:-default}" \
+         HOOK_TOOL_USE_ID="${HOOK_TOOL_USE_ID:-}" \
+         HOOK_STOP_HOOK_ACTIVE="${HOOK_STOP_HOOK_ACTIVE:-0}" \
+         HOOK_TOOL_INPUT_JSON="${HOOK_TOOL_INPUT_JSON:-{\}}" \
+         HOOK_TOOL_RESPONSE_JSON="${HOOK_TOOL_RESPONSE_JSON:-{\}}"
+}

package/templates/hook-packs/claude-code/lib/run-handlers.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 8,16
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# Shared handler-dispatch loop for Claude Code hook dispatchers.
+#
+# Source this file from a dispatcher script, then call:
+#
+#   run_handlers [--short-circuit-on-block] <handler-entry>...
+#
+# Each handler-entry is a whitespace-separated string whose first token is
+# the handler script filename (relative to HOOKS_DIR) and whose remaining
+# tokens are positional arguments forwarded to that script. Example:
+#
+#   run_handlers "cwd-guard.sh" "audit.sh tool-use" "session-log.sh"
+#
+# The caller must set HOOKS_DIR before sourcing this file (the dispatcher
+# boilerplate does this already).
+#
+# Environment variables consumed:
+#   HOOK_INPUT_JSON       — the sanitized JSON payload piped to every handler.
+#                           If not yet set, parse_hook_input is called to
+#                           populate it along with all HOOK_* scalar vars.
+#   CLAUDE_HOOK_DRY_RUN   — if non-empty and non-zero, still invoke every
+#                           handler but always return 0 from run_handlers and
+#                           emit "[DRY-RUN] <handler>.sh would have exited <N>"
+#                           to stderr for any non-zero exit.
+#   CLAUDE_HOOK_TIMING    — if non-empty and non-zero, emit
+#                           "[timing] <handler>.sh: <N>ms" to stderr after
+#                           each handler invocation. Does not affect exit codes
+#                           or stdout behavior.
+#
+# Stdout: the last non-empty buffer written to a handler's stdout is forwarded
+#         to run_handlers' caller's stdout ("last wins").
+#
+# Return value: the maximum exit code across all handlers (or 2 immediately if
+#               --short-circuit-on-block is set and any handler exits 2). When
+#               CLAUDE_HOOK_DRY_RUN is set the effective return is always 0.
+#
+# Idempotent source: safe to source multiple times.
+
+if [[ -n "${_HOOK_RUN_HANDLERS_LOADED:-}" ]]; then
+  return 0 2>/dev/null || exit 0
+fi
+_HOOK_RUN_HANDLERS_LOADED=1
+
+# ---------------------------------------------------------------------------
+# _rh_is_truthy <value>
+# Returns 0 (true) when value is non-empty and not "0".
+# ---------------------------------------------------------------------------
+_rh_is_truthy() {
+  local val="${1:-}"
+  [[ -n "$val" && "$val" != "0" ]]
+}
+
+# ---------------------------------------------------------------------------
+# _rh_ms_now
+# Prints current Unix time in milliseconds (integer).
+# Uses date +%s%N if available, falls back to python3.
+# ---------------------------------------------------------------------------
+_rh_ms_now() {
+  local ns
+  ns=$(date +%s%N 2>/dev/null)
+  # macOS date does not support %N; it prints literally "%N"
+  if [[ "$ns" == *%N* ]]; then
+    python3 -c 'import time; print(int(time.time() * 1000))'
+  else
+    printf '%d\n' "$(( ns / 1000000 ))"
+  fi
+}
+
+_rh_stdout_priority() {
+  local payload="$1"
+  local decision
+  decision=$(printf '%s' "$payload" | jq -r '.decision // .hookSpecificOutput.permissionDecision // ""' 2>/dev/null || true)
+  case "$decision" in
+    block) printf '3\n' ;;
+    ask) printf '2\n' ;;
+    *) printf '1\n' ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# run_handlers [--short-circuit-on-block] <handler-entry>...
+# ---------------------------------------------------------------------------
+run_handlers() {
+  local short_circuit=0
+  if [[ "${1:-}" == "--short-circuit-on-block" ]]; then
+    short_circuit=1
+    shift
+  fi
+
+  # Ensure the input is parsed and HOOK_INPUT_JSON is available.
+  # parse-input.sh is idempotent (guarded by _HOOK_PARSE_INPUT_LOADED).
+  if [[ -z "${HOOK_INPUT_JSON:-}" ]]; then
+    # HOOKS_DIR must be set by the caller (dispatcher boilerplate).
+    # shellcheck source=parse-input.sh
+    source "${HOOKS_DIR}/lib/parse-input.sh" 2>/dev/null || return 0
+    parse_hook_input || return 0
+  fi
+
+  local dry_run=0
+  _rh_is_truthy "${CLAUDE_HOOK_DRY_RUN:-}" && dry_run=1
+
+  local timing=0
+  _rh_is_truthy "${CLAUDE_HOOK_TIMING:-}" && timing=1
+
+  local max_exit=0
+  local last_stdout=""
+  local last_stdout_priority=0
+
+  # Snapshot the outer $@ into an array so `set --` inside the loop can safely
+  # clobber positional params without breaking iteration. Using "$@" directly
+  # with `for entry in "$@"` captures at loop start on modern bash, but this
+  # is safer across shells and makes the intent explicit.
+  local entries
+  entries=("$@")
+
+  local entry
+  for entry in "${entries[@]}"; do
+    # Split on whitespace: first token = script, rest = positional args.
+    # shellcheck disable=SC2086
+    set -- $entry
+    local handler="$1"
+    shift
+    # "$@" now holds the handler's positional args (may be empty). Use it
+    # directly rather than stashing into a local array -- bash 3.2 (macOS
+    # default) has quirky ${arr[@]+"${arr[@]}"} expansion behavior for
+    # empty arrays under set -u in certain command-substitution contexts.
+    # "$@" has no such quirks: empty positional params under set -u is a
+    # normal, non-error case.
+
+    local handler_path="${HOOKS_DIR}/${handler}"
+    if [[ ! -x "$handler_path" ]]; then
+      continue
+    fi
+
+    local t_start=0
+    if (( timing )); then
+      t_start=$(_rh_ms_now)
+    fi
+
+    local stderr_file
+    stderr_file=$(mktemp)
+    local stdout_buf
+    stdout_buf=$(printf '%s' "$HOOK_INPUT_JSON" \
+                  | "$handler_path" "$@" 2>"$stderr_file")
+    local exit_code=$?
+
+    local t_elapsed=0
+    if (( timing )); then
+      local t_end
+      t_end=$(_rh_ms_now)
+      t_elapsed=$(( t_end - t_start ))
+    fi
+
+    # Re-emit handler stderr prefixed with handler name.
+    if [[ -s "$stderr_file" ]]; then
+      while IFS= read -r line; do
+        printf '[%s] %s\n' "$handler" "$line" >&2
+      done < "$stderr_file"
+    fi
+    rm -f "$stderr_file"
+
+    # Timing annotation (after handler stderr so they don't interleave).
+    if (( timing )); then
+      printf '[timing] %s: %dms\n' "$handler" "$t_elapsed" >&2
+    fi
+
+    # Dry-run annotation for non-zero exits.
+    if (( dry_run )) && (( exit_code != 0 )); then
+      printf '[DRY-RUN] %s would have exited %d\n' "$handler" "$exit_code" >&2
+      exit_code=0
+    fi
+
+    # Accumulate stdout. Structured block/ask decisions outrank lower-priority
+    # hook context so a later handler cannot accidentally erase a safety
+    # boundary emitted by an earlier handler.
+    if [[ -n "$stdout_buf" ]]; then
+      local stdout_priority
+      stdout_priority=$(_rh_stdout_priority "$stdout_buf")
+      if [[ "$stdout_priority" -eq 3 ]]; then
+        printf '%s\n' "$stdout_buf"
+        return 2
+      fi
+      if [[ "$stdout_priority" -ge "$last_stdout_priority" ]]; then
+        last_stdout="$stdout_buf"
+        last_stdout_priority="$stdout_priority"
+      fi
+    fi
+
+    # Short-circuit on blocking exit (exit 2), unless dry-run zeroed it.
+    if (( short_circuit )) && [[ "$exit_code" -eq 2 ]]; then
+      [[ -n "$last_stdout" ]] && printf '%s\n' "$last_stdout"
+      return 2
+    fi
+
+    if [[ "$exit_code" -gt "$max_exit" ]]; then
+      max_exit="$exit_code"
+    fi
+  done
+
+  [[ -n "$last_stdout" ]] && printf '%s\n' "$last_stdout"
+
+  if (( dry_run )); then
+    return 0
+  fi
+  return "$max_exit"
+}