forge-orkes 0.42.0 → 0.44.0

package/template/.claude/hooks/block-dangerous-commands.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks destructive shell commands.
+# PreToolUse hook for Bash. Exit 2 = block. Exit 0 = allow.
+#
+# Deterministic belt-and-braces: this fires regardless of what the model decides,
+# so it catches the cases a model-driven skill (securing) would miss when skipped.
+#
+# Configurable via env:
+#   CLAUDE_PROTECTED_BRANCHES  comma list of branches push is refused to.
+#                              Default: main,master + git init.defaultBranch.
+#                              Set to "" (empty) to DISABLE the protected-branch
+#                              push check only — force-push, fs, db, and publish
+#                              guards still apply. Forge's own dev repo does this
+#                              because framework work legitimately lands on main.
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "jq is required for command protection hooks but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+contains_cmd() { printf '%s' "$COMMAND" | grep -qE "$1"; }
+contains_icmd() { printf '%s' "$COMMAND" | grep -qiE "$1"; }
+
+# ── Protected branch list ────────────────────────────────────────────────
+# Use ${VAR-default} (no colon) so an explicitly-empty value disables the check
+# while an unset value falls back to the default.
+DEFAULT_BRANCHES="main,master"
+if GIT_DEFAULT=$(git config --get init.defaultBranch 2>/dev/null) && [ -n "$GIT_DEFAULT" ]; then
+  DEFAULT_BRANCHES="$DEFAULT_BRANCHES,$GIT_DEFAULT"
+fi
+PROTECTED_BRANCHES="${CLAUDE_PROTECTED_BRANCHES-$DEFAULT_BRANCHES}"
+
+# ── Git push protections ────────────────────────────────────────────────
+if contains_cmd '(^|[;&|()]+[[:space:]]*)git[[:space:]]+push'; then
+  # Protected-branch checks are skipped when the list is empty.
+  if [ -n "$PROTECTED_BRANCHES" ]; then
+    BR_REGEX=$(printf '%s' "$PROTECTED_BRANCHES" | tr ',' '\n' | awk 'NF{printf "%s%s",sep,$0; sep="|"}')
+    # Explicit refspec to a protected branch (origin main, :main, HEAD:main)
+    if contains_cmd "git[[:space:]]+push[[:space:]]+[^[:space:]]+[[:space:]]+([^[:space:]]*:)?($BR_REGEX)(\$|[[:space:]])"; then
+      MATCHED_BRANCH=$(printf '%s' "$COMMAND" | grep -oE "($BR_REGEX)(\$|[[:space:]])" | head -1 | tr -d '[:space:]')
+      emit_deny "Blocked: push to protected branch '${MATCHED_BRANCH:-main}'. Use a feature branch and open a PR."
+    fi
+    if contains_cmd "git[[:space:]]+push.*:($BR_REGEX)(\$|[[:space:]])"; then
+      MATCHED_BRANCH=$(printf '%s' "$COMMAND" | grep -oE ":($BR_REGEX)(\$|[[:space:]])" | head -1 | tr -d ': [:space:]')
+      emit_deny "Blocked: push to protected branch '${MATCHED_BRANCH:-main}' via refspec. Use a feature branch and open a PR."
+    fi
+    # Bare `git push` while on protected branch
+    if contains_cmd 'git[[:space:]]+push[[:space:]]*($|[;&|])'; then
+      CURRENT=$(git branch --show-current 2>/dev/null || true)
+      if [ -n "$CURRENT" ] && printf '%s' ",$PROTECTED_BRANCHES," | grep -q ",$CURRENT,"; then
+        emit_deny "Blocked: you are on '$CURRENT' (a protected branch). Switch to a feature branch."
+      fi
+    fi
+  fi
+  # Force push (but allow --force-with-lease). Always enforced — Forge never force-pushes.
+  if contains_cmd 'git[[:space:]]+push([[:space:]]+[^[:space:]]+)*[[:space:]]+(-[a-zA-Z]*f[a-zA-Z]*|--force)([[:space:]=]|$)' \
+     && ! contains_cmd '\-\-force-with-lease'; then
+    emit_deny "Blocked: force push is not allowed. Use --force-with-lease if you must overwrite remote."
+  fi
+fi
+
+# ── Destructive filesystem operations ───────────────────────────────────
+# rm -rf targeting root, home, $HOME, $VAR (any unresolved expansion), or parent traversal.
+CMD_NOQUOTE=$(printf '%s' "$COMMAND" | tr -d "'\"")
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+(/([[:space:]]|\*|$)|~|\$HOME|\$[A-Za-z_][A-Za-z0-9_]*|\.\./\.\.)' ; then
+  emit_deny "Blocked: recursive force-delete on /, ~, \$HOME, an unresolved \$VAR, or .../.. path. Specify a concrete safe target."
+fi
+# rm -rf /usr, /etc, /var, /bin, etc.
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+/(usr|etc|var|bin|sbin|lib|opt|root|boot)([[:space:]/]|$)'; then
+  emit_deny "Blocked: recursive delete targeting a system directory."
+fi
+# rm -rf where the target is produced by $(...) or `...` command substitution.
+if printf '%s' "$CMD_NOQUOTE" | grep -qE 'rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-?[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+[^;&|]*(\$\(|`)'; then
+  emit_deny "Blocked: recursive force-delete with a shell-substituted target (\$(...) or \`...\`). Pass a literal path."
+fi
+
+# ── Dangerous database operations ───────────────────────────────────────
+if contains_icmd 'DROP[[:space:]]+(TABLE|DATABASE|SCHEMA)[[:space:]]+'; then
+  emit_deny "Blocked: DROP TABLE/DATABASE/SCHEMA detected. Run manually if intended."
+fi
+# DELETE FROM without a WHERE on the SAME statement (split on ';').
+if printf '%s\n' "$COMMAND" | awk '
+  BEGIN { IGNORECASE=1; RS=";" }
+  /DELETE[[:space:]]+FROM[[:space:]]+[A-Za-z_][A-Za-z0-9_.]*/ {
+    if ($0 !~ /WHERE/) { print "BAD"; exit }
+  }
+' | grep -q BAD; then
+  emit_deny "Blocked: DELETE FROM without a WHERE clause. Add a WHERE or run manually."
+fi
+if contains_icmd 'TRUNCATE[[:space:]]+TABLE'; then
+  emit_deny "Blocked: TRUNCATE TABLE detected. Run manually if intended."
+fi
+
+# ── Framework-specific destructive migration commands ───────────────────
+# These drop data. Block — require manual invocation against a dev DB.
+if contains_icmd '(php[[:space:]]+artisan[[:space:]]+(migrate:fresh|migrate:reset|migrate:refresh|db:wipe)|(rails|rake)[[:space:]]+db:(drop|reset)|prisma[[:space:]]+migrate[[:space:]]+reset|sequelize[[:space:]]+db:drop)([[:space:]]|$)'; then
+  emit_deny "Blocked: destructive migration command detected (drops/recreates the database). Run manually, and only against a dev DB."
+fi
+
+# ── Dangerous system commands ───────────────────────────────────────────
+# chmod: any world-writable/universal mode (0?777 or a+rwx)
+if contains_cmd 'chmod([[:space:]]+-[a-zA-Z]+)*[[:space:]]+0?777([[:space:]]|$)' \
+  || contains_cmd 'chmod([[:space:]]+-[a-zA-Z]+)*[[:space:]]+a\+rwx([[:space:]]|$)'; then
+  emit_deny "Blocked: chmod 777 / a+rwx grants everyone full access. Use restrictive perms."
+fi
+
+# curl/wget piped to a shell
+if contains_cmd '(curl|wget)[[:space:]].*\|[[:space:]]*(sudo[[:space:]]+)?(bash|sh|zsh|ksh|fish|dash|csh)([[:space:]]|$)'; then
+  emit_deny "Blocked: piping downloaded content directly to a shell is dangerous."
+fi
+
+# Disk / partition. Only REDIRECTIONS to /dev/ are destructive — `2>/dev/null` is not.
+if printf '%s' "$COMMAND" | grep -qE '(^|[^0-9&])>[[:space:]]*/dev/[a-zA-Z][a-zA-Z0-9]*' \
+   && ! printf '%s' "$COMMAND" | grep -qE '>[[:space:]]*/dev/(null|stdout|stderr|tty|zero|random|urandom)([[:space:]]|$)' ; then
+  emit_deny "Blocked: redirection into a raw device file can destroy data."
+fi
+if contains_cmd '(^|[;&|[:space:]])(mkfs|mkfs\.[a-z0-9]+)([[:space:]]|$)' \
+  || contains_cmd '(^|[;&|[:space:]])dd[[:space:]]+[^|]*(if|of)=/dev/[a-zA-Z]' ; then
+  emit_deny "Blocked: mkfs/dd against a device node. Irreversible data loss."
+fi
+
+# ── Destructive git ─────────────────────────────────────────────────────
+if contains_cmd 'git[[:space:]]+reset[[:space:]]+--hard'; then
+  emit_deny "Blocked: git reset --hard discards uncommitted changes permanently. Use git stash or commit first."
+fi
+if contains_cmd 'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'; then
+  emit_deny "Blocked: git clean -f permanently deletes untracked files."
+fi
+
+# ── Accidental package publishing ───────────────────────────────────────
+# Allow --dry-run variants. Covers the common package managers.
+publish_patterns=(
+  '(npm|yarn|pnpm|bun)[[:space:]]+publish'
+  'cargo[[:space:]]+publish'
+  'gem[[:space:]]+push'
+  'twine[[:space:]]+upload'
+  'uv[[:space:]]+publish'
+  'poetry[[:space:]]+publish'
+  'composer[[:space:]]+publish'
+)
+for pat in "${publish_patterns[@]}"; do
+  if contains_cmd "$pat" && ! contains_cmd '(^|[[:space:]])(--dry-run|-n)([[:space:]=]|$)'; then
+    emit_deny "Blocked: publishing packages should run in CI or be done manually, not via the agent."
+  fi
+done
+
+exit 0

