---
title: "How to make Claude Code verify its own work, from prompt to Stop hook"
description: "To make Claude Code verify its own work, give it a check with a pass or fail result, then move that check out of the prompt into a Stop hook and a reviewer that never saw the session."
url: "https://aldena.ai/blog/claude-code-verify-its-own-work"
---

# How to make Claude Code verify its own work, from prompt to Stop hook

Published 2026-11-21.

## Why Claude Code says it's done when it isn't

To make Claude Code verify its own work, give it a pass-or-fail check, then run that check from a Stop hook that Claude can't skip.

Anthropic's [best practices for Claude Code](https://code.claude.com/docs/en/best-practices) describe the most common bad session as Claude saying it was done when it wasn't quite, "usually because it had no way to check its own work." A check is anything that answers pass or fail without Claude's opinion: a test file, a build's exit code, a linter, a script that diffs output against a fixture.

Handing Claude the check is half of it, and I sort the rest into three tiers by who decides the check passed. In the first, Claude decides whether to run the check and reads the result itself. In the second, another model judges. In the third, an exit code decides.

I checked every command and setting here against Anthropic's docs on November 21, 2026, when the newest Claude Code release was [2.1.330](https://code.claude.com/docs/en/changelog).

![Three tiers of checks for Claude Code: asked, where Claude decides whether to run a prompt line, the CLAUDE.md check command or a verify skill; judged, where /goal, /code-review or a read-only reviewer subagent reads the result; and enforced, where a Stop hook that exits 2 or CI on the pull request decides by exit code](https://cdn.aldena.ai/images/blog/claude-code-verify-its-own-work-1-20261121.png)

## Where the check lives decides who grades it

Eight places can hold the same check, and of those eight only a Stop hook and CI on the pull request decide with an exit code.

| Where the check lives                                                                     | Who decides it passed                            | Where it falls short                                                               |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
| A line in your prompt, such as `run the auth tests after, and keep going until they pass` | Claude                                           | No guarantee Claude follows it                                                     |
| The check command in `CLAUDE.md`                                                          | Claude, in every session                         | An "always typecheck" line "works most of the time, not every time"                |
| A project skill named `verify`                                                            | Claude, told to run it right before each commit  | Not run for changes to docs or tests                                               |
| `/verify`, once Claude says it's done                                                     | Claude, by building and running the app          | Claude still judges the result it built                                            |
| `/goal all tests in tests/auth pass and lint is clean`                                    | A small, fast model, after every turn            | Runs no commands and reads no files, so it judges only what Claude surfaced        |
| `/code-review`, or a subagent limited to `tools: Read, Grep, Glob`                        | A fresh context that never saw your conversation | By default the same model or a smaller one, so fresh eyes without a smarter answer |
| A `Stop` hook that exits 2                                                                | Claude Code, on every stop                       | Gives way after eight blocks in a row with no tool call between them               |
| CI on the pull request                                                                    | Your CI runner, outside the session              | Too late to send Claude back mid-turn                                              |

Start at the second row. Anthropic's best practices call the check command the single most useful line in your `CLAUDE.md`, because Claude needs it to check its work as it goes. It's still a request, though. For anything a command can answer, I'd climb to the Stop hook, and for what no command can judge, such as whether the change matches the spec, I'd add a reviewer.

`/goal` earns its place on long background runs. There, Claude can end a turn on a progress summary with items still open, and the goal sends it back. In a session I'm watching, I skip it.

## A Stop hook that won't let the turn end

A Stop hook is a command in `.claude/settings.json` that Claude Code runs every time Claude tries to end its turn, and exit code 2 sends Claude back to work.

![One turn with a Stop hook: Claude says the types are fixed and tries to end its turn, Claude Code runs pnpm tsc --noEmit 1>&2 || exit 2, exit 0 ends the turn while exit 2 blocks it and sends the TypeScript error on stderr back to Claude, and after 8 blocks in a row with no tool call between them Claude Code ends the turn anyway](https://cdn.aldena.ai/images/blog/claude-code-verify-its-own-work-2-20261121.png)

The type-check version from [Anthropic's docs](https://code.claude.com/docs/en/best-practices#enforce-the-check-with-a-stop-hook) is one hook entry:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }]
      }
    ]
  }
}
```

The `1>&2` sends the compiler output to stderr, and whatever the hook prints to stderr goes back to Claude as the reason it can't finish yet. So Claude gets the exact errors instead of a bare refusal, fixes them and tries to stop again, and the hook runs again.

If the hook blocks eight stops in a row with no tool call between them, Claude Code overrides the next block and ends the turn, and [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](https://code.claude.com/docs/en/env-vars) raises the cap. I'd leave the default. Eight stops without a single tool call means Claude has stopped trying to fix anything, and a ninth block won't change that.

Commit the file and [everyone who clones the repository](https://code.claude.com/docs/en/settings) gets the same hook ([which Claude Code file goes where](https://aldena.ai/blog/share-claude-code-rules-across-a-team) has the full map). Keep the command fast, since it runs on every stop. A type-check and a lint fit there, and a 15-minute end-to-end suite belongs in CI.

Keep it a `command` hook, too. A `prompt` or `agent` hook asks another model to decide, which puts it back in the judged tier. [`/goal`](https://code.claude.com/docs/en/goal) is exactly that, a session-scoped, prompt-based Stop hook whose evaluator is a small, fast model, and its tokens bill on top of the main turn's. The [Codex plugin's review gate](https://aldena.ai/blog/claude-code-and-codex-together) mixes the two tiers. Per the plugin's [README](https://github.com/openai/codex-plugin-cc), it's a `Stop` hook that runs a Codex review of Claude's response and blocks the stop when Codex finds issues, so Claude Code makes sure the review happens and a model decides the verdict.

## A gate per phase beats one check at the end

Julio Casal's [write-up from July 2026](https://juliocasal.com/blog/Make-Claude-Code-Verify-Its-Own-Work) shows why a long plan needs a pass-or-fail gate after each phase instead of one verification step at the end.

![Two ways to check a four-phase change: verifying only at the end, where a leftover reference from phase A surfaces after phase D under three phases of changes, against a gate after every phase, such as a grep for the old name returning nothing, row counts matching, a build with 0 errors and 0 warnings, and passing integration and browser tests, where the same leftover reference fails gate A](https://cdn.aldena.ai/images/blog/claude-code-verify-its-own-work-3-20261121.png)

Claude's first plan for Casal's change copied the shape of his spec, which saved all the verification for the final phase. By his count it would have touched 90 files before checking anything. He rejected the plan and asked for verification steps in every phase, each one something a machine could answer: a search for the removed field names comes back empty, record counts match, the build reports 0 errors and 0 warnings. The Phase A gate caught a leftover reference while Phase A was still the only change in play. He finished with 209 integration tests and 20 Playwright tests passing and 0 build warnings.

A gate written into the plan is still a line Claude reads. To put the commit gate into Claude Code's own instructions instead of yours, add a project skill named `verify`. On [v2.1.286 or later](https://code.claude.com/docs/en/skills#run-your-checks-before-each-commit), when a `verify` or `simplify` skill is in place at session start, Claude Code's commit instructions tell Claude to run it right before each commit, except for changes to docs or tests. The bundled `/verify` doesn't count. The recipe `/verify` records at your repo root does, and `/verify` writes one there when it has to build and drive your app without a recorded recipe.

That's still the asked tier, so the type-check stays in the Stop hook as well.

## The ceiling of self-verification

Self-verification breaks down when Claude games the check, and commenters in a [Hacker News thread](https://news.ycombinator.com/item?id=44678535) about Anthropic's teams describe Claude deleting or skipping tests, then calling the fix done.

A Stop hook doesn't catch that. Delete the failing test and `pnpm test` exits 0, and the hook lets the turn end. The session that wrote a bug also reads the code through the assumption that produced it, so a second look from that session shares the blind spot.

![Two readers of the same diff: the session that wrote it sees the diff, the plan, its own reasoning and its earlier claim that all tests pass, and holds Read, Edit, Write and Bash, while a reviewer subagent defined in .claude/agents/reviewer.md sees only the diff and the spec, never the conversation, and holds only Read, Grep and Glob](https://cdn.aldena.ai/images/blog/claude-code-verify-its-own-work-4-20261121.png)

So the next tier is a reviewer that didn't write the code. [`/code-review`](https://code.claude.com/docs/en/code-review-local) reviews your branch and uncommitted changes in a subagent with its own context window, and without `--fix` it only reports. For a reviewer you define yourself, give a subagent in `.claude/agents/` only read tools, and Claude Code enforces that it can't edit anything:

```markdown
---
name: reviewer
description: Reviews the current diff against a spec before a pull request.
tools: Read, Grep, Glob
---

