REMOTE-1458: Unified agent icon-with-status across Warp surfaces

Summary

Warp shows an "agent icon" on several surfaces — vertical tabs, the pane header, the inline conversation list menu (the slide-out list of ACTIVE + PAST runs in conversation_list/item.rs), and the notifications mailbox. This spec defines the canonical agent-icon treatment and the cross-surface consistency contract so the same logical run always renders as the same icon no matter which surface it appears on. The Agent Management View (card list) is explicitly out of scope for this pass — its richer layout owns its own status treatment and we're not disrupting it yet. Reference issue: https://linear.app/warpdotdev/issue/REMOTE-1458.

Problem

Across Warp's agent-run surfaces today, users frequently can't tell two fundamental things:

Whether a cloud run is Oz or a third-party harness (Claude Code, Gemini CLI). Cloud runs with a non-oz harness render with the Oz cloud glyph during the entire pre-setup / setup phase because the client-side CLIAgentSessionsModel — the thing every surface consults for harness identity — is only populated once the harness CLI is detected in the shared session. Until then, even a Claude run that the user explicitly selected looks like an Oz run.
Whether a third-party agent run is local or in the cloud. A local claude CLI session and a cloud-mode Claude run render with identical brand colors and glyphs; nothing distinguishes the two, so users can't tell whether "Claude" in their tab bar is running on their machine or in a remote sandbox. Concretely, each surface contributes to the ambiguity in its own way:
app/src/workspace/view/vertical_tabs.rs resolves the tab icon from CLIAgentSessionsModel::session(terminal_view.id()). Before the harness CLI starts, ambient runs fall through to the plain OzAgent variant regardless of which harness the user selected.
app/src/terminal/view/pane_impl.rs renders a single plain OzCloud glyph for every ambient run via render_ambient_agent_indicator and an unbadged Oz/OzCloud glyph for conversation-bound terminals via render_agent_indicator. No brand circle, no status badge, no harness distinction, no local-vs-cloud distinction.
app/src/workspace/view/conversation_list/item.rs (render_item) renders a plain Icon::Cloud glyph for every ambient row and a plain render_status_element for every local row — no brand color, no harness distinction. Rows representing Oz cloud, Claude cloud, and Gemini cloud runs all render as the same cloud outline.
app/src/ai/agent_management/notifications/item_rendering.rs renders the correct brand color and glyph per CLI agent but hardcodes is_ambient: false, so a notification triggered by a cloud-mode Claude run looks identical to one triggered by a local Claude session. Beyond the visual problem, the derivation logic itself is duplicated across surfaces and drifts: vertical tabs alone has two separate waterfalls (resolve_icon_with_status_variant and TypedPane::summary_pane_kind) that recompute the same fields, and neither routes through TerminalView::selected_conversation_status_for_display, which is where "surface InProgress during cloud setup" logic wants to live. Adding a fifth surface today means copy-pasting the waterfall a third time and re-reasoning about every edge case.

Goals

