What Is the Your-Turn State in an AI Coding Session?

Verified 2026-07-27. Claude Code and Codex alternate between agent work and human decisions. The your-turn state names the moment when the agent is waiting for input, approval, clarification, or another deliberate developer action.

The definition is intentionally narrower than stopped, inactive, or finished. Those labels describe process activity. Your-turn describes ownership of the next step.

What counts as your-turn evidence?

Strong evidence comes from a semantic event in the session record: an assistant response requesting input, a structured approval prompt, or a completion event that explicitly returns control. The event should include a timestamp and enough session identity to route the developer back to the right terminal or desktop window.

Weak evidence includes file modification time, a pause in token output, or an unchanged process list. Each can be useful as a freshness signal, but none proves that the next action belongs to the developer.

What the state does not prove

• It does not prove the requested implementation is correct.
• It does not prove tests or builds passed.
• It does not prove the entire task is complete.
• It does not authorize an app to approve or resume work automatically.

A status surface should keep these verification questions outside the state label. Otherwise a convenient alert becomes an unsupported quality claim.

Your-turn in a multi-session workflow

A developer may run several Claude Code and Codex sessions at once. The companion should retain the provider, project or thread identifier, and most recent semantic event for each session. Aggregation can then rank a genuine your-turn state above passive working or stale state without erasing where the event came from.

If two sessions need attention, the UI should show both or provide a deterministic priority rule. Collapsing them into one generic badge can send the developer to the wrong task.

Avoiding alert noise

The best notification is contextual. When the exact session is already visible, a sound can be suppressed while the visual your-turn state remains. If the developer moves away, the pending handoff should still be eligible for an alert.

Deduplication matters too. Re-reading the same event after an app restart must not generate another notification. A stable event key or equivalent replay guard should make one handoff produce one alert.

A simple verification sequence

1. Start two named sessions in different projects.
2. Keep one working and make the other ask a real question.
3. Confirm only the requesting session enters your-turn.
4. Bring that exact session frontmost and inspect sound suppression.
5. Restart the companion and verify the same event is not announced twice.
6. Answer the prompt and confirm the state leaves your-turn when new work begins.

How Agent Island uses the state

Agent Island v1.7.1 shows Claude Code and Codex status on macOS and Windows and provides your-turn alerts. Session data is processed locally and is not uploaded to Agent Island. The alert remains a visibility feature; Agent Island does not silently approve prompts or resume the coding agent.