# Hooks

Hooks are harness code that runs automatically at defined points in the agent loop, making behavior guaranteed instead of hoped for.

> A hook is code the harness runs automatically at a fixed point in the agent loop. It runs every time, whether or not the model remembers.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/hooks

**Diagram:** Hooks run inside the harness at fixed points of the loop — every time, whatever the model decides.

- Model — decides the next action
- → tool call
- Harness · deterministic (session start, stop):
  - Before-tool hook — allow · block · rewrite
  - →
  - Tool runs — edit · shell · MCP
  - →
  - After-tool hook — format · lint · log

A hook is a small program you register with the harness. When the agent reaches a defined point in its loop, the harness runs your program, passes it details about what is happening, and acts on the result. The model is not asked and cannot skip it.

Hooks can observe (log a tool call), modify (format a file after an edit) or block (refuse a command before it runs). Which of these an event supports, and how you express it, depends on the agent.

## Why it exists

An [instruction file](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files) can say "run the formatter after editing" or "never delete recursively". The model follows this most of the time. When it does not, you find unformatted code in review, or a destructive command running. A request to a probabilistic system is not a guarantee.

## How it works

**Diagram:** The harness, not the model, runs the hook — deterministic, with your permissions — and the hook's answer decides whether the action goes ahead.

- You register — a command for an event, optionally with a matcher
- → event fires
- Harness runs it — sends the event data, often JSON on stdin
- →
- Command works — any script — format, check, log
- → exit code / output
- Harness decides:
  - Continue — the action goes ahead
  - Block — stopped, with a reason

<warning>

A hook runs with your user's permissions and is code from the repository. Review hooks like any script, and do not trust hook configuration from a repository you have not read.

</warning>

## Use it when

- Something must happen every time: formatting, logging, validation.
- An action must be prevented, not discouraged.
- You need an audit record that does not depend on the model's cooperation.

## Use something else when

- The agent just needs to know a convention → [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files)
- A procedure needs judgment and several steps → [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills)
- You need to contain what the agent can reach → [Sandboxing](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing)
- You need to limit what the agent may do → [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model)
- You want to share the hook set with a team → [Plugins](https://ai-sw-factory.mellicci.dev/fundamentals/plugins)

## Key terms

- **Hook** — harness-run code at a lifecycle event.
- **Lifecycle event** — a named point in the loop.
- **Matcher** — filters which events trigger a hook.
- **Blocking hook** — can stop an action and give a reason.