freno-dev/marketing/approved/agent-done-signal/copy.md

# How do you know when your coding agent is done?

> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 fact-check
> card, verdict: "Approve both — move to approved/"). Not published; a human
> places it on nook.freno.me from `approved/`.
> This page never names a product of ours and never names a competitor.
> Internal target: first page of the FRE-199 pair, Thu 2026-11-06.

Often, you don't — not from the terminal alone. A coding agent's turn can end in
silence: the prompt returns, the cursor blinks, and a finished turn looks exactly
like one that stalled, is still running, or is waiting on you. The fix is to stop
trusting silence and wire the two moments that matter — *the turn ended* and *the
agent needs you* — to something you will actually see.

## Why silence is the failure mode

A terminal coding agent ends a turn by printing a prompt. If you are in another
window, another room, or running several agents at once, nothing in that output
distinguishes "finished" from "blocked on a permission prompt" from "dead". The
task being done and you finding out are two different events, and the second one
has no default signal.

Practitioners keep rediscovering this. One operator running a self-hosted queue
of autonomous agent sessions described sessions that "finished their work but
never sent the done signal, and held their slots for hours" — their fix was to
derive "done" from git state plus an idle transcript instead of trusting the
agent's own signal. A public service post about a code-review plugin described
the mirror image: a green checkmark and "No findings" when the review had not
run at all. An empty result and a successful result rendered identically.

That is the trap in one sentence: **zero looks exactly like success.**

## What the turn-ending signal actually is

Claude Code gives you two hooks that bracket the moments worth surfacing:

- **`Stop`** fires when the agent finishes responding — the end of a turn.
- **`Notification`** fires when Claude Code sends a notification. A permission
  prompt is one of these: the hook's payload carries a `notification_type` of
  `permission_prompt` and a message like "Claude needs your permission".
- **`StopFailure`** fires instead of `Stop` when the turn ends on an API error —
  rate limits, authentication problems, and the like.

All three can run a command of your choosing. The hooks reference documents the
events and includes a desktop-notification example built on macOS's `osascript`.

## What to check or do

1. **Wire turn-end to a notification you will actually notice.** A `Stop` hook
   that calls `osascript -e 'display notification …'` (or your terminal's
   notification escape) turns the silent prompt-return into a visible event.
   A terminal bell is not this — it is mute the moment you switch windows.
2. **Route permission waits separately from completions.** The `Notification`
   hook's payload tells you which kind it is. A permission wait means the agent
   is *blocked on you*; treating it as "done" hides the one state that costs the
   most time.
3. **Don't trust the exit signal alone.** Check the artifacts: `git status`,
   `git log`, whether the transcript has gone idle. The queue operator's rule
   generalises — a "done" that has to name what it is waiting on is a "done"
   you can act on.
4. **Surface the failure path too.** A turn that ends on an API error fires
   `StopFailure`, not `Stop` — an alert wired to the wrong one misses exactly
   the runs that need attention.

One next step: take the agent command you run most often and give its end-of-turn
a notification you would notice from across the room. That single wire closes the
most expensive silence in the workflow.

---

## Fact-check table (not part of the page)

Every technical claim above, with its primary source. Claims about Claude Code's
behaviour come from its own documentation, re-read 2026-11-05.

| # | Claim in the page | Source |
|---|---|---|
| 1 | `Stop` fires when the agent finishes responding (end of a turn); hook cadence is "per turn: UserPromptSubmit, Stop, StopFailure" | Claude Code hooks reference — https://docs.anthropic.com/en/docs/claude-code/hooks |
| 2 | `Notification` fires "when Claude Code sends a notification"; example payload carries `notification_type: "permission_prompt"`, message "Claude needs your permission" | same hooks reference (Notification event section) |
| 3 | `StopFailure` "runs instead of Stop when the turn ends due to an API error" (rate limits, authentication) | same hooks reference (StopFailure section) |
| 4 | Hooks run a command of your choosing; a desktop-notification example using `osascript` is in the reference | same hooks reference (desktop notification example) |
| 5 | Operator anecdote: sessions that finished work but never signalled done, holding slots for hours; fix = derive done from git + idle transcript | r/ClaudeCode thread 1xjb3j0 ("Are you running a self-hosted queue of autonomous Claude Code sessions?", 2026-10-31), quoted in `drafts/listening.md` Scan 4 addendum. Quoted as one operator's described practice, not a measurement. |
| 6 | PSA anecdote: code-review plugin showed green check + "No findings" without running | r/ClaudeCode 1xmnz2c (2026-11-03), logged in `drafts/listening.md` Scan 6. |
| 7 | "Zero looks exactly like success" | Verbatim buyer phrasing, three independent instances (1xm09fs, 1xmnz2c, plus HN repeats) in `drafts/listening.md` Scans 5–8. Used as the problem's name, attributed to no one. |

**Ban compliance:** no product of ours named · no competitor named · no
superlatives · no benchmark numbers · no invented testimonials (anecdotes are
real threads, described without handles) · no price · no roadmap dates.