fix(plugin-dev): validate-hook-schema.sh handles plugin hooks.json format#77556
Open
sorapallivenkatesh wants to merge 1 commit into
Open
Conversation
…rmat
The hook schema validator only understood the flat settings.json format
(events at the top level). Given a plugin `hooks.json`, which wraps events
under a `"hooks"` key alongside an optional `"description"`, it treated
`description` and `hooks` as event names and then crashed with
`jq: Cannot index string with number`. This is the exact format the
Hook Development skill documents and every bundled plugin uses.
It also flagged a missing `matcher` field as an error for every hook, but
`matcher` is optional — it only applies to PreToolUse/PostToolUse, and even
there an absent matcher means "match all". Events like Stop, SessionStart,
and UserPromptSubmit never carry one, so valid configs failed validation.
- Detect and unwrap the plugin `{"hooks": {...}}` wrapper; fall back to the
flat settings format.
- Stop treating `matcher` as required.
Verified against the bundled hookify and security-guidance hooks.json
(now pass), a flat matcher-less Stop config (now passes), and a
deliberately broken config (errors still reported).
This was referenced Jul 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The hook-schema validator shipped in the plugin-dev plugin's Hook Development skill (
plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh) has two bugs that make it fail on valid configurations — including the exact format the skill itself documents.1. Crashes on plugin
hooks.jsonfiles.The validator only understood the flat settings format, where hook events live at the top level. But plugin
hooks.jsonuses a wrapper — events nested under a"hooks"key alongside an optional"description"— which is the format documented inSKILL.mdand used by every bundled plugin (hookify, security-guidance, ralph-wiggum, …). Given a real pluginhooks.json, the validator treateddescriptionandhooksas event names and then crashed:2. Treats
matcheras required.It reported
❌ Missing 'matcher' fieldfor any hook entry without a matcher. Butmatcheris optional: it only applies toPreToolUse/PostToolUse(to target specific tools), and even there an absent matcher means "match all". Events likeStop,SessionStart, andUserPromptSubmitnever carry one, so valid configs failed validation.Fix
{"hooks": {...}}wrapper (ignoringdescription); fall back to the flat settings format.matcheras required.No behavior change for genuinely invalid configs — missing
hooksarrays, bad hooktype, missingcommand/prompt, and non-numeric timeouts are still reported.Verification
plugins/hookify/hooks/hooks.json(wrapper)plugins/security-guidance/hooks/hooks.json(wrapper, matchers, timeouts)Stophook