claude-world/director-mode-lite / skills/hooks-check
hooks-check
VerifiedValidate hooks configuration and scripts. Use after adding or editing hooks in settings.json, before committing hook changes, or when a hook fails to fire.
Hooks Validator
Validate hooks configuration in .claude/settings.json and hook scripts against
the official Claude Code spec.
Validation Steps
1. Check settings.json
Verify the hooks section exists and is valid.
2. Validate Hook Event Names
Claude Code defines 33 hook events. Accept any of them; flag unknown names
with a typo hint (e.g. PrePromptSubmit -> UserPromptSubmit,
PostToolBatchFailure -> PostToolBatch, SubagentStarts -> SubagentStart).
| Group | Events |
|---|---|
| Lifecycle | SessionStart, SessionEnd, Setup |
| Prompt | UserPromptSubmit, UserPromptExpansion |
| Tool | PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch |
| Permission | PermissionRequest, PermissionDenied |
| Subagent | SubagentStart, SubagentStop |
| Stop | Stop, StopFailure |
| Task | TaskCreated, TaskCompleted |
| Compaction | PreCompact, PostCompact |
| Notification | Notification, MessageDisplay |
| MCP elicitation | Elicitation, ElicitationResult |
| Model | PreModelSwitch, PostModelSwitch |
| Environment | ConfigChange, CwdChanged, DirectoryAdded, FileChanged, InstructionsLoaded, WorktreeCreate, WorktreeRemove, TeammateIdle |
That is all 33 events. See the official hooks docs for each event's payload.
3. Validate Each Hook Entry
-
typeis present and one of:command,prompt,http,mcp_tool,agent - If
type: command:commandpath exists and script is executable; a shell-form path variable is quoted ("$CLAUDE_PROJECT_DIR"/...), or the hook uses exec form (args) - If
type: promptoragent:promptstring is non-empty - If
type: http:urlis set; iftype: mcp_tool:serverandtoolare set -
matcheris a string if present (exact names joined by|or,,*, or a regex); warn when it sits on an event without matcher support (UserPromptSubmit,Stop,PostToolBatch,TeammateIdle,TaskCreated,TaskCompleted,WorktreeCreate,WorktreeRemove,MessageDisplay,CwdChanged), where it is silently ignored -
timeoutis a positive integer if present (defaults: 600s command/http/mcp_tool, 30s prompt, 60s agent) -
ifis a permission rule such asBash(git *), used only on tool events -
onFailureiscontinueorblock(v2.1.295+); recommendblockfor security guards -
onceappears only in skill frontmatter hooks; settings files ignore it -
async/asyncRewakeappear only on command hooks -
statusMessageis a string if present -
SessionEndmatchers do not usebypass_permissions_disabled(removed in v2.1.234)
4. Validate Hook Scripts
- File exists and is executable
- Has an appropriate shebang
- If the script emits structured output on stdout, it is valid JSON.
Silent / exit-code-only hooks are valid — no stdout is required
(exit
0= allow/continue, exit2= block forPreToolUse).
Decision Output Schema
When a script does emit JSON, validate it against the event contract:
- PreToolUse:
hookSpecificOutput.permissionDecisionisallow,deny,ask, ordefer(-ponly). The legacy top-level{"decision": "approve" | "block"}is still accepted. - Prompt / agent hooks: the model's verdict is
{"ok": true}or{"ok": false, "reason": "..."}. - Stop / SubagentStop: continuation uses
{"decision": "block", "reason": "<next prompt>"}— the key isreason. - Input JSON always carries the event under
hook_event_name(nothook_type).
Output Format
## Hooks Validation Report
### Configuration Status: VALID / INVALID
### Configured Hooks
| Event | Matcher | Script | Status |
|-------|---------|--------|--------|
| Stop | * | auto-loop-stop.sh | OK |
### Script Validation
| Script | Exists | Executable | Output |
|--------|--------|------------|--------|
| auto-loop-stop.sh | OK | OK | JSON OK / silent |
### Issues Found
1. [Issue and fix]
Auto-Fix
- Make scripts executable
- Add missing shebang
- Create missing hook scripts
- Correct a misspelled event name to the nearest valid event
- Normalize
hook_type->hook_event_namein emitted JSON
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |