Hook Creator

Caution

Hooks fail silently when the wrong output channel is used. additionalContext on a Stop event does nothing — Claude never sees it. decision:"block" on PostToolUse is not a valid field. Getting the event-to-channel mapping wrong means the hook runs and produces zero effect, with no error to debug.

Tip

hook-creator knows all 26 events, 4 hook types, and the full routing matrix. Describe what you want in plain language — it picks the right event, output channel, and schema, then delivers a working file with fail-safe error handling included.

Quick reference

Field	Value
Trigger	”create hook”, “PreToolUse hook”, “Stop hook”, “hook doesn’t work”, “debug hook”
Model	opus
Tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch
Output	Hook file (`.sh` or `.mjs`) + config snippet + verification checklist

When to use

Create a new hook — you know what you want the hook to do, but not which event or output format to use
Debug a broken hook — the hook runs but Claude ignores it, or the session is stuck
Validate an existing hook — check routing, schema, fail-safe, and stop_hook_active guard
Choose a hook type — unsure whether to use command, http, prompt, or agent hook
Add context injection — inject project rules, mode state, or subagent instructions at session or tool boundaries

Examples

"Create a PreToolUse hook that blocks `rm -rf` commands"

"My Stop hook keeps blocking the session even after the task finishes.
 The hook checks a state file but the session never exits."

"Write a SessionStart hook that injects the contents of .project-rules.md
 into every new session as additionalContext"

Flow

Clarify intent
Asks which event, which behavior (block / inject / modify / log), and where the hook config should live (project settings, global settings, or plugin hooks.json). Skips questions when intent is unambiguous.
Select event and channel
Applies the routing matrix — picks the correct event from 26 options and the right output channel (additionalContext, updatedInput, permissionDecision, decision) for your goal. Wrong channel = silent failure, so this step is non-negotiable.
Generate the hook file
Writes a .sh (bash) or .mjs (Node.js) file from a production template. Always includes: stdin parsing, try/catch with output({}) fallback, stop_hook_active guard for Stop/SubagentStop hooks, and correct shebang.
Generate the config snippet
Produces the exact JSON block to paste into your target config file (settings.json, settings.local.json, or hooks.json). Includes matcher, hook type, and command path.
Deliver verification checklist
Lists what to confirm: shebang, fail-safe catch, schema validity, executable bit, performance (<1s for blocking hooks). For debugging sessions, runs the hook manually with test input and explains what each output field does.

Event catalogue and routing matrix (expand for reference)

Output channel by event

Goal	Channel	Event
Inject context for Claude	`additionalContext`	SessionStart, PreToolUse, UserPromptSubmit
Inject into subagent prompt	`updatedInput.prompt`	PreToolUse (matcher: Task)
Block tool execution	`permissionDecision:"deny"`	PreToolUse
Block session stop	`decision:"block"` + `reason`	Stop
Post-tool feedback	`additionalContext`	PostToolUse
Modify tool parameters	`updatedInput`	PreToolUse
Show user warning (Claude does NOT see)	`systemMessage`	Any
Auto-allow permission	`decision.behavior:"allow"`	PermissionRequest
Control teammates	`{continue, stopReason}` JSON	TeammateIdle, TaskCompleted, TaskCreated

All 26 events

Event	Blocking?	Key use
SessionStart	No	Context injection on start/resume
UserPromptSubmit	Yes	Gate or modify user prompts
PreToolUse	Yes	Allow / deny / modify tool calls
PermissionRequest	Yes	Auto-allow or auto-deny permission dialogs
PostToolUse	No	Feedback after tool completes
PostToolUseFailure	No	React to failed tool call
SubagentStart	No	Inject into subagent context
SubagentStop	Yes	Block subagent exit
Stop	Yes	Block session exit until condition met
PreCompact	No	Write handoff before auto-compact
PostCompact	No	React after compact
Notification	No	Log or react to notifications
TeammateIdle	Yes	Control agent team flow
TaskCompleted	Yes	Accept or re-assign tasks
TaskCreated	Yes	Intercept new tasks
ConfigChange	Yes	React to settings file changes
InstructionsLoaded	No	Track CLAUDE.md / rules file loads
FileChanged	No	React to file system changes
CwdChanged	No	React to directory changes
WorktreeCreate	Yes	Intercept worktree creation
WorktreeRemove	No	React to worktree removal
StopFailure	No	React to rate-limit / API errors
Elicitation	Yes	Auto-fill MCP forms
ElicitationResult	Yes	Post-elicitation hook
SessionEnd	No	Cleanup on session close
PermissionDenied	Yes	Retry after auto-mode denial (v2.1.89+)

Hook types

Type	Timeout	When to use
`command`	600s	Shell/Node script — deterministic, file I/O, external tools
`http`	600s	POST JSON to external API or webhook (v2.1.63+)
`prompt`	30s	Single Haiku LLM call for natural-language validation
`agent`	60s	Multi-step analysis with Read/Grep/Glob access

agent-type hooks spawn a subagent. The spawned subagent inherits the session’s permissionMode. Never configure the parent session with --dangerously-skip-permissions just to avoid hook permission prompts — use a narrow permissionMode: acceptEdits on the hook’s agent definition instead.

📄

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.