surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

fix: Add missing matcher fields to hooks.json filesBrowse 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

Claude authored on Dec 15, 2025 parent eb87245 · commit 411381bf3e91

6 changed files+86 -10compared with eb87245

Mplugins/explanatory-output-style/hooks/hooks.json

Mplugins/hookify/hooks/hooks.json

Mplugins/learning-output-style/hooks/hooks.json

Mplugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh

Mplugins/ralph-wiggum/hooks/hooks.json

Ascripts/validate-all-hooks.sh

Mplugins/explanatory-output-style/hooks/hooks.json+1 -0

		@@ -3,6 +3,7 @@
3	3	"hooks": {
4	4	"SessionStart": [
5	5	{
	6	+ "matcher": "*",
6	7	"hooks": [
7	8	{
8	9	"type": "command",

Mplugins/hookify/hooks/hooks.json+4 -0

		@@ -3,6 +3,7 @@
3	3	"hooks": {
4	4	"PreToolUse": [
5	5	{
	6	+ "matcher": "*",
6	7	"hooks": [
7	8	{
8	9	"type": "command",
		@@ -14,6 +15,7 @@
14	15	],
15	16	"PostToolUse": [
16	17	{
	18	+ "matcher": "*",
17	19	"hooks": [
18	20	{
19	21	"type": "command",
		@@ -25,6 +27,7 @@
25	27	],
26	28	"Stop": [
27	29	{
	30	+ "matcher": "*",
28	31	"hooks": [
29	32	{
30	33	"type": "command",
		@@ -36,6 +39,7 @@
36	39	],
37	40	"UserPromptSubmit": [
38	41	{
	42	+ "matcher": "*",
39	43	"hooks": [
40	44	{
41	45	"type": "command",

Mplugins/learning-output-style/hooks/hooks.json+1 -0

		@@ -3,6 +3,7 @@
3	3	"hooks": {
4	4	"SessionStart": [
5	5	{
	6	+ "matcher": "*",
6	7	"hooks": [
7	8	{
8	9	"type": "command",

Mplugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh+30 -10

		@@ -40,7 +40,27 @@
40	40	echo "Checking root structure..."
41	41	VALID_EVENTS=("PreToolUse" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification")
42	42
43		-for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
	43	+# Detect format: plugin format has { description?, hooks: {...} } wrapper
	44	+# Settings format has events directly at root level
	45	+is_plugin_format=false
	46	+if jq -e '.hooks' "$HOOKS_FILE" >/dev/null 2>&1; then
	47	+ is_plugin_format=true
	48	+ HOOKS_PATH=".hooks"
	49	+ echo "Detected plugin format (with 'hooks' wrapper)"
	50	+
	51	+ # Validate allowed root keys for plugin format
	52	+ for key in $(jq -r 'keys[]' "$HOOKS_FILE"); do
	53	+ if [ "$key" != "hooks" ] && [ "$key" != "description" ]; then
	54	+ echo "⚠️ Unknown root key in plugin format: $key (expected: 'hooks', 'description')"
	55	+ fi
	56	+ done
	57	+else
	58	+ HOOKS_PATH="."
	59	+ echo "Detected settings format (events at root)"
	60	+fi
	61	+
	62	+# Validate event types
	63	+for event in $(jq -r "$HOOKS_PATH \| keys[]" "$HOOKS_FILE"); do
44	64	found=false
45	65	for valid_event in "${VALID_EVENTS[@]}"; do
46	66	if [ "$event" = "$valid_event" ]; then
		@@ -62,12 +82,12 @@
62	82	error_count=0
63	83	warning_count=0
64	84
65		-for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do
66		- hook_count=$(jq -r ".\"$event\" \| length" "$HOOKS_FILE")
	85	+for event in $(jq -r "$HOOKS_PATH \| keys[]" "$HOOKS_FILE"); do
	86	+ hook_count=$(jq -r "$HOOKS_PATH.\"$event\" \| length" "$HOOKS_FILE")
67	87
68	88	for ((i=0; i<hook_count; i++)); do
69	89	# Check matcher exists
70		- matcher=$(jq -r ".\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
	90	+ matcher=$(jq -r "$HOOKS_PATH.\"$event\"[$i].matcher // empty" "$HOOKS_FILE")
71	91	if [ -z "$matcher" ]; then
72	92	echo "❌ $event[$i]: Missing 'matcher' field"
73	93	((error_count++))
		@@ -75,7 +95,7 @@
75	95	fi
76	96
77	97	# Check hooks array exists
78		- hooks=$(jq -r ".\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
	98	+ hooks=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks // empty" "$HOOKS_FILE")
79	99	if [ -z "$hooks" ] \|\| [ "$hooks" = "null" ]; then
80	100	echo "❌ $event[$i]: Missing 'hooks' array"
81	101	((error_count++))
		@@ -83,10 +103,10 @@
83	103	fi
84	104
85	105	# Validate each hook in the array
86		- hook_array_count=$(jq -r ".\"$event\"[$i].hooks \| length" "$HOOKS_FILE")
	106	+ hook_array_count=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks \| length" "$HOOKS_FILE")
87	107
88	108	for ((j=0; j<hook_array_count; j++)); do
89		- hook_type=$(jq -r ".\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
	109	+ hook_type=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].type // empty" "$HOOKS_FILE")
90	110
91	111	if [ -z "$hook_type" ]; then
92	112	echo "❌ $event[$i].hooks[$j]: Missing 'type' field"
		@@ -102,7 +122,7 @@
102	122
103	123	# Check type-specific fields
104	124	if [ "$hook_type" = "command" ]; then
105		- command=$(jq -r ".\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
	125	+ command=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].command // empty" "$HOOKS_FILE")
106	126	if [ -z "$command" ]; then
107	127	echo "❌ $event[$i].hooks[$j]: Command hooks must have 'command' field"
108	128	((error_count++))
		@@ -114,7 +134,7 @@
114	134	fi
115	135	fi
116	136	elif [ "$hook_type" = "prompt" ]; then
117		- prompt=$(jq -r ".\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
	137	+ prompt=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE")
118	138	if [ -z "$prompt" ]; then
119	139	echo "❌ $event[$i].hooks[$j]: Prompt hooks must have 'prompt' field"
120	140	((error_count++))
		@@ -128,7 +148,7 @@
128	148	fi
129	149
130	150	# Check timeout
131		- timeout=$(jq -r ".\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
	151	+ timeout=$(jq -r "$HOOKS_PATH.\"$event\"[$i].hooks[$j].timeout // empty" "$HOOKS_FILE")
132	152	if [ -n "$timeout" ] && [ "$timeout" != "null" ]; then
133	153	if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
134	154	echo "❌ $event[$i].hooks[$j]: Timeout must be a number"

Mplugins/ralph-wiggum/hooks/hooks.json+1 -0

		@@ -3,6 +3,7 @@
3	3	"hooks": {
4	4	"Stop": [
5	5	{
	6	+ "matcher": "*",
6	7	"hooks": [
7	8	{
8	9	"type": "command",

Ascripts/validate-all-hooks.sh+49 -0

		@@ -1,0 +1,49 @@
	1	+#!/bin/bash
	2	+# Validate all hooks.json files in the repository
	3	+# This script can be run in CI to ensure all plugins have valid hook configurations
	4	+
	5	+set -euo pipefail
	6	+
	7	+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
	8	+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
	9	+VALIDATOR="$REPO_ROOT/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh"
	10	+
	11	+echo "🔍 Validating all hooks.json files in the repository..."
	12	+echo ""
	13	+
	14	+# Find all hooks.json files
	15	+mapfile -t HOOKS_FILES < <(find "$REPO_ROOT/plugins" -name "hooks.json" -type f 2>/dev/null)
	16	+
	17	+if [ ${#HOOKS_FILES[@]} -eq 0 ]; then
	18	+ echo "No hooks.json files found"
	19	+ exit 0
	20	+fi
	21	+
	22	+echo "Found ${#HOOKS_FILES[@]} hooks.json file(s)"
	23	+echo ""
	24	+
	25	+errors=0
	26	+for hooks_file in "${HOOKS_FILES[@]}"; do
	27	+ relative_path="${hooks_file#$REPO_ROOT/}"
	28	+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
	29	+ echo "📄 $relative_path"
	30	+ echo ""
	31	+
	32	+ if bash "$VALIDATOR" "$hooks_file"; then
	33	+ echo ""
	34	+ else
	35	+ echo ""
	36	+ ((errors++))
	37	+ fi
	38	+done
	39	+
	40	+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
	41	+echo ""
	42	+
	43	+if [ $errors -eq 0 ]; then
	44	+ echo "✅ All ${#HOOKS_FILES[@]} hooks.json file(s) are valid!"
	45	+ exit 0
	46	+else
	47	+ echo "❌ $errors hooks.json file(s) have validation errors"
	48	+ exit 1
	49	+fi