Agent status

Every session has a state:

State	On the tab	Means
working	a ring	the program is busy
needs you	a yellow dot	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.

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. libghostty’s program status protocol (OSC 7501) counts as a report too.
2. Hooks, for agents that have them. alto hooks install sets up Claude Code and Codex to call alto status as they go. See Set up your agents.
3. Your own reports. Anything can call alto status needs-you --why "…" from inside a session.

A surer source’s state holds until it lets go. Typing into a session answers needs you.

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 you: permission: Bash”. Needing you also bounces the Dock icon once on macOS.

From the command line:

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