Render the same agent icon shape everywhere Warp represents an agent run: a brand-color circle containing the agent glyph, a status badge at the bottom-right (local runs) or a white cloud lobe with the status icon inside (ambient/cloud runs).
Make the icon reflect the user's selected harness the moment a cloud run is committed — i.e. as soon as AmbientAgentViewModel transitions out of NotAmbientAgent, not only once the CLI command has started.
Make the status component reflect the correct run state on every surface, including the cloud-setup pre-first-exchange phase (surface as InProgress).
When a single logical run is represented on multiple surfaces at the same time (e.g. a cloud task that's both a visible pane and a card in the conversation list), every surface renders a pixel-identical icon.
Keep non-agent surfaces (plain terminal pane, shell indicators, error indicators) visually unchanged.

Non-goals

Redesigning the agent-icon visual itself. The circle + badge + cloud-lobe shape is defined in the Figma reference at https://www.figma.com/design/chk9pwt35jTJhf9KnHmZyE/Components?node-id=6535-4010 and is taken as given here.
Changing how CLIAgentSessionsModel is populated, how shared sessions are joined, or how the Oz / harness detection pipeline works.
Showing agent icons on surfaces that don't currently render an agent identity at all beyond the ones listed here.
Migrating status rendering away from ConversationStatus; we still use that type as the canonical "what state is this in" value.
Changing per-harness brand colors, icon glyphs, or sizing constants beyond what's needed to reuse the vertical-tab sizing on other surfaces.

User experience

The canonical agent icon is a brand-color circle containing the agent glyph, with either a bottom-right status badge (local runs) or a white cloud lobe containing the status icon (ambient/cloud runs). It is rendered uniformly on every surface enumerated below, at surface-appropriate sizes.

Vertical tabs

When the user has selected a third-party harness (Claude, Gemini) and the run is in any ambient state (Setup, Composing, WaitingForSession, AgentRunning, Failed, Cancelled, NeedsGithubAuth), the vertical tab icon shows that harness's brand-color circle with the cloud lobe — not the Oz cloud circle — even before the harness CLI has started running.
When the CLIAgentSessionsModel later registers the actual CLI session, the tab continues to render the same agent brand (matching the selected harness), so there's no visible "flip" at harness-start.
When the run's harness is Oz, the tab shows the existing Oz ambient circle (brand purple background, Oz glyph, cloud lobe, status).
When the selected harness changes while composing (user opens the dropdown and picks a different harness), the icon updates immediately.

Pane header

The existing "agent indicator" slot on the pane-header title row (rendered via render_ambient_agent_indicator for cloud sessions and render_agent_indicator for conversation-bound terminals) switches to the same brand-color circle + status badge + cloud lobe treatment used in vertical tabs, at the same visual dimensions (16px icon / ~24px overall circle).
For an ambient Claude run in setup phase, the pane header shows a Claude-orange circle with a white cloud lobe containing the InProgress spinner — matching what the vertical tab shows for the same run.
For a local CLI agent session (e.g. claude running in a plain terminal), the pane header shows the CLI agent's brand circle with the status badge, no cloud lobe.
For plain-terminal / shell / error cases (no agent), the existing indicators (render_terminal_mode_indicator and its shell / error variants) remain unchanged. The new circle treatment only replaces the agent-specific indicators.

In the rows rendered by conversation_list/item.rs::render_item, the current leading-slot icon (a plain Icon::Cloud for ambient rows, or render_status_element for local rows) is replaced by the same agent icon-with-status treatment — brand circle, optional cloud lobe, status badge inside the lobe (ambient) or at the bottom-right (local).
For cloud Task rows (i.e. rows whose underlying ConversationOrTask::Task is an AmbientAgentTask), the harness is resolved from agent_config_snapshot.harness and the cloud lobe is rendered.
For local Conversation rows (ConversationOrTask::Conversation), the icon renders as a local Oz circle (no cloud lobe). Local conversations don't carry a harness field; they're treated as Oz for this surface.
The status inside the badge/lobe comes from ConversationOrTask::status(app) — which already maps task states and conversation states to ConversationStatus.
Row sizing is tuned to match the existing status_element_size footprint (font_size + STATUS_ELEMENT_PADDING * 2.) so adopting the unified icon doesn't shift row heights. Visual proportions follow the vertical tabs sizing.
Out of scope: the Agent Management View (AgentManagementView::render_card / render_header_row in app/src/ai/agent_management/view.rs) retains its current leading status icon. That surface has its own richer card layout with action buttons, session status labels, etc., and is intentionally not migrated in this pass.

Notifications mailbox

Notifications triggered by a cloud-mode agent run surface the cloud lobe in their avatar; notifications from local runs continue to render without the lobe.
Concretely, when AgentNotificationsModel::add_notification fires, the emit path resolves whether the originating terminal view was in an ambient session (via TerminalView::ambient_agent_view_model) and threads that flag into the notification, which in turn reaches render_agent_avatar instead of today's hardcoded false.
The avatar's brand color, glyph, and status icon keep matching the existing notification categories (Complete, Request, Error); only the cloud lobe is newly honored.

Cross-surface consistency guarantee

Given any single logical agent run (a cloud Task, a local conversation, a local CLI session), when it is visible simultaneously on two or more of the surfaces above, the resulting icon is pixel-identical (same brand color, same glyph, same status, same cloud-lobe presence). Achieving this is the centralization objective of this spec, and is validated by a shared test suite.

Edge cases

Harness selected but run not yet dispatched (Composing state): the vertical tab and pane header immediately reflect the selected third-party harness. The card surface is not applicable (no task yet).
Harness changed mid-composing: icons update immediately on every surface that reflects the composing view-model.
Viewer joins an existing shared session whose harness is not yet fetched: briefly renders as Oz until enter_viewing_existing_session resolves the task; once resolved, the icon updates to the correct harness. Acceptable — not new behavior, just inherited from REMOTE-1454.
Harness CLI detected by CLIAgentSessionsModel does not match the view-model's selected harness (rare): the CLIAgentSessionsModel session wins on surfaces that consult it directly (vertical tabs and pane header), because it represents observed reality. The conversation-list card still derives from agent_config_snapshot.harness since that's its only input.
Plain terminal, no agent at all: all four surfaces render whatever they render today — the new circle treatment does not replace plain-terminal indicators.
Cloud notification vs. local notification for the same agent kind (e.g. Claude): they now visually differ — the cloud one has the white lobe, the local one has the bottom-right status badge. This is intentional and consistent with vertical tabs.
Completed ambient run viewed as a historical conversation (no live AmbientAgentViewModel): the card renders based on the AmbientAgentTask fields. If the task's agent_config_snapshot.harness is present, we show that harness with the cloud lobe; otherwise we fall back to Oz. The pane header for a read-only replay uses whatever ambient_agent_view_model.selected_harness() resolved to when the viewer joined.

Success criteria

Selecting Claude (or Gemini) in the harness dropdown and submitting a cloud run immediately updates the tab icon to the Claude (or Gemini) brand circle with a cloud lobe containing the InProgress status — no Oz-cloud intermediate state.
The pane header for the same run shows the same Claude circle + cloud lobe + status as the tab.
The conversation list card for the same run shows the same Claude circle + cloud lobe + status.
When the run transitions to Success / Error / Blocked / Cancelled, the status icon inside the cloud lobe updates on every surface at once.
Starting a local claude CLI session (no cloud) shows a Claude brand circle with a bottom-right status badge on the vertical tab, pane header, and notifications (when a notification fires). No cloud lobe on any surface.
The legacy non-agent indicators (plain terminal, shell, error) are visually unchanged.
All the existing validation cases from REMOTE-1454 (non-oz cloud setup UX) continue to pass unchanged.

Validation

Spawn a Claude cloud run and observe the tab icon, pane header indicator, and conversation list card; confirm all three render as a Claude-orange circle with a cloud lobe containing the spinner during setup, and that they all transition together to the harness-running state when the claude CLI begins executing.
Spawn a Gemini cloud run and confirm the same using the Gemini brand color.
Spawn an Oz cloud run and confirm the three surfaces show Oz purple + cloud lobe + status, matching each other.
Start a local claude CLI session in a plain terminal and confirm the tab, pane header, and any notification emitted (e.g. on a blocked permission request) show a Claude circle + bottom-right status badge with no cloud lobe.
Cancel / fail / block a cloud Claude run; confirm the status icon inside the cloud lobe updates on every surface.
Open the inline conversation list menu after running several agents (Oz cloud, Claude cloud, Gemini cloud, local Claude, local Oz) and confirm each row's leading icon correctly identifies the agent and ambient-ness.
Let a cloud-mode Claude run complete while the tab is not focused; open the notifications mailbox and confirm the notification's avatar is a Claude circle with a cloud lobe.
Toggle CloudMode off; confirm no regression to existing non-cloud agent icons (local Oz, local CLI agents).
Toggle AgentHarness off; confirm all cloud runs fall back to the Oz treatment and no Claude/Gemini icons appear on any surface.

14 KiB Raw Blame History