Skip to content

claude-world/director-mode-lite / skills/hooks-check

hooks-check

Verified

Validate 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).

GroupEvents
LifecycleSessionStart, SessionEnd, Setup
PromptUserPromptSubmit, UserPromptExpansion
ToolPreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch
PermissionPermissionRequest, PermissionDenied
SubagentSubagentStart, SubagentStop
StopStop, StopFailure
TaskTaskCreated, TaskCompleted
CompactionPreCompact, PostCompact
NotificationNotification, MessageDisplay
MCP elicitationElicitation, ElicitationResult
ModelPreModelSwitch, PostModelSwitch
EnvironmentConfigChange, 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

  • type is present and one of: command, prompt, http, mcp_tool, agent
  • If type: command: command path exists and script is executable; a shell-form path variable is quoted ("$CLAUDE_PROJECT_DIR"/...), or the hook uses exec form (args)
  • If type: prompt or agent: prompt string is non-empty
  • If type: http: url is set; if type: mcp_tool: server and tool are set
  • matcher is 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
  • timeout is a positive integer if present (defaults: 600s command/http/mcp_tool, 30s prompt, 60s agent)
  • if is a permission rule such as Bash(git *), used only on tool events
  • onFailure is continue or block (v2.1.295+); recommend block for security guards
  • once appears only in skill frontmatter hooks; settings files ignore it
  • async / asyncRewake appear only on command hooks
  • statusMessage is a string if present
  • SessionEnd matchers do not use bypass_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, exit 2 = block for PreToolUse).

Decision Output Schema

When a script does emit JSON, validate it against the event contract:

  • PreToolUse: hookSpecificOutput.permissionDecision is allow, deny, ask, or defer (-p only). 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 is reason.
  • Input JSON always carries the event under hook_event_name (not hook_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_name in emitted JSON
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall