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.

Источник