@bookedsolid/reagent 0.5.0 → 0.6.0

package/hooks/ci-config-protection.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# PostToolUse hook: ci-config-protection.sh
+# Fires AFTER every Write tool call.
+# Scans CI workflow files for dangerous permission or trust-boundary patterns.
+# Advisory only (exit 0) — warns loudly but does not block.
+#
+# Triggers only when file_path matches .github/workflows/
+#
+# Patterns checked:
+#   - permissions: write-all
+#   - pull_request_target (trust escalation trigger)
+#   - secrets: inherit
+#
+# Exit codes:
+#   0 = OK (including advisory warnings — not blocking)
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent 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)
+
+# ── Only trigger for .github/workflows/ paths ─────────────────────────────────
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" != *".github/workflows/"* ]]; then
+  exit 0
+fi
+
+# ── Extract written content ───────────────────────────────────────────────────
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+
+if [[ -z "$CONTENT" ]]; then
+  exit 0
+fi
+
+# ── Scan for dangerous CI patterns ───────────────────────────────────────────
+WARNINGS=()
+
+if printf '%s' "$CONTENT" | grep -qE 'permissions:[[:space:]]*write-all'; then
+  WARNINGS+=("permissions: write-all — grants all GitHub Actions permissions (read+write). Scope to only required permissions.")
+fi
+
+if printf '%s' "$CONTENT" | grep -qE 'pull_request_target'; then
+  WARNINGS+=("pull_request_target — runs with write permissions from the base repo in context of a PR. Dangerous if combined with checkout of PR head code.")
+fi
+
+if printf '%s' "$CONTENT" | grep -qE 'secrets:[[:space:]]*inherit'; then
+  WARNINGS+=("secrets: inherit — passes all secrets to called workflow. Only use with trusted reusable workflows in the same org.")
+fi
+
+if [[ ${#WARNINGS[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# ── Print advisory ────────────────────────────────────────────────────────────
+{
+  printf 'CI-CONFIG-PROTECTION: Potentially dangerous CI pattern in %s\n' "$(basename "$FILE_PATH")"
+  for WARNING in "${WARNINGS[@]}"; do
+    printf '  ADVISORY: %s\n' "$WARNING"
+  done
+  printf 'Note: This is advisory only. Review the workflow carefully before merging.\n'
+  printf 'Reference: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/\n'
+} >&2
+
+exit 0

package/hooks/file-size-guard.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# PreToolUse hook: file-size-guard.sh
+# Fires BEFORE every Write or Edit tool call.
+# Blocks writes where content byte length exceeds 512KB (524288 bytes).
+#
+# Content extraction:
+#   Write tool → tool_input.content
+#   Edit tool  → tool_input.new_string (checks the replacement only)
+#
+# Exit codes:
+#   0 = file size within limits — allow
+#   2 = file size exceeds limit — block
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# Extract content based on tool type
+if [[ "$TOOL_NAME" == "Write" ]]; then
+  CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+elif [[ "$TOOL_NAME" == "Edit" ]]; then
+  CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null)
+else
+  exit 0
+fi
+
+if [[ -z "$CONTENT" ]]; then
+  exit 0
+fi
+
+# ── Byte length check ─────────────────────────────────────────────────────────
+LIMIT=524288  # 512KB
+
+# Use printf + wc for portable byte counting
+BYTE_LENGTH=$(printf '%s' "$CONTENT" | wc -c | tr -d ' ')
+
+if [[ "$BYTE_LENGTH" -gt "$LIMIT" ]]; then
+  printf 'File size guard: %s bytes exceeds 512KB limit\n' "$BYTE_LENGTH" >&2
+  printf '  File: %s\n' "${FILE_PATH:-unknown}" >&2
+  printf 'Block reason: Writing files larger than 512KB risks memory issues and slow tool calls.\n' >&2
+  printf 'Fix: Split the content into multiple smaller files or chunks.\n' >&2
+  exit 2
+fi
+
+exit 0

package/hooks/git-config-guard.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# PreToolUse hook: git-config-guard.sh
+# Fires BEFORE every Bash tool call.
+# Blocks git config commands that modify security-critical git settings.
+#
+# Blocked patterns:
+#   - git config core.hooksPath  (redirects/disables hooks)
+#   - git config http.sslVerify  (disables TLS verification)
+#   - git config safe.directory  (bypasses ownership checks)
+#   - git config user.email/user.name (alters identity for commit signing)
+#
+# Exit codes:
+#   0 = safe — allow the command
+#   2 = dangerous git config detected — block
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent 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
+
+# Only proceed if git config is present
+if ! printf '%s' "$CMD" | grep -qiE 'git[[:space:]]+(config|(-[a-zA-Z]+[[:space:]]+)*config)'; then
+  exit 0
+fi
+
+# ── Check for dangerous settings ──────────────────────────────────────────────
+BLOCKED_REASON=""
+
+# core.hooksPath — redirects or disables git hooks
+if printf '%s' "$CMD" | grep -qiE 'git[[:space:]].*config.*core\.hookspath'; then
+  BLOCKED_REASON="core.hooksPath — redirecting the hooks directory disables all safety gates"
+fi
+
+# http.sslVerify false — disables TLS cert verification
+if [[ -z "$BLOCKED_REASON" ]] && printf '%s' "$CMD" | grep -qiE 'git[[:space:]].*config.*http\.sslverify'; then
+  if printf '%s' "$CMD" | grep -qiE 'http\.sslverify[[:space:]]+(false|0)'; then
+    BLOCKED_REASON="http.sslVerify false — disabling TLS verification enables MITM attacks"
+  fi
+fi
+
+# safe.directory — bypasses ownership safety checks
+if [[ -z "$BLOCKED_REASON" ]] && printf '%s' "$CMD" | grep -qiE 'git[[:space:]].*config.*safe\.directory'; then
+  BLOCKED_REASON="safe.directory — modifying this setting bypasses git ownership security checks"
+fi
+
+# user.email or user.name — altering commit identity
+if [[ -z "$BLOCKED_REASON" ]] && printf '%s' "$CMD" | grep -qiE 'git[[:space:]].*config[[:space:]].*(--global|--system)[[:space:]].*user\.(email|name)'; then
+  BLOCKED_REASON="user.email/user.name with --global/--system flag — alters git identity globally, affecting all repos"
+fi
+
+if [[ -n "$BLOCKED_REASON" ]]; then
+  printf 'GIT-CONFIG-GUARD: Dangerous git config command blocked\n' >&2
+  printf '  Reason: %s\n' "$BLOCKED_REASON" >&2
+  printf '  Command: %s\n' "$(printf '%s' "$CMD" | head -c 200)" >&2
+  printf 'Block reason: Modifying this git setting undermines repository security.\n' >&2
+  printf 'If you need to change this setting, request human escalation.\n' >&2
+  exit 2
+fi
+
+exit 0

package/hooks/import-guard.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# PostToolUse hook: import-guard.sh
+# Fires AFTER every Write tool call.
+# Scans written JS/TS/MJS content for dangerous import and eval patterns.
+# Advisory only (exit 0) — warns loudly but does not block.
+#
+# Triggers only for .ts, .js, .mjs files.
+#
+# Patterns checked:
+#   - require('child_process') or require("child_process")
+#   - require('vm') or require("vm")
+#   - eval(
+#   - new Function(
+#   - dynamic require with variable: require(variable)
+#
+# Exit codes:
+#   0 = OK (including advisory warnings — not blocking)
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent 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)
+
+# ── Only trigger for .ts, .js, .mjs files ────────────────────────────────────
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  *.ts|*.js|*.mjs) ;;
+  *) exit 0 ;;
+esac
+
+# ── Extract written content ───────────────────────────────────────────────────
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+
+if [[ -z "$CONTENT" ]]; then
+  exit 0
+fi
+
+# ── Scan for dangerous patterns ───────────────────────────────────────────────
+WARNINGS=()
+
+# require('child_process') or require("child_process")
+if printf '%s' "$CONTENT" | grep -qE "require\(['\"]child_process['\"]"; then
+  WARNINGS+=("require('child_process') — grants shell execution capability. Use safer alternatives or document the necessity.")
+fi
+
+# require('vm') or require("vm")
+if printf '%s' "$CONTENT" | grep -qE "require\(['\"]vm['\"]"; then
+  WARNINGS+=("require('vm') — Node.js VM module allows dynamic code execution. Ensure input is fully trusted and sandboxed.")
+fi
+
+# eval(
+if printf '%s' "$CONTENT" | grep -qE '\beval\('; then
+  WARNINGS+=("eval( — dynamic code evaluation is a code injection risk. Avoid unless the input is fully controlled and sanitized.")
+fi
+
+# new Function(
+if printf '%s' "$CONTENT" | grep -qE '\bnew[[:space:]]+Function\('; then
+  WARNINGS+=("new Function( — dynamic function construction is equivalent to eval. Avoid unless the input is fully controlled.")
+fi
+
+# Dynamic require with variable: require(variable) — not require('literal')
+if printf '%s' "$CONTENT" | grep -qE "require\([^'\"][^)]*\)"; then
+  WARNINGS+=("Dynamic require(variable) — loading modules by variable name can be exploited for path traversal. Prefer static imports.")
+fi
+
+if [[ ${#WARNINGS[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# ── Print advisory ────────────────────────────────────────────────────────────
+{
+  printf 'IMPORT-GUARD: Potentially dangerous import pattern in %s\n' "$(basename "$FILE_PATH")"
+  for WARNING in "${WARNINGS[@]}"; do
+    printf '  ADVISORY: %s\n' "$WARNING"
+  done
+  printf 'Note: This is advisory only. These patterns are not always unsafe but require review.\n'
+} >&2
+
+exit 0

package/hooks/network-exfil-guard.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# PreToolUse hook: network-exfil-guard.sh
+# Fires BEFORE every Bash tool call.
+# Blocks curl/wget commands that could exfiltrate data or execute remote code.
+#
+# Blocked patterns:
+#   - curl/wget piped to sh/bash (remote code execution)
+#   - curl/wget -d @file (posting file contents)
+#   - curl/wget to hosts not in the allowlist
+#
+# Allowlisted hosts:
+#   registry.npmjs.org, github.com, api.github.com, raw.githubusercontent.com
+#
+# Exit codes:
+#   0 = safe — allow the command
+#   2 = dangerous network pattern — block
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent 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
+
+# Only proceed if curl or wget is present
+if ! printf '%s' "$CMD" | grep -qiE '(^|[[:space:];]|&&|\|\|)(curl|wget)[[:space:]]'; then
+  exit 0
+fi
+
+# ── Check 1: Piped to shell (remote code execution) ───────────────────────────
+if printf '%s' "$CMD" | grep -qiE '(curl|wget)[^|]*\|[[:space:]]*(bash|sh|zsh|fish|dash)'; then
+  printf 'NETWORK-EXFIL-GUARD: Remote code execution pattern blocked\n' >&2
+  printf '  Pattern: curl/wget output piped to shell interpreter\n' >&2
+  printf '  Command: %s\n' "$(printf '%s' "$CMD" | head -c 200)" >&2
+  printf 'Block reason: Executing remote scripts without inspection is a supply chain risk.\n' >&2
+  printf 'Fix: Download first, inspect the script, then execute manually.\n' >&2
+  exit 2
+fi
+
+# ── Check 2: Posting file contents (-d @filename) ─────────────────────────────
+if printf '%s' "$CMD" | grep -qiE '(curl|wget).*-d[[:space:]]+@'; then
+  printf 'NETWORK-EXFIL-GUARD: File content upload pattern blocked\n' >&2
+  printf '  Pattern: curl -d @file posts file contents to remote host\n' >&2
+  printf '  Command: %s\n' "$(printf '%s' "$CMD" | head -c 200)" >&2
+  printf 'Block reason: Uploading local file contents to a remote host may exfiltrate sensitive data.\n' >&2
+  exit 2
+fi
+
+# ── Check 3: Host allowlist ───────────────────────────────────────────────────
+ALLOWLIST=(
+  "registry.npmjs.org"
+  "github.com"
+  "api.github.com"
+  "raw.githubusercontent.com"
+  "objects.githubusercontent.com"
+  "codeload.github.com"
+)
+
+# Extract URLs/hosts from the command
+# Look for http/https URLs and bare hostnames after curl/wget flags
+URLS=$(printf '%s' "$CMD" | grep -oE 'https?://[^[:space:]"'"'"']+' | head -20)
+
+if [[ -z "$URLS" ]]; then
+  # No parseable URLs — allow (could be a variable-based URL we can't inspect)
+  exit 0
+fi
+
+BLOCKED_HOST=""
+while IFS= read -r URL; do
+  [[ -z "$URL" ]] && continue
+  # Extract hostname
+  HOST=$(printf '%s' "$URL" | sed -E 's|https?://([^/:?#]+).*|\1|')
+
+  # Check against allowlist
+  ALLOWED=0
+  for ALLOWED_HOST in "${ALLOWLIST[@]}"; do
+    if [[ "$HOST" == "$ALLOWED_HOST" ]] || [[ "$HOST" == *".$ALLOWED_HOST" ]]; then
+      ALLOWED=1
+      break
+    fi
+  done
+
+  if [[ $ALLOWED -eq 0 ]]; then
+    BLOCKED_HOST="$HOST"
+    break
+  fi
+done <<< "$URLS"
+
+if [[ -n "$BLOCKED_HOST" ]]; then
+  printf 'NETWORK-EXFIL-GUARD: Request to non-allowlisted host blocked\n' >&2
+  printf '  Host: %s\n' "$BLOCKED_HOST" >&2
+  printf '  Command: %s\n' "$(printf '%s' "$CMD" | head -c 200)" >&2
+  printf 'Block reason: Network requests are restricted to known safe registries and GitHub.\n' >&2
+  printf 'Allowlisted hosts: registry.npmjs.org, github.com, api.github.com, raw.githubusercontent.com\n' >&2
+  printf 'If this host is needed, request human escalation to update the allowlist.\n' >&2
+  exit 2
+fi
+
+exit 0

package/hooks/output-validation.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# PostToolUse hook: output-validation.sh
+# Fires AFTER every Bash tool call.
+# Scans tool stdout for credential patterns and blocks (exit 2) if found.
+#
+# Content extraction:
+#   PostToolUse → tool_response (stdout from Bash)
+#
+# Exit codes:
+#   0 = no credential patterns detected — allow
+#   2 = credential pattern detected     — block
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+# ── Extract tool output ───────────────────────────────────────────────────────
+# PostToolUse payload has tool_response field containing the output
+OUTPUT=$(printf '%s' "$INPUT" | jq -r '
+  if .tool_response then
+    if (.tool_response | type) == "array" then
+      [.tool_response[] | .text // ""] | join("\n")
+    elif (.tool_response | type) == "string" then
+      .tool_response
+    else
+      (.tool_response.content // .tool_response.text // "") | if type == "array" then [.[] | .text // ""] | join("\n") else . end
+    end
+  else
+    ""
+  end
+' 2>/dev/null)
+
+if [[ -z "$OUTPUT" ]]; then
+  exit 0
+fi
+
+# ── Scan for credential patterns ──────────────────────────────────────────────
+FOUND=0
+PATTERN_LABEL=""
+
+# AWS access key (AKIA...)
+if printf '%s' "$OUTPUT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+  FOUND=1
+  PATTERN_LABEL="AWS Access Key ID (AKIA...)"
+fi
+
+# GitHub tokens
+if [[ $FOUND -eq 0 ]] && printf '%s' "$OUTPUT" | grep -qE 'gh[puors]_[A-Za-z0-9]{36}'; then
+  FOUND=1
+  PATTERN_LABEL="GitHub Personal Access Token (ghp_/ghs_/...)"
+fi
+
+# GitHub fine-grained PAT
+if [[ $FOUND -eq 0 ]] && printf '%s' "$OUTPUT" | grep -qE 'github_pat_[A-Za-z0-9_]{82}'; then
+  FOUND=1
+  PATTERN_LABEL="GitHub fine-grained PAT (github_pat_...)"
+fi
+
+# Generic API key pattern: sk-... (OpenAI, Anthropic, Stripe test)
+if [[ $FOUND -eq 0 ]] && printf '%s' "$OUTPUT" | grep -qE 'sk-[A-Za-z0-9_-]{20,}'; then
+  FOUND=1
+  PATTERN_LABEL="Generic API key (sk-...)"
+fi
+
+# Bearer token (with value)
+if [[ $FOUND -eq 0 ]] && printf '%s' "$OUTPUT" | grep -qE 'Bearer [A-Za-z0-9._-]{20,}'; then
+  FOUND=1
+  PATTERN_LABEL="Bearer token"
+fi
+
+# Private key header
+if [[ $FOUND -eq 0 ]] && printf '%s' "$OUTPUT" | grep -qE -- '-----BEGIN (RSA|EC|OPENSSH|PGP) PRIVATE KEY-----'; then
+  FOUND=1
+  PATTERN_LABEL="Private key block"
+fi
+
+if [[ $FOUND -eq 1 ]]; then
+  printf 'OUTPUT-VALIDATION: Credential pattern detected in Bash output\n' >&2
+  printf '  Pattern matched: %s\n' "$PATTERN_LABEL" >&2
+  printf 'Block reason: Tool output contains what appears to be a live credential.\n' >&2
+  printf 'The credential must not be logged, forwarded, or stored. Rotate it immediately if real.\n' >&2
+  exit 2
+fi
+
+exit 0

package/hooks/rate-limit-guard.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# PreToolUse hook: rate-limit-guard.sh
+# Fires BEFORE every Bash and Write tool call.
+# Blocks if more than 20 calls to the same tool occur within 60 seconds.
+# Uses a log file per tool in /tmp/reagent-rate-limit-{tool}.log.
+#
+# Exit codes:
+#   0 = within rate limit — allow
+#   2 = rate limit exceeded — block
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── Dependency check ──────────────────────────────────────────────────────────
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'REAGENT 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 ────────────────────────────────────────────────────────────────
+REAGENT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+HALT_FILE="${REAGENT_ROOT}/.reagent/HALT"
+if [ -f "$HALT_FILE" ]; then
+  printf 'REAGENT HALT: %s\nAll agent operations suspended. Run: reagent unfreeze\n' \
+    "$(head -c 1024 "$HALT_FILE" 2>/dev/null || echo 'Reason unknown')" >&2
+  exit 2
+fi
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+if [[ -z "$TOOL_NAME" ]]; then
+  exit 0
+fi
+
+# Sanitize tool name for use in filename
+SAFE_TOOL=$(printf '%s' "$TOOL_NAME" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9-')
+LOG_FILE="/tmp/reagent-rate-limit-${SAFE_TOOL}.log"
+
+LIMIT=20
+WINDOW=60  # seconds
+
+NOW=$(date +%s)
+CUTOFF=$(( NOW - WINDOW ))
+
+# ── Prune old entries and count recent calls ──────────────────────────────────
+RECENT_COUNT=0
+
+if [[ -f "$LOG_FILE" ]]; then
+  # Filter to only entries within the window, count them
+  RECENT_LINES=$(awk -v cutoff="$CUTOFF" '$1 > cutoff' "$LOG_FILE" 2>/dev/null || true)
+  RECENT_COUNT=$(printf '%s' "$RECENT_LINES" | grep -c '[0-9]' 2>/dev/null || echo "0")
+
+  # Rewrite log file with only recent entries (prune old ones)
+  printf '%s\n' "$RECENT_LINES" > "$LOG_FILE" 2>/dev/null || true
+else
+  # Create log file
+  touch "$LOG_FILE" 2>/dev/null || true
+fi
+
+# ── Check rate limit ──────────────────────────────────────────────────────────
+if [[ "$RECENT_COUNT" -ge "$LIMIT" ]]; then
+  printf 'RATE-LIMIT-GUARD: Tool call rate limit exceeded\n' >&2
+  printf '  Tool: %s\n' "$TOOL_NAME" >&2
+  printf '  Calls in last 60s: %d (limit: %d)\n' "$RECENT_COUNT" "$LIMIT" >&2
+  printf 'Block reason: More than %d %s calls within 60 seconds indicates a runaway loop.\n' "$LIMIT" "$TOOL_NAME" >&2
+  printf 'The session will resume normally once the rate window resets.\n' >&2
+  exit 2
+fi
+
+# ── Record this invocation ────────────────────────────────────────────────────
+printf '%d\n' "$NOW" >> "$LOG_FILE" 2>/dev/null || true
+
+exit 0