Examples

Each page picks one capability, frames it as a problem you have hit, and links to a self-contained docs/examples/*.py file you can drop into your hooks directory. Work through them by job, from guarding against mistakes to composing a full hooks file.

Run any example

Every page embeds a runnable hook. Clone the repo and exercise the whole set with:

uvx capt-hook --hooks docs/examples test

Deterministic hooks assert their verdicts inline (inline tests); LLM- and session-state-driven hooks are verified by replaying a real session (replay), because a stubbed model proves only the wiring.

Threat modeling

Stop dangerous actions before they run.

Example	Teaches	Verified
Command safety	block_command plus command-line AST predicates	inline tests
Deploy & secret guard	block infra-destroying commands and secret leaks	inline tests

Feedback

Drive the agent with the right nudge at the right time.

Example	Teaches	Verified
Code quality	layered detection: regex hook, AST lint, signal nudge, llm_gate	tests + replay
Failure recovery	a signal-driven `Stop` nudge when failures repeat	inline tests
Surface tracked corrections	a `Stop` nudge pointing at the session reviewer’s queue	inline tests
No Go panic	an ast-grep Pattern warning on Go `panic()`	inline tests
LLM cost control	bound an LLM hook’s token spend	replay
Diff review	ground an llm_gate in a compact `<diff>` of the change	replay

Workflow

Enforce process across a session.

Example	Teaches	Verified
Settings & configuration	a HooksSettings subclass read by a sibling hook	tests + replay
Session workflow	`@workflow_state` spanning several events	replay
Durable cross-session state	DurableState + Deque remembering across sessions	inline tests
Multi-step workflow	workflow / Step / Artifact before `SubagentStop`	replay

Reusable & advanced

Build rules you compose and reuse.

Example	Teaches	Verified
Conditions composition	stack `only_if` and `skip_if` to target one edit	inline tests
Custom condition	a CustomCondition predicate fed to a nudge	inline tests
Style guide	styleguide running StyleRule matchers on changed lines	inline tests
Rewrite code	rewrite edits in place with an ast-grep fix template	inline tests
Test integrity	prompt_check detecting weakened tests	replay
A complete hooks file	several primitives composing in one file	replay