How hooks work

Free sample

Events, blocking exit codes, install, and how to test one before trusting it.

hooks/README.md · 1.7 KB

hooks/README.md

# Hooks

Instructions are advice. Hooks are enforcement.

Anything you genuinely cannot allow — editing generated files, committing a
secret, skipping the formatter — belongs in a hook, not in a memory file.
The model can misread a memory file. It cannot misread an exit code.

## How they work (Claude Code)

Hooks are shell commands wired to tool events in `.claude/settings.json`.
The two that matter:

- **PreToolUse** — runs before a tool call. Exit non-zero to block it. The
  message on stderr goes back to the model, so it can correct itself.
- **PostToolUse** — runs after. Use for formatting, regeneration, notifying.

The hook receives the tool call as JSON on stdin.

## What is here

    settings.json              Wires up all three hooks
    block-generated-edits.sh   Refuses edits to generated/vendored paths
    secret-scan.sh             Refuses writes containing key-shaped strings
    format-on-write.sh         Runs your formatter after every edit

## Install

    mkdir -p .claude/hooks
    cp hooks/*.sh .claude/hooks/
    chmod +x .claude/hooks/*.sh
    # merge hooks/settings.json into .claude/settings.json

Then **edit the paths and commands in each script** — they ship with
placeholders and a safe default of doing nothing.

## Test them before you trust them

A hook that silently fails is worse than no hook, because you will stop
checking. Verify each one:

    echo '{"tool_input":{"file_path":"pkg/generated/x.go"}}' | .claude/hooks/block-generated-edits.sh
    echo $?    # expect 2

## Porting

Codex supports lifecycle hooks in its config; Cline and Roo Code have their
own mechanisms. Where there is no hook support, the fallback that actually
works is a **pre-commit hook** in git — same guarantee, later feedback.

That was one of 28 files

The rest of The Agent Operating Kit is written the same way. $39 once, yours permanently, 14-day refund.

# Hooks Instructions are advice. Hooks are enforcement. Anything you genuinely cannot allow — editing generated files, committing a secret, skipping the formatter — belongs in a hook, not in a memory file. The model can misread a memory file. It cannot misread an exit code. ## How they work (Claude Code) Hooks are shell commands wired to tool events in `.claude/settings.json`. The two that matter: - **PreToolUse** — runs before a tool call. Exit non-zero to block it. The message on stderr goes back to the model, so it can correct itself. - **PostToolUse** — runs after. Use for formatting, regeneration, notifying. The hook receives the tool call as JSON on stdin. ## What is here settings.json Wires up all three hooks block-generated-edits.sh Refuses edits to generated/vendored paths secret-scan.sh Refuses writes containing key-shaped strings format-on-write.sh Runs your formatter after every edit ## Install mkdir -p .claude/hooks cp hooks/*.sh .claude/hooks/ chmod +x .claude/hooks/*.sh # merge hooks/settings.json into .claude/settings.json Then **edit the paths and commands in each script** — they ship with placeholders and a safe default of doing nothing. ## Test them before you trust them A hook that silently fails is worse than no hook, because you will stop checking. Verify each one: echo '{"tool_input":{"file_path":"pkg/generated/x.go"}}' | .claude/hooks/block-generated-edits.sh echo $? # expect 2 ## Porting Codex supports lifecycle hooks in its config; Cline and Roo Code have their own mechanisms. Where there is no hook support, the fallback that actually works is a **pre-commit hook** in git — same guarantee, later feedback.