Your Hook Is Configured Correctly and Never Runs

Description and use

Claude hook configurations can silently fail due to ignored matchers, misapplied if conditions, deprecated keys, or missing required fields. Use ccheck and the checklist to ensure hooks run as intended.

Problem

Hooks in Claude’s .claude/ configuration can silently fail to run or run unexpectedly due to ignored matchers, misapplied if conditions, deprecated keys, missing required fields, or mismatched tool names, without any error feedback.

Outcome

By following the checklist and using ccheck, developers can ensure hooks run only when intended, preventing silent failures and unintended executions.

Workflow

• 1. Identify the event type you want to hook (e.g., UserPromptSubmit).
• 2. Verify the event supports matchers; if not, the matcher will be ignored.
• 3. For non-tool events, avoid using the "if" field; it only applies to tool events.
• 4. Update deprecated keys: replace "disableArtifact" with "enableArtifact" (note the boolean inversion).
• 5. Ensure required fields for the handler type are present (e.g., "command" for command handlers).
• 6. For MCP tools from plugins, include the plugin prefix in the matcher (e.g., mcp__plugin_my-plugin_db__).
• 7. Run the external checker (ccheck) to detect ignored or broken configurations.
• 8. Review ccheck output and adjust the settings.json accordingly.
• 9. Test the hook by triggering the event and confirming expected behavior.

Evidence

If you add a matcher field to an event without matcher support, it is silently ignored.

Source

For tool events, you can filter more narrowly by setting the if field on individual hook handlers.

Source

disableArtifact is the trap. The replacement inverts the sense.

Source

A checker stops being read after the first false positive.

Source