From 411381bf3e91034245c53b57fd88476cd43797b0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 15 Dec 2025 18:14:58 +0000
Subject: [PATCH] fix: Add missing matcher fields to hooks.json files

Stop hooks (and other hook types) were not firing because they were
missing the required "matcher" field. According to the hook development
documentation, all hooks must have a matcher field - "*" for wildcard
matching.

Changes:
- Add matcher: "*" to all hooks in hookify, ralph-wiggum,
  explanatory-output-style, and learning-output-style plugins
- Update validate-hook-schema.sh to properly handle plugin format
  (with 'hooks' wrapper) vs settings format (events at root)
- Add validate-all-hooks.sh script to validate all hooks.json files

Fixes: https://anthropic.slack.com/archives/C08EHE6JF3L/p1765822035850959
---
 .../explanatory-output-style/hooks/hooks.json |  1 +
 plugins/hookify/hooks/hooks.json              |  4 ++
 .../learning-output-style/hooks/hooks.json    |  1 +
 .../scripts/validate-hook-schema.sh           | 40 +++++++++++----
 plugins/ralph-wiggum/hooks/hooks.json         |  1 +
 scripts/validate-all-hooks.sh                 | 49 +++++++++++++++++++
 6 files changed, 86 insertions(+), 10 deletions(-)
 create mode 100755 scripts/validate-all-hooks.sh

diff --git a/plugins/explanatory-output-style/hooks/hooks.json b/plugins/explanatory-output-style/hooks/hooks.json
index d1fb8a57..32521439 100644
--- a/plugins/explanatory-output-style/hooks/hooks.json
+++ b/plugins/explanatory-output-style/hooks/hooks.json
@@ -3,6 +3,7 @@
   "hooks": {
     "SessionStart": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
diff --git a/plugins/hookify/hooks/hooks.json b/plugins/hookify/hooks/hooks.json
index d65daca7..a246ccf5 100644
--- a/plugins/hookify/hooks/hooks.json
+++ b/plugins/hookify/hooks/hooks.json
@@ -3,6 +3,7 @@
   "hooks": {
     "PreToolUse": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
@@ -14,6 +15,7 @@
     ],
     "PostToolUse": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
@@ -25,6 +27,7 @@
     ],
     "Stop": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
@@ -36,6 +39,7 @@
     ],
     "UserPromptSubmit": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
