build: 🤖 Improve the Claude hook integrations

Author: stracker-phil

.claude/hooks/config.example.json

@@ -1,5 +1,6 @@
 {
-	"_comment": "Copy this file to config.local.json to disable individual hooks locally. config.local.json is gitignored. Each key is a hook script filename; set it to false to bail that hook. Any hook not listed (or with no config file at all) is enabled.",
-	"php-review-track.sh": true,
-	"php-review-stop.sh": true
+	"_comment": "Copy this file to config.local.json to disable individual hooks locally.",
+
+	"_info-php-review": "Disable the hooks that trigger a code review after editing PHP files.",
+	"php-review": true
 }

.claude/hooks/php-review-stop.sh

@@ -12,13 +12,16 @@
 # unchanged file is never nudged twice and the loop terminates cleanly once edits
 # stop changing content. Silent (exit 0) when there is nothing new to review.
 
-# Local opt-out: hooks/config.local.json maps each hook filename to a boolean.
-# A script set to false here bails immediately. No config file (the default) or a
+# Everything below parses JSON with jq. Without it, bail silently.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Local opt-out: hooks/config.local.json maps each "feature" to a boolean.
+# A disabled feature bails immediately. No config file (the default) or a
 # missing key means enabled.
+feature="php-review"
 config="$(dirname "$0")/config.local.json"
 if [ -f "$config" ]; then
-	self="$(basename "$0")"
-	enabled=$(jq -r --arg k "$self" 'if has($k) then .[$k] else true end' "$config" 2>/dev/null)
+	enabled=$(jq -r --arg k "$feature" 'if has($k) then .[$k] else true end' "$config" 2>/dev/null)
 	[ "$enabled" = "false" ] && exit 0
 fi
 
@@ -41,6 +44,8 @@ content_hash() {
 list=""
 for marker in "$dir"/touched-*; do
 	[ -e "$marker" ] || continue
+	# The glob also matches the ".reviewed" sidecars we write below; skip them.
+	case "$marker" in *.reviewed) continue ;; esac
 	file=$(cat "$marker" 2>/dev/null)
 	[ -n "$file" ] && [ -f "$file" ] || continue
 
@@ -55,6 +60,6 @@ done
 
 [ -n "$list" ] || exit 0
 
-reason="Before finishing this turn, review your PHP changes. Dispatch the \`php-review\` agent once for each file below (in parallel is fine), then apply any fixes it reports. Files needing review:${list}"
+reason="Before finishing this turn, review your PHP changes. Dispatch the \`php-review\` agent once for each file below (in parallel is fine), each with the prompt \`review CHANGES in <file>\`, then apply any fixes it reports. Files needing review:${list}"
 
 jq -n --arg r "$reason" '{decision: "block", reason: $r}'

.claude/hooks/php-review-track.sh

@@ -8,13 +8,16 @@
 # here get reviewed later, so pre-existing dirty files the session never edited
 # are left alone.
 
-# Local opt-out: hooks/config.local.json maps each hook filename to a boolean.
-# A script set to false here bails immediately. No config file (the default) or a
+# Everything below parses JSON with jq. Without it, bail silently.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Local opt-out: hooks/config.local.json maps each "feature" to a boolean.
+# A disabled feature bails immediately. No config file (the default) or a
 # missing key means enabled.
+feature="php-review"
 config="$(dirname "$0")/config.local.json"
 if [ -f "$config" ]; then
-	self="$(basename "$0")"
-	enabled=$(jq -r --arg k "$self" 'if has($k) then .[$k] else true end' "$config" 2>/dev/null)
+	enabled=$(jq -r --arg k "$feature" 'if has($k) then .[$k] else true end' "$config" 2>/dev/null)
 	[ "$enabled" = "false" ] && exit 0
 fi