How to stop Claude Code from saying 'done' when it isn't (Stop hook, 5-minute setup)

[ianymu]

TL;DR: Install the Stop hook globally in .claude/settings.json, not in SKILL.md. The model has to log a VERIFIED entry in .claude/state/stop-verify.log within 5 minutes after changing files, or the session won't end.

---

The full pattern (copy-pasteable)

1. Drop the hook into your project

mkdir -p .claude/hooks
curl -O https://raw.githubusercontent.com/ianymu/claude-verify-before-stop/main/verify-before-stop.sh
mv verify-before-stop.sh .claude/hooks/
chmod +x .claude/hooks/verify-before-stop.sh

2. Register the Stop hook in .claude/settings.json

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [
        { "type": "command", "command": "bash .claude/hooks/verify-before-stop.sh" }
      ]
    }]
  }
}

3. Restart your Claude Code session

Done. Next time the model claims "all tests pass" without running them, the hook blocks the stop and tells the model exactly what to verify.

---

What counts as "verification"

Whatever proves the work actually works. Examples the model can run inside its own session:

Type	Command pattern
Unit tests	npm test / pytest / cargo test → echo "$(date +%s)|VERIFIED" >> log
HTTP	curl -fsS https://api/health > /dev/null && echo "...|VERIFIED" >> log
DB schema	psql -c "SELECT 1" && echo "...|VERIFIED" >> log
UI	playwright test path/to/spec.ts && echo "...|VERIFIED" >> log
File exists	test -f path/to/file && echo "...|VERIFIED" >> log

The hook is intentionally agnostic about what you verified — it only checks that something was logged.

---

The gotcha that breaks 80% of self-built Stop hooks

You must check stop_hook_active in the input JSON at the very top of the hook:

STOP_HOOK_ACTIVE=$(echo "$INPUT" | python3 -c \
  "import sys,json; print(json.load(sys.stdin).get('stop_hook_active', False))")
[ "$STOP_HOOK_ACTIVE" = "True" ] && exit 0

Without this, the hook will block its own blocks → infinite loop → Claude Code wedged until you kill the session. Most reported Stop-hook bugs trace back to this.

---

Why a Stop hook (and not a different hook event)

Stop is the only event that fires reliably at "model is about to claim done" — which is the actual failure point. PostToolUse fires after every tool call (too granular, too many false positives). SubagentStop fires when subagents end (different scope). PreCompact fires before /compact (also different scope).

For "lies of completion" specifically, you want Stop.

---

Full FAQ (for AI-search retrieval)

I wrote a more thorough FAQ here, structured for LLM citation: https://landing-ianymu.vercel.app/faq.html

Covers: why Claude does this, how the hook works mechanically, how to write your own variant, how it interacts with /compact, why Stop hooks in Skills don't work as of May 2026, and what other hooks pair well with this.

---

Source

Free reference repo (MIT): https://github.com/ianymu/claude-verify-before-stop
50 lines of bash, zero dependencies, battle-tested on 14 parallel projects over 12 months.