Agent status

Every session has a state:

State	On the tab	Means
working	a ring	the program is busy
needs you	yellow: ! a permission, ? a question, a lock for signing in, a dot otherwise	a permission prompt, a question, a bell
done	a green dot	finished, and you haven’t looked yet
idle	nothing	at a prompt, or quiet

A tab with several panes shows the most pressing of them. Done becomes idle once its pane is on screen in the front window.

A tab behind that needs you is tinted toward the theme’s yellow, and glows briefly when it starts needing you, so it stands out from across the tab strip. Hovering it says why: “claude needs your permission: Bash”. In a split, the pane that needs you is outlined in the same yellow. The tab in front isn’t tinted (you’re already there), and neither is done, so the tint always means something is waiting on you.

An agent that quits or is killed while it was still working or asking you shows as idle, with the reason “stopped”, not done: it finished nothing, so you aren’t told it did.

Where it comes from

In three layers, surest last:

1. What the terminal sees, with no setup. Which program is in the foreground, output versus quiet, the bell, notification escape sequences (OSC 9 and OSC 777), progress (OSC 9;4), and shell integration marks (OSC 133) for prompts, commands and exit codes. The program status protocol (OSC 7501, which Claude Code, Copilot CLI and others send by themselves) counts as a report too: a program can report on parts of itself (build, build/test), and the session shows the most pressing part, as in “eu-west: permission: Apply?”.
2. Hooks, for agents that have them. alto agents install sets up Claude Code and Codex to call alto hook as they go. See Set up your agents.
3. Your own reports. Anything can call alto report needs-you --why "…" from inside a session, and --need permission, question or auth to say what it waits for.

A surer source’s state holds until it lets go. Typing into a session answers needs you. When an agent’s turn ends, a permission or a question it asked during the turn goes with it; a sign-in it’s still waiting for stays.

Alto never reads the screen’s text to decide. That breaks whenever a tool changes its interface, and agents put spinners in their window titles, so titles aren’t read either.

Being told

A pane that starts needing you or finishes while it isn’t in front of you (another tab, or the window in the background) posts a notification: Alto · api, “claude needs your permission: Bash”, or “has a question”, or “needs you to sign in”. Needing you also bounces the Dock icon once on macOS. Which of these are posted is a setting: Settings, General, Notifications, or notify_needs_you and notify_done in settings.toml.

From the command line:

alto ls        # every session and its state
alto ls --waiting   # what needs you, here and on every device you reach, newest first
alto report --session 3
alto wait 3 --until needs-you   # block until it does