# 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.

> **Tip: Run any example**
>
> Every page embeds a runnable hook. Clone the repo and exercise the whole set with:
>
> ``` bash
> 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](../../docs/examples/command-safety.md) | [block_command](../../reference/primitives.md#captain_hook.block_command) plus command-line AST predicates | inline tests |
| [Deploy & secret guard](../../docs/examples/deploy-secret-guard.md) | 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](../../docs/examples/code-quality.md) | layered detection: regex [hook](../../reference/registration.md#captain_hook.hook), AST [lint](../../reference/primitives.md#captain_hook.lint), signal [nudge](../../reference/primitives.md#captain_hook.nudge), [llm_gate](../../reference/primitives.md#captain_hook.llm_gate) | tests + replay |
| [Failure recovery](../../docs/examples/failure-recovery.md) | a signal-driven `Stop` nudge when failures repeat | inline tests |
| [Surface tracked corrections](../../docs/examples/corrections-nudge.md) | a `Stop` nudge pointing at the session reviewer's queue | inline tests |
| [No Go panic](../../docs/examples/no-go-panic.md) | an ast-grep [Pattern](../../reference/conditions.md#captain_hook.Pattern) warning on Go `panic()` | inline tests |
| [LLM cost control](../../docs/examples/llm-cost-control.md) | bound an LLM hook's token spend | replay |
| [Diff review](../../docs/examples/diff-review.md) | ground an [llm_gate](../../reference/primitives.md#captain_hook.llm_gate) in a compact `<diff>` of the change | replay |


# Workflow

Enforce process across a session.

| Example | Teaches | Verified |
|----|----|----|
| [Settings & configuration](../../docs/examples/settings-config.md) | a [HooksSettings](../../reference/configuration-prompts.md#captain_hook.HooksSettings) subclass read by a sibling hook | tests + replay |
| [Session workflow](../../docs/examples/session-workflow.md) | `@workflow_state` spanning several events | replay |
| [Durable cross-session state](../../docs/examples/durable-guard.md) | [DurableState](../../reference/state-sessions.md#captain_hook.DurableState) + [Deque](../../reference/state-sessions.md#captain_hook.Deque) remembering across sessions | inline tests |
| [Multi-step workflow](../../docs/examples/multi-step-workflow.md) | [workflow](../../reference/state-sessions.md#captain_hook.workflow) / [Step](../../reference/state-sessions.md#captain_hook.Step) / [Artifact](../../reference/state-sessions.md#captain_hook.Artifact) before `SubagentStop` | replay |


# Reusable & advanced

Build rules you compose and reuse.

| Example | Teaches | Verified |
|----|----|----|
| [Conditions composition](../../docs/examples/conditions-composition.md) | stack `only_if` and `skip_if` to target one edit | inline tests |
| [Custom condition](../../docs/examples/custom-condition.md) | a [CustomCondition](../../reference/conditions.md#captain_hook.CustomCondition) predicate fed to a [nudge](../../reference/primitives.md#captain_hook.nudge) | inline tests |
| [Style guide](../../docs/examples/styleguide.md) | [styleguide](../../reference/primitives.md#captain_hook.style.styleguide) running [StyleRule](../../reference/primitives.md#captain_hook.style.StyleRule) matchers on changed lines | inline tests |
| [Rewrite code](../../docs/examples/rewrite-code.md) | rewrite edits in place with an ast-grep fix template | inline tests |
| [Test integrity](../../docs/examples/test-integrity.md) | [prompt_check](../../reference/primitives.md#captain_hook.prompt_check) detecting weakened tests | replay |
| [A complete hooks file](../../docs/examples/capstone.md) | several primitives composing in one file | replay |