Responses

Response builders for hook handlers.

Response Functions

allow

allow(
    *,
    modify: dict[str, Any] | None = None,
    message: str | None = None,
    additional_context: str | None = None,
) -> HookResponse

Allow the action to proceed.

Parameters:

Name	Type	Description	Default
modify	dict[str, Any] | None	Optional dict to modify tool input before execution	None
message	str | None	Optional message shown to user	None
additional_context	str | None	Optional text injected into Claude's context alongside the tool result (PreToolUse/PostToolUse). For a bare context injection on any event, prefer :func:context.	None

Returns:

Type	Description
HookResponse	HookResponse with approve decision

deny

deny(
    reason: str,
    *,
    interrupt: bool = False,
    additional_context: str | None = None,
) -> HookResponse

Deny/block the action.

Parameters:

Name	Type	Description	Default
reason	str	Explanation shown to Claude	required
interrupt	bool	If True, stops Claude entirely	False
additional_context	str | None	Optional extra context injected for Claude alongside the denial (PreToolUse/PostToolUse).	None

Returns:

Type	Description
HookResponse	HookResponse with deny decision

block

block(reason: str) -> HookResponse

Block Stop/SubagentStop - force Claude to continue.

Parameters:

Name	Type	Description	Default
reason	str	Explanation of what Claude should do	required

Returns:

Type	Description
HookResponse	HookResponse with block decision

approve_permission

approve_permission(
    *, modify: dict[str, Any] | None = None
) -> PermissionHookResponse

Approve a permission request.

Parameters:

Name	Type	Description	Default
modify	dict[str, Any] | None	Optional dict to modify tool input before execution	None

Returns:

Type	Description
PermissionHookResponse	PermissionHookResponse with allow behavior

deny_permission

deny_permission(
    message: str | None = None, *, interrupt: bool = False
) -> PermissionHookResponse

Deny a permission request.

Parameters:

Name	Type	Description	Default
message	str | None	Explanation shown to Claude	None
interrupt	bool	If True, stops Claude entirely	False

Returns:

Type	Description
PermissionHookResponse	PermissionHookResponse with deny behavior

Response Classes

BaseHookResponse

Bases: ABC

Abstract base class for hook responses.

should_return

should_return() -> bool

Whether this response should be returned (stop handler chain).

Override in subclasses for custom behavior. Default: always return.

to_json abstractmethod

to_json(hook_event_name: str | None = None) -> str

Serialize to Claude Code expected JSON format.

Parameters:

Name	Type	Description	Default
hook_event_name	str | None	The event being responded to. Some events (notably PreToolUse) require an event-specific output shape; pass it so the response serializes correctly.	None

HookResponse dataclass

Bases: BaseHookResponse

Response from a hook handler.

decision class-attribute instance-attribute

decision: str | None = None

reason class-attribute instance-attribute

reason: str | None = None

message class-attribute instance-attribute

message: str | None = None

interrupt class-attribute instance-attribute

interrupt: bool = False

to_json

to_json(hook_event_name: str | None = None) -> str

Serialize to Claude Code expected JSON format.