Responses

Response builders for hook handlers.

Response Functions

allow

allow(
    *,
    modify: dict[str, Any] | None = None,
    message: 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

Returns:

Type	Description
HookResponse	HookResponse with approve decision

deny

deny(
    reason: str, *, interrupt: bool = False
) -> 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

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() -> str

Serialize to Claude Code expected JSON format.

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() -> str

Serialize to Claude Code expected JSON format.