Seven States Your Coding-Agent Monitor Must Not Confuse

A process is alive. A transcript changed. A stop hook fired. A permission prompt appeared.

Those are observations, not session states.

If a developer tool turns each signal directly into a badge, it will eventually report a completed turn as still waiting, a quiet task as successful, or a bookkeeping write as fresh work. A more reliable monitor separates evidence from the time-bounded conclusion shown to the user.

Start with one session, not one provider

The unit of observation should be a single local session or thread. A provider badge can summarize several threads later, but it should not erase their identities.

Every observation needs at least:

• a provider;
• a stable session key;
• an observation time;
• the newest relevant semantic activity time.

This is an operational model. It does not claim that generated code is correct or that the project-level task is complete.

Use seven primary states

The smallest useful state set I have found is:

inactive
running
waiting_for_user
completed
blocked
stalled
unknown

running requires fresh start, progress, tool-use, or streaming evidence tied to the current turn.

waiting_for_user requires an explicit permission, elicitation, clarification, or other input request that has not already been answered.

completed requires a terminal event for the current turn and no later activity that supersedes it. It does not mean the code is correct.

blocked requires an explicit failure that prevents normal continuation, such as authentication, quota, policy, provider, or execution failure.

stalled is intentionally weaker. The turn was running, then exceeded a documented silence threshold without a terminal or blocked event. Silence can support a stalled inference; it cannot prove completion.

unknown is not the same as idle. It means the evidence is missing, contradictory, unsupported, or too old for a stronger conclusion.

Keep cause and confidence out of the state name

Products often multiply states by mixing presentation with evidence. Keep these as modifiers instead:

• reason: permission, auth, rate limit, process exit, or silence timeout;
• freshness: age of the semantic event;
• confidence: explicit, inferred, or fallback;
• attention: none, informational, user action, or urgent recovery;
• turn identity: the key used for deduplication;
• source: hook, session record, process signal, file metadata, or heuristic.

This lets the UI say blocked: authentication without creating a new top-level state for every error type.

Resolve conflicting signals deliberately

When signals disagree, prefer the most specific fresh evidence belonging to the current turn:

1. Explicit semantic events such as a permission request, terminal event, or structured provider error.
2. Later user or agent activity that supersedes an earlier event.
3. Correlated process and session activity.
4. File modification time when no semantic timestamp exists.
5. Silence-based inference, which may produce stalled but never completed.

The second rule matters as much as the first. A valid completion event becomes stale as soon as a later user prompt starts another turn.

Test transitions, not just strings

A monitor is not robust because it recognizes one happy-path marker. At minimum, test:

• a new turn does not inherit the previous completion;
• replaying one event produces one notification;
• later activity revokes an older completed or waiting state;
• permission requests remain distinct from ordinary completion;
• error-shaped terminal records become blocked, not completed;
• silence never fabricates success;
• restart recovery reconstructs state without replaying an old alert;
• one completed session does not hide another running session;
• malformed timestamps and partial writes degrade safely;
• old completed and stalled states expire;
• the test verifies where raw session data is read, retained, and transmitted.

This vocabulary is useful beyond any one product. It gives maintainers, reviewers, and researchers a shared way to ask what a status claim means and what evidence can revoke it.

Read the complete taxonomy, transition model, and evaluation levels