hook-development

Define a PreToolUse entry in your plugin's hooks/hooks.json with a matcher for target tools and a hook of type prompt or command. The hook receives tool input via stdin and returns JSON with a permissionDecision of allow, deny, or ask.

Prompt-based hooks use LLM reasoning for context-aware validation on events like Stop and PreToolUse, while command hooks execute bash scripts for fast deterministic checks. Use prompt hooks for complex logic and command hooks for performance-critical validations.

Hooks load only at session start, so editing hooks.json or hook scripts does not affect the current session. Exit Claude Code and restart with claude, then verify loaded hooks using the /hooks command or claude --debug.

Use a PreToolUse hook matching Bash that inspects the command input and returns a deny decision with exit code 2. Validate inputs with jq, check for path traversal and sensitive files, and quote all variables to prevent injection.

${CLAUDE_PLUGIN_ROOT} is an environment variable pointing to the plugin directory, making hook command paths portable across machines. Reference scripts as bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh instead of hardcoding absolute paths.