Stop hook

A script the harness runs when the agent tries to end its turn. If the script says no, the agent is told why and has to keep working.

An agent can finish without committing, so git's hooks may never fire. This one fires when it decides it is done, and turns "please run the tests before you finish" from a request into a step the harness takes whether the agent remembers or not. The agent can't end its turn while tests are failing until the hook lets it, or the harness's own limit is reached.

Say it to your agent

“Add a Stop hook that runs bun test and bun run typecheck, and blocks with the last 20 lines of output if either fails. Don't exit early on stop_hook_active, because that gives you one retry. If the harness ends your turn with the tests still failing, tell me so plainly.”

Not to be confused with Pre-commit hook

A pre-commit hook belongs to git and fires when code is committed. A stop hook belongs to the agent harness and fires when the agent tries to stop, whether or not anything was committed.

Where you see it

In Claude Code as of November 2026, a Stop hook can return a decision of block, with a reason, and the agent goes back to work with that reason. After eight continuations in a row the harness overrides the next block, and a tool call resets that count. The input has stop_hook_active, and the docs say: "Check this value or process the transcript to avoid blocking on a condition that will never resolve." Exiting at once on that value gives the agent a single retry, and the docs' own typecheck example has no such guard. The onFailure setting has no effect here, so a Stop hook that can't run doesn't hold the agent.

Stop hook

Before the agent

The agent

The harness

Everything it can get wrong

The operator

The workshop