FIELD TOOL / HOOK FALSE-FINISH GUARD

A Stop hook means the turn ended. It does not prove the work finished.

Use this when Claude Code hooks fire while a background task or subagent is still running. The guard separates notification from completion: check live children, require a proof receipt, and only page a human when the run is actually done or actually stuck.

The expensive bug is a false receipt, not a noisy notification.

If a Stop hook announces “finished” at every turn boundary, your automation starts training you to ignore the only alarm that matters. Treat hook events as state transitions, then make completion earn its name.

TURN_ENDED means Claude yielded control, not that background work stopped.
WORK_PENDING means at least one child/task/process still has no final receipt.
DONE_VERIFIED means the declared proof command, URL, or file check passed.
STUCK means the next useful move needs a missing fact, boundary, or human choice.

Rule: never send a “task finished” notification from the Stop hook alone. Send “turn ended” unless the run also proves no background work remains and the acceptance check passed.

Copyable Stop hook guard packet

Before wiring Claude Code Stop hooks to alerts, enforce this guard.

1. NAME THE EVENT
- Stop hook = TURN_ENDED only.
- It may not claim DONE unless the completion gate below passes.

2. TRACK BACKGROUND WORK
Maintain a tiny run ledger:
- run_id:
- parent_turn_id:
- child_task_ids:
- background_process_ids:
- last_seen_status:
- started_at:
- max_runtime:

3. COMPLETION GATE
Only emit DONE_VERIFIED when all are true:
- no child task is still running or unknown;
- no background process is still running or unknown;
- the acceptance check exists;
- the acceptance check has been run after the last code/tool change;
- the receipt includes command/URL/file path + observed result.

4. SAFE ALERT MAP
- TURN_ENDED + pending work -> quiet log or low-priority "still running" note.
- TURN_ENDED + no acceptance check -> STUCK: missing proof contract.
- TURN_ENDED + acceptance failed -> STUCK: include smallest failing receipt.
- TURN_ENDED + completion gate passed -> DONE_VERIFIED.

5. ANTI-FALSE-FINISH RULE
Do not phrase any Stop-hook alert as:
- task complete;
- build done;
- tests passed;
- ready to ship;
unless the completion gate passed in the same run.

6. HUMAN PAGE RULE
Page a human only when:
- DONE_VERIFIED needs review/deploy approval;
- STUCK needs credentials, money, legal terms, private data, or a scope decision;
- runtime exceeded max_runtime and no child can produce a new receipt.

7. RECEIPT FORMAT
Every final alert must include:
- state: DONE_VERIFIED or STUCK;
- last command/check run;
- one-line observed result;
- remaining unknown if any;
- next safe action.

If the hook cannot inspect background state, downgrade every Stop event to TURN_ENDED and refuse to claim completion.

Pair with fork-storm breaker Want the harness audited?

Rename the hook.

Call it turn_ended in your own wrapper so downstream automations cannot confuse it with completion.

Keep a run ledger.

A JSON row with child ids, process ids, last status, and max runtime beats a clever notification string.

Alert on states, not vibes.

Use TURN_ENDED, WORK_PENDING, DONE_VERIFIED, and STUCK. Ambiguous “finished” messages rot trust.

Make proof mandatory.

The final alert needs the acceptance check that ran after the last change. A hook event without proof is only transport.

Fail closed on unknown children.

If the hook cannot inspect background state, it cannot claim done. Unknown background work means pending, not finished.

Page humans for boundaries.

Noise burns trust. Page only for verified completion or a real boundary: credentials, money, legal terms, private data, or scope.