@bookedsolid/rea 0.1.0

package/hooks/dangerous-bash-interceptor.sh

@@ -0,0 +1,362 @@
+#!/bin/bash
+# PreToolUse hook: dangerous-bash-interceptor.sh
+# Fires BEFORE every Bash tool call.
+# Detects destructive shell commands and blocks them (exit 2) or warns (exit 0).
+#
+# Compatible with: interactive sessions + headless Docker (no TTY required).
+# All diagnostic output goes to stderr only.
+#
+# Content extraction:
+#   Bash tool → tool_input.command
+#
+# Exit codes:
+#   0 = safe or advisory-only — allow the command to run
+#   2 = HIGH severity danger detected — block the command with feedback
+
+set -uo pipefail
+
+# ── 1. Read ALL stdin immediately before doing anything else ──────────────────
+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 tool_input.command from the hook payload ─────────────────────────
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+# ── 5. Helper: truncate command for display ────────────────────────────────────
+truncate_cmd() {
+  local STR="$1"
+  local MAX=200
+  if [[ ${#STR} -gt $MAX ]]; then
+    printf '%s' "${STR:0:$MAX}..."
+  else
+    printf '%s' "$STR"
+  fi
+}
+
+# ── 6. Violation accumulators ──────────────────────────────────────────────────
+HIGH_FILE=$(mktemp "${TMPDIR:-/tmp}/rea-bash-high-XXXXXX")
+MEDIUM_FILE=$(mktemp "${TMPDIR:-/tmp}/rea-bash-medium-XXXXXX")
+
+cleanup_violations() {
+  rm -f "$HIGH_FILE" "$MEDIUM_FILE"
+}
+trap cleanup_violations EXIT
+
+add_high() {
+  local LABEL="$1"
+  local DETAIL="$2"
+  shift 2
+  printf 'HIGH|%s|%s\n' "$LABEL" "$DETAIL" >> "$HIGH_FILE"
+  for ALT in "$@"; do
+    printf 'ALT:%s\n' "$ALT" >> "$HIGH_FILE"
+  done
+  printf 'END_VIOLATION\n' >> "$HIGH_FILE"
+}
+
+add_medium() {
+  local LABEL="$1"
+  local DETAIL="$2"
+  shift 2
+  printf 'MEDIUM|%s|%s\n' "$LABEL" "$DETAIL" >> "$MEDIUM_FILE"
+  for ALT in "$@"; do
+    printf 'ALT:%s\n' "$ALT" >> "$MEDIUM_FILE"
+  done
+  printf 'END_VIOLATION\n' >> "$MEDIUM_FILE"
+}
+
+# ── 7. Per-segment evaluation helper ──────────────────────────────────────────
+# Split on &&, ||, ;, and newlines and test a pattern against each segment.
+# Returns 0 if ANY segment matches the pattern.
+any_segment_matches() {
+  local PATTERN="$1"
+  while IFS= read -r SEG; do
+    if printf '%s' "$SEG" | grep -qiE "$PATTERN"; then
+      return 0
+    fi
+  done < <(printf '%s' "$CMD" | sed 's/&&/\n/g; s/||/\n/g; s/;/\n/g')
+  return 1
+}
+
+# ── 8. Smart exclusion flags ──────────────────────────────────────────────────
+CMD_IS_REBASE_SAFE=0
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+(rebase)[[:space:]].*(--abort|--continue)'; then
+  CMD_IS_REBASE_SAFE=1
+fi
+
+CMD_IS_CLEAN_DRY=0
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+clean.*([ \t]-n|--dry-run)'; then
+  CMD_IS_CLEAN_DRY=1
+fi
+
+# ── 9. HIGH severity checks ────────────────────────────────────────────────────
+
+# H1: git push --force or -f (per-segment — prevents --force-with-lease poisoning)
+# A segment containing --force-with-lease is excluded; other segments are not.
+while IFS= read -r SEGMENT; do
+  SEGMENT=$(printf '%s' "$SEGMENT" | sed 's/^[[:space:]]*//')
+  [[ -z "$SEGMENT" ]] && continue
+  # Skip segments that use the safe --force-with-lease
+  if printf '%s' "$SEGMENT" | grep -qiE 'git[[:space:]]+push.*--force-with-lease'; then
+    continue
+  fi
+  if printf '%s' "$SEGMENT" | grep -qiE 'git[[:space:]]+push.*(--force|-f[[:space:]])' || \
+     printf '%s' "$SEGMENT" | grep -qiE 'git[[:space:]]+push.*(--force|-f)$'; then
+    add_high \
+      "git push --force — force push detected" \
+      "Force-pushing rewrites public history and breaks collaborators' local copies." \
+      "Alt: Use 'git push --force-with-lease' — blocks if upstream has new commits you haven't pulled."
+    break
+  fi
+done < <(printf '%s' "$CMD" | sed 's/&&/\n/g; s/||/\n/g; s/;/\n/g')
+
+# H2: git rebase — advisory (MEDIUM)
+if [[ $CMD_IS_REBASE_SAFE -eq 0 ]]; then
+  if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+rebase([[:space:]]|$)'; then
+    add_medium \
+      "git rebase — rewrites commit history (advisory)" \
+      "Rebase changes commit SHAs. Safe on local feature branches; dangerous on shared/published branches." \
+      "Alt: 'git merge origin/main' preserves history (creates merge commit)." \
+      "     'git rebase --abort' to cancel if in progress."
+  fi
+fi
+
+# H3: git checkout -- .
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+checkout[[:space:]]+--[[:space:]]+\.'; then
+  add_high \
+    "git checkout -- . — discards all uncommitted changes" \
+    "Overwrites working tree changes with HEAD. Uncommitted work is lost permanently." \
+    "Alt: 'git stash' to temporarily shelve changes, 'git restore <file>' for individual files."
+fi
+
+# H4: git restore . (any form — with or without --staged flag)
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+restore[[:space:]].*[[:space:]]\.([[:space:]]|$)' || \
+   printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+restore[[:space:]]+\.[[:space:]]*$'; then
+  add_high \
+    "git restore . — discards all uncommitted changes" \
+    "Restores every tracked file to HEAD, permanently discarding all working tree modifications." \
+    "Alt: 'git stash' to save changes temporarily, or restore individual files: 'git restore <file>'."
+fi
+
+# H5: git clean -f
+if [[ $CMD_IS_CLEAN_DRY -eq 0 ]]; then
+  if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'; then
+    add_high \
+      "git clean -f — removes untracked files" \
+      "Permanently deletes untracked files from the working tree. Cannot be undone via git." \
+      "Alt: 'git clean -n' (dry-run) to preview what would be deleted before committing."
+  fi
+fi
+
+# H6: DROP TABLE or DROP DATABASE in psql
+if printf '%s' "$CMD" | grep -qiE '(psql|pgcli)[^|&;]*DROP[[:space:]]+(TABLE|DATABASE|SCHEMA)'; then
+  add_high \
+    "DROP TABLE/DATABASE via psql — destructive DDL" \
+    "Running destructive DDL directly in psql bypasses migration pipeline safety checks." \
+    "Alt: Use your project's migration tool. Never run DROP via ad-hoc psql."
+fi
+
+# H7: kill -9 with pgrep subshell
+if printf '%s' "$CMD" | grep -qiE 'kill[[:space:]]+-9[[:space:]]+(\$\(|`)'; then
+  add_high \
+    "kill -9 with pgrep subshell — aggressive process termination" \
+    "Sends SIGKILL to processes matched by name, which may kill unintended processes." \
+    "Alt: 'kill -15 <pid>' (SIGTERM) for graceful shutdown."
+fi
+
+# H8: killall -9
+if printf '%s' "$CMD" | grep -qiE 'killall[[:space:]]+-9[[:space:]]+\S'; then
+  add_high \
+    "killall -9 — SIGKILL all matching processes" \
+    "Immediately terminates all processes with the given name without cleanup." \
+    "Alt: 'killall -15 <name>' (SIGTERM) allows graceful shutdown."
+fi
+
+# H9: git commit --no-verify
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+commit.*--no-verify'; then
+  add_high \
+    "git commit --no-verify — skipping pre-commit hooks" \
+    "Bypasses all pre-commit safety gates including secret scanning and linting." \
+    "Alt: Fix the underlying hook failure rather than bypassing it."
+fi
+
+# H10: HUSKY=0 bypass — suppresses all git hooks without --no-verify
+if printf '%s' "$CMD" | grep -qiE '(^|[[:space:];]|&&|\|\|)HUSKY=0[[:space:]]+git[[:space:]]+(commit|push|tag)'; then
+  add_high \
+    "HUSKY=0 — bypasses all husky git hooks" \
+    "Setting HUSKY=0 disables pre-commit, commit-msg, and pre-push safety gates without --no-verify." \
+    "Alt: Fix the underlying hook failure rather than suppressing all hooks."
+fi
+
+# H11: rm -rf with broad targets
+# Covers combined flags (rm -rf, rm -fr), split flags (rm -r -f), and long flags (rm --recursive --force)
+BROAD_TARGETS='(\/|~\/|\.\/\*|\*|\.|src|dist|build|node_modules)'
+if printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+-[a-zA-Z]*r[a-zA-Z]*f[[:space:]]+${BROAD_TARGETS}" || \
+   printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+-[a-zA-Z]*f[a-zA-Z]*r[[:space:]]+${BROAD_TARGETS}" || \
+   printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+-[a-zA-Z]*r[[:space:]]+-[a-zA-Z]*f[[:space:]]+${BROAD_TARGETS}" || \
+   printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+-[a-zA-Z]*f[[:space:]]+-[a-zA-Z]*r[[:space:]]+${BROAD_TARGETS}" || \
+   printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+--recursive[[:space:]]+--force[[:space:]]+${BROAD_TARGETS}" || \
+   printf '%s' "$CMD" | grep -qiE "rm[[:space:]]+--force[[:space:]]+--recursive[[:space:]]+${BROAD_TARGETS}"; then
+  add_high \
+    "rm -rf with broad target — mass file deletion" \
+    "Permanently deletes files and directories. Cannot be undone." \
+    "Alt: Move to a temp location first, or use 'rm -ri' for interactive deletion."
+fi
+
+# H12: curl/wget piped directly to shell (supply chain attack vector)
+if printf '%s' "$CMD" | grep -qiE '(curl|wget)[^|]*\|[[:space:]]*(bash|sh|zsh|fish)'; then
+  add_high \
+    "curl/wget piped to shell — remote code execution" \
+    "Executing remote scripts without inspection is a major supply chain risk." \
+    "Alt: Download first, inspect the script, then execute: curl -o script.sh URL && cat script.sh && bash script.sh"
+fi
+
+# H13: git push --no-verify — bypasses pre-push hooks
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+push.*--no-verify'; then
+  add_high \
+    "git push --no-verify — skipping pre-push hooks" \
+    "Bypasses all pre-push safety gates including CI checks." \
+    "Alt: Fix the underlying hook failure rather than bypassing it."
+fi
+
+# H14: git -c core.hooksPath= — redirects or disables hook execution
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+-c[[:space:]]+core\.hookspath'; then
+  add_high \
+    "git -c core.hooksPath — overriding hooks directory" \
+    "Redirecting the hooks path can disable all safety hooks." \
+    "Alt: Fix the underlying hook issue. Do not bypass the hooks directory."
+fi
+
+# H15: REA_BYPASS env var — attempted escape hatch
+if printf '%s' "$CMD" | grep -qiE '(^|[[:space:];]|&&|\|\|)REA_BYPASS[[:space:]]*='; then
+  add_high \
+    "REA_BYPASS env var — unauthorized bypass attempt" \
+    "Setting REA_BYPASS is not a supported escape mechanism and indicates a bypass attempt." \
+    "Alt: If you need to override a gate, request human escalation."
+fi
+
+# H16: alias/function definitions containing bypass strings
+if printf '%s' "$CMD" | grep -qiE '(alias|function)[[:space:]]+[a-zA-Z_]+.*(--(no-verify|force)|HUSKY=0|core\.hookspath)'; then
+  add_high \
+    "Alias/function definition with bypass — circumventing safety gates" \
+    "Defining aliases or functions that embed bypass flags defeats safety hooks." \
+    "Alt: Do not wrap bypass patterns in aliases or functions."
+fi
+
+# H17: context_protection — block commands that should be delegated to subagents
+# Reads context_protection.delegate_to_subagent from .rea/policy.yaml.
+# These commands produce excessive output that exhausts coordinator context windows.
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [[ -f "$POLICY_FILE" ]]; then
+  DELEGATE_PATTERNS=()
+  IN_DELEGATE_BLOCK=0
+  while IFS= read -r line; do
+    if printf '%s' "$line" | grep -qE '^[[:space:]]*delegate_to_subagent:'; then
+      # Check for inline empty array
+      if printf '%s' "$line" | grep -qE 'delegate_to_subagent:[[:space:]]*\[\]'; then
+        break
+      fi
+      IN_DELEGATE_BLOCK=1
+      continue
+    fi
+    if [[ $IN_DELEGATE_BLOCK -eq 1 ]]; then
+      # Block sequence items start with "  - "
+      if printf '%s' "$line" | grep -qE '^[[:space:]]*-[[:space:]]'; then
+        pattern=$(printf '%s' "$line" | sed "s/^[[:space:]]*-[[:space:]]*//; s/^[\"']//; s/[\"']$//")
+        if [[ -n "$pattern" ]]; then
+          DELEGATE_PATTERNS+=("$pattern")
+        fi
+      else
+        # Non-continuation line = end of block
+        break
+      fi
+    fi
+  done < "$POLICY_FILE"
+
+  for pattern in "${DELEGATE_PATTERNS[@]+"${DELEGATE_PATTERNS[@]}"}"; do
+    # Use fixed-string match — these are command prefixes, not regex
+    if printf '%s' "$CMD" | grep -qF "$pattern"; then
+      add_high \
+        "Context protection — command must run in a subagent" \
+        "This command produces excessive output that will exhaust the coordinator context window. Delegate it to a subagent instead of running it directly." \
+        "Alt: Use the Agent tool to delegate: Agent(subagent_type: 'qa-engineer-automation', prompt: 'Run $pattern and report pass/fail summary only.')" \
+        "Alt: The context_protection policy in .rea/policy.yaml lists commands that must be delegated."
+      break
+    fi
+  done
+fi
+
+# ── 10. MEDIUM severity checks ────────────────────────────────────────────────
+
+# M1: npm install --force
+if printf '%s' "$CMD" | grep -qiE 'npm[[:space:]]+(install|i)[[:space:]].*--force'; then
+  add_medium \
+    "npm install --force — bypasses dependency resolution" \
+    "--force skips conflict checks and can install incompatible package versions." \
+    "Alt: Resolve the dependency conflict explicitly. Use --legacy-peer-deps if needed."
+fi
+
+# ── 11. Evaluate and report ───────────────────────────────────────────────────
+
+TRUNCATED_CMD=$(truncate_cmd "$CMD")
+
+print_violations() {
+  local VF="$1"
+  local NOTE_LABEL="$2"
+  while IFS= read -r LINE; do
+    case "$LINE" in
+      HIGH\|*|MEDIUM\|*)
+        local SEV LABEL DETAIL
+        SEV=$(printf '%s' "$LINE" | cut -d'|' -f1)
+        LABEL=$(printf '%s' "$LINE" | cut -d'|' -f2)
+        DETAIL=$(printf '%s' "$LINE" | cut -d'|' -f3)
+        printf '  %s: %s\n' "$SEV" "$LABEL"
+        printf '  %s: %s\n' "$NOTE_LABEL" "$DETAIL"
+        ;;
+      ALT:*)
+        printf '  %s\n' "${LINE#ALT:}"
+        ;;
+      END_VIOLATION)
+        printf '\n'
+        ;;
+    esac
+  done < "$VF"
+}
+
+if [[ -s "$HIGH_FILE" ]]; then
+  {
+    printf 'BASH INTERCEPTED: Dangerous command blocked\n'
+    print_violations "$HIGH_FILE" "Reason"
+    printf '  BLOCKED COMMAND: %s\n' "$TRUNCATED_CMD"
+  } >&2
+  exit 2
+fi
+
+if [[ -s "$MEDIUM_FILE" ]]; then
+  {
+    printf 'BASH ADVISORY: Potentially risky command (not blocked)\n'
+    print_violations "$MEDIUM_FILE" "Note"
+    printf '  COMMAND: %s\n' "$TRUNCATED_CMD"
+  } >&2
+  exit 0
+fi
+
+exit 0

