feat: render subagent activity in chat UI — open design questions

[rdwj]

Summary

The agent-template repo is designing a subagent-as-tool feature that lets a primary agent delegate sub-steps to specialist agents and receive structured results — see fips-agents/agent-template#165 ("feat: subagent-as-tool — composable agent delegation") and the design doc at planning/subagent-tool-design.md in that repo.

When subagents land in the agent layer, the gateway and UI will need to decide how to render that activity. Decisions made now in the agent layer about which StreamEvents to emit, how nesting is communicated, and what metadata travels on each event will directly constrain the UI's options later. This issue captures the open questions on the UI side so the agent-side design can be informed before it ships.

This issue is deliberately a discussion / requirements issue, not an implementation. No rendering decisions yet — the goal is to surface the questions and feed answers back to fips-agents/agent-template#165.

Open design space

Inline vs. side-panel

Subagent activity could render as:

• Inline as a tool call. Compact, fits the existing tool-call UX, easy to skim. Loses richness when the subagent has its own multi-step internal flow.
• Side panel / canvas with one pane per active subagent. Richer, useful for ops dashboards and parallel delegations. Heavier UX, more screen real-estate.
• Hybrid. Collapsed inline by default, expandable to a side panel for detail. Probably the right default — cheap visual cost, full detail on demand.

What does the user see?

• Subagent prompts (the task payload the parent sent)?
• Subagent intermediate tool calls?
• Just the final result?
• Configurable per agent? Per role? Per tenant?

There is a real tension here. Customer-service operators may not want to see internal delegation; ops dashboards may want every step. Healthcare deployments may legally need full audit visibility, even when the operator never reads it.

Multiple concurrent subagents

A primary agent that fans out per-file analysis to N workers will have N concurrent subagent threads. Options:

• Tabbed view. One tab per subagent, switch between them.
• Stacked panes. All visible, scrolling within each.
• List with expand-to-detail. Compact list of running subagents, click to expand one.

Cancellation

Can the user kill a running subagent from the UI? The agent layer would need a cancellation channel — the framework does not currently expose one for tool calls in flight. If the UI wants this, it becomes a forward-request to the agent layer.

History / replay

When reviewing a past session, are subagent threads expanded by default or collapsed? For a long session with dozens of delegations, the default needs to be "collapsed" or the timeline becomes unreadable.

Streaming

When the agent layer adds streaming subagents (v2 in the design doc), the UI receives nested SubagentDelta events. What does the UI need from each event to render coherently? Likely:

• A stable subagent_run_id to attach deltas to the right rendering surface.
• The original event type so the UI can apply the same rendering as for top-level events.
• A depth or breadcrumb so nested-delegation chains (subagent calling sub-subagent) render correctly.

Required from the agent side (forward request)

These are suggestions for fips-agents/agent-template#165, not commitments. They reflect what the UI is most likely to need:

• Nested events with explicit hierarchy. Each subagent event should carry parent_span_id, subagent_name, and depth. The UI uses these to attach deltas to the right rendering surface.
• Lifecycle events. subagent.started, subagent.completed, subagent.failed, subagent.cancelled — explicit so the UI can show progress, error states, and cancellation distinctly.
• Token / cost roll-up at completion. The completion event should include tokens_used and cost_usd so the UI can surface delegation cost without computing it client-side.
• Stable IDs across the lifetime of a delegation. A subagent_run_id that persists from start to completion, so streaming deltas attach correctly.
• Cancellation channel. Optional but valuable; if the agent layer can accept a cancellation request mid-call, the UI can surface a cancel button.

The agent-side design doc already proposes most of these. This issue captures the UI's perspective so the agent layer can confirm or adjust before v1 ships.

Out of scope

• Deciding the rendering. Deliberately open until subagents land in the agent layer and we see real telemetry. The right rendering depends on what real deployments do (one shallow delegation per session vs. deep chains; a few parallel workers vs. dozens; brief invocations vs. long-running).
• Implementing anything. This issue is requirements-gathering. The implementation issue (or issues) will follow once the agent-side feature ships and the rendering shape is decided.

Action items

• Track the agent-side issue (feat: subagent-as-tool — composable agent delegation agent-template#165) and surface comments here when the design firms up.
• Once v1 of subagent support ships in the agent layer, revisit this issue with concrete telemetry from a real deployment.
• Decide rendering shape (inline / side-panel / hybrid) once we have data.

Related

• feat: subagent-as-tool — composable agent delegation agent-template#165 — agent-side feature.
• fips-agents/agent-template's planning/subagent-tool-design.md — full design.