ClaudeCode.Hook behaviour (ClaudeCode v0.21.0)

Behaviour for hook callbacks.

Implement this behaviour in a module, or pass an anonymous function with the same call/2 signature. Used by both :can_use_tool and :hooks options.

Return types by event

The return type depends on which event the hook is registered for:

can_use_tool / PreToolUse (permission decisions)

:allow
{:allow, updated_input}
{:allow, updated_input, permissions: [permission_update]}
{:deny, reason}
{:deny, reason, interrupt: true}

PostToolUse / PostToolUseFailure (observation only)

:ok

UserPromptSubmit

:ok
{:reject, reason}

Stop / SubagentStop

:ok
{:continue, reason}

PreCompact

:ok
{:instructions, custom_instructions}

Notification / SubagentStart (observation only)

:ok

Summary

Callbacks

call(input, tool_use_id)

Functions

invoke(hook, input, tool_use_id)

Invokes a hook callback (module or function) with error protection.

Callbacks

call(input, tool_use_id)

@callback call(input :: map(), tool_use_id :: String.t() | nil) :: term()

Functions

invoke(hook, input, tool_use_id)

@spec invoke(module() | function(), map(), String.t() | nil) :: term()

Invokes a hook callback (module or function) with error protection.

Returns the callback's result, or {:error, reason} if it raises.