package/hooks/dependency-audit-gate.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# PreToolUse hook: dependency-audit-gate.sh
+# Fires BEFORE every Bash tool call.
+# Detects package install commands (npm install, pnpm add, yarn add) and
+# verifies the package exists on the registry before allowing the install.
+#
+# Exit codes:
+#   0 = allow (not an install command, or package verified)
+#   2 = block (package not found on registry)
+
+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
+
+# ── 5. Detect package install commands ────────────────────────────────────────
+# Match: npm install <pkg>, npm i <pkg>, pnpm add <pkg>, yarn add <pkg>
+# Skip: npm install (no args), npm ci, npm install --save-dev (without new pkg)
+
+extract_packages() {
+  local cmd="$1"
+
+  # npm install/add with packages (skip flags and local paths)
+  if printf '%s' "$cmd" | grep -qiE '(npm[[:space:]]+(install|i|add)|pnpm[[:space:]]+(add|install)|yarn[[:space:]]+add)[[:space:]]'; then
+    # Extract the part after the install command
+    local after_cmd
+    after_cmd=$(printf '%s' "$cmd" | sed -E 's/.*(npm[[:space:]]+(install|i|add)|pnpm[[:space:]]+(add|install)|yarn[[:space:]]+add)[[:space:]]+//')
+
+    # Split on spaces and filter
+    for token in $after_cmd; do
+      # Skip flags
+      if [[ "$token" == -* ]]; then continue; fi
+      # Skip local paths
+      if [[ "$token" == ./* || "$token" == /* || "$token" == ../* ]]; then continue; fi
+      # Skip empty
+      if [[ -z "$token" ]]; then continue; fi
+      # Strip version specifier for lookup
+      local pkg_name
+      pkg_name=$(printf '%s' "$token" | sed -E 's/@[^@/]+$//')
+      # Handle scoped packages (@scope/name)
+      if [[ -z "$pkg_name" ]]; then
+        pkg_name="$token"
+      fi
+      printf '%s\n' "$pkg_name"
+    done
+  fi
+}
+
+PACKAGES=$(extract_packages "$CMD")
+
+if [[ -z "$PACKAGES" ]]; then
+  exit 0
+fi
+
+# ── 6. Verify packages exist on registry ──────────────────────────────────────
+FAILED=""
+CHECKED=0
+
+while IFS= read -r pkg; do
+  [[ -z "$pkg" ]] && continue
+  CHECKED=$((CHECKED + 1))
+
+  # Cap at 5 packages per command to avoid slow hook
+  if [[ $CHECKED -gt 5 ]]; then
+    break
+  fi
+
+  # Use npm view to check if package exists
+  # macOS doesn't have `timeout` by default, use a background process with kill
+  if command -v timeout >/dev/null 2>&1; then
+    if ! timeout 5 npm view "$pkg" name >/dev/null 2>&1; then
+      FAILED="${FAILED}  - ${pkg}\n"
+    fi
+  else
+    # Fallback: run npm view without timeout (still fast for simple checks)
+    if ! npm view "$pkg" name >/dev/null 2>&1; then
+      FAILED="${FAILED}  - ${pkg}\n"
+    fi
+  fi
+done <<< "$PACKAGES"
+
+if [[ -n "$FAILED" ]]; then
+  {
+    printf 'DEPENDENCY AUDIT: Package not found on npm registry\n'
+    printf '\n'
+    printf '  The following packages could not be verified:\n'
+    printf '%b' "$FAILED"
+    printf '\n'
+    printf '  Rule: All packages must exist on the npm registry before installation.\n'
+    printf '  Check: Is the package name spelled correctly? Does it exist on npmjs.com?\n'
+  } >&2
+  exit 2
+fi
+
+exit 0

package/hooks/env-file-protection.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# PreToolUse hook: env-file-protection.sh
+# Fires BEFORE every Bash tool call.
+# Blocks commands that read .env* / .envrc files via shell text utilities.
+#
+# Rationale: .env files contain credentials. Reading them via Bash exposes
+# the values in command output, logs, and agent transcripts. Load credentials
+# in code only (process.env, os.environ, etc.) — never via shell reads.
+#
+# Trigger: command matches ALL of:
+#   1. Uses a text-reading utility (list below)
+#   2. References a .env* or .envrc filename
+#
+# Exit codes:
+#   0 = allow
+#   2 = block (env file read detected)
+
+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
+
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+truncate_cmd() {
+  local STR="$1"
+  local MAX=100
+  if [[ ${#STR} -gt $MAX ]]; then
+    printf '%s' "${STR:0:$MAX}..."
+  else
+    printf '%s' "$STR"
+  fi
+}
+
+# Text-reading utilities (shell and common alternatives)
+# Defense-in-depth: this list catches the most common shell-based exfiltration
+# vectors. It is NOT exhaustive. Known gaps include:
+#   - Docker volume mounts (docker run -v .env:/...) — separate concern
+#   - Editor commands (vim, nano, code) — not typically used by agents
+#   - Redirects/process substitution (< .env) without a listed utility
+#   - Network tools (curl file://, nc) — low-risk in agent context
+# The goal is to block casual and accidental reads, not defeat a determined
+# adversary with shell access.
+PATTERN_UTILITY='(cat|head|tail|less|more|grep|sed|awk|bat|strings|printf|xargs|tee|jq|python3?[[:space:]]+-c|ruby[[:space:]]+-e)[[:space:]]'
+# Also catch: source/., cp (reads then writes elsewhere)
+PATTERN_SOURCE='(source|\.)[[:space:]]+[^;|&]*\.env'
+PATTERN_CP_ENV='cp[[:space:]]+[^;|&]*\.env'
+# .env* files or .envrc (direnv)
+PATTERN_ENV_FILE='(\.env[a-zA-Z0-9._-]*|\.envrc)([[:space:]]|"|'"'"'|$)'
+
+MATCHES_UTILITY=0
+MATCHES_ENV_FILE=0
+
+if printf '%s' "$CMD" | grep -qE "$PATTERN_UTILITY"; then
+  MATCHES_UTILITY=1
+fi
+
+if printf '%s' "$CMD" | grep -qE "$PATTERN_ENV_FILE"; then
+  MATCHES_ENV_FILE=1
+fi
+
+# Direct source/cp of .env files — always block
+if printf '%s' "$CMD" | grep -qE "$PATTERN_SOURCE" || \
+   printf '%s' "$CMD" | grep -qE "$PATTERN_CP_ENV"; then
+  TRUNCATED_CMD=$(truncate_cmd "$CMD")
+  {
+    printf 'ENV FILE PROTECTION: Direct sourcing or copying of .env files is blocked.\n'
+    printf '\n'
+    printf '  Command: %s\n' "$TRUNCATED_CMD"
+    printf '\n'
+    printf '  Rule: Load credentials in code only — never via shell source or cp.\n'
+    printf '  Use: process.env.VAR_NAME, os.environ["VAR_NAME"], etc.\n'
+  } >&2
+  exit 2
+fi
+
+if [[ $MATCHES_UTILITY -eq 1 && $MATCHES_ENV_FILE -eq 1 ]]; then
+  TRUNCATED_CMD=$(truncate_cmd "$CMD")
+  {
+    printf 'ENV FILE PROTECTION: Reading .env files via Bash is blocked.\n'
+    printf '\n'
+    printf '  Command: %s\n' "$TRUNCATED_CMD"
+    printf '\n'
+    printf '  Rule: Load credentials in code only, never via shell.\n'
+    printf '  Use: process.env.VAR_NAME, os.environ["VAR_NAME"], etc.\n'
+    printf '  .env files must not be read via shell utilities in agent sessions.\n'
+  } >&2
+  exit 2
+fi
+
+exit 0

package/hooks/pr-issue-link-gate.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# pr-issue-link-gate.sh — PreToolUse: Bash
+#
+# Ensures every `gh pr create` command references at least one GitHub issue
+# via closes/fixes/resolves #N syntax in the PR body. When the magic keyword
+# is present, GitHub automatically closes the linked issue when the PR merges
+# to the default branch and creates a cross-reference in the issue timeline.
+#
+# This gate is ADVISORY (exit 0) — it warns but does not block. Some PRs
+# legitimately have no linked issue (chores, hotfixes, release PRs). The
+# advisory gives the agent an opportunity to add the link before proceeding.
+#
+# Only active for Bash tool calls containing `gh pr create`.
+# JSONL-only projects (no GitHub) are unaffected — gh is unavailable there.
+#
+# Triggered by: PreToolUse — Bash tool
+
+set -euo pipefail
+
+# shellcheck source=_lib/common.sh
+source "$(dirname "$0")/_lib/common.sh"
+
+check_halt
+
+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 pr create
+if ! echo "$COMMAND" | grep -qE 'gh\s+pr\s+create'; then
+  exit 0
+fi
+
+require_jq
+
+# Check for closing keywords followed by an issue number
+# Accepted: closes #N, fixes #N, resolves #N (case-insensitive, any spacing)
+if echo "$COMMAND" | grep -qiE '(closes|fixes|resolves)\s+#[0-9]+'; then
+  exit 0
+fi
+
+# Advisory — warn but do not block.
+# Chore PRs, release PRs, and hotfixes may legitimately have no linked issue.
+printf 'PR ISSUE LINK ADVISORY: This PR does not reference a GitHub issue.\n' >&2
+printf '\n' >&2
+printf 'When a PR body includes a closing reference, GitHub automatically:\n' >&2
+printf '  - Closes the issue when the PR merges to the default branch\n' >&2
+printf '  - Creates a cross-reference in the issue timeline\n' >&2
+printf '  - Links the PR in the CHANGELOG context\n' >&2
+printf '\n' >&2
+printf 'Add to the --body:\n' >&2
+printf '  closes #N    closes one issue\n' >&2
+printf '  fixes #N     same effect\n' >&2
+printf '  resolves #N  same effect\n' >&2
+printf '  closes #N, closes #M   closes multiple issues\n' >&2
+printf '\n' >&2
+printf 'If this is a chore, release, or hotfix PR with no upstream issue, you may proceed.\n' >&2
+
+# Exit 0 — advisory only, does not block the PR creation
+exit 0