debug-hooks

Maestro hooks may not fire due to incorrect registration in settings, missing hook scripts, or silent failures in detached processes. To debug hook execution, systematically verify hook configuration, inspect compiled bundles, and manually test inputs.

To debug a PostToolUse hook producing incorrect output, trace the execution flow, verify the input payload format, and confirm the hook script's logic. Manually test the hook with sample inputs to isolate processing errors.

Verifying Maestro hook registration involves checking both project and global settings files for correct hook declarations. Ensure the hook scripts and compiled bundles are present, up-to-date, and properly referenced in the configuration.

Silent failures in Maestro hook detached processes occur when spawned processes hide errors from the main execution flow. Identify these by inspecting hook files, checking outputs directly, and testing hook functionality manually.

The best way to troubleshoot unexpected Maestro hook behavior is following a systematic workflow: check outputs, verify hook registration, inspect hook files, manually test with sample inputs, and identify silent failures in detached processes.