Agent status at a glance: blocked / working / idle badges on tabs, sidebar, and menu bar

[arzafran]

You can't tell which agent needs you without clicking through every workspace. The state users actually context-switch for is "blocked" (agent waiting on an approval or a question), and today nothing surfaces it.

Design

Two-tier status authority per surface:

1. Lifecycle hooks (authoritative). We already install hooks for Claude Code, Codex, and OpenCode. When hooks are installed for the agent in a surface, their reports are the single source of truth: no fallback detection runs, so there's never two sources disagreeing.
2. Screen-rule fallback (later). For agents without hooks, classify from the live bottom-of-screen snapshot using per-agent rule manifests (TOML: regions, regexes, priorities). Terminal title and progress escape sequences help when present but rules must work from the screen alone.

Strict-blocked rule (applies to both tiers): only mark blocked when the visible screen matches a known approval / question / permission UI. If nothing matches, default to idle. A false "blocked" trains users to ignore the badge, which kills the whole feature.

Surfacing

• Tab and sidebar badges per surface state (working / blocked / idle; done can ride on the existing notification flow)
• Menu bar: "N agents blocked" alongside the unread count, click to jump
• Socket: expose state on surface.list so the CLI and external tools see it too

Tasks

1. v1, hook tier only: state model + badges + menu bar, driven by the integrations we already ship (verify: booted Claude instance shows working while streaming, blocked on a permission prompt, idle at rest)
2. v2, rule manifests for non-integrated agents (own issue when we get there)

Rules must be written clean-room by us, from our own screen captures.

[arzafran]

v1 (hook tier) shipped in #174: per-surface working/blocked/idle state fed exclusively by the Claude Code / Codex / OpenCode lifecycle hooks, strict-blocked rule enforced, surfaced as sidebar tab badges, a menu-bar "N agents blocked" jump item, and agent_state on surface.list. Per this issue's own scoping, v2 (clean-room screen-rule manifests for non-integrated agents) gets its own issue when we get there. One manual check remains for the next dogfood session: a booted Claude instance showing working while streaming, blocked on a permission prompt, idle at rest.