You didn't write this diff. For each requirement in the spec, name the file and line
that implements it, or report it missing. Flag any test that was deleted, skipped or
loosened. Report only what affects correctness, and skip style.
```

Keep the last line. [Anthropic's best practices](https://code.claude.com/docs/en/best-practices) warn that a reviewer asked to find problems will always find _something_, and fixing every finding piles up abstraction layers and tests for cases that can't happen.

By default a reviewer subagent is the same model or a smaller one on the same task, and the same page is frank about what that buys: "a fresh pair of eyes," but "not a smarter answer." A different model for the reviewer helps when you have one to pick, and so does checking each finding against the code before Claude acts on it, which I cover in [AI code review tools](https://aldena.ai/blog/ai-code-review-tools).

## Evidence over claims

Evidence is the command Claude ran plus its output, or a screenshot, and [Anthropic's best practices](https://code.claude.com/docs/en/best-practices) tell you to ask for it in place of a summary.

Ask for it in the prompt, for example with `paste the command you ran and the last 20 lines of its output`. Reading that is faster than rerunning the check yourself, and for a run you weren't watching it's the only evidence you'll get.

For UI work the check can be a [browser screenshot](https://code.claude.com/docs/en/chrome) next to the mockup. Once Claude says it's done, [`/verify`](https://code.claude.com/docs/en/skills) has Claude build and run the app to confirm the change does what it should, without falling back to tests or type checks.

## How Aldena keeps the author out of the grading

In Aldena, the Code Review agent never edits code, so the agent that grades a change is never the agent that made it.

![An Aldena project canvas with links drawn from the Delivery agent to a Full-Stack Build agent and to a Code Review agent, the Code Review agent on a different model from the other two, above a Give the team a task box addressed to Delivery](https://cdn.aldena.ai/images/blog/ai-code-review-tools-5-20261116.png)

You draw each handoff as a link on the [org chart](https://aldena.ai/features/org-chart), and an agent hands work only to the agents it delegates to. The [Delivery agent](https://aldena.ai/agent/ai-engineering-manager) runs its delegates one at a time, in this order: architecture if that agent is hired, the build, backend then frontend tests, review, then fixes split by lane. The [Code Review agent](https://aldena.ai/agent/ai-code-reviewer) reads the working diff in five separate passes (maintainability, security, performance, backend correctness and frontend correctness) and merges them into one report, with findings grouped critical, high and medium by file and line. The Delivery agent routes each finding back to the build agent that wrote it. Review and fix repeat up to two rounds and stop early once a pass finds nothing critical or high.

Each agent carries its own model and reasoning effort, so the reviewer can run on a different model from the agent whose code it reads.

The build agents check their own work first. The [Full-Stack Build agent](https://aldena.ai/agent/ai-full-stack-developer) gets each layer green before the next: type-check, lint, migrations, a booted server curled endpoint by endpoint, then a frontend build. The Backend Build agent doesn't bypass a failing check, so no skipped lints and no disabled tests, which is the Hacker News failure written down as a rule. A rule is still something a model reads, and that's why the reviewer comes after it. The [Bug Fix agent](https://aldena.ai/agent/ai-bug-fixer) reproduces the failure first, and every fix comes with a regression test that fails before the change and passes after.

At the end, the Delivery agent branches, commits, pushes and opens the pull request against the default branch, then stops. If a delegate fails, it halts and says why instead of pushing a branch it knows is broken. It never writes code and never merges, and no agent merges its own work, so the diff, test results and reasoning reach [a person](https://aldena.ai/features/human-in-the-loop) first. I'd keep CI on that pull request anyway, as the last exit code before anything merges.

## What I'd set up first

For a TypeScript repo, four pieces cover all three tiers: the check command in `CLAUDE.md`, the `tsc` Stop hook, a read-only reviewer subagent and CI on the pull request.

Add `/goal` for long runs nobody is watching, and a `verify` skill once `/verify` has recorded how your app starts. Then read the pasted output before Claude's summary of it.
