creating-hooks

Define a hooks.json file that binds a lifecycle event like preToolUse to a command script, then place the pack under .github/hooks/. The script reads the hook payload from stdin and returns a JSON permissionDecision such as deny with a reason.

Use a preToolUse hook whose script pattern-matches the toolArgs command against destructive patterns like rm -rf or git reset --hard. On a match, return permissionDecision deny with a clear, user-readable reason explaining what to do instead.

Yes, hooks.json supports separate command entries: a Bash script via the command field and a PowerShell script via the windows field. Both scripts should implement the same policy so behavior is consistent across platforms.

Use a hook when you need deterministic enforcement at a specific lifecycle event, such as blocking a command before it runs. Use instructions for guidance-only behavior, a skill for reusable workflows, and a prompt for user-started tasks.

Hooks run on lifecycle events, so long-running scripts create friction on every trigger. Keep scripts short and deterministic, set a tight timeoutSec such as 10 seconds, and start with observe or warn modes before enabling hard blocks.