Skip to content

Knowledge base

Hooks

When to reach for a hook instead of an instruction file, and the jobs teams give hooks in day-to-day work with coding agents.

Written by

Updated:

Glossary 33

A hook is a command, script or check that the agent harness runs automatically when a given event occurs in a session. In Claude Code the events include PreToolUse and PostToolUse around every tool call, UserPromptSubmit when a prompt arrives, Stop when the agent finishes, and SessionStart and SessionEnd. A hook can let the action through, block it, or give the agent extra context.

Why use a hook instead of an instruction?

An instruction in CLAUDE.md is advice the model weighs; a hook runs every time. Anthropic’s own guidance draws the same line: use hooks for actions that must happen with no exceptions. That makes hooks the place for checks that cannot depend on the agent remembering them.

What do teams use hooks for?

Control, feedback and record-keeping. A PreToolUse hook blocks a dangerous shell command before it runs. A PostToolUse hook runs the type checker after every edit and feeds the errors back, so the agent fixes them right away. A Stop hook can archive the transcript or keep a turn from ending until a check passes. Hooks run inside the harness, so on their own they are not a security boundary: isolation below the agent still matters.

Resources

Articles

Documentation