Mapping Agent States to Red, Amber and Green

On Status Light, a red dome sits above amber and green lenses on a matte-black case. That fixed arrangement forces a useful small vocabulary, but the catalogue does not confirm that software can set those lenses.

Why is three states the right number?

Three states are easy to recognize without reading, which makes them suitable for a distant summary. They are not enough to represent every tool call, test result and conversation phase. The light should answer whether to keep working, look now or investigate, while a terminal carries the evidence.

More nuanced state belongs in text. Adding blink patterns and mixed colours can recreate a dashboard that nobody remembers.

Which agent events belong to each colour?

Amber should come from a confirmed request for human input or permission. Red should require a verified failure that blocks the task. Green may represent ordinary working or a completed response ready for review, depending on one written local policy. Tool-specific hooks must be translated into those meanings explicitly.

Terminal activity, silence and generated prose are not reliable event types by themselves. Prefer structured notifications, exit statuses and test results. Treat parse errors and unavailable sources as unknown.

Should green mean idle or mean success?

Choose one. If green means the agent finished speaking, it does not mean the code is correct. If green means verified success, require the relevant checks and human review before setting it. Mixing those definitions produces a reassuring signal with no stable claim behind it.

For an attention light, an all-off idle state can be clearer than permanent green. The team should be able to explain the state without looking at implementation code.

How do you keep the mapping honest over time?

Version the state table, add examples for every event source and expire stale records. Test simultaneous agents and out-of-order updates. Review the policy when tools change their hook payloads, and record the last update time beside the detailed state.

The Status Light physically supplies the three named lenses, but software control remains an unanswered integration question. Validate the real interface first. Until then, run the same mapping in tmux or a local text display and measure whether it changes useful behavior. Assign ownership as well as colour. Amber with nobody responsible becomes permanent background decoration, while red without a recovery link creates panic rather than action. The detail record should include task, source event, terminal target and a clear next step. Add a manual acknowledgement that changes display state without altering the underlying agent record.