@bookedsolid/rea 0.1.0

package/hooks/push-review-gate.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# PreToolUse hook: push-review-gate.sh
+# Fires BEFORE every Bash tool call that matches "git push".
+# Runs a full diff analysis against the target branch and requests
+# security + code review before allowing the push.
+#
+# Exit codes:
+#   0 = allow (no meaningful diff, or review cached)
+#   2 = block (needs review)
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
+INPUT=$(cat)
+
+# ── 2. Dependency check ──────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── 3. HALT check ────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── 4. Parse command ──────────────────────────────────────────────────────────
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+# Only trigger on git push commands
+if ! printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+push'; then
+  exit 0
+fi
+
+# ── 5. Check if quality gates are enabled ─────────────────────────────────────
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [[ -f "$POLICY_FILE" ]]; then
+  if grep -qE 'push_review:[[:space:]]*false' "$POLICY_FILE" 2>/dev/null; then
+    exit 0
+  fi
+fi
+
+# ── 6. Determine target branch ───────────────────────────────────────────────
+CURRENT_BRANCH=$(cd "$REA_ROOT" && git branch --show-current 2>/dev/null || echo "")
+TARGET_BRANCH="main"
+
+# Try to extract target from push command (git push origin <branch>)
+PUSH_TARGET=$(printf '%s' "$CMD" | grep -oE 'git[[:space:]]+push[[:space:]]+[a-zA-Z_-]+[[:space:]]+([a-zA-Z0-9/_-]+)' | awk '{print $NF}' 2>/dev/null || echo "")
+if [[ -n "$PUSH_TARGET" ]]; then
+  TARGET_BRANCH="$PUSH_TARGET"
+fi
+
+# ── 7. Get diff against target ───────────────────────────────────────────────
+MERGE_BASE=$(cd "$REA_ROOT" && git merge-base "$TARGET_BRANCH" HEAD 2>/dev/null || echo "")
+
+if [[ -z "$MERGE_BASE" ]]; then
+  # Can't determine merge base — fail-open
+  exit 0
+fi
+
+DIFF_FULL=$(cd "$REA_ROOT" && git diff "$MERGE_BASE"...HEAD 2>/dev/null || echo "")
+
+if [[ -z "$DIFF_FULL" ]]; then
+  # No diff — nothing to review
+  exit 0
+fi
+
+LINE_COUNT=$(printf '%s' "$DIFF_FULL" | grep -cE '^\+[^+]|^-[^-]' 2>/dev/null || echo "0")
+
+# ── 8. Check review cache ────────────────────────────────────────────────────
+PUSH_SHA=$(printf '%s' "$DIFF_FULL" | shasum -a 256 | cut -d' ' -f1 2>/dev/null || echo "")
+
+# Resolve rea CLI (node_modules/.bin first, dist fallback)
+REA_CLI_ARGS=()
+if [[ -f "${REA_ROOT}/node_modules/.bin/rea" ]]; then
+  REA_CLI_ARGS=(node "${REA_ROOT}/node_modules/.bin/rea")
+elif [[ -f "${REA_ROOT}/dist/cli/index.js" ]]; then
+  REA_CLI_ARGS=(node "${REA_ROOT}/dist/cli/index.js")
+fi
+
+if [[ -n "$PUSH_SHA" ]] && [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
+  CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$CURRENT_BRANCH" --base "$TARGET_BRANCH" 2>/dev/null || echo '{"hit":false}')
+  if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true' >/dev/null 2>&1; then
+    # Review was already approved — notify and allow the push through
+    DISCORD_LIB="${REA_ROOT}/hooks/_lib/discord.sh"
+    if [ -f "$DISCORD_LIB" ]; then
+      # shellcheck source=/dev/null
+      source "$DISCORD_LIB"
+      discord_notify "dev" "Push passed quality gates on \`${CURRENT_BRANCH}\` -- $(cd "$REA_ROOT" && git log -1 --oneline 2>/dev/null)" "green"
+    fi
+    exit 0
+  fi
+fi
+
+# ── 9. Block and request review ──────────────────────────────────────────────
+FILE_COUNT=$(printf '%s' "$DIFF_FULL" | grep -c '^\+\+\+ ' 2>/dev/null || echo "0")
+
+{
+  printf 'PUSH REVIEW GATE: Review required before pushing\n'
+  printf '\n'
+  printf '  Branch: %s → %s\n' "$CURRENT_BRANCH" "$TARGET_BRANCH"
+  printf '  Scope: %s files changed, %s lines\n' "$FILE_COUNT" "$LINE_COUNT"
+  printf '\n'
+  printf '  Action required:\n'
+  printf '  1. Spawn a code-reviewer agent to review: git diff %s...HEAD\n' "$MERGE_BASE"
+  printf '  2. Spawn a security-engineer agent for security review\n'
+  printf '  3. After both pass, cache the result:\n'
+  printf '     rea cache set %s pass --branch %s --base %s\n' "$PUSH_SHA" "$CURRENT_BRANCH" "$TARGET_BRANCH"
+  printf '\n'
+} >&2
+exit 2

package/hooks/secret-scanner.sh

@@ -0,0 +1,229 @@
+#!/bin/bash
+# PreToolUse hook: secret-scanner.sh
+# Fires BEFORE every Write or Edit tool call.
+# Scans content about to be written for credential patterns and blocks (exit 2)
+# if real secrets are detected — before they ever touch disk.
+#
+# Content extraction:
+#   Write tool → tool_input.content
+#   Edit tool  → tool_input.new_string
+#
+# NOTE: This hook is a last-resort pre-write guard. The primary secret gate is
+# gitleaks running in the pre-commit hook. This hook stops obvious credentials
+# before they hit disk. It cannot catch all encoding tricks — rely on gitleaks
+# for comprehensive coverage.
+#
+# Exit codes:
+#   0 = no secrets detected — allow the tool to proceed
+#   2 = secrets detected    — block the tool call
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── HALT check ────────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+CONTENT_WRITE=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+CONTENT_EDIT=$(printf '%s' "$INPUT"  | jq -r '.tool_input.new_string // empty' 2>/dev/null)
+
+if [[ -n "$CONTENT_WRITE" ]]; then
+  CONTENT="$CONTENT_WRITE"
+elif [[ -n "$CONTENT_EDIT" ]]; then
+  CONTENT="$CONTENT_EDIT"
+else
+  exit 0
+fi
+
+# Smart file-path exclusions (suffix-based only — no directory exclusions)
+if [[ -n "$FILE_PATH" ]]; then
+  if [[ "$FILE_PATH" == *.env.example || "$FILE_PATH" == *.env.sample ]]; then
+    exit 0
+  fi
+  # Test files are NOT excluded — real secrets in test files must be caught.
+  # The is_placeholder() function handles false positives from test fixtures.
+fi
+
+# Build line-filtered content
+# Strip: shell comment lines (#) and lines where process.env.VAR is the RHS of an assignment
+# NOT stripped: lines that merely mention process.env somewhere (bypass vector if too broad)
+FILTERED_FILE=$(mktemp "${TMPDIR:-/tmp}/rea-secret-scan-XXXXXX") || {
+  printf 'SECRET-SCAN ERROR: Failed to create temp file — blocking write (fail-secure)\n' >&2
+  exit 2
+}
+
+VIOLATIONS_FILE=""
+
+cleanup() {
+  rm -f "$FILTERED_FILE"
+  [[ -n "$VIOLATIONS_FILE" ]] && rm -f "$VIOLATIONS_FILE"
+}
+trap cleanup EXIT
+
+printf '%s' "$CONTENT" | awk '
+{
+  line = $0
+  trimmed = line
+  sub(/^[[:space:]]+/, "", trimmed)
+  # Skip shell comment lines only
+  if (substr(trimmed, 1, 1) == "#") next
+  # Skip lines where process.env.VAR is the RHS of an assignment
+  # Pattern: = process.env.SOMETHING  (not just any mention of process.env)
+  if (trimmed ~ /=[[:space:]]*process\.env\.[A-Z_]+[^a-zA-Z]?$/) next
+  if (trimmed ~ /=[[:space:]]*process\.env\.[A-Z_]+[[:space:]]*[;,)]/) next
+  if (trimmed ~ /os\.environ\[/) next
+  print line
+}
+' > "$FILTERED_FILE" 2>/dev/null
+
+if [[ ! -s "$FILTERED_FILE" ]]; then
+  exit 0
+fi
+
+is_placeholder() {
+  local MATCH
+  MATCH=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  [[ "$MATCH" =~ \<[a-z_]+\> ]] && return 0
+  [[ "$MATCH" =~ your_key_here  ]] && return 0
+  [[ "$MATCH" =~ your_api_key   ]] && return 0
+  [[ "$MATCH" =~ your_secret    ]] && return 0
+  [[ "$MATCH" =~ placeholder    ]] && return 0
+  [[ "$MATCH" =~ changeme       ]] && return 0
+  [[ "$MATCH" =~ insert.*here   ]] && return 0
+  # Prefix checks: require full placeholder compound, not just a prefix
+  [[ "$MATCH" =~ ^(test|fake|mock|demo|example)_(key|token|secret|credential|api)$ ]] && return 0
+  [[ "$MATCH" =~ ^test_[a-z_]+_key$ ]] && return 0
+  # Repeated-character dummies (aaaaaaa, 1111111, etc.)
+  if printf '%s' "$MATCH" | grep -qE '^(.)\1{7,}$'; then return 0; fi
+  return 1
+}
+
+VIOLATIONS_FILE=$(mktemp "${TMPDIR:-/tmp}/rea-secret-violations-XXXXXX") || {
+  printf 'SECRET-SCAN ERROR: Failed to create violations file — blocking write (fail-secure)\n' >&2
+  exit 2
+}
+
+scan_pattern() {
+  local SEVERITY="$1"
+  local LABEL="$2"
+  local PATTERN="$3"
+  local MATCHES GREP_EXIT MATCH SNIPPET
+  MATCHES=$(grep -oE -e "$PATTERN" "$FILTERED_FILE" 2>/dev/null)
+  GREP_EXIT=$?
+  [[ $GREP_EXIT -ne 0 ]] && return 0
+  [[ -z "$MATCHES" ]]    && return 0
+  MATCHES=$(printf '%s\n' "$MATCHES" | head -5)
+  while IFS= read -r MATCH; do
+    [[ -z "$MATCH" ]] && continue
+    if is_placeholder "$MATCH"; then continue; fi
+    if [[ ${#MATCH} -gt 60 ]]; then
+      SNIPPET="${MATCH:0:60}..."
+    else
+      SNIPPET="$MATCH"
+    fi
+    printf '%s|%s|%s\n' "$SEVERITY" "$LABEL" "$SNIPPET" >> "$VIOLATIONS_FILE"
+  done <<< "$MATCHES"
+}
+
+# ── HIGH severity patterns ─────────────────────────────────────────────────────
+
+scan_pattern "HIGH" "AWS Access Key ID" \
+  'AKIA[0-9A-Z]{16}'
+
+scan_pattern "HIGH" "AWS Secret Access Key" \
+  '[Aa][Ww][Ss]_SECRET_ACCESS_KEY[[:space:]]*=[[:space:]]*[A-Za-z0-9/+]{40}'
+
+scan_pattern "HIGH" "Private key block" \
+  '-----BEGIN (RSA|EC|OPENSSH|PGP) PRIVATE KEY-----'
+
+scan_pattern "HIGH" "Anthropic API key" \
+  'sk-ant-api03-[A-Za-z0-9_-]{93}'
+
+scan_pattern "HIGH" "Anthropic OAuth token" \
+  'sk-ant-oat01-[A-Za-z0-9_-]{86}'
+
+scan_pattern "HIGH" "GitHub classic Personal Access Token" \
+  'gh[puors]_[A-Za-z0-9]{36}'
+
+scan_pattern "HIGH" "GitHub fine-grained Personal Access Token" \
+  'github_pat_[A-Za-z0-9_]{82}'
+
+scan_pattern "HIGH" "Stripe live secret/restricted key" \
+  '(sk|rk)_live_[A-Za-z0-9]{24,}'
+
+scan_pattern "HIGH" "Stripe webhook signing secret" \
+  'whsec_[A-Za-z0-9+/]{40,}'
+
+scan_pattern "HIGH" "Generic secret assignment (double-quoted)" \
+  '(SECRET|PASSWORD|PRIVATE_KEY|API_SECRET)[[:space:]]*=[[:space:]]*"[^"]{20,}"'
+
+scan_pattern "HIGH" "Generic secret assignment (single-quoted)" \
+  "(SECRET|PASSWORD|PRIVATE_KEY|API_SECRET)[[:space:]]*=[[:space:]]*'[^']{20,}'"
+
+scan_pattern "HIGH" "Supabase service role key (JWT)" \
+  'SUPABASE_SERVICE_ROLE_KEY[[:space:]]*=[[:space:]]*["\'"'"']eyJ[A-Za-z0-9._-]{50,}'
+
+# ── MEDIUM severity patterns ───────────────────────────────────────────────────
+
+scan_pattern "MEDIUM" ".env credential assignment" \
+  '^(ANTHROPIC_API_KEY|SUPABASE_SERVICE_ROLE_KEY|DATABASE_URL|STRIPE_SECRET)[[:space:]]*=[[:space:]]*[^[:space:]]+'
+
+scan_pattern "MEDIUM" "Stripe test API key (real credential, test env)" \
+  '(sk|pk|rk)_test_[A-Za-z0-9]{24,}'
+
+scan_pattern "MEDIUM" "Stripe live publishable key" \
+  'pk_live_[A-Za-z0-9]{24,}'
+
+scan_pattern "MEDIUM" "Hardcoded DB connection string with password" \
+  'postgresql://[^:]+:[^@]{8,}@'
+
+scan_pattern "MEDIUM" "Supabase anon key in non-client context" \
+  'SUPABASE_ANON_KEY[[:space:]]*=[[:space:]]*["\'"'"']eyJ[A-Za-z0-9._-]{50,}'
+
+if [[ ! -s "$VIOLATIONS_FILE" ]]; then
+  exit 0
+fi
+
+FILE_BASENAME=$(basename "${FILE_PATH:-unknown}")
+HIGH_COUNT=$(grep -cF 'HIGH|' "$VIOLATIONS_FILE" 2>/dev/null || true)
+: "${HIGH_COUNT:=0}"
+
+if [[ "$HIGH_COUNT" -gt 0 ]]; then
+  {
+    printf 'SECRET DETECTED: Potential credential in %s\n' "$FILE_BASENAME"
+    COUNT=0
+    while IFS='|' read -r SEVERITY LABEL SNIPPET; do
+      [[ -z "$SEVERITY" ]] && continue
+      COUNT=$(( COUNT + 1 ))
+      if [[ $COUNT -gt 5 ]]; then break; fi
+      printf '  %s: %s — '"'"'%s'"'"'\n' "$SEVERITY" "$LABEL" "$SNIPPET"
+    done < "$VIOLATIONS_FILE"
+    printf 'Block reason: Writing credentials to disk risks exposure via git history.\n'
+    printf 'Fix: Load credentials from environment variables — never hardcode secrets.\n'
+  } >&2
+  exit 2
+fi
+
+{
+  printf 'SECRET-SCAN WARN: Low-confidence credential pattern in %s (advisory — not blocking)\n' "$FILE_BASENAME"
+  while IFS='|' read -r SEVERITY LABEL SNIPPET; do
+    [[ -z "$SEVERITY" ]] && continue
+    printf '  %s: %s — '"'"'%s'"'"'\n' "$SEVERITY" "$LABEL" "$SNIPPET"
+  done < "$VIOLATIONS_FILE"
+  printf 'Note: Heuristic match — may be a false positive. If real, load from environment.\n'
+} >&2
+exit 0

package/hooks/security-disclosure-gate.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# security-disclosure-gate.sh — PreToolUse: Bash
+#
+# Intercepts `gh issue create` commands that contain security-sensitive
+# keywords and blocks them. Routing depends on REA_DISCLOSURE_MODE:
+#
+#   advisory (default) — redirect to GitHub Security Advisories (private)
+#                        Use for public OSS repos
+#   issues             — redirect to gh issue create with security + internal labels
+#                        Use for permanently private client repos
+#   disabled           — pass through (not recommended)
+#
+# Set REA_DISCLOSURE_MODE in .rea/policy.yaml (written to settings.json
+# env by rea init). Defaults to "advisory" when unset.
+#
+# Triggered by: PreToolUse — Bash tool
+
+set -euo pipefail
+
+# shellcheck source=_lib/common.sh
+source "$(dirname "$0")/_lib/common.sh"
+
+check_halt
+
+# Read disclosure mode — default to advisory
+DISCLOSURE_MODE="${REA_DISCLOSURE_MODE:-advisory}"
+
+# Disabled mode: pass through entirely
+if [[ "$DISCLOSURE_MODE" == "disabled" ]]; then
+  exit 0
+fi
+
+INPUT="$(cat)"
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+if [[ "$TOOL_NAME" != "Bash" ]]; then
+  exit 0
+fi
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+# Only intercept gh issue create
+if ! echo "$COMMAND" | grep -qE 'gh\s+issue\s+create'; then
+  exit 0
+fi
+
+require_jq
+
+# Security-sensitive keywords that should not appear in public issues —
+# these terms suggest a vulnerability, exploit path, or bypass technique
+SECURITY_PATTERNS=(
+  # Vulnerability classes
+  'bypass'
+  'exploit'
+  'injection'
+  'traversal'
+  'exfiltrat'
+  'escalat'
+  'privilege'
+  'rce'
+  'remote.code.exec'
+  'arbitrary.code'
+  'code.execution'
+  'zero.day'
+  '0day'
+  'CVE-'
+  'CVSS'
+  'GHSA-'
+  # Reagent-specific sensitive terms
+  'hook.bypass'
+  'HALT.bypass'
+  'redaction.bypass'
+  'policy.bypass'
+  'middleware.bypass'
+  'skip.*gate'
+  'evad'
+  # Credential/secret exposure
+  'secret.*leak'
+  'credential.*leak'
+  'token.*leak'
+  'key.*expos'
+  'expos.*secret'
+  # Prompt injection
+  'prompt.inject'
+  'jailbreak'
+  'jail.break'
+)
+
+# Scan the full command text (title + body + flags) for sensitive patterns
+FULL_TEXT=$(echo "$COMMAND" | tr '[:upper:]' '[:lower:]')
+
+MATCHED_PATTERN=""
+for PATTERN in "${SECURITY_PATTERNS[@]}"; do
+  if echo "$FULL_TEXT" | grep -qiE "$PATTERN"; then
+    MATCHED_PATTERN="$PATTERN"
+    break
+  fi
+done
+
+if [[ -z "$MATCHED_PATTERN" ]]; then
+  exit 0
+fi
+
+# ─── Route based on disclosure mode ──────────────────────────────────────────
+
+if [[ "$DISCLOSURE_MODE" == "issues" ]]; then
+  # Private repo mode: redirect to labeled internal issue
+  json_output "block" \
+    "SECURITY DISCLOSURE GATE: This issue appears to describe a security finding (matched: '${MATCHED_PATTERN}').
+
+This project is configured for PRIVATE disclosure (REA_DISCLOSURE_MODE=issues).
+
+CORRECT PATH for security findings in this private repo:
+  Use: gh issue create --label 'security,internal' --title '...' --body '...'
+
+The 'security' and 'internal' labels keep this off public project boards and
+mark it for maintainer-only triage. Do NOT use the public issue queue without
+these labels for security findings.
+
+If this is NOT a security finding, rephrase the title/body to avoid triggering
+security patterns, then retry."
+
+else
+  # Advisory mode (default): redirect to GitHub Security Advisories
+  json_output "block" \
+    "SECURITY DISCLOSURE GATE: This issue appears to describe a security vulnerability (matched: '${MATCHED_PATTERN}'). Do NOT create a public GitHub issue for security vulnerabilities.
+
+CORRECT DISCLOSURE PATH:
+1. Use GitHub Security Advisories (private):
+   gh api repos/{owner}/{repo}/security-advisories --method POST --input - <<'JSON'
+   { \"summary\": \"...\", \"description\": \"...\", \"severity\": \"medium|high|critical\",
+     \"vulnerabilities\": [{\"package\": {\"name\": \"@pkg\", \"ecosystem\": \"npm\"}}] }
+   JSON
+2. Or navigate to: Security tab → Advisories → 'Report a vulnerability'
+3. Or email security@bookedsolid.tech (see SECURITY.md)
+
+The finding will be publicly disclosed AFTER a patch is released (coordinated disclosure).
+
+WHY: Public issues expose vulnerabilities before users can patch. This is enforced by the
+security-disclosure-gate hook (REA_DISCLOSURE_MODE=${DISCLOSURE_MODE}).
+
+If this is NOT a security vulnerability, rephrase the issue to avoid triggering
+security patterns, then retry."
+fi
+
+exit 2

package/hooks/settings-protection.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# PreToolUse hook: settings-protection.sh
+# Fires BEFORE every Write or Edit tool call.
+# Blocks modifications to critical configuration files that, if tampered with,
+# would disable the entire hook safety layer.
+#
+# Protected paths (security controls and hook infrastructure ONLY):
+#   .claude/settings.json       — hook configuration
+#   .claude/settings.local.json — local hook overrides
+#   .claude/hooks/*             — hook scripts themselves
+#   .husky/*                    — git hook scripts
+#   .rea/policy.yaml        — autonomy/blocking policy
+#   .rea/HALT               — kill switch file
+#
+# NOT protected (operational files agents may legitimately write):
+#   .rea/review-cache.json  — cache file, writable by CLI and agents
+#   .rea/tasks.jsonl        — task store, managed by task MCP tools
+#
+# Exit codes:
+#   0 = allow (path not protected)
+#   2 = block (protected path modification attempt)
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately ─────────────────────────────────────────────
+INPUT=$(cat)
+
+# ── 2. Dependency check ──────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REA ERROR: jq is required but not installed.\n' >&2
+  printf 'Install: brew install jq  OR  apt-get install -y jq\n' >&2
+  exit 2
+fi
+
+# ── 3. HALT check ────────────────────────────────────────────────────────────
+REA_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REA_ROOT}/.rea/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REA HALT: %s\nAll agent operations suspended. Run: rea unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── 4. Extract file path from payload ─────────────────────────────────────────
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# ── 5. Normalize path for comparison ──────────────────────────────────────────
+# Convert to relative path from project root for consistent matching
+normalize_path() {
+  local p="$1"
+  local root="$REA_ROOT"
+
+  # Strip project root prefix if present
+  if [[ "$p" == "$root"/* ]]; then
+    p="${p#$root/}"
+  fi
+
+  # URL decode common sequences
+  p=$(printf '%s' "$p" | sed 's/%2[Ff]/\//g; s/%2[Ee]/./g; s/%20/ /g')
+
+  # Collapse path traversals
+  # Remove ./ components
+  p=$(printf '%s' "$p" | sed 's|\./||g')
+
+  # Remove leading ./
+  p="${p#./}"
+
+  printf '%s' "$p"
+}
+
+NORMALIZED=$(normalize_path "$FILE_PATH")
+
+# ── 6. Protected path patterns ────────────────────────────────────────────────
+PROTECTED_PATTERNS=(
+  '.claude/settings.json'
+  '.claude/settings.local.json'
+  '.claude/hooks/'
+  '.husky/'
+  '.rea/policy.yaml'
+  '.rea/HALT'
+)
+
+for pattern in "${PROTECTED_PATTERNS[@]}"; do
+  # Exact match
+  if [[ "$NORMALIZED" == "$pattern" ]]; then
+    {
+      printf 'SETTINGS PROTECTION: Modification blocked\n'
+      printf '\n'
+      printf '  File: %s\n' "$FILE_PATH"
+      printf '  Rule: This file is protected from agent modification.\n'
+      printf '\n'
+      printf '  Protected files include hook scripts, settings, policy,\n'
+      printf '  and kill switch files. These must be modified by humans\n'
+      printf '  via rea CLI or direct editing.\n'
+      printf '\n'
+      printf '  Use: rea init (to update hooks/settings)\n'
+      printf '       rea freeze/unfreeze (for HALT file)\n'
+      printf '       Edit .rea/policy.yaml manually\n'
+    } >&2
+    exit 2
+  fi
+
+  # Directory prefix match (patterns ending in /)
+  if [[ "$pattern" == */ ]] && [[ "$NORMALIZED" == "$pattern"* ]]; then
+    {
+      printf 'SETTINGS PROTECTION: Modification blocked\n'
+      printf '\n'
+      printf '  File: %s\n' "$FILE_PATH"
+      printf '  Rule: Files under %s are protected from agent modification.\n' "$pattern"
+      printf '\n'
+      printf '  These files control the hook safety layer and must be\n'
+      printf '  modified by humans via rea CLI or direct editing.\n'
+    } >&2
+    exit 2
+  fi
+done
+
+# ── 7. Case-insensitive fallback check ────────────────────────────────────────
+# Catch case-manipulation bypass attempts (e.g., .Claude/Settings.json)
+LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+for pattern in "${PROTECTED_PATTERNS[@]}"; do
+  LOWER_PATTERN=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
+  if [[ "$LOWER_NORM" == "$LOWER_PATTERN" ]]; then
+    {
+      printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
+      printf '\n'
+      printf '  File: %s\n' "$FILE_PATH"
+      printf '  Matched: %s\n' "$pattern"
+    } >&2
+    exit 2
+  fi
+  if [[ "$LOWER_PATTERN" == */ ]] && [[ "$LOWER_NORM" == "$LOWER_PATTERN"* ]]; then
+    {
+      printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
+      printf '\n'
+      printf '  File: %s\n' "$FILE_PATH"
+      printf '  Matched: %s*\n' "$pattern"
+    } >&2
+    exit 2
+  fi
+done
+
+exit 0