# captain_hook

> Declarative hook framework for Claude Code

## Docs

### API Reference

#### Registration
> Declaring and registering hooks.

- [hook](https://yasyf.github.io/captain-hook/reference/hook.html)
- [on](https://yasyf.github.io/captain-hook/reference/on.html)
- [register](https://yasyf.github.io/captain-hook/reference/register.html)

#### Primitives
> One-line hooks for the common cases.

- [audit](https://yasyf.github.io/captain-hook/reference/audit.html): Register a hook that appends one JSONL record per matching event
- [gate](https://yasyf.github.io/captain-hook/reference/gate.html): Register a blocking gate — shorthand for ``nudge(message, block=True, ...)``
- [nudge](https://yasyf.github.io/captain-hook/reference/nudge.html): Register a nudge that warns (or blocks) when conditions or signals match
- [lint](https://yasyf.github.io/captain-hook/reference/lint.html): Register a lint check that runs on Python file edits/writes
- [diff_lint](https://yasyf.github.io/captain-hook/reference/diff_lint.html)
- [block_command](https://yasyf.github.io/captain-hook/reference/block_command.html): Register a declarative hook that blocks a Bash command matching a pattern
- [warn_command](https://yasyf.github.io/captain-hook/reference/warn_command.html): Register a declarative hook that warns on a Bash command matching a pattern
- [llm_gate](https://yasyf.github.io/captain-hook/reference/llm_gate.html): Register an LLM-powered blocking gate
- [llm_nudge](https://yasyf.github.io/captain-hook/reference/llm_nudge.html): Register an LLM-powered advisory nudge
- [llm_evaluate](https://yasyf.github.io/captain-hook/reference/llm_evaluate.html)
- [prompt_check](https://yasyf.github.io/captain-hook/reference/prompt_check.html): Run an LLM check with a formatted prompt and return block/warn/None
- [style.styleguide](https://yasyf.github.io/captain-hook/reference/style.styleguide.html)
- [style.matchers](https://yasyf.github.io/captain-hook/reference/style.matchers.html)
- [style.StyleRule](https://yasyf.github.io/captain-hook/reference/style.StyleRule.html)
- [style.StyleDiffRule](https://yasyf.github.io/captain-hook/reference/style.StyleDiffRule.html)
- [style.Violation](https://yasyf.github.io/captain-hook/reference/style.Violation.html)
- [GateVerdict](https://yasyf.github.io/captain-hook/reference/GateVerdict.html): LLM response model for ``llm_gate``. The LLM sets ``block=True`` to deny
- [NudgeVerdict](https://yasyf.github.io/captain-hook/reference/NudgeVerdict.html): LLM response model for ``llm_nudge``. The LLM sets ``fire=True`` to trigger the nudge
- [PromptCheckVerdict](https://yasyf.github.io/captain-hook/reference/PromptCheckVerdict.html): LLM response model for ``prompt_check``. Action is ``"ok"``, ``"warning"``, or ``"block"``

#### Conditions
> Typed filters that decide when hooks fire.

- [Tool](https://yasyf.github.io/captain-hook/reference/Tool.html): Condition matching the current event's tool name against a regex pattern
- [FilePath](https://yasyf.github.io/captain-hook/reference/FilePath.html): Condition matching the current event's file path against glob patterns
- [TouchedFile](https://yasyf.github.io/captain-hook/reference/TouchedFile.html): Transcript-history condition: true when an Edit/Write targeted a file matching the glob
- [TestFile](https://yasyf.github.io/captain-hook/reference/TestFile.html): Condition that matches when the current event targets a test file (``test_*.py``, ``conftest.py``)
- [ReadFile](https://yasyf.github.io/captain-hook/reference/ReadFile.html): Transcript-history condition: true when a Read tool use targeted a matching file
- [RanCommand](https://yasyf.github.io/captain-hook/reference/RanCommand.html): Transcript-history condition: true when a Bash tool use with a matching command exists
- [UsedSkill](https://yasyf.github.io/captain-hook/reference/UsedSkill.html): Transcript-history condition: true when a Skill tool use with a matching name exists
- [InPlanMode](https://yasyf.github.io/captain-hook/reference/InPlanMode.html): Matches when the agent is in plan mode
- [Waiting](https://yasyf.github.io/captain-hook/reference/Waiting.html): Waiting()
- [Signal](https://yasyf.github.io/captain-hook/reference/Signal.html): A regex-based signal pattern used in the scoring pipeline
- [Signals](https://yasyf.github.io/captain-hook/reference/Signals.html): Bundle of signal patterns with a scoring threshold
- [CustomCondition](https://yasyf.github.io/captain-hook/reference/CustomCondition.html): Protocol for user-defined hook conditions

#### Events & Results
> Typed lifecycle events and hook outcomes.

- [Event](https://yasyf.github.io/captain-hook/reference/Event.html): Hook lifecycle events that can trigger registered hooks
- [BaseHookEvent](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.html): Base class for all hook events, providing access to raw payload, context, and convenience methods
- [ToolHookEvent](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.html): Event for tool-related hooks, adding tool name, input, command, and file access
- [PreToolUseEvent](https://yasyf.github.io/captain-hook/reference/PreToolUseEvent.html): Fires before a tool is executed. Return a block result to prevent execution
- [PostToolUseEvent](https://yasyf.github.io/captain-hook/reference/PostToolUseEvent.html): Fires after a tool completes successfully, with access to the tool response
- [PostToolUseFailureEvent](https://yasyf.github.io/captain-hook/reference/PostToolUseFailureEvent.html): Fires after a tool fails, providing the error message and interrupt status
- [UserPromptSubmitEvent](https://yasyf.github.io/captain-hook/reference/UserPromptSubmitEvent.html): Fires when the user submits a prompt, before the agent processes it
- [StopEvent](https://yasyf.github.io/captain-hook/reference/StopEvent.html): Fires when the agent is about to stop. Return a block result to prevent stopping
- [SubagentStartEvent](https://yasyf.github.io/captain-hook/reference/SubagentStartEvent.html): Fires when a subagent is launched. Provides ``agent_type`` for filtering
- [SubagentStopEvent](https://yasyf.github.io/captain-hook/reference/SubagentStopEvent.html): Fires when a subagent finishes. Provides ``agent_type`` for filtering
- [PreCompactEvent](https://yasyf.github.io/captain-hook/reference/PreCompactEvent.html): Fires before context compaction, providing the trigger and custom instructions
- [NotificationEvent](https://yasyf.github.io/captain-hook/reference/NotificationEvent.html): Fires on system notifications, providing message, title, and notification type
- [HookContext](https://yasyf.github.io/captain-hook/reference/HookContext.html): Runtime context injected into every hook event: session state, transcript, settings, and LLM/CLI helpers
- [HookResult](https://yasyf.github.io/captain-hook/reference/HookResult.html): The return value from a hook handler, specifying the action and optional message
- [Action](https://yasyf.github.io/captain-hook/reference/Action.html): Hook result action determining how the hook output is handled
- [Agent](https://yasyf.github.io/captain-hook/reference/Agent.html): Condition matching the current event's subagent type against a name pattern
- [Content](https://yasyf.github.io/captain-hook/reference/Content.html): Condition matching the current event's file content against a regex

#### BaseHookEvent Methods
> Methods for the BaseHookEvent class

- [BaseHookEvent.event](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.event.html)
- [BaseHookEvent.is_subagent](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.is_subagent.html)
- [BaseHookEvent.session_id](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.session_id.html)
- [BaseHookEvent.tasks](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.tasks.html)
- [BaseHookEvent.user_prompt](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.user_prompt.html)
- [BaseHookEvent.stop_hook_active](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.stop_hook_active.html)
- [BaseHookEvent.transcript_path](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.transcript_path.html)
- [BaseHookEvent.permission_mode](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.permission_mode.html)
- [BaseHookEvent.parent_agent_type](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.parent_agent_type.html)
- [BaseHookEvent.tool_name](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.tool_name.html)
- [BaseHookEvent.input](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.input.html)
- [BaseHookEvent.command](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.command.html)
- [BaseHookEvent.command_line](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.command_line.html)
- [BaseHookEvent.file](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.file.html)
- [BaseHookEvent.content](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.content.html)
- [BaseHookEvent.old](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.old.html)
- [BaseHookEvent.agent_type](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.agent_type.html)
- [BaseHookEvent.command_matches](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.command_matches.html)
- [BaseHookEvent.file_matches](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.file_matches.html)
- [BaseHookEvent.content_matches](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.content_matches.html)
- [BaseHookEvent.allow](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.allow.html)
- [BaseHookEvent.warn](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.warn.html)
- [BaseHookEvent.block](https://yasyf.github.io/captain-hook/reference/BaseHookEvent.block.html)

#### ToolHookEvent Methods
> Methods for the ToolHookEvent class

- [ToolHookEvent.tool_name](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.tool_name.html)
- [ToolHookEvent.command_line](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.command_line.html)
- [ToolHookEvent.content](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.content.html)
- [ToolHookEvent.old](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.old.html)
- [ToolHookEvent.agent_type](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.agent_type.html)
- [ToolHookEvent.command_matches](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.command_matches.html)
- [ToolHookEvent.file_matches](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.file_matches.html)
- [ToolHookEvent.content_matches](https://yasyf.github.io/captain-hook/reference/ToolHookEvent.content_matches.html)

#### HookContext Methods
> Methods for the HookContext class

- [HookContext.t](https://yasyf.github.io/captain-hook/reference/HookContext.t.html)
- [HookContext.s](https://yasyf.github.io/captain-hook/reference/HookContext.s.html)
- [HookContext.state](https://yasyf.github.io/captain-hook/reference/HookContext.state.html)
- [HookContext.conf](https://yasyf.github.io/captain-hook/reference/HookContext.conf.html)
- [HookContext.c](https://yasyf.github.io/captain-hook/reference/HookContext.c.html)
- [HookContext.turn](https://yasyf.github.io/captain-hook/reference/HookContext.turn.html)
- [HookContext.prior](https://yasyf.github.io/captain-hook/reference/HookContext.prior.html)
- [HookContext.call_cli](https://yasyf.github.io/captain-hook/reference/HookContext.call_cli.html)
- [HookContext.git](https://yasyf.github.io/captain-hook/reference/HookContext.git.html)
- [HookContext.changed_paths](https://yasyf.github.io/captain-hook/reference/HookContext.changed_paths.html)
- [HookContext.repo_root](https://yasyf.github.io/captain-hook/reference/HookContext.repo_root.html)
- [HookContext.current_branch](https://yasyf.github.io/captain-hook/reference/HookContext.current_branch.html)
- [HookContext.call_llm](https://yasyf.github.io/captain-hook/reference/HookContext.call_llm.html)
- [HookContext.resolve_schema_path](https://yasyf.github.io/captain-hook/reference/HookContext.resolve_schema_path.html)

#### Files & Commands
> Path matching and AST-level command inspection.

- [File](https://yasyf.github.io/captain-hook/reference/File.html): A file path wrapper with glob matching, prefix checks, and test-file detection
- [file.PathMatcher](https://yasyf.github.io/captain-hook/reference/file.PathMatcher.html)
- [file.categorize_files](https://yasyf.github.io/captain-hook/reference/file.categorize_files.html)
- [utils.read_json](https://yasyf.github.io/captain-hook/reference/utils.read_json.html)
- [Command](https://yasyf.github.io/captain-hook/reference/Command.html): A single parsed shell command with executable, arguments, env vars, and redirects
- [CommandLine](https://yasyf.github.io/captain-hook/reference/CommandLine.html): A full parsed bash command line, potentially containing multiple commands joined by operators
- [Redirect](https://yasyf.github.io/captain-hook/reference/Redirect.html): A shell redirect parsed from a bash command (e.g. ``> file.txt``, ``2>&1``)
- [EditOp](https://yasyf.github.io/captain-hook/reference/EditOp.html): A parsed Edit tool operation extracted from a transcript tool use
- [WriteOp](https://yasyf.github.io/captain-hook/reference/WriteOp.html): A parsed Write/Create tool operation extracted from a transcript tool use
- [TaskOp](https://yasyf.github.io/captain-hook/reference/TaskOp.html): A parsed task-tracker operation (create/update/get/list) extracted from a transcript tool use

#### File Methods
> Methods for the File class

- [File.__getattr__](https://yasyf.github.io/captain-hook/reference/File.__getattr__.html)
- [File.__str__](https://yasyf.github.io/captain-hook/reference/File.__str__.html)
- [File.__fspath__](https://yasyf.github.io/captain-hook/reference/File.__fspath__.html)
- [File.__eq__](https://yasyf.github.io/captain-hook/reference/File.__eq__.html)
- [File.__hash__](https://yasyf.github.io/captain-hook/reference/File.__hash__.html)
- [File.is_test](https://yasyf.github.io/captain-hook/reference/File.is_test.html)
- [File.matches](https://yasyf.github.io/captain-hook/reference/File.matches.html)
- [File.under](https://yasyf.github.io/captain-hook/reference/File.under.html)
- [File.exists](https://yasyf.github.io/captain-hook/reference/File.exists.html)
- [File.read_text](https://yasyf.github.io/captain-hook/reference/File.read_text.html)
- [File.contains](https://yasyf.github.io/captain-hook/reference/File.contains.html)

#### Command Methods
> Methods for the Command class

- [Command.parse](https://yasyf.github.io/captain-hook/reference/Command.parse.html)
- [Command.empty](https://yasyf.github.io/captain-hook/reference/Command.empty.html)
- [Command.argv](https://yasyf.github.io/captain-hook/reference/Command.argv.html)
- [Command.program](https://yasyf.github.io/captain-hook/reference/Command.program.html)
- [Command.env_dict](https://yasyf.github.io/captain-hook/reference/Command.env_dict.html)
- [Command.matches](https://yasyf.github.io/captain-hook/reference/Command.matches.html)
- [Command.has_arg](https://yasyf.github.io/captain-hook/reference/Command.has_arg.html)
- [Command.__str__](https://yasyf.github.io/captain-hook/reference/Command.__str__.html)
- [Command.__contains__](https://yasyf.github.io/captain-hook/reference/Command.__contains__.html)
- [Command.__bool__](https://yasyf.github.io/captain-hook/reference/Command.__bool__.html)

#### CommandLine Methods
> Methods for the CommandLine class

- [CommandLine.parse](https://yasyf.github.io/captain-hook/reference/CommandLine.parse.html)
- [CommandLine.commands](https://yasyf.github.io/captain-hook/reference/CommandLine.commands.html)
- [CommandLine.primary](https://yasyf.github.io/captain-hook/reference/CommandLine.primary.html)
- [CommandLine.head](https://yasyf.github.io/captain-hook/reference/CommandLine.head.html)
- [CommandLine.__iter__](https://yasyf.github.io/captain-hook/reference/CommandLine.__iter__.html)
- [CommandLine.__len__](https://yasyf.github.io/captain-hook/reference/CommandLine.__len__.html)
- [CommandLine.__str__](https://yasyf.github.io/captain-hook/reference/CommandLine.__str__.html)
- [CommandLine.__contains__](https://yasyf.github.io/captain-hook/reference/CommandLine.__contains__.html)
- [CommandLine.__bool__](https://yasyf.github.io/captain-hook/reference/CommandLine.__bool__.html)
- [CommandLine.q](https://yasyf.github.io/captain-hook/reference/CommandLine.q.html)
- [CommandLine.node_text](https://yasyf.github.io/captain-hook/reference/CommandLine.node_text.html)
- [CommandLine.word_text](https://yasyf.github.io/captain-hook/reference/CommandLine.word_text.html)
- [CommandLine.extract_redirect](https://yasyf.github.io/captain-hook/reference/CommandLine.extract_redirect.html)
- [CommandLine.extract_command](https://yasyf.github.io/captain-hook/reference/CommandLine.extract_command.html)
- [CommandLine.collect_parts](https://yasyf.github.io/captain-hook/reference/CommandLine.collect_parts.html)
- [CommandLine.walk_redirected](https://yasyf.github.io/captain-hook/reference/CommandLine.walk_redirected.html)
- [CommandLine.walk_node](https://yasyf.github.io/captain-hook/reference/CommandLine.walk_node.html)
- [CommandLine.fallback](https://yasyf.github.io/captain-hook/reference/CommandLine.fallback.html)

#### Transcript
> Typed access to conversation history.

- [Transcript](https://yasyf.github.io/captain-hook/reference/Transcript.html): The full session transcript: a sequence of messages with tool-use querying, slicing, and history checks
- [TranscriptMessage](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.html): A single message in a transcript with parsed content blocks, tool-use extraction, and text access
- [TranscriptSlice](https://yasyf.github.io/captain-hook/reference/TranscriptSlice.html): A contiguous slice of a Transcript, returned by slicing operations like ``recent``, ``after``, ``before``
- [ToolUse](https://yasyf.github.io/captain-hook/reference/ToolUse.html): A transcript tool invocation with typed input parsing, file/command access, and result linkage
- [ToolUseQuery](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.html): Chainable query builder for filtering and inspecting transcript tool uses
- [ToolUseSequence](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.html): Sequence of tool uses that filters out errors by default
- [Turn](https://yasyf.github.io/captain-hook/reference/Turn.html): The current conversation turn starting from the last user message, with edited-file tracking
- [Task](https://yasyf.github.io/captain-hook/reference/Task.html): A task read from Claude Code's native task store (``~/.claude/tasks/<list-id>/<id>.json``)
- [Tasks](https://yasyf.github.io/captain-hook/reference/Tasks.html): The live task list for one session, read from the native store rather than the transcript

#### Transcript Methods
> Methods for the Transcript class

- [Transcript.is_user_message](https://yasyf.github.io/captain-hook/reference/Transcript.is_user_message.html)
- [Transcript.__len__](https://yasyf.github.io/captain-hook/reference/Transcript.__len__.html)
- [Transcript.__bool__](https://yasyf.github.io/captain-hook/reference/Transcript.__bool__.html)
- [Transcript.__getitem__](https://yasyf.github.io/captain-hook/reference/Transcript.__getitem__.html)
- [Transcript.__str__](https://yasyf.github.io/captain-hook/reference/Transcript.__str__.html)
- [Transcript.from_path](https://yasyf.github.io/captain-hook/reference/Transcript.from_path.html)
- [Transcript.from_simple_messages](https://yasyf.github.io/captain-hook/reference/Transcript.from_simple_messages.html)
- [Transcript.from_messages](https://yasyf.github.io/captain-hook/reference/Transcript.from_messages.html)
- [Transcript.from_parsed](https://yasyf.github.io/captain-hook/reference/Transcript.from_parsed.html)
- [Transcript.tool_uses](https://yasyf.github.io/captain-hook/reference/Transcript.tool_uses.html)
- [Transcript.count_tools](https://yasyf.github.io/captain-hook/reference/Transcript.count_tools.html)
- [Transcript.has_tool](https://yasyf.github.io/captain-hook/reference/Transcript.has_tool.html)
- [Transcript.commands](https://yasyf.github.io/captain-hook/reference/Transcript.commands.html)
- [Transcript.has_command](https://yasyf.github.io/captain-hook/reference/Transcript.has_command.html)
- [Transcript.has_edit_to](https://yasyf.github.io/captain-hook/reference/Transcript.has_edit_to.html)
- [Transcript.user_said](https://yasyf.github.io/captain-hook/reference/Transcript.user_said.html)
- [Transcript.all_edits_under](https://yasyf.github.io/captain-hook/reference/Transcript.all_edits_under.html)
- [Transcript.first_user_message](https://yasyf.github.io/captain-hook/reference/Transcript.first_user_message.html)
- [Transcript.after](https://yasyf.github.io/captain-hook/reference/Transcript.after.html)
- [Transcript.before](https://yasyf.github.io/captain-hook/reference/Transcript.before.html)
- [Transcript.prior](https://yasyf.github.io/captain-hook/reference/Transcript.prior.html)
- [Transcript.recent](https://yasyf.github.io/captain-hook/reference/Transcript.recent.html)
- [Transcript.full_text](https://yasyf.github.io/captain-hook/reference/Transcript.full_text.html)
- [Transcript.assistant_text](https://yasyf.github.io/captain-hook/reference/Transcript.assistant_text.html)
- [Transcript.extract_files](https://yasyf.github.io/captain-hook/reference/Transcript.extract_files.html)
- [Transcript.has_read](https://yasyf.github.io/captain-hook/reference/Transcript.has_read.html)
- [Transcript.has_skill](https://yasyf.github.io/captain-hook/reference/Transcript.has_skill.html)
- [Transcript.subagents](https://yasyf.github.io/captain-hook/reference/Transcript.subagents.html)
- [Transcript.count_failures](https://yasyf.github.io/captain-hook/reference/Transcript.count_failures.html)
- [Transcript.has_override](https://yasyf.github.io/captain-hook/reference/Transcript.has_override.html)
- [Transcript.edit_ops](https://yasyf.github.io/captain-hook/reference/Transcript.edit_ops.html)
- [Transcript.write_ops](https://yasyf.github.io/captain-hook/reference/Transcript.write_ops.html)
- [Transcript.task_ops](https://yasyf.github.io/captain-hook/reference/Transcript.task_ops.html)
- [Transcript.turn_start](https://yasyf.github.io/captain-hook/reference/Transcript.turn_start.html)
- [Transcript.current_turn](https://yasyf.github.io/captain-hook/reference/Transcript.current_turn.html)
- [Transcript.since_last_user](https://yasyf.github.io/captain-hook/reference/Transcript.since_last_user.html)

#### TranscriptMessage Methods
> Methods for the TranscriptMessage class

- [TranscriptMessage.from_raw](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.from_raw.html)
- [TranscriptMessage.is_async_tool_use](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.is_async_tool_use.html)
- [TranscriptMessage.notification](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.notification.html)
- [TranscriptMessage.tool_uses](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.tool_uses.html)
- [TranscriptMessage.tool_results](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.tool_results.html)
- [TranscriptMessage.text](https://yasyf.github.io/captain-hook/reference/TranscriptMessage.text.html)

#### ToolUse Methods
> Methods for the ToolUse class

- [ToolUse.is_error](https://yasyf.github.io/captain-hook/reference/ToolUse.is_error.html)
- [ToolUse.input](https://yasyf.github.io/captain-hook/reference/ToolUse.input.html)
- [ToolUse.file](https://yasyf.github.io/captain-hook/reference/ToolUse.file.html)
- [ToolUse.command](https://yasyf.github.io/captain-hook/reference/ToolUse.command.html)
- [ToolUse.command_line](https://yasyf.github.io/captain-hook/reference/ToolUse.command_line.html)
- [ToolUse.agent_type](https://yasyf.github.io/captain-hook/reference/ToolUse.agent_type.html)

#### ToolUseQuery Methods
> Methods for the ToolUseQuery class

- [ToolUseQuery.where](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.where.html)
- [ToolUseQuery.count](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.count.html)
- [ToolUseQuery.any](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.any.html)
- [ToolUseQuery.list](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.list.html)
- [ToolUseQuery.first](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.first.html)
- [ToolUseQuery.last](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.last.html)
- [ToolUseQuery.files](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.files.html)
- [ToolUseQuery.__iter__](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.__iter__.html)
- [ToolUseQuery.__len__](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.__len__.html)
- [ToolUseQuery.__bool__](https://yasyf.github.io/captain-hook/reference/ToolUseQuery.__bool__.html)

#### ToolUseSequence Methods
> Methods for the ToolUseSequence class

- [ToolUseSequence.where](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.where.html)
- [ToolUseSequence.__getitem__](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.__getitem__.html)
- [ToolUseSequence.__iter__](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.__iter__.html)
- [ToolUseSequence.__len__](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.__len__.html)
- [ToolUseSequence.__bool__](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.__bool__.html)
- [ToolUseSequence.with_errors](https://yasyf.github.io/captain-hook/reference/ToolUseSequence.with_errors.html)

#### Tasks Methods
> Methods for the Tasks class

- [Tasks.resolve_root](https://yasyf.github.io/captain-hook/reference/Tasks.resolve_root.html)
- [Tasks.for_session](https://yasyf.github.io/captain-hook/reference/Tasks.for_session.html)
- [Tasks.__getitem__](https://yasyf.github.io/captain-hook/reference/Tasks.__getitem__.html)
- [Tasks.__len__](https://yasyf.github.io/captain-hook/reference/Tasks.__len__.html)
- [Tasks.get](https://yasyf.github.io/captain-hook/reference/Tasks.get.html)
- [Tasks.with_status](https://yasyf.github.io/captain-hook/reference/Tasks.with_status.html)
- [Tasks.pending](https://yasyf.github.io/captain-hook/reference/Tasks.pending.html)
- [Tasks.in_progress](https://yasyf.github.io/captain-hook/reference/Tasks.in_progress.html)
- [Tasks.completed](https://yasyf.github.io/captain-hook/reference/Tasks.completed.html)
- [Tasks.open](https://yasyf.github.io/captain-hook/reference/Tasks.open.html)
- [Tasks.all_completed](https://yasyf.github.io/captain-hook/reference/Tasks.all_completed.html)

#### Tool Inputs
> Parsed tool-input models.

- [InputBase](https://yasyf.github.io/captain-hook/reference/InputBase.html): Base class for typed tool inputs. Provides ``from_raw()`` parsing and ``as_()`` type narrowing
- [FileInputBase](https://yasyf.github.io/captain-hook/reference/FileInputBase.html): Base for tool inputs that reference a file, providing a cached ``file`` property returning a ``File``
- [AgentInput](https://yasyf.github.io/captain-hook/reference/AgentInput.html): Parsed Agent/Task tool input
- [BashInput](https://yasyf.github.io/captain-hook/reference/BashInput.html): Parsed Bash/Execute tool input
- [EditInput](https://yasyf.github.io/captain-hook/reference/EditInput.html): Parsed Edit tool input with old/new content for replacements
- [GenericInput](https://yasyf.github.io/captain-hook/reference/GenericInput.html): Fallback typed input for unrecognized tools, providing dict-like ``get()`` access to raw data
- [GlobInput](https://yasyf.github.io/captain-hook/reference/GlobInput.html): Parsed Glob tool input
- [GrepInput](https://yasyf.github.io/captain-hook/reference/GrepInput.html): Parsed Grep tool input
- [ReadInput](https://yasyf.github.io/captain-hook/reference/ReadInput.html): Parsed Read tool input
- [SkillInput](https://yasyf.github.io/captain-hook/reference/SkillInput.html): Parsed Skill tool input
- [TaskCreateInput](https://yasyf.github.io/captain-hook/reference/TaskCreateInput.html): Parsed TaskCreate tool input
- [TaskUpdateInput](https://yasyf.github.io/captain-hook/reference/TaskUpdateInput.html): Parsed TaskUpdate tool input
- [WriteInput](https://yasyf.github.io/captain-hook/reference/WriteInput.html): Parsed Write/Create tool input
- [ToolResult](https://yasyf.github.io/captain-hook/reference/ToolResult.html): A tool-result content block linking back to its tool use via ``tool_use_id``

#### Signals
> NLP signal scoring over transcript text.

- [Clause](https://yasyf.github.io/captain-hook/reference/Clause.html): Clause(noun: 'Phrase', verb: 'Phrase | None' = None, adj: 'Phrase | None' = None, negated: 'bool' = False)
- [NlpSignal](https://yasyf.github.io/captain-hook/reference/NlpSignal.html): NlpSignal(*, clauses: 'Sequence[Clause]', weight: 'int' = 1)
- [Phrase](https://yasyf.github.io/captain-hook/reference/Phrase.html): Phrase(*terms: 'str') -> 'None'

#### State & Sessions
> Session state, workflow state, and multi-step workflows.

- [HookState](https://yasyf.github.io/captain-hook/reference/HookState.html): Per-hook persistent state tracked across events in a session (``fire_count`` for ``max_fires``)
- [PrimitiveState](https://yasyf.github.io/captain-hook/reference/PrimitiveState.html): Per-primitive state for nudges/gates: last fire index, consumed-signal hashes, and echo-window lemmas
- [SourceEdits](https://yasyf.github.io/captain-hook/reference/SourceEdits.html): SourceEdits(lang: 'str' = 'py', include_tests: 'bool' = False, paths: 'str | None' = None)
- [workflow_state](https://yasyf.github.io/captain-hook/reference/workflow_state.html)
- [SessionSlot](https://yasyf.github.io/captain-hook/reference/SessionSlot.html): A typed slot for reading/writing a single Pydantic model in a session directory
- [SessionStore](https://yasyf.github.io/captain-hook/reference/SessionStore.html): Class-keyed store providing typed ``SessionSlot`` access via ``store[ModelClass]``
- [session_state](https://yasyf.github.io/captain-hook/reference/session_state.html): Decorator that registers a Pydantic model for collective ``SessionStore`` introspection
- [Workflow](https://yasyf.github.io/captain-hook/reference/Workflow.html): Workflow(*, label: 'str', marker: 'str', steps: 'list[Step]', artifacts: 'list[Artifact[BaseModel]]' = <factory>, post_complete: 'Callable[[BaseHookEvent], HookResult | None] | None' = None, on_start: 'Callable[[BaseHookEvent], HookResult | None] | None' = None)
- [Step](https://yasyf.github.io/captain-hook/reference/Step.html): Step(*, name: 'str', check: 'Callable[[Transcript], bool]', stopped_at: 'str', next_step: 'str')
- [Artifact](https://yasyf.github.io/captain-hook/reference/Artifact.html): Artifact(*, path: 'str', model: 'type[M]', validate: 'Callable[[M], str | None]' = <function Artifact.<lambda> at 0x7f5d0f7647c0>)
- [text_matches](https://yasyf.github.io/captain-hook/reference/text_matches.html)
- [workflow](https://yasyf.github.io/captain-hook/reference/workflow.html)

#### SessionStore Methods
> Methods for the SessionStore class

- [SessionStore.__getitem__](https://yasyf.github.io/captain-hook/reference/SessionStore.__getitem__.html)
- [SessionStore.load](https://yasyf.github.io/captain-hook/reference/SessionStore.load.html)
- [SessionStore.track](https://yasyf.github.io/captain-hook/reference/SessionStore.track.html)
- [SessionStore.untrack](https://yasyf.github.io/captain-hook/reference/SessionStore.untrack.html)
- [SessionStore.tracked_models](https://yasyf.github.io/captain-hook/reference/SessionStore.tracked_models.html)
- [SessionStore.tracked_paths](https://yasyf.github.io/captain-hook/reference/SessionStore.tracked_paths.html)

#### Testing
> Inline tests for hooks.

- [Input](https://yasyf.github.io/captain-hook/reference/Input.html): Inline test input descriptor modeling an event payload. Set fields based on the target event type
- [Allow](https://yasyf.github.io/captain-hook/reference/Allow.html): Inline test expectation: the hook should allow (return None or action ``"allow"``)
- [Block](https://yasyf.github.io/captain-hook/reference/Block.html): Inline test expectation: the hook should block. Optional regex ``pattern`` matches the block message
- [Warn](https://yasyf.github.io/captain-hook/reference/Warn.html): Inline test expectation: the hook should warn. Optional regex ``pattern`` matches the warning message
- [TranscriptFixture](https://yasyf.github.io/captain-hook/reference/TranscriptFixture.html): A lightweight transcript stub for use in inline tests

#### Configuration & Prompts
> Settings, scaffolding, and LLM prompt helpers.

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

#### Prompt Methods
> Methods for the Prompt class

- [Prompt.system](https://yasyf.github.io/captain-hook/reference/Prompt.system.html)
- [Prompt.context](https://yasyf.github.io/captain-hook/reference/Prompt.context.html)
- [Prompt.ask](https://yasyf.github.io/captain-hook/reference/Prompt.ask.html)
- [Prompt.from_template](https://yasyf.github.io/captain-hook/reference/Prompt.from_template.html)
- [Prompt.load](https://yasyf.github.io/captain-hook/reference/Prompt.load.html)
- [Prompt.__str__](https://yasyf.github.io/captain-hook/reference/Prompt.__str__.html)