Patterns
Agent Actions
Tool calls, subagent orchestration, parallel execution, plan cards, clarifying questions, decision flows, and approval gates for agent-driven approval and product workflows.
Actions
Tool Calls
Expandable, human-readable action indicators. Each tool call shows a plain-language label — never a function signature. Click to reveal key-value details.
| Property | Spec |
|---|---|
| Tool title | 14px sans, font-weight 400 (never bold) |
| Inner detail text | 12px, key in muted, value in foreground |
| Icons | All monochrome — no colored status indicators |
| Labels | Human-readable only — no function signatures or code |
| Duration | Right-aligned in muted text; errors show "failed ·" prefix |
| Interaction | Click anywhere on the header row to expand/collapse |
Tool calls should feel like quiet status updates, not system logs. The user glances at them during execution and digs in only when something looks wrong.
Orchestration
Subagent Orchestration
Expandable rows showing delegated subagent work. Each row carries its own progress indicator and related tool calls.
| Property | Spec |
|---|---|
| Progress format | "N of M unit" — concrete, not percentage-based |
| Completion | "complete" badge replaces the progress count |
| Running indicator | Pulsing dot next to the badge while in-progress |
| Nesting | Nested tool calls inherit the same collapsed style |
| Progress bar | 1px foreground/40 bar with transition-transform duration-500 |
Subagent cards let users monitor delegated work without leaving their current context. The progress bar provides glanceable status while nested tools offer drill-down detail.
Planning
Plan Cards
Step-progress cards that show the agent's execution plan. Completed steps are muted with line-through; the current step pulses subtly; pending steps are dimmed.
| Property | Spec |
|---|---|
| Step indicator | 6px square dot, rounded-sm — not a checkbox or number |
| Done state | Muted foreground + line-through |
| Active state | Foreground + pulse animation |
| Pending state | Muted foreground at 60% opacity |
| Editable mode | Drag handle + remove button on hover per step |
| Progress badge | "N of M complete" or step count in editable mode |
Plan cards give users a sense of progress and predictability. The editable mode allows corrections before the agent commits to an approach — a key trust-building pattern.
Concurrency
Parallel Execution
IDE-style tree connectors for operations running concurrently. The parent row collapses the branch; each child expands to show tool call details inline.
| Element | Spec |
|---|---|
| Vertical spine | 1px line from parent icon to last child, masked by bg-background behind each icon |
| L-connectors | rounded-bl-lg border-l + border-b connecting spine to each child |
| Icon masking | size-6 bg-background circle behind size-5 icon creates clean spine breaks |
| Hover state | Row label and icon transition to text-foreground; timestamp fades in on right |
| Last child | bg-background mask covers spine below the final L-bend |
| Sequential fallback | Flat list of bordered rows, no tree connectors |
The tree view uses Perplexity-style connectors — a vertical spine with L-shaped branch lines, icons that mask the spine for clean breaks, and hover-revealed timestamps. Each child row is lightweight: no borders, no cards, just text and an expand chevron.
Decisions
Decision Flow
When the agent needs the user to choose between options that have different consequences. Each option shows what will happen if selected.
How should I handle the missing audit log entries for Timestamp handling?
| Pattern | Spec |
|---|---|
| Pending state | All options clickable with hover effect and consequence preview |
| Resolved state | Selected option highlighted, others hidden, confirmation shown |
| Selected card | Primary border + subtle primary background tint |
| Consequence previews | Border-left callout with arrow indicator inside each option |
| Auto-selection | Never auto-select — always wait for explicit user choice |
Decisions are the highest-trust pattern in the system — they grant the user explicit control over how the agent proceeds. Never bypass them with auto-selection or hidden defaults.
Clarification
Clarifying Questions
When the agent is blocked by missing intent, ask a focused question with answerable options, optional free text, and a clear skip path. This keeps clarification out of a vague back-and-forth chat loop.
| Property | Spec |
|---|---|
| Question shape | One focused question with 2-5 answerable options |
| Selection | Single or multi-select rows with explicit selected state |
| Other input | Inline textarea for constraints that do not fit the options |
| Skip path | Visible skip control when the agent can continue with defaults |
| Submit | Continue disabled until an option or free-text answer exists |
| Answered state | Selected answers collapse into readable chips before work resumes |
Clarifying questions should reduce ambiguity, not create a survey. Prefer choices when the agent can name the likely answers. Use the free-text row only for constraints, missing context, or edge cases.
Confirmation
Approval Gate
Human-in-the-loop confirmation before the agent performs a consequential action. The user reviews the action details and explicitly approves or denies.
| Property | Spec |
|---|---|
| Action summary | Shield icon + plain-language description of what the agent wants to do |
| Detail panel | Muted background container with key-value or diff preview |
| Diff format | Green-ish (+) for additions, red-ish (−) for removals, muted tones |
| Approve button | Primary fill — should feel deliberate, not default |
| Deny button | Ghost/outline — lower visual weight than approve |
| Result states | Success (primary border), denied (destructive border), with reset button |
Approval gates are the most critical trust pattern in the system. They ensure the agent never takes consequential actions without explicit human confirmation — essential for high-trust workflows where mistakes have regulatory consequences.