Skip to content

types

types

Event

Bases: Flag

Hook lifecycle events that can trigger registered hooks.

Combinable with | to match multiple events in a single hook registration.

Example

hook(Event.Stop | Event.SubagentStop, message="review first", block=True)

Action

Bases: StrEnum

Hook result action determining how the hook output is handled.

  • block: Prevents the tool use or stops the agent.
  • warn: Adds advisory context without blocking.
  • allow: Explicitly permits the action.

Tool dataclass 

Tool(pattern: str)

Condition matching the current event's tool name against a regex pattern.

Use in only_if or skip_if to filter hooks by which tool is being used.

Example

hook(Event.PreToolUse, only_if=[Tool("Bash|Execute")], message="...", block=True)

FilePath 

FilePath(*patterns: str, **kwargs: bool)

Bases: FilePathFields

Condition matching the current event's file path against glob patterns.

Accepts one or more glob patterns as positional arguments.

Example

hook(Event.PostToolUse, only_if=[FilePath(".py", ".pyi")], message="Python file edited")

Command dataclass 

Command(pattern: str)

Condition matching the current event's bash command against a regex.

Only relevant for PreToolUse events targeting the Bash/Execute tool.

Example

hook(Event.PreToolUse, only_if=[Command(r"git\s+stash")], message="blocked", block=True)

Content dataclass 

Content(pattern: str, project_only: bool = True)

Condition matching the current event's file content against a regex.

Applies to Edit (new content) and Write (file content) tool events.

UsedSkill dataclass 

UsedSkill(name: str, subagents: bool = True)

Transcript-history condition: true when a Skill tool use with a matching name exists.

ReadFile 

ReadFile(*patterns: str, **kwargs: bool)

Bases: ReadFileFields

Transcript-history condition: true when a Read tool use targeted a matching file.

Accepts one or more glob patterns as positional arguments.

TestFile dataclass 

TestFile(project_only: bool = True)

Condition that matches when the current event targets a test file (test_*.py, conftest.py).

Agent dataclass 

Agent(name: str)

Condition matching the current event's subagent type against a name pattern.

TouchedFile 

TouchedFile(*patterns: str, **kwargs: bool)

Bases: TouchedFileFields

Transcript-history condition: true when an Edit/Write targeted a file matching the glob.

Accepts one or more glob patterns as positional arguments.

RanCommand dataclass 

RanCommand(pattern: str, subagents: bool = True)

Transcript-history condition: true when a Bash tool use with a matching command exists.

InPlanMode dataclass 

InPlanMode()

Matches when the agent is in plan mode.

Reads permission_mode from the current event payload; falls back to counting EnterPlanMode vs ExitPlanMode tool uses in the transcript when the payload omits the field.

ConditionList dataclass 

ConditionList(conditions: tuple[TCondition, ...])

Container for a tuple of conditions; base class for combinators like Or.

Or 

Or(*conditions: TCondition)

Bases: ConditionList

Match if any of the inner conditions matches.

CustomCondition

Bases: Protocol

Protocol for user-defined hook conditions.

Implement check to create arbitrary matching logic beyond the built-in condition types.

Example

class LargeFile(CustomCondition): ... def check(self, evt: BaseHookEvent) -> bool: ... return bool(evt.file and evt.file.path.stat().st_size > 1_000_000) ... app.hook(Event.PreToolUse, only_if=[LargeFile()], message="Large file", block=True)

Signal dataclass 

Signal(*, pattern: str, weight: int = 1, flags: int = 0)

A regex-based signal pattern used in the scoring pipeline.

Signals are matched against transcript text via re.search. Each match contributes weight to the cumulative score. Use negative weights to suppress false positives.

Example

Signal(pattern=r"retry", weight=2, flags=re.IGNORECASE)

Signals dataclass 

Signals(
    patterns: Sequence[Signal | NlpSignal],
    threshold: int,
    window: int = 15,
)

Bundle of signal patterns with a scoring threshold.

When a bare list[Signal] is passed to a primitive, resolve_signals wraps it with threshold=1 — meaning any single signal match triggers. Pass a higher threshold to require multiple signals to fire together.

HookResult dataclass 

HookResult(*, action: Action, message: str | None = None)

The return value from a hook handler, specifying the action and optional message.

of classmethod 
of(
    action: Action, message: str | None = None
) -> HookResult

Build a HookResult, dedenting and stripping message for readable triple-quoted handler returns.

RegisteredHook dataclass 

RegisteredHook(
    *,
    spec: HookSpec,
    handler: Callable[[BaseHookEvent], HookResult | None]
    | None = None,
    name: str = "",
    source_file: str = "",
)

A registered hook pairing a HookSpec with an optional handler callable.