package/template/.claude/hooks/forge-active-skill-guard.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Forge PreToolUse(Write|Edit) workflow guard.
+#
+# Blocks code edits when no Forge skill is driving the session, nudging the
+# operator to invoke /forge or /quick-tasking first. A skill IS active when
+# EITHER signal holds:
+#
+#   (a) the ephemeral marker .forge/.active-skill exists — written by the
+#       PostToolUse(Skill) hook on every Skill invocation; reliable for short
+#       skills (quick-tasking) but cleared between turns / at session
+#       boundaries, so a long executing run loses it mid-flight; OR
+#   (b) a milestone is mid-execution (current.status: executing) — the durable
+#       signal that survives across turns because it lives in a committed state
+#       file, not an ephemeral marker.
+#
+# (b) is the fix for the failure mode where the marker was cleared 3+ times in
+# one executing session and legitimate edits got blocked (forge#12). When (b)
+# holds we also re-assert the marker so the rest of the turn is cheap.
+#
+# Contract: exit 0 = allow, exit 2 = block with guidance. Advisory workflow
+# gate — the documented bypass is `touch .forge/.active-skill`.
+
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -n "$ROOT" ] || ROOT="$PWD"
+FORGE="$ROOT/.forge"
+
+# (a) marker present → active.
+[ -f "$FORGE/.active-skill" ] && exit 0
+
+# (b) a milestone is executing → durable "skill active" signal that outlives the
+#     marker. Match the indented `current.status: executing` line; a milestone
+#     file is small, so the grep is cheap.
+if ls "$FORGE"/state/milestone-*.yml >/dev/null 2>&1; then
+  if grep -qE '^[[:space:]]+status:[[:space:]]*executing([[:space:]]|$)' "$FORGE"/state/milestone-*.yml 2>/dev/null; then
+    # Self-heal: re-assert the marker so later checks this turn short-circuit at (a).
+    printf 'executing\n' > "$FORGE/.active-skill" 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+echo "[Forge] No active skill. Invoke /forge or /quick-tasking before editing code. To bypass: touch .forge/.active-skill" >&2
+exit 2

