Why isn’t my hook firing?

A hook that silently never runs is one of the most common agent-config puzzles. Here is how to track it down with Berth.

1. Is the event name right?

Hooks fire on specific lifecycle events (e.g., PreToolUse before a tool call, PostToolUse after one). If the event name doesn’t match a real event, the hook never runs. Berth shows when each hook is set to fire.

2. Are hooks disabled globally?

A disableAllHooks setting turns every hook off at once. Berth’s health checks surface this — it’s the first thing to rule out.

3. Is the matcher too narrow?

Many hooks use a matcher to target specific tools. If the matcher doesn’t match the tool you’re using, nothing happens. Check the matcher against the tool name in the session’s tool timeline.

4. Does the command file exist?

A hook points at a command or script. If the path is wrong or the file is missing, the hook can’t run. Berth validates hook entry paths in health checks.