forge-orkes 0.42.0 → 0.46.0

package/template/.claude/hooks/tests/cases/scan-secrets.cases.json

@@ -0,0 +1,218 @@
+[
+  {
+    "name": "flags AWS access key ID on Write",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "AWS_KEY = 'AKIAIOSFODNN7EXAMPLE'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "\"permissionDecision\":\"ask\""
+  },
+  {
+    "name": "flags AWS secret access key assignment",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "aws_secret_access_key = \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\""
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "AWS secret key"
+  },
+  {
+    "name": "flags GitHub personal access token",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "GH_TOKEN = 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "GitHub token"
+  },
+  {
+    "name": "flags Anthropic API key",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "ANTHROPIC_API_KEY = 'sk-ant-abcdefghijklmnopqrstuv'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Anthropic API key"
+  },
+  {
+    "name": "flags Slack bot token",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "content": "SLACK_TOKEN = 'xoxb-1234567890-abcdefghijk'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Slack token"
+  },
+  {
+    "name": "flags a private key block",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "secrets/key.pem",
+        "content": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "private key block"
+  },
+  {
+    "name": "flags Postgres connection string with embedded credentials",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env.example",
+        "content": "DATABASE_URL=postgres://admin:s3cretP@ss@db.example.com:5432/app"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "connection string with credentials"
+  },
+  {
+    "name": "flags Laravel APP_KEY with real base64 value",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env",
+        "content": "APP_KEY=base64:IAm40CharsOfBase64EncodedAppKeyForLaravelApp="
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Laravel APP_KEY"
+  },
+  {
+    "name": "flags hardcoded password assignment with literal value",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "app/Services/MailService.php",
+        "content": "$password = \"realPassword123\";"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "hardcoded credential"
+  },
+  {
+    "name": "flags secret found inside an Edit new_string",
+    "input": {
+      "tool_name": "Edit",
+      "tool_input": {
+        "file_path": "src/config.py",
+        "old_string": "TOKEN = ''",
+        "new_string": "TOKEN = 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'"
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "GitHub token"
+  },
+  {
+    "name": "allows password field that references process.env",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/db.js",
+        "content": "const password = process.env.DB_PASSWORD;"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows password field that uses Laravel env() helper",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "config/database.php",
+        "content": "'password' => env('DB_PASSWORD', ''),"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows password mentioned only in a comment",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "app/Services/MailService.php",
+        "content": "// Remember to set the MAIL_PASSWORD in .env\n$mailer = new Mailer();"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows empty content",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/empty.py",
+        "content": ""
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "ignores non-Write/Edit tools",
+    "input": {
+      "tool_name": "Bash",
+      "tool_input": {
+        "command": "echo ghp_abcdefghijklmnopqrstuvwxyz0123456789"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows an APP_KEY placeholder shorter than 40 chars",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": ".env.example",
+        "content": "APP_KEY=base64:TODO_RUN_ARTISAN_KEY_GENERATE"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows a regular Python file with no secrets",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "src/utils.py",
+        "content": "def add(a: int, b: int) -> int:\n    return a + b\n"
+      }
+    },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "flags a Google API key",
+    "input": {
+      "tool_name": "Write",
+      "tool_input": {
+        "file_path": "config.js",
+        "content": "const key = \"AIzaSyD-1234567890abcdefGHIJKLMNOPqrstuv\""
+      }
+    },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Google API key"
+  }
+]

package/template/.claude/hooks/tests/cases/warn-large-files.cases.json

@@ -0,0 +1,146 @@
+[
+  {
+    "name": "denies writing into node_modules",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "node_modules/react/index.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "node_modules"
+  },
+  {
+    "name": "denies writing into nested node_modules",
+    "input": { "tool_name": "Edit", "tool_input": { "file_path": "apps/web/node_modules/foo/index.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "node_modules"
+  },
+  {
+    "name": "denies writing into dist",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "dist/bundle.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "build output"
+  },
+  {
+    "name": "denies writing into build",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "build/app.js" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "build output"
+  },
+  {
+    "name": "denies writing into vendor",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "vendor/laravel/framework/src/foo.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "vendor"
+  },
+  {
+    "name": "denies writing into storage/framework",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "storage/framework/views/cached.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "framework caches"
+  },
+  {
+    "name": "denies writing into bootstrap/cache",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "bootstrap/cache/config.php" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "framework caches"
+  },
+  {
+    "name": "denies writing into storage/logs",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "storage/logs/laravel.log" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "runtime logs"
+  },
+  {
+    "name": "denies writing into __pycache__",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/__pycache__/module.cpython-311.pyc" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "__pycache__"
+  },
+  {
+    "name": "denies writing into .venv",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".venv/lib/python3.11/site-packages/foo.py" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "virtual environment"
+  },
+  {
+    "name": "denies writing into .pytest_cache",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".pytest_cache/v/cache/lastfailed" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "Python tool caches"
+  },
+  {
+    "name": "denies writing into coverage",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "coverage/lcov.info" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "coverage"
+  },
+  {
+    "name": "denies writing a .DS_Store",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".DS_Store" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": ".DS_Store"
+  },
+  {
+    "name": "denies writing a .so binary",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "lib/native.so" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "binary files"
+  },
+  {
+    "name": "denies writing a .exe",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "bin/tool.exe" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "binary files"
+  },
+  {
+    "name": "denies writing a .zip archive",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "release/bundle.zip" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "archive"
+  },
+  {
+    "name": "denies writing a .phar",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "tools/composer.phar" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "archive"
+  },
+  {
+    "name": "denies writing an mp4",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "assets/intro.mp4" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "media files"
+  },
+  {
+    "name": "denies writing a .pyc",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/module.pyc" } },
+    "expect_exit": 2,
+    "expect_stdout_contains": "bytecode"
+  },
+  {
+    "name": "allows writing a regular Python file",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/domains/service.py" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a regular PHP file",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "app/Cerebro/Domains/Services/DomainService.php" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a Vue file in resources",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": "resources/js/pages/domains/Index.vue" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "allows writing a .gitignore",
+    "input": { "tool_name": "Write", "tool_input": { "file_path": ".gitignore" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  },
+  {
+    "name": "no-op when file_path is missing",
+    "input": { "tool_name": "Bash", "tool_input": { "command": "ls" } },
+    "expect_exit": 0,
+    "expect_stdout_not_contains": "permissionDecision"
+  }
+]

package/template/.claude/hooks/tests/forge-reserve.test.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-reserve.sh (ADR-021).
+#
+# Needs no network and no fixtures beyond a temp dir. Each case builds a throwaway
+# git repo, seeds ids, and asserts the helper's stdout + file side effects. Run:
+#   ./.claude/hooks/tests/forge-reserve.test.sh
+# Exits 0 iff every case passes; non-zero on any failure. Self-cleans on exit.
+set -u
+
+# Resolve the helper from THIS script's own location so the test works from any cwd.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../forge-reserve.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+
+# One temp root; every throwaway repo lives under it; single cleanup.
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+check() { # desc, actual, expected
+  if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi
+}
+
+# Fresh repo on branch `main` (symbolic-ref sets the unborn branch name portably,
+# no git ≥2.28 -b flag needed). Prints its path.
+new_repo() {
+  d="$ROOT/repo.$1"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD refs/heads/main
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  printf '%s\n' "$d"
+}
+
+# --- Case 1: allocation from in-tree ADR ------------------------------------
+d="$(new_repo case1)"; cd "$d"
+mkdir -p docs/decisions
+: > docs/decisions/ADR-005-something.md
+git add -A && git commit -qm init
+got="$("$HELPER" adr --milestone m-x)"
+check "case1 in-tree ADR-005 -> ADR-006" "$got" "ADR-006"
+
+# --- Case 2: ledger beats tree (uncommitted sibling — the ADR-016-blind case) -
+d="$(new_repo case2)"; cd "$d"
+mkdir -p docs/decisions
+: > docs/decisions/ADR-005-something.md
+git add -A && git commit -qm init
+mkdir -p .git/forge
+printf 'adr\tADR-050\tm-x\t2026-01-01T00:00:00Z\n' > .git/forge/id-reservations
+got="$("$HELPER" adr --milestone m-x)"
+check "case2 ledger(ADR-050) beats tree(ADR-005) -> ADR-051" "$got" "ADR-051"
+
+# --- Case 3: main:reservations.yml floor (committed, then removed from tree) --
+d="$(new_repo case3)"; cd "$d"
+mkdir -p .forge
+cat > .forge/reservations.yml <<'YML'
+reservations:
+  - kind: fr
+    id: FR-200
+    milestone: m-x
+    reserved_at: "2026-01-01"
+    summary: "seed"
+YML
+git add -A && git commit -qm init
+rm .forge/reservations.yml   # gone from the working tree; survives only on main
+got="$("$HELPER" fr --milestone m-x)"
+check "case3 main floor FR-200 -> FR-201" "$got" "FR-201"
+
+# --- Case 4: dual-write side effects + no commit made by the helper ----------
+d="$(new_repo case4)"; cd "$d"
+git commit --allow-empty -qm init
+ledger=".git/forge/id-reservations"
+before=0; [ -f "$ledger" ] && before="$(wc -l < "$ledger" | tr -d ' ')"
+got="$("$HELPER" nfr --milestone m-x --summary "dual write check")"
+after="$(wc -l < "$ledger" | tr -d ' ')"
+check "case4 ledger grew by exactly 1" "$((after - before))" "1"
+if grep -q "id: $got" .forge/reservations.yml; then
+  pass "case4 reservations.yml has a $got block"
+else
+  fail "case4 reservations.yml missing $got block"
+fi
+check "case4 no new commit (HEAD count still 1)" "$(git rev-list --count HEAD)" "1"
+if [ -n "$(git status --porcelain .forge/reservations.yml)" ]; then
+  pass "case4 reservations.yml is uncommitted (dirty)"
+else
+  fail "case4 reservations.yml unexpectedly clean"
+fi
+
+# --- Case 5: unknown kind — non-zero exit, empty stdout, nothing written -----
+d="$(new_repo case5)"; cd "$d"
+git commit --allow-empty -qm init
+out="$("$HELPER" zzz --milestone m-x 2>/dev/null)"; rc=$?
+check "case5 unknown kind exits non-zero" "$( [ "$rc" -ne 0 ] && echo yes || echo no )" "yes"
+check "case5 unknown kind prints nothing on stdout" "$out" ""
+[ ! -f .git/forge/id-reservations ] && pass "case5 ledger not created" || fail "case5 ledger was created"
+[ ! -f .forge/reservations.yml ] && pass "case5 reservations.yml not created" || fail "case5 reservations.yml was created"
+
+# --- Case 6: N-way concurrency yields N distinct ids, N ledger lines ---------
+d="$(new_repo case6)"; cd "$d"
+git commit --allow-empty -qm init
+outdir="$d/outs"; mkdir -p "$outdir"
+N=8
+i=1
+while [ "$i" -le "$N" ]; do
+  ( "$HELPER" fr --milestone m-x > "$outdir/out.$i" 2>/dev/null ) &
+  i=$((i + 1))
+done
+wait
+distinct="$(cat "$outdir"/out.* | sort -u | grep -c .)"
+check "case6 $N concurrent runs -> $N distinct ids" "$distinct" "$N"
+ledger_lines="$(grep -c '^fr	' .git/forge/id-reservations)"
+check "case6 $N distinct ledger fr lines" "$ledger_lines" "$N"
+
+# --- Report -----------------------------------------------------------------
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/hooks/tests/run.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Runs all hook test cases and reports pass/fail.
+#
+# Usage:
+#   .claude/hooks/tests/run.sh              # run all hooks
+#   .claude/hooks/tests/run.sh protect-files  # run one hook
+#
+# Case files live in .claude/hooks/tests/cases/<hook>.cases.json.
+# Each case is an object with: name, input, expect_exit, expect_stdout_contains,
+# expect_stdout_not_contains. See README.md for the full schema.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOKS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+CASES_DIR="$SCRIPT_DIR/cases"
+
+# Hermetic run: cases assert default behavior, so neutralise the env knobs that
+# a maintainer's session may set (Forge's own dev repo exports both). Without
+# this, FORGE_ALLOW_HOOK_EDITS=1 lifts protect-files' hook/settings guards and an
+# empty CLAUDE_PROTECTED_BRANCHES disables the push checks — turning real cases red.
+unset FORGE_ALLOW_HOOK_EDITS
+unset CLAUDE_PROTECTED_BRANCHES
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'jq is required to run hook tests. Install with: brew install jq (macOS) or apt install jq (Linux).\n' >&2
+  exit 1
+fi
+
+# Optional single-hook filter.
+FILTER="${1:-}"
+
+PASSED=0
+FAILED=0
+SKIPPED=0
+FAILURES=()
+
+run_case() {
+  local hook_script="$1" case_json="$2"
+  local name input expect_exit expect_contains expect_not_contains
+  name=$(printf '%s' "$case_json" | jq -r '.name')
+  input=$(printf '%s' "$case_json" | jq -c '.input')
+  expect_exit=$(printf '%s' "$case_json" | jq -r '.expect_exit // 0')
+  expect_contains=$(printf '%s' "$case_json" | jq -r '.expect_stdout_contains // ""')
+  expect_not_contains=$(printf '%s' "$case_json" | jq -r '.expect_stdout_not_contains // ""')
+
+  local output rc
+  output=$(printf '%s' "$input" | "$hook_script" 2>&1)
+  rc=$?
+
+  local reasons=()
+  if [ "$rc" -ne "$expect_exit" ]; then
+    reasons+=("exit $rc, expected $expect_exit")
+  fi
+  if [ -n "$expect_contains" ] && ! printf '%s' "$output" | grep -qF -- "$expect_contains"; then
+    reasons+=("stdout missing: $expect_contains")
+  fi
+  if [ -n "$expect_not_contains" ] && printf '%s' "$output" | grep -qF -- "$expect_not_contains"; then
+    reasons+=("stdout should not contain: $expect_not_contains")
+  fi
+
+  if [ "${#reasons[@]}" -eq 0 ]; then
+    printf '  [PASS] %s\n' "$name"
+    PASSED=$((PASSED + 1))
+  else
+    printf '  [FAIL] %s\n' "$name"
+    for reason in "${reasons[@]}"; do
+      printf '         %s\n' "$reason"
+    done
+    if [ -n "$output" ]; then
+      printf '         output: %s\n' "$output" | head -3
+    fi
+    FAILED=$((FAILED + 1))
+    FAILURES+=("$name")
+  fi
+}
+
+for case_file in "$CASES_DIR"/*.cases.json; do
+  [ -f "$case_file" ] || continue
+
+  hook_name=$(basename "$case_file" .cases.json)
+
+  if [ -n "$FILTER" ] && [ "$hook_name" != "$FILTER" ]; then
+    continue
+  fi
+
+  hook_script="$HOOKS_DIR/$hook_name.sh"
+
+  if [ ! -f "$hook_script" ]; then
+    printf '[SKIP] %s — hook script not found at %s\n' "$hook_name" "$hook_script"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [ ! -x "$hook_script" ]; then
+    printf '[SKIP] %s — hook script not executable (run: chmod +x %s)\n' "$hook_name" "$hook_script"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  printf '\n%s\n' "$hook_name"
+
+  count=$(jq -r 'length' "$case_file")
+  for i in $(seq 0 $((count - 1))); do
+    case_json=$(jq -c ".[$i]" "$case_file")
+    run_case "$hook_script" "$case_json"
+  done
+done
+
+printf '\n---\n%d passed, %d failed, %d skipped\n' "$PASSED" "$FAILED" "$SKIPPED"
+
+if [ "$FAILED" -gt 0 ]; then
+  printf '\nFailed cases:\n'
+  for f in "${FAILURES[@]}"; do
+    printf '  - %s\n' "$f"
+  done
+  exit 1
+fi

package/template/.claude/hooks/warn-large-files.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Forge safety guardrail — blocks writes to build artifacts, binaries, and
+# dependency directories. PreToolUse hook for Edit|Write. Exit 2 = block.
+
+set -uo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"jq is required for file protection hooks but is not installed.\"}}"
+  exit 2
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Dependency, build, and cache directories across common stacks.
+REASON=""
+case "$FILE_PATH" in
+  # Node / JS / TS
+  node_modules/*|*/node_modules/*)
+    REASON="Cannot write into node_modules/ — install dependencies via the package manager instead." ;;
+  dist/*|*/dist/*|build/*|*/build/*|.next/*|*/.next/*|.nuxt/*|*/.nuxt/*|.output/*|*/.output/*)
+    REASON="Cannot write into build output directories — these are generated by the build process." ;;
+  # PHP / Laravel
+  vendor/*|*/vendor/*)
+    REASON="Cannot write into vendor/ — use composer instead." ;;
+  storage/framework/*|*/storage/framework/*|bootstrap/cache/*|*/bootstrap/cache/*)
+    REASON="Cannot write into Laravel framework caches — these are rebuilt by artisan." ;;
+  storage/logs/*|*/storage/logs/*)
+    REASON="Cannot write into storage/logs/ — these are runtime logs." ;;
+  # Python
+  __pycache__/*|*/__pycache__/*)
+    REASON="Cannot write into __pycache__/ — these are generated by Python." ;;
+  .venv/*|*/.venv/*|venv/*|*/venv/*)
+    REASON="Cannot write into virtual environment directories." ;;
+  .pytest_cache/*|*/.pytest_cache/*|.ruff_cache/*|*/.ruff_cache/*|.mypy_cache/*|*/.mypy_cache/*|.tox/*|*/.tox/*)
+    REASON="Cannot write into Python tool caches (pytest/ruff/mypy/tox) — these are regenerated automatically." ;;
+  # Go / Rust
+  target/debug/*|*/target/debug/*|target/release/*|*/target/release/*)
+    REASON="Cannot write into Rust target/ build output." ;;
+  # Generic
+  coverage/*|*/coverage/*|htmlcov/*|*/htmlcov/*|.nyc_output/*|*/.nyc_output/*)
+    REASON="Cannot write into coverage reports — these are regenerated by the test runner." ;;
+  .DS_Store|*/.DS_Store)
+    REASON="Cannot write .DS_Store — macOS metadata files should not be committed." ;;
+esac
+
+if [ -n "$REASON" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+# Block binary and archive file extensions.
+BASENAME=$(basename "$FILE_PATH")
+case "$BASENAME" in
+  *.wasm|*.so|*.dylib|*.dll|*.exe|*.o|*.a)
+    REASON="Cannot write binary files — these should be compiled, not hand-written." ;;
+  *.zip|*.tar|*.tar.gz|*.tar.bz2|*.tgz|*.rar|*.7z|*.phar)
+    REASON="Cannot write archive/bundle files." ;;
+  *.mp4|*.mov|*.avi|*.mkv|*.mp3|*.wav|*.flac)
+    REASON="Cannot write media files — add these manually outside the agent." ;;
+  *.pyc|*.pyo|*.class)
+    REASON="Cannot write compiled bytecode files." ;;
+esac
+
+if [ -n "$REASON" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
+  exit 2
+fi
+
+exit 0