package/template/.claude/hooks/format-on-save.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Forge — runs the project's formatter after the agent edits a file.
+# PostToolUse hook for Edit|Write|MultiEdit. Always exits 0 — a formatting
+# failure must never block subsequent work.
+#
+# "Most specific project config wins". A formatter only runs when BOTH the tool
+# and the project's config for it are present, so this never fires against repos
+# that haven't opted in.
+
+set -uo pipefail
+
+# jq missing → silently skip. Never block work over formatting.
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+EXT="${FILE_PATH##*.}"
+EXT_LC=$(printf '%s' "$EXT" | tr '[:upper:]' '[:lower:]')
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+has_file() { [ -f "$REPO_ROOT/$1" ]; }
+has_any()  { for f in "$@"; do has_file "$f" && return 0; done; return 1; }
+pyproject_has() { has_file "pyproject.toml" && grep -q "^\[$1\]" "$REPO_ROOT/pyproject.toml" 2>/dev/null; }
+pkgjson_has_key() { has_file "package.json" && grep -q "\"$1\"" "$REPO_ROOT/package.json" 2>/dev/null; }
+
+run() {
+  printf 'format-on-save: %s\n' "$*" >&2
+  "$@" >/dev/null 2>&1 || true
+}
+
+case "$EXT_LC" in
+  # ── Python ────────────────────────────────────────────────────────────
+  py)
+    if command -v ruff >/dev/null 2>&1 \
+       && ( has_any "ruff.toml" ".ruff.toml" || pyproject_has "tool.ruff" ); then
+      run ruff format "$FILE_PATH"
+      run ruff check --fix "$FILE_PATH"
+    elif command -v black >/dev/null 2>&1 && pyproject_has "tool.black"; then
+      run black --quiet "$FILE_PATH"
+      command -v isort >/dev/null 2>&1 && run isort --quiet "$FILE_PATH"
+    fi
+    ;;
+  # ── PHP / Laravel ─────────────────────────────────────────────────────
+  php)
+    if [ -x "$REPO_ROOT/vendor/bin/pint" ]; then
+      run "$REPO_ROOT/vendor/bin/pint" "$FILE_PATH"
+    elif command -v php-cs-fixer >/dev/null 2>&1 && has_any ".php-cs-fixer.php" ".php-cs-fixer.dist.php"; then
+      run php-cs-fixer fix "$FILE_PATH"
+    fi
+    ;;
+  # ── JS / TS / Vue / CSS / HTML / JSON / MD / YAML ─────────────────────
+  js|jsx|ts|tsx|vue|mjs|cjs|css|scss|sass|less|html|json|jsonc|md|mdx|yml|yaml)
+    if has_any "biome.json" "biome.jsonc" && [ -x "$REPO_ROOT/node_modules/.bin/biome" ]; then
+      run "$REPO_ROOT/node_modules/.bin/biome" format --write "$FILE_PATH"
+      run "$REPO_ROOT/node_modules/.bin/biome" check --write "$FILE_PATH"
+    else
+      if [ -x "$REPO_ROOT/node_modules/.bin/prettier" ] \
+         && ( has_any ".prettierrc" ".prettierrc.json" ".prettierrc.js" ".prettierrc.cjs" ".prettierrc.mjs" ".prettierrc.yaml" ".prettierrc.yml" "prettier.config.js" "prettier.config.cjs" "prettier.config.mjs" \
+              || pkgjson_has_key "prettier" ); then
+        run "$REPO_ROOT/node_modules/.bin/prettier" --write --log-level=silent "$FILE_PATH"
+      fi
+      case "$EXT_LC" in
+        js|jsx|ts|tsx|vue|mjs|cjs)
+          if [ -x "$REPO_ROOT/node_modules/.bin/eslint" ] \
+             && ( has_any ".eslintrc" ".eslintrc.js" ".eslintrc.cjs" ".eslintrc.json" ".eslintrc.yml" ".eslintrc.yaml" "eslint.config.js" "eslint.config.mjs" "eslint.config.cjs" "eslint.config.ts" \
+                  || pkgjson_has_key "eslintConfig" ); then
+            run "$REPO_ROOT/node_modules/.bin/eslint" --fix "$FILE_PATH"
+          fi
+          ;;
+      esac
+    fi
+    ;;
+  # ── Rust ──────────────────────────────────────────────────────────────
+  rs)
+    command -v rustfmt >/dev/null 2>&1 && run rustfmt "$FILE_PATH"
+    ;;
+  # ── Go ────────────────────────────────────────────────────────────────
+  go)
+    if command -v goimports >/dev/null 2>&1; then
+      run goimports -w "$FILE_PATH"
+    elif command -v gofmt >/dev/null 2>&1; then
+      run gofmt -w "$FILE_PATH"
+    fi
+    ;;
+  # ── Shell ─────────────────────────────────────────────────────────────
+  sh|bash)
+    command -v shfmt >/dev/null 2>&1 && run shfmt -w "$FILE_PATH"
+    ;;
+esac
+
+exit 0

