Agent hooks
Agent hooks are user-defined commands or scripts that a coding agent runs automatically at set points in its work, such as before a tool call or after a file edit, to check, block or extend what it does.
Also called: hooks
By Divya Sharma · Checked Nov 15, 2026 · How we review
Instructions in a prompt or an instructions file are suggestions the model usually follows. Hooks are code that runs every time, whatever the model decides. That makes them the place for rules that must hold, and for chores you do not want to depend on the model remembering.
How it works
You register a hook in the agent's settings against an event. In Claude Code, events include the start of a session, the moment a user sends a prompt, just before a tool runs (PreToolUse), just after it finishes (PostToolUse), and when the agent stops. The agent passes details of the event, such as the tool name and its input, to your script. The script can let the action proceed, block it with a reason the model sees, or add context.
Common uses
Run a formatter or linter after every file edit. Block shell commands that delete files or touch secrets. Refuse edits to protected paths. Send a desktop notification when the agent needs input. Log every tool call for audit.
Hooks versus permissions
Agent permissions are allow and deny lists for tools. Hooks are programmable, so they can inspect arguments and apply rules a list cannot express. Both are part of the agent harness.
Limits
A hook runs with your user's full access, so a careless or malicious hook script is itself a risk; review hooks in shared repositories before enabling them. Pattern-matching on commands can be bypassed, so treat hooks as one layer alongside an agent sandbox, not the only one.
Related terms
- Coding agent
- A coding agent is an AI agent that works on software directly: it reads a codebase, edits files, runs commands and tests, and repeats until a change works, rather than only suggesting code for a person to paste.
- Agent harness
- An agent harness is the software around a model that turns it into a working agent: the loop, tools, system prompt, permissions, context management and any files used to carry progress between sessions.
- Agent permissions
- Agent permissions are the rules that decide which tools, files, commands, networks and accounts an AI agent may use, and which actions need a human's approval first, so a mistaken or manipulated agent can do limited damage.
- Agent instructions file (AGENTS.md)
- An agent instructions file is a Markdown file in a code repository, such as AGENTS.md or CLAUDE.md, that a coding agent reads at the start of a session to learn the project's commands, conventions and rules.
- Agent sandbox
- An agent sandbox is an isolated environment, such as a container, virtual machine or operating-system restriction, in which an AI agent runs code and commands so it cannot reach files, networks or data outside set limits.