When a coding agent stops producing output, the next step is not automatically yours. It may be waiting on a tool, calculating, stalled, or actually finished. A useful your-turn state needs stronger evidence than silence.
The definition I use is narrow: your-turn means a specific Claude Code or Codex session has produced evidence that the next useful action belongs to the developer.
Process state and action ownership are separate
“Stopped” describes activity. “Your turn” describes ownership of the next step.
A semantic session event can support that handoff: an assistant message that asks a question, a structured approval prompt, or a completion event that explicitly returns control. File modification time, low CPU, and an unchanged process list are freshness clues, not proof of a handoff.
This distinction prevents two common errors:
- calling a slow tool invocation finished;
- calling an inactive but stalled process ready for the user.
When evidence is stale or ambiguous, the honest state is uncertainty.
The event must keep its session identity
Multi-session workflows make generic alerts almost useless. If three Codex sessions are open, “Codex needs you” still leaves the developer searching.
The handoff record should preserve the provider, project or thread identity, semantic event, and event time. Aggregation can rank a real your-turn state above passive working or stale state, but it must not erase the origin of the event.
If two sessions need attention, the UI should show both or apply a deterministic priority rule. A single generic badge is not enough.
An alert does not prove quality
Your-turn does not mean:
- the implementation is correct;
- tests passed;
- the full task is complete;
- the companion may approve or resume work automatically.
Those are separate verification and authorization questions. A status label should not smuggle them into a convenient notification.
Suppression and replay protection
Notification policy is part of the state model. When the exact target session is already frontmost, an extra sound may add no value. The visual state can remain while the sound is suppressed. If the developer switches away, the pending handoff must remain eligible for an alert.
The monitor must also deduplicate events. Re-reading the same local record after an app restart should not produce a second alert. Stable event identity, or a documented replay key, keeps one handoff equal to one notification.
A practical test
- Start two sessions in different projects.
- Leave one working and make the other ask a real question.
- Confirm only the requesting session becomes your-turn.
- Bring that session frontmost and inspect the alert policy.
- Restart the monitor and verify the same event does not fire twice.
- Answer the prompt and confirm new work clears the handoff state.
Agent Island v1.7.1 applies this model to Claude Code and Codex status on macOS and Windows. It reports the handoff; it does not silently operate the coding agent.
The canonical your-turn guide contains the full boundary and verification sequence.
Top comments (0)