package/template/.claude/hooks/protect-files.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks edits to sensitive or generated files.
+# PreToolUse hook for Edit|Write. Exit 2 = block. Exit 0 = allow.
+
+set -uo pipefail
+
+emit() {
+  # $1 = decision (deny|ask) ; $2 = reason
+  local decision="$1"
+  local reason="${2//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s","permissionDecisionReason":"%s"}}\n' "$decision" "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit deny "jq is required for file protection hooks but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+
+BASENAME=$(basename -- "$FILE_PATH")
+BASENAME_LC=$(printf '%s' "$BASENAME" | tr '[:upper:]' '[:lower:]')
+PATH_LC=$(printf '%s' "$FILE_PATH" | tr '[:upper:]' '[:lower:]')
+
+# Allowlist: template/example env files are meant to be checked in and edited.
+case "$BASENAME_LC" in
+  .env.example|.env.sample|.env.dist|.env.template)
+    exit 0
+    ;;
+esac
+
+# Protected basename patterns (matched case-insensitively).
+PROTECTED_PATTERNS=(
+  ".env"
+  ".env.*"
+  "*.pem"
+  "*.key"
+  "*.crt"
+  "*.p12"
+  "*.pfx"
+  "id_rsa"
+  "id_ed25519"
+  "credentials.json"
+  ".npmrc"
+  ".pypirc"
+  ".composer-auth.json"
+  "auth.json"
+  # Lock files — update through the package manager, never by hand.
+  "package-lock.json"
+  "yarn.lock"
+  "pnpm-lock.yaml"
+  "composer.lock"
+  "uv.lock"
+  "poetry.lock"
+  "Gemfile.lock"
+  "Cargo.lock"
+  "go.sum"
+  # Generated / minified
+  "*.gen.ts"
+  "*.generated.*"
+  "*.min.js"
+  "*.min.css"
+)
+
+shopt -s nocasematch 2>/dev/null || true
+for pattern in "${PROTECTED_PATTERNS[@]}"; do
+  case "$BASENAME_LC" in
+    $pattern)
+      emit deny "Protected file: $BASENAME matches pattern '$pattern'. Edit via the package manager or the appropriate secret store."
+      ;;
+  esac
+done
+
+# Sensitive directories (lower-cased path for case-insensitive matches).
+case "$PATH_LC" in
+  .git/*|*/.git/*)
+    emit deny "Cannot edit files inside .git/" ;;
+  secrets/*|*/secrets/*)
+    emit deny "Cannot edit files inside secrets/" ;;
+  .secrets/*|*/.secrets/*)
+    emit deny "Cannot edit files inside .secrets/" ;;
+  .env|.env.*|*/.env|*/.env.*)
+    emit deny "Cannot edit .env files" ;;
+esac
+
+# Framework-authoring files. In a normal project these are re-synced via
+# /upgrading, never hand-edited — so we block hooks and prompt on settings.
+# FORGE_ALLOW_HOOK_EDITS=1 lifts both, set only in the Forge framework repo
+# itself (where authoring hooks and settings IS the work).
+if [ -z "${FORGE_ALLOW_HOOK_EDITS:-}" ]; then
+  case "$PATH_LC" in
+    .claude/hooks/*|*/.claude/hooks/*)
+      emit deny "Cannot edit hook scripts — these enforce safety boundaries. Update them in the framework repo and re-sync (/upgrading)." ;;
+    .claude/settings.json|*/.claude/settings.json|.claude/settings.local.json|*/.claude/settings.local.json)
+      emit ask "Editing settings.json — this controls permissions and hooks. Confirm this change." ;;
+  esac
+fi
+
+exit 0

