Hook Creator

inherit 33 events · 5 handler types

Quick reference

Field	Value
Agent	brewcode:hook-creator
Triggers	create hook, PreToolUse hook, debug hook
Model	inherit: uses the session model
Tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch
Output	Hook or handler configuration, registration snippet, verification evidence, and limits

What it does

Create, debug, or validate a lifecycle hook against the actual event contract. Hook Creator selects the event, handler type, input schema, output channel, matcher, and failure policy. Its source references were refreshed through Claude Code 2.1.285.

Give the main caller one bounded deliverable: behavior, owned files, target registration surface, and acceptance evidence. Ordinary subagent questions return to the caller; permission and approval gates stay in the main session. The agent follows an existing well-built hook alongside project rules.

When to use

• Block an action before it runs, with an explicit hard-gate failure policy.
• Add advisory operating context at a supported lifecycle boundary.
• Fix output that a hook emits but the event ignores.
• Diagnose a stop loop, incorrect matcher, or broken registration.
• Choose between deterministic, HTTP, MCP, prompt, and agent handlers.

Examples

Create one PreToolUse hook for the project's destructive command policy.
Own its script and registration snippet. Preserve existing hooks, reject unsafe
input explicitly, and test both allowed and denied calls.

Debug my Stop hook: it keeps blocking after the task finishes.
Verify the Stop output contract and stop_hook_active guard.

Workflow

Handler types

Type	Purpose and limits
command	Deterministic executable or shell handler; event-specific stdout and exit behavior
http	Send hook input to an endpoint and interpret its supported response
mcp_tool	Invoke a configured MCP tool; connection and event support constrain execution
prompt	LLM decision handler with ok/reason output; supported events only
agent	LLM agent decision handler; supported events only

Prompt and agent handlers evaluate decisions; their prompt text is not ordinary context injection. They are not available on every event. For example, SessionStart supports command/MCP handlers, while Setup skips MCP and runs command handlers. PermissionRequest skips agent handlers, and its decisions require that event’s output shape rather than a generic prompt ok=false response.

Command exec form

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/example.mjs"],
  "timeout": 5
}

With args present, command resolves on PATH and runs directly without shell parsing. Each argument is literal after supported substitutions; shell quoting and expansion do not apply. Shell form remains available when a pipe or other shell operation is actually needed. Args, shell, async, and asyncRewake are command-only configuration fields.

Event-specific output

Goal	Correct contract
Add context on a supported event	hookSpecificOutput.additionalContext
Deny a tool before execution	PreToolUse permissionDecision=deny
Modify tool parameters	Supported updatedInput field; reserve for one owner
Give stop feedback or continue work	Stop/SubagentStop context or decision=block with reason
Report after a tool runs	PostToolUse context/feedback; prior side effects remain
Replace a visible tool result	Supported PostToolUse updatedToolOutput
Show ordinary user-facing status	Top-level systemMessage, where supported
Create a custom worktree	WorktreeCreate command stdout contains only its created absolute path

UserPromptSubmit cannot rewrite the prompt through updatedInput. Setup discards JSON output fields. PreCompact has event-specific blocking but no additionalContext injection; PostCompact does not provide that context channel either. PermissionRequest and PermissionDenied have their own decision/retry contracts. Use the reference matrix before copying another event’s schema.

Context can accumulate across handlers. Parameter/result modifications have single-writer semantics; multiple owners can overwrite each other’s edits.

Exit codes and errors

Valid JSON can take effect on nonzero exits. For standard decision events, valid output fields are parsed even when the process exits nonzero. Exit 2 still blocks where supported and cannot be overridden by an allow decision. Other events ignore or route exit codes differently; worktree events use their own contract.

Prefer exit 0 and one JSON object for structured output. A failed command is not automatically a hard denial. Advisory hooks can return an empty result on failure; a policy gate must emit an explicit supported denial or blocking failure. Never reuse an advisory fail-open template for a hard safety requirement without changing and testing its failure paths.

Async handlers do not synchronously block the action. AsyncRewake can report a later result, but it does not turn background work into a pre-action gate.

Reference and validation boundaries

The current references under brewcode/skills/agents/references/ cover all 33 events, five handler types, I/O routing, registration, environment variables, templates, and upstream changes. Consult the exact event/type support rather than assuming every event can block or every handler accepts the same fields.

Test fixtures validate implemented branches; successful local checks do not prove live registration or every runtime payload variant. The final report distinguishes generated files, registration changes, tests actually run, and any remaining live verification.

Related