To stop Claude Code ending its turn early, give it a completion check that runs after every turn: set a goal with /goal and a condition Claude can prove, or add a Stop hook that blocks the stop until your tests pass. Neither guarantees the task is finished.
To stop Claude Code from ending its turn before the work is done, give it a completion check that runs after every turn. The quickest way is the built-in /goal command: type /goal followed by a condition Claude can prove, such as "npm test exits 0", and Claude keeps working until a separate model agrees the condition holds. The more controllable way is a Stop hook, a script in your settings that blocks the stop and tells Claude what is still wrong. Neither guarantees completion, and both have limits covered below.
The pattern is familiar to anyone doing substantial work with Claude Code: Claude writes the feature, says it is finished, and the tests have not been run. This guide follows the current Claude Code /goal documentation and hooks reference. The documentation was re-read on 15 November 2026. The example scripts below follow the documented exit-code contract; the longer test-suite script is a sketch to adapt, so try it on a throwaway branch before relying on it.
Why does Claude Code keep ending its turn?
A turn ends when Claude replies without asking for another tool call. Claude decides that moment itself. The Claude Code docs put it plainly: on its own, Claude stops when it judges the work done. That judgment is about the conversation, not your repository. Claude can reach "I have finished" while a test is red, an acceptance criterion is untouched or a question to you is still open.
Completing a turn and completing a task are different events. Users report Claude stopping with unfinished to-dos (one example thread). Those are individual reports, not documented behaviour. What is documented is the fix: a check that runs after each turn and can send Claude back to work.
Method 1: use a Stop hook
A Stop hook is a command that Claude Code runs every time the main agent finishes responding. It receives a JSON description of the turn on stdin. If it exits with code 2, Claude is prevented from stopping and whatever the hook wrote to stderr is handed to Claude as the reason to keep going. Exit 0 lets the turn end. The hook does not run if you interrupt the turn yourself, and API errors fire a separate StopFailure event instead.
A copyable example
This hook blocks the stop until a file called DONE.txt exists. It is deliberately trivial so you can see the mechanism work before swapping in a real check. Save it as .claude/hooks/check-done.sh and make it executable:
#!/bin/bash
# Stop hook: block the turn from ending until the real check passes.
cat > /dev/null # read and discard the hook's JSON input
if [ -f DONE.txt ]; then
exit 0 # check passes: let Claude stop
fi
echo "DONE.txt does not exist yet. Create it containing the word finished, then stop." >&2
exit 2 # block the stop, send stderr to Claude as the reason
Then register it in .claude/settings.json in your project:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-done.sh"
}
]
}
]
}
}
With this hook in place, if Claude tries to stop before DONE.txt exists, it receives the hook's message as the reason to keep working, and it can stop once the file is there. Where the configuration lives decides its scope:
.claude/settings.json: this project, shareable through git..claude/settings.local.json: this project, personal and gitignored.~/.claude/settings.json: every project on your machine.
Stop hooks ignore matcher, so leave it out. Settings changes are normally picked up automatically; if they are not, restart the session.
Swap in a real check
The useful version runs your test command and feeds the failure back. This sketch follows the same exit-code contract. It also counts attempts, so a test that can never pass cannot keep you looping:
#!/bin/bash
cat > /dev/null
COUNT_FILE=".claude/.stop-attempts"
n=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
OUT=$(mktemp)
if npm test --silent > "$OUT" 2>&1; then
rm -f "$COUNT_FILE"
exit 0 # tests pass: allow the stop
fi
if [ "$n" -ge 5 ]; then
rm -f "$COUNT_FILE"
exit 0 # five blocked turns: hand control back to you
fi
echo $((n + 1)) > "$COUNT_FILE"
echo "npm test is failing. Fix the failures, then stop. Last output:" >&2
tail -n 20 "$OUT" >&2
exit 2
Add .claude/.stop-attempts to .gitignore. Replace npm test with your own command.
Inspect, troubleshoot and remove it
- Type
/hooksin Claude Code for a read-only list of configured hooks and where each came from. - Start with
claude --debug, or run/debuginside a session, to see hook output in the debug log. - If a hook seems to do nothing, check that the JSON is valid (no trailing commas or comments) and that the file sits in the right location.
- Your script needs its dependencies. The official docs' example uses
jqto readstop_hook_active, so that script fails ifjqis not installed. The examples above avoid it. - To remove it, delete the
Stopblock from settings. To pause every hook, set"disableAllHooks": true.
The loop protection
A Stop hook that always blocks would run forever, so Claude Code includes two protections. Stop input carries a stop_hook_active field, which is true when Claude is already continuing because of a stop hook. The docs' suggested guard is to exit 0 when it is true, but that allows only one extra turn, so the examples above use an attempt counter instead. Second, after stop hooks have continued a turn eight times in a row, Claude Code overrides the next block and ends the turn. The count resets each time Claude calls a tool, so a hook that blocks while Claude keeps making edits can run longer than eight iterations. If a hook genuinely needs more, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises the cap.
You can also return JSON instead of using exit 2: {"decision": "block", "reason": "..."}, with the exit code at 0. Pick one style per hook. Do not mix them.
Method 2: set a completion goal with /goal
/goal is built into Claude Code and is a wrapper around a session-scoped prompt-based Stop hook. It is subject to your version, and it is unavailable if disableAllHooks is true or if managed settings set allowManagedHooksOnly. The documentation notes that restoring a goal on resume works on every route from v2.1.239, and that automatic retries and check-ins need later versions, so update if yours is old.
Set a goal by typing the condition after the command. Setting it starts a turn immediately:
/goal all tests in test/auth pass and the lint step is clean
After each turn, a small fast model reads the condition and the conversation and returns one of three verdicts: not yet met (Claude keeps going, using the reason as guidance), met (the goal clears), or impossible (the goal clears with the reason recorded). Two things follow from that design:
- The evaluator does not run commands or read files. It only judges what Claude has put in the conversation, so write conditions Claude's own output can prove, such as "
npm testexits 0" or "git statusis clean". - Conditions can be up to 4,000 characters. Add a bound such as "or stop after 20 turns" and Claude reports progress against it.
Run /goal with no argument to see the condition, how long it has run, the turns evaluated, token spend and the evaluator's latest reason. Run /goal clear to remove it (stop, off, reset, none and cancel work too). /clear also removes it. It works non-interactively, so this runs the whole loop in one command:
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"
Add --output-format stream-json --verbose if you want to watch progress, because plain text output only prints at the end. A goal does not change your permission mode: in Manual mode Claude still asks before tool calls your settings do not allow, so run it in auto mode for unattended work.
Method 3: other ways to keep Claude working
- Prompt-type or agent-type Stop hooks. A
"type": "prompt"hook asks a model whether the work is complete and feeds back a reason if not. A"type": "agent"hook can run commands and read files to verify, such as running the test suite. The docs mark agent hooks as experimental. - Completion criteria in your prompt or CLAUDE.md. Worth writing, but advisory only. An instruction file is read probabilistically, which is why it should not be your only check (your CLAUDE.md is not a control).
/loop. It re-runs a prompt on a time interval rather than starting the next turn when one finishes, so it suits polling and recurring jobs more than finishing a feature.- Auto mode. It approves tool calls within a turn but does not start a new one. It pairs with
/goalinstead of replacing it.
Stop hooks or /goal: which should you use?
| Question | Stop hook | /goal |
|---|---|---|
| Setup | Write a script and edit a settings file | One typed command |
| Who judges "done" | Your script, so a real test run | A small model reading the conversation |
| Scope | Every session in the settings file's scope | The current session only |
| Best for | Rules that must hold on every task | One-off jobs with a clear end state |
| Main limit | Eight-in-a-row cap, resets on tool calls | Can only judge what Claude shows it |
A workable rule of thumb: use /goal for a single big task and a Stop hook for a check you want on every task. Where a pass or fail can be computed, prefer the hook, because it does not take Claude's word for anything.
A practical setup for a large feature
Say you need Claude to implement a feature, run the tests, fix failures, verify the acceptance criteria and stop. Put the criteria in the goal, with the proof Claude must show and a bound:
/goal The saved-filters feature in docs/specs/saved-filters.md is implemented.
Done means all of these are shown in this conversation:
1. `npm test` exits 0, with the output pasted.
2. Each numbered acceptance criterion in the spec is listed with the file and test that covers it.
3. `git status` shows no files changed outside src/filters and test/filters.
If a step needs a human decision, a credential or a permission that has not been granted, stop and say exactly what is needed.
Or stop after 25 turns.
The escape clause matters. It gives Claude a legitimate way to end the turn, so it does not invent a result to satisfy the condition. For extra safety on a repository where the tests are the real contract, pair it with the test-running Stop hook above.
Common mistakes and limitations
- A vague condition. "The feature works" gives the evaluator nothing to check. Name a command and its expected result.
- Endless loops. A hook that blocks regardless of state will burn tokens until the cap. Add an attempt counter, and note that the cap resets whenever Claude calls a tool.
- Token cost. Every continuation is another model turn. Bound the goal with a turn count and watch the token spend in
/goal. - Claimed testing. A model-judged check accepts "all tests pass" if Claude says it. Require pasted output, or use a hook that runs the tests itself. Why a check that cannot fail proves nothing is covered in negative testing AI-generated code.
- Permissions. Claude cannot continue past a tool call it is not allowed to make. A goal does not change your permission mode.
- Errors that clear the goal. Per the docs, an authentication failure, exhausted credit balance, unrecoverable context overflow or unavailable model clears it, and you must set it again. A rate limit or claude.ai usage limit pauses it instead.
- Human approval. Some work should stop for a person. Say so in the condition.
Treat all of this as a way to reduce babysitting, not to remove oversight. Nothing here keeps Claude running indefinitely, and a met goal means a model agreed with the evidence, not that the software is correct. The Lead Source blog has more on running coding agents on real projects.
How do I stop an unwanted continuation?
Interrupt the turn with Esc; Stop hooks do not fire on a user interrupt. Then run /goal clear for a goal, or remove the hook from settings for a hook. In non-interactive mode, press Ctrl+C.
Written by the team at Lead Source, where the day job is lead source tracking: working out which marketing actually brings customers.