Seven States Your Coding-Agent Monitor Must Not Confuse

Observations vs. Session States

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:

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

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.