package/template/.claude/hooks/scan-secrets.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — scans file content for accidental secrets before writing.
+# PreToolUse hook for Edit|Write. Exit 2 = block (decision "ask" so the user can
+# override for genuine test fixtures). Exit 0 = allow.
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "jq is required for secret scanning but is not installed. Install with: brew install jq (macOS) or apt install jq (Linux)."
+fi
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+if [ "$TOOL_NAME" = "Write" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+else
+  exit 0
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+MATCHES=""
+
+# AWS Access Key IDs
+if echo "$CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+  MATCHES="$MATCHES AWS access key (AKIA...);"
+fi
+# AWS Secret Access Keys (40 chars base64 after a key assignment)
+if echo "$CONTENT" | grep -qiE '(aws_secret_access_key|secret_key)[[:space:]]*[=:][[:space:]]*["\x27]?[A-Za-z0-9/+=]{40}'; then
+  MATCHES="$MATCHES AWS secret key;"
+fi
+# GitHub tokens (PAT, OAuth, App)
+if echo "$CONTENT" | grep -qE '(ghp_|gho_|ghs_|ghr_|github_pat_)[a-zA-Z0-9_]{20,}'; then
+  MATCHES="$MATCHES GitHub token;"
+fi
+# OpenAI / Anthropic / Stripe style keys (sk-...)
+if echo "$CONTENT" | grep -qE 'sk-[a-zA-Z0-9]{20,}'; then
+  MATCHES="$MATCHES API key (sk-...);"
+fi
+# Anthropic-specific keys
+if echo "$CONTENT" | grep -qE 'sk-ant-[a-zA-Z0-9_-]{20,}'; then
+  MATCHES="$MATCHES Anthropic API key;"
+fi
+# Slack tokens
+if echo "$CONTENT" | grep -qE 'xox[bpras]-[0-9a-zA-Z-]{10,}'; then
+  MATCHES="$MATCHES Slack token;"
+fi
+# Google API keys
+if echo "$CONTENT" | grep -qE 'AIza[0-9A-Za-z_-]{35}'; then
+  MATCHES="$MATCHES Google API key;"
+fi
+# Private key blocks
+if echo "$CONTENT" | grep -qE -- '-----BEGIN[[:space:]]+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----'; then
+  MATCHES="$MATCHES private key block;"
+fi
+# Connection strings with embedded credentials
+if echo "$CONTENT" | grep -qE '(mongodb|postgres|postgresql|mysql|redis|amqp|smtp|mssql)(\+[a-z]+)?://[^:[:space:]]+:[^@[:space:]]+@'; then
+  MATCHES="$MATCHES connection string with credentials;"
+fi
+# Laravel APP_KEY with a real base64 value (not a placeholder)
+if echo "$CONTENT" | grep -qE 'APP_KEY[[:space:]]*=[[:space:]]*base64:[A-Za-z0-9+/=]{40,}'; then
+  MATCHES="$MATCHES Laravel APP_KEY;"
+fi
+# Generic password/secret/token assignments with literal string values.
+# Excludes env var references (process.env, os.environ, getenv, ${...}, ENV[, env(, config()).
+if echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27][^"\x27]{8,}["\x27]' && \
+   ! echo "$CONTENT" | grep -qiE '(password|secret|token|api_key|apikey|api_secret)[[:space:]]*[=:][[:space:]]*["\x27]?(process\.env|os\.environ|getenv|\$\{|ENV\[|env\(|config\()'; then
+  MATCHES="$MATCHES hardcoded credential;"
+fi
+
+if [ -n "$MATCHES" ]; then
+  # "ask" not "deny" — warn but let the user override (could be a fixture).
+  REASON="Possible secret detected in content:$MATCHES Review carefully before allowing."
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/tests/README.md

@@ -0,0 +1,76 @@
+# Hook tests
+
+Data-driven test harness for the Claude Code hooks in `.claude/hooks/`. Cases live in JSON files, the driver pipes each input to the hook and checks the exit code and stdout.
+
+## Running
+
+```bash
+# All hooks
+.claude/hooks/tests/run.sh
+
+# One hook
+.claude/hooks/tests/run.sh protect-files
+.claude/hooks/tests/run.sh block-dangerous-commands
+.claude/hooks/tests/run.sh warn-large-files
+```
+
+Requires `jq`. Install with `brew install jq` (macOS) or `apt install jq` (Linux).
+
+## Layout
+
+```
+tests/
+  run.sh                              # driver
+  cases/
+    <hook-name>.cases.json            # test cases for .claude/hooks/<hook-name>.sh
+```
+
+The driver matches cases to hook scripts by filename: `cases/protect-files.cases.json` runs against `.claude/hooks/protect-files.sh`. If the hook script is missing or not executable, the test file is skipped.
+
+## Case schema
+
+Each case file is a JSON array of objects:
+
+```json
+{
+  "name": "denies editing .env at repo root",
+  "input": { "tool_name": "Edit", "tool_input": { "file_path": ".env" } },
+  "expect_exit": 2,
+  "expect_stdout_contains": "\"permissionDecision\":\"deny\"",
+  "expect_stdout_not_contains": "allow"
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | Human-readable test label |
+| `input` | yes | JSON piped to the hook on stdin — matches Claude Code's hook input format |
+| `expect_exit` | no (default 0) | Expected process exit code. `2` = permission denied, `0` = allowed |
+| `expect_stdout_contains` | no | Substring that must appear in stdout (combined with stderr) |
+| `expect_stdout_not_contains` | no | Substring that must NOT appear |
+
+The driver combines stdout and stderr, so a hook that writes errors to stderr is still matched against `expect_stdout_contains`.
+
+## Adding a new case
+
+1. Pick the right case file (`cases/<hook>.cases.json`) — or create one if you are testing a new hook.
+2. Append a new object to the array. Keep the name as a sentence that reads like a spec: `"denies rm -rf $HOME"`, `"allows artisan migrate"`.
+3. Run the hook-specific filter to verify: `.claude/hooks/tests/run.sh <hook>`.
+
+## Adding a new hook
+
+1. Write the hook at `.claude/hooks/<hook-name>.sh` and `chmod +x` it.
+2. Create `cases/<hook-name>.cases.json` with at least one deny case, one allow case, and one no-op case (missing input field).
+3. Run `.claude/hooks/tests/run.sh <hook-name>`.
+
+## What good coverage looks like
+
+For a `deny`/`allow` style hook, every case file should include:
+
+- At least one **deny** per distinct rule the hook implements (so the hook script cannot be trivially gutted without turning tests red).
+- At least one **allow** that sits right next to a deny path (e.g. `git push origin main` denies, `git push origin feature/foo` allows) — proves the pattern is specific, not blanket.
+- One **no-op** case where the hook input does not match the shape the hook expects (e.g. `file_path` missing, `command` empty) — proves the hook fails open for irrelevant events.
+
+## Why this lives here
+
+Hooks run on every tool call the agent makes. If they regress silently, either the agent starts bypassing real protections, or innocent edits start getting blocked and the hooks get disabled in frustration. A small test harness catches both before they land.