diff --git a/plugins/learning-output-style/hooks/hooks.json b/plugins/learning-output-style/hooks/hooks.json
index b3ab7ce9..e7f7036c 100644
--- a/plugins/learning-output-style/hooks/hooks.json
+++ b/plugins/learning-output-style/hooks/hooks.json
@@ -3,6 +3,7 @@
   "hooks": {
     "SessionStart": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
diff --git a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
index fed0a1f1..da368bad 100755
--- a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
+++ b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
@@ -40,7 +40,27 @@ echo ""
 echo "Checking root structure..."
 VALID_EVENTS=("PreToolUse" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
 
-for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
+# Detect format: plugin format has { description?, hooks: {...} } wrapper
+# Settings format has events directly at root level
+is_plugin_format=false
+if jq -e '.hooks' "$HOOKS_FILE" >/dev/null 2>&1; then
+  is_plugin_format=true
+  HOOKS_PATH=".hooks"
+  echo "Detected plugin format (with 'hooks' wrapper)"
+
+  # Validate allowed root keys for plugin format
+  for key in $(jq -r 'keys[]' "$HOOKS_FILE"); do
+    if [ "$key" != "hooks" ] && [ "$key" != "description" ]; then
+      echo "⚠️  Unknown root key in plugin format: $key (expected: 'hooks', 'description')"
+    fi
+  done
+else
+  HOOKS_PATH="."
+  echo "Detected settings format (events at root)"
+fi
+
+# Validate event types
+for event in $(jq -r "$HOOKS_PATH | keys[]" "$HOOKS_FILE"); do
   found=false
   for valid_event in "${VALID_EVENTS[@]}"; do
     if [ "$event" = "$valid_event" ]; then
@@ -62,12 +82,12 @@ echo "Validating individual hooks..."
 error_count=0
 warning_count=0
 
-for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
-  hook_count=$(jq -r ".\"$event\" | length" "$HOOKS_FILE")
+for event in $(jq -r "$HOOKS_PATH | keys[]" "$HOOKS_FILE"); do
+  hook_count=$(jq -r "$HOOKS_PATH.\"$event\" | length" "$HOOKS_FILE")
 
   for ((i=0; i<hook_count; i++)); do
     # Check matcher exists
-    matcher=$(jq -r ".\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
+    matcher=$(jq -r "$HOOKS_PATH.\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
     if [ -z "$matcher" ]; then
       echo "❌ $event[$i]: Missing 'matcher' field"
       ((error_count++))
@@ -75,7 +95,7 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
     fi
 
     # Check hooks array exists
-    hooks=$(jq -r ".\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
+    hooks=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
     if [ -z "$hooks" ] || [ "$hooks" = "null" ]; then
       echo "❌ $event[$i]: Missing 'hooks' array"
       ((error_count++))
@@ -83,10 +103,10 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
     fi
 
     # Validate each hook in the array
-    hook_array_count=$(jq -r ".\"$event\"[$i].hooks | length" "$HOOKS_FILE")
+    hook_array_count=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks | length" "$HOOKS_FILE")
 
     for ((j=0; j<hook_array_count; j++)); do
-      hook_type=$(jq -r ".\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
+      hook_type=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
 
       if [ -z "$hook_type" ]; then
         echo "❌ $event[$i].hooks[$j]: Missing 'type' field"
@@ -102,7 +122,7 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
 
       # Check type-specific fields
       if [ "$hook_type" = "command" ]; then
-        command=$(jq -r ".\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
+        command=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
         if [ -z "$command" ]; then
           echo "❌ $event[$i].hooks[$j]: Command hooks must have 'command' field"
           ((error_count++))
@@ -114,7 +134,7 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
           fi
         fi
       elif [ "$hook_type" = "prompt" ]; then
-        prompt=$(jq -r ".\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
+        prompt=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
         if [ -z "$prompt" ]; then
           echo "❌ $event[$i].hooks[$j]: Prompt hooks must have 'prompt' field"
           ((error_count++))
@@ -128,7 +148,7 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
       fi
 
       # Check timeout
-      timeout=$(jq -r ".\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
+      timeout=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
       if [ -n "$timeout" ] && [ "$timeout" != "null" ]; then
         if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
           echo "❌ $event[$i].hooks[$j]: Timeout must be a number"
diff --git a/plugins/ralph-wiggum/hooks/hooks.json b/plugins/ralph-wiggum/hooks/hooks.json
index 2e5f6979..a99c1aaf 100644
--- a/plugins/ralph-wiggum/hooks/hooks.json
+++ b/plugins/ralph-wiggum/hooks/hooks.json
@@ -3,6 +3,7 @@
   "hooks": {
     "Stop": [
       {
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
diff --git a/scripts/validate-all-hooks.sh b/scripts/validate-all-hooks.sh
new file mode 100755
index 00000000..19a10a70
--- /dev/null
+++ b/scripts/validate-all-hooks.sh
@@ -0,0 +1,49 @@
+#!/bin/bash
+# Validate all hooks.json files in the repository
+# This script can be run in CI to ensure all plugins have valid hook configurations
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+VALIDATOR="$REPO_ROOT/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh"
+
+echo "🔍 Validating all hooks.json files in the repository..."
+echo ""
+
+# Find all hooks.json files
+mapfile -t HOOKS_FILES < <(find "$REPO_ROOT/plugins" -name "hooks.json" -type f 2>/dev/null)
+
+if [ ${#HOOKS_FILES[@]} -eq 0 ]; then
+  echo "No hooks.json files found"
+  exit 0
+fi
+
+echo "Found ${#HOOKS_FILES[@]} hooks.json file(s)"
+echo ""
+
+errors=0
+for hooks_file in "${HOOKS_FILES[@]}"; do
+  relative_path="${hooks_file#$REPO_ROOT/}"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "📄 $relative_path"
+  echo ""
+
+  if bash "$VALIDATOR" "$hooks_file"; then
+    echo ""
+  else
+    echo ""
+    ((errors++))
+  fi
+done
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+if [ $errors -eq 0 ]; then
+  echo "✅ All ${#HOOKS_FILES[@]} hooks.json file(s) are valid!"
+  exit 0
+else
+  echo "❌ $errors hooks.json file(s) have validation errors"
+  exit 1
+fi