Your Hook Is Configured Correctly and Never Runs

说明与用途

Claude 的钩子配置可能因忽略的匹配器、错误的 if 条件、已弃用的键或缺失必需字段而静默失效。使用 ccheck 和检查清单，确保钩子按预期运行。

问题

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.

结果

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

工作流

• 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.

证据

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

来源

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

来源

disableArtifact is the trap. The replacement inverts the sense.

来源

A checker stops being read after the first false positive.

来源