A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
fix(hooks): correct pre-tool-check.sh hook protocol bugs (#72)
yarlinghebce7cf8cb4a8
diff --git a/06-hooks/pre-tool-check.sh b/06-hooks/pre-tool-check.shindex 932395e..f2dbdc0 100644--- a/06-hooks/pre-tool-check.sh+++ b/06-hooks/pre-tool-check.sh@@ -29,7 +29,18 @@# Input: JSON via stdin with the shape:# { "tool_name": "Bash", "tool_input": { "command": "..." } }#-# Output: Exit 0 to allow, exit 2 to block, or print JSON to modify behavior.+# Output convention (per Claude Code hook protocol):+# - exit 0 → allow. stdout may contain JSON (hookSpecificOutput); stderr+# is silently discarded, so warnings printed to stderr are NOT visible.+# For observability on allowed commands, write to an audit log file.+# - exit 2 → block. stderr is surfaced back to Claude as the block reason.+# Any echo explaining *why* a command was blocked MUST be redirected to+# stderr with `>&2`, otherwise Claude Code reports "No stderr output".+#+# Audit log: every invocation is recorded to+# $CLAUDE_PROJECT_DIR/.claude/hooks/audit.log+# with the decision (BLOCK/WARN/ALLOW), so you can observe WARN-tier+# matches even though their stderr output is dropped by Claude Code.# Read the full JSON input from stdinINPUT=$(cat)@@ -42,24 +53,41 @@ if [ -z "$COMMAND" ]; thenCOMMAND="$INPUT"fi+# ── Audit log ─────────────────────────────────────────────────────────────────+# Records every invocation with the final decision. This is the only reliable+# way to observe the WARN tier, because Claude Code silently drops stderr on+# exit 0. Falls back to $(pwd) when the hook is invoked outside Claude Code+# (e.g. for local testing).+LOG_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/hooks"+LOG_FILE="$LOG_DIR/audit.log"+mkdir -p "$LOG_DIR" 2>/dev/null+log_decision() {+ echo "$(date -u +%FT%TZ) [$1] $COMMAND" >> "$LOG_FILE"+}+# ── Blocked patterns ──────────────────────────────────────────────────────────# These commands are blocked unconditionally because they are almost always# destructive and rarely intentional in an automated context.BLOCKED_PATTERNS=(- "rm -rf /"+ # Anchor `rm -rf /` so `/` must be followed by whitespace or end of line,+ # otherwise substring matching would falsely flag e.g. `rm -rf /tmp/foo`.+ "rm -rf /([[:space:]]|$)""rm -rf \*""dd if=/dev/zero""dd if=/dev/random"- ":(){:|:&};:" # Fork bomb+ ":\(\)\{:\|:&\};:" # Fork bomb (regex metachars escaped)"mkfs\." # Filesystem format"format c:" # Windows disk format)for pattern in "${BLOCKED_PATTERNS[@]}"; doif echo "$COMMAND" | grep -qE "$pattern"; then- echo "❌ Blocked: Potentially destructive command detected: $pattern"- echo " Command: $COMMAND"+ log_decision "BLOCK:$pattern"+ # These echoes MUST go to stderr — Claude Code surfaces stderr as the+ # block reason on exit 2. Writing to stdout would show "No stderr output".+ echo "❌ Blocked: Potentially destructive command detected: $pattern" >&2+ echo " Command: $COMMAND" >&2exit 2fidone@@ -79,17 +107,23 @@ WARNING_PATTERNS=("truncate")-WARNINGS=0+MATCHED_WARNINGS=""for pattern in "${WARNING_PATTERNS[@]}"; doif echo "$COMMAND" | grep -qi "$pattern"; then- echo "⚠️ Warning: High-risk operation detected: $pattern"- WARNINGS=$((WARNINGS + 1))+ MATCHED_WARNINGS="${MATCHED_WARNINGS:+$MATCHED_WARNINGS,}$pattern"+ # Mirror the warning on stderr for humans running the hook manually.+ # Claude Code drops this on exit 0 — the audit log is the reliable+ # record (see WARN entries).+ echo "⚠️ Warning: High-risk operation detected: $pattern" >&2fidone-if [ "$WARNINGS" -gt 0 ]; then- echo " Command: $COMMAND"- echo " Proceeding — review the above warnings before continuing."+if [ -n "$MATCHED_WARNINGS" ]; then+ log_decision "WARN:$MATCHED_WARNINGS"+ echo " Command: $COMMAND" >&2+ echo " Proceeding — review the above warnings before continuing." >&2+else+ log_decision "ALLOW"fi# ── Allow ─────────────────────────────────────────────────────────────────────