writing-hooks

Design Claude Code hooks by specifying event types, hook script structures, and matcher patterns to automate policy checks. Use a hooks.json file to define command, prompt, or agent hooks that enforce quality gates across Claude workflows reliably.

Command, prompt, and agent hooks serve distinct automation purposes in Claude Code. Command hooks execute scripts for policy checks, while prompt and agent hooks handle different workflow stages, guiding when to use each for reliable hook orchestration and quality gates.

Validate a PreToolUse command hook by creating a sample hooks.json that defines the hook structure and matcher patterns, then verifying its behavior. Ensure scripts use the ${CLAUDE_PLUGIN_ROOT} path variable for portable and reliable execution across environments.

Use blocking behavior for Claude Code hooks when strict policy enforcement is required, and advisory behavior for non-critical warnings. Choose fail-open patterns to allow workflows to proceed on errors, or fail-closed patterns to halt execution when strict quality gates are necessary.

Regex matchers are used in Claude Code hooks to target specific tool events for automation. By configuring matcher patterns in your hooks.json, you can precisely filter which tool calls trigger your command hook scripts for policy enforcement and quality validation.

Use the ${CLAUDE_PLUGIN_ROOT} variable in hook scripts to ensure portable path practices for reliable hook orchestration. It specifies script locations consistently, allowing plugin authors to automate checks and enforce policies across different Claude workflow environments without path errors.