API Reference

Registration

Declaring and registering hooks.

hook()
on()

Primitives

One-line hooks for the common cases.

gate(): Register a blocking gate — nudge(message, block=True, ...) with an explicit signature.
nudge(): Register a nudge that warns (or blocks) when conditions or signals match.
lint(): Register a lint check that runs on source-file edits and writes.
diff_lint(): Register a diff lint: flag only constructs the edit introduces.
block_command(): Register a declarative hook that blocks a Bash command matching a pattern.
warn_command(): Register a declarative hook that warns on a Bash command matching a pattern.
rewrite_command(): Register a PreToolUse hook that rewrites a matching Bash command.
rewrite_code(): Register a PreToolUse hook that structurally rewrites edited code before it is written.
llm_gate(): Register an LLM-powered blocking gate.
llm_nudge(): Register an LLM-powered advisory nudge.
prompt_check(): Run an LLM check with a formatted prompt and return block/warn/None.
approve(): Register a hook that answers matching tool permissions with allow.
deny(): Register a hook that answers matching tool permissions with deny.
llm_approve(): Register an LLM safety judge that auto-approves permission dialogs it deems safe.
style.styleguide(): Register one change-scoped hook applying the given style rules to Python edits and writes.
style.matchers: Composable AST matchers for style rules — import this module as M.
style.StyleRule: Base class for a single-tree AST style rule applied to Python edits and writes.
style.StyleDiffRule: Base class for a diff rule: flags constructs newly introduced by the change.
style.ast_grep_rule(): Build a [StyleRule][captain_hook.style.StyleRule] from an inline ast-grep pattern.
style.ast_grep_diff_rule(): Like [ast_grep_rule][captain_hook.style.ast_grep_rule], but flags only matches the edit newly introduces.
style.AstGrepStyleRule: A [StyleRule][captain_hook.style.StyleRule] matched by an ast-grep pattern over source text.
style.AstGrepStyleDiffRule: An [AstGrepStyleRule][captain_hook.style.AstGrepStyleRule] that flags only constructs the edit introduces.
style.Violation: A single style violation, located by line so the runner can scope it to the edit.
style.Change: The pre- and post-edit state of a file, passed to every style rule’s check.
GateVerdict: LLM response model for llm_gate. The LLM sets block=True to deny.
NudgeVerdict: LLM response model for llm_nudge. The LLM sets fire=True to trigger the nudge.
PromptCheckVerdict: LLM response model for prompt_check. Action is "ok", "warning", or "block".
SafetyVerdict: LLM response model for llm_approve. The LLM sets safe=True to auto-approve.

Conditions

Typed filters that decide when hooks fire.

Tool: Condition matching the current event’s tool name against one or more names.
FilePath: Condition matching the current event’s file path against glob patterns.
types.Command: Condition matching the current event’s bash command against a regex.
Content: Condition matching the current event’s file content against a regex.
Pattern: Condition matching the edit’s new content against an ast-grep structural pattern.
TouchedFile: Transcript-history condition: true when an Edit/Write targeted a file matching the glob.
TestFile: Condition that matches when the current event targets a test file.
ReadFile: Transcript-history condition: true when a Read tool use targeted a matching file.
RanCommand: Transcript-history condition: true when a Bash tool use running argv exists.
Runs: Structural Bash condition: true when a parsed command’s argv starts with argv.
UsedSkill: Transcript-history condition: true when a Skill tool use named one of names.
UsedTool: Transcript-history condition: true when a tool use named one of names exists.
UserSaid: Matches when a user prompt matches one of patterns.
InPlanMode: Matches when the agent is in plan mode.
Waiting: Condition matching while the session is parked on out-of-band work.
FromSubagent: Condition matching when the current event originates from a subagent or teammate.
SkipPermissions: Condition matching when the session was launched with permission bypass available.
FromTeammate: Matches when the current turn’s in-flight subagent spawn is a named teammate.
FreshSession: Matches a SessionStart from a fresh startup or clear, not a resume or compact.
Headless: Matches a headless claude -p / SDK run (CLAUDE_CODE_ENTRYPOINT in the sdk-* family).
RewritingExistingPlan: Matches a Write to a plan file (.md under plans/ or specs/) already written this
ScratchPath: Matches a file-tool target resolving into a system temp root or a scratch-named directory.
EditedSource: Matches when the session edited a non-test, in-repo source file (docs and config excluded).
Commits: Matches a command line whose primary command explicitly names a path ending in suffix.
Redirects: Matches when any command in the line carries a shell redirect (input or output).
Or: Match if any of the inner conditions matches.
And: Match only if every inner condition matches (useful nested inside Or/Not).
Not: Match only if the inner condition does not match.
Signal: A regex-based signal pattern used in the scoring pipeline.
Signals: Bundle of signal patterns with a scoring threshold.
CustomCondition: Protocol for user-defined hook conditions.
CustomCommandLineCondition: CustomCondition that fires only when a parsed Bash command line is present.
CustomInputTypeCondition: CustomCondition that fires only for a specific typed tool call.
workflow_script_source(): The pending Workflow call’s script source, or None.
workflow_opt_values(): Best-effort raw-source scan for values pinned to key in agent() opts. Never raises.

Events & Results

Typed lifecycle events and hook outcomes.

Event: Hook lifecycle events that can trigger registered hooks.
BaseHookEvent: Base class for all hook events, providing access to raw payload, context, and convenience methods.
ToolHookEvent: Event for tool-related hooks, adding tool name, input, command, and file access.
ToolRewriteEvent: Tool event whose input can be rewritten before it runs.
PreToolUseEvent: Fires before a tool is executed. Return a block result to prevent execution.
PermissionRequestEvent: Fires when a permission dialog would be shown.
PostToolUseEvent: Fires after a tool completes successfully, with access to the tool response.
PostToolUseFailureEvent: Fires after a tool fails, providing the error message and interrupt status.
UserPromptSubmitEvent: Fires when the user submits a prompt, before the agent processes it.
StopEvent: Fires when the agent is about to stop. Return a block result to prevent stopping.
SubagentStartEvent: Fires when a subagent is launched. Provides agent_type for filtering.
SubagentStopEvent: Fires when a subagent finishes. Provides agent_type for filtering.
BackgroundTask: A background task keeping the session alive, from a Stop/SubagentStop payload.
SessionCron: A scheduled prompt registered on the session, from a Stop/SubagentStop payload.
PreCompactEvent: Fires before context compaction, providing the trigger and custom instructions.
NotificationEvent: Fires on system notifications, providing message, title, and notification type.
SessionStartEvent: Fires when a session starts, providing what triggered it. Warns inject context; it cannot block.
SessionEndEvent: Fires when the session ends, providing the termination reason. Output is ignored, so it cannot block.
HookContext: Runtime context injected into every hook event.
Turn: The current turn as a one-turn ~cc_transcript.query.Session view.
HookResult: The return value from a hook handler, specifying the action and optional message.
Action: Hook result action determining how the hook output is handled.
Agent: Condition matching the current event’s subagent type against one or more names.

Files & Commands

Path matching and AST-level command inspection.

File: A file path wrapper with glob matching, prefix checks, and test-file detection.
file.PathMatcher: A reusable set of glob patterns for matching file paths. Supports in operator.
file.categorize_files(): Split paths into source, test, and skipped buckets for a language.
util.fs.read_json(): Read and parse a JSON file, returning default on missing file or parse error.
util.fs.resolve_binary(): Resolve an absolute, executable path for name, or None.
util.fs.binary_supports(): Whether the binary name advertises flag in its --help output.
Cmd: The parsed command line behind evt.cmd — a walk over every command invocation it contains.
Call: One command invocation reached by walking a command line — a top-level occurrence, a
Target: One operand of a command — a literal path or a glob — with resolution and blast-radius predicates.
Targets: The operand targets of a command, in order — iterable, sized, and expandable as a whole.
Expansion: The paths a target’s glob resolves to, plus whether the walk budget was exhausted.
Command: A single parsed shell command with executable, arguments, env vars, and redirects.
CommandLine: A full parsed bash command line, potentially containing multiple commands joined by operators.
Redirect: A shell redirect parsed from a bash command (e.g. > file.txt, 2>&1).
Word: One structural word of a parsed command (Command.words).

Tool Calls

Typed tool-call inputs reached via evt.input and evt.as_input().

ToolCall
ToolCallBase: Common shape of every typed tool call.
ReadCall: A Read of a file, optionally windowed.
BashCall: A Bash/Execute shell invocation.
EditCall: An Edit replacement of old with new in one file.
MultiEditCall: A MultiEdit applying edits to one file, in order.
WriteCall: A Write/Create of a whole file.
NotebookEditCall: A NotebookEdit replacing a cell’s source.
GlobCall: A Glob file-pattern search.
GrepCall: A Grep content search.
SkillCall: A Skill invocation.
TaskCall: An Agent/Task subagent dispatch.
TaskCreateCall: A TaskCreate tracker entry.
TaskUpdateCall: A TaskUpdate tracker change.
ExitPlanModeCall: An ExitPlanMode/ExitSpecMode plan submission.
OtherCall: A tool the platform does not type: unknown names, MCP tools, and — under

Tasks

The native task list, read via evt.tasks.

Task: A task read from Claude Code’s native task store (~/.claude/tasks/<list-id>/<id>.json).
Tasks: The live task list for one session, read from the native store rather than the transcript.

Signals

NLP signal scoring over transcript text.

Clause: One dependency-aware pattern matched against each sentence of a text.
NlpSignal: A transcript signal that scores weight when any clause matches a sentence.
Phrase: A set of lowercased lemmas naming one concept, matched against tokens by lemma.
is_past_predicate(): Whether tok reports a completed action.
has_nominal_subject(): Whether tok has a substantive active subject.
subject_kind(): The shape of tok’s subject, as Clause’s subject constraint sees it.

State & Sessions

Session state, workflow state, and multi-step workflows.

HookState: Per-hook persistent state tracked across events in a session (fire_count for max_fires).
PrimitiveState: Per-primitive nudge/gate state shared across all hooks in a session.
SourceEdits: Condition matching an Edit/Write of a non-test source file in one language.
WorkflowState: Base for a pydantic model that bundles one session workflow across several hooks.
workflow_state()
SessionSlot: A typed slot for reading/writing a single Pydantic model in a session directory.
SessionStore: Class-keyed store providing typed SessionSlot access via store[ModelClass].
session_state(): Decorator that registers a Pydantic model for collective SessionStore introspection.
DurableState: Base for a model persisted across sessions, scoped by the scope class keyword.
DurableSlot: A SessionSlot rooted in a durable directory; inherits the locked mutate().
DurableStore: Class-keyed durable store providing typed DurableSlot access via store[Model].
Deque: A bounded deque field type whose maxlen survives JSON round-trips.
Workflow
Step: One step of a workflow() guard: check gates progress, message is shown when it fails.
Artifact
text_matches()
workflow()

Transcripts

Registering external transcripts into a session’s deep view.

register_transcript(): Register an external transcript against session_id so it folds into the deep view.
RegisteredTranscript: An external transcript folded into a session’s deep view — a codex thread id or a file path.
RegisteredTranscripts: The external transcripts registered against one session, in registration order.

Testing

Inline tests for hooks.

Input: Inline test input descriptor modeling an event payload.
T: Namespaced transcript-fixture builders for Input(transcript=[...]) in inline tests.
Allow: Inline test expectation: the hook should allow (return None or action "allow").
Block: Inline test expectation: the hook should block. Optional regex pattern matches the block message.
Warn: Inline test expectation: the hook should warn. Optional regex pattern matches the warning message.
Rewrite: Inline test expectation: the hook should rewrite the tool input.
Ask: Inline test expectation: the hook returned no result (None).
FileFixture: Inline-test file descriptor: materialized to a real temp file so size/stat-based guards run for real.
TranscriptFixture: A lightweight transcript stub for use in inline tests.

Configuration & Prompts

Settings, scaffolding, and LLM prompt helpers.

HooksSettings: Base settings class for hook configuration, backed by environment variables with HOOKS_ prefix.
build_settings(): Build settings from a conf module via an explicit HooksSettings subclass or auto-inferred fields.
Prompt: Fluent builder for structured LLM prompts with system text, XML context sections, and a question.

Prompt Contexts

Declarative evidence blocks attached to LLM primitive prompts.

PromptContext: One declarative XML block attached to an LLM primitive’s prompt.
apply_contexts(): Append each context’s block to prompt in order, each clipped to max_len characters.
BeforeEdit: The pending edit’s pre-image, as a <before_edit> block.
AfterEdit: The pending edit’s new text, as an <after_edit> block.
Introduced: Constructs the pending edit newly introduces, as an auto-tagged block.
WorkflowScriptSource: Gating context: the pending Workflow call’s script source, headed by its model pins.
UserMessages: The session’s user prompts as a <user_messages> request/authorization record.
Excerpts: Verbatim excerpts pulled from a text under a character budget.
excerpt_around(): Verbatim excerpts of text around each (start, end) character span.
COMMENT_TYPES: Tree-sitter node kinds that denote a comment, across every supported grammar.
Edit: The pending edit’s before/after source, parsed for structural queries.
SyntaxNode: One node of a parsed syntax tree — the framework’s face over the ast-grep binding node.
Match: A structural match, located by 1-based line to align with Violation and changed-line scoping.