BlockRenderer
Category: Terminal & Rendering
Source: block_renderer.dart
Enums
ToolCallPhase
The lifecycle phase of a tool call, used to drive the status suffix displayed next to the tool name in the terminal (e.g. "running…", "denied").
Semantics:
- [preparing]: model named the tool; arguments still streaming.
- [awaitingApproval]: user decision required before execution.
- [running]: Glue is actively executing the tool.
- [done]: tool completed successfully.
- [denied]: user or policy refused execution before it ran.
- [cancelled]: user cancelled while the tool was active (Ctrl+C or
/cancel). Distinct from [denied] (never ran) and [error] (ran but failed on its own). - [error]: tool ran but returned an error.
| Value | Description |
|---|---|
preparing | |
awaitingApproval | |
running | |
done | |
denied | |
cancelled | |
error |
Classes
ToolCallRenderState
Snapshot of a tool call's display state, passed to [BlockRenderer.renderToolCallRef].
Keeps rendering concerns separate from the agent event model — the renderer never needs to know about [AgentEvent] directly.
Constructor
ToolCallRenderState({required this.name, this.args, required this.phase})Properties
| Property | Type | Description |
|---|---|---|
name | String | |
args | Map<String, dynamic>? | |
phase | ToolCallPhase |
BlockRenderer
Renders conversation blocks as styled terminal text.
A 1-character margin is reserved on each side so output never renders flush against the terminal edges.
Constructor
BlockRenderer(this.width)Properties
| Property | Type | Description |
|---|---|---|
width | int | Total terminal width. |
Methods
String renderUser(String text)
Render a user message block.
String renderAssistant(String text)
Render an assistant message block.
String renderThinking(String text)
Render a streaming reasoning / "thinking" block. Styled dim + italic so the user reads it as deliberative-aside, not as the final answer. ▸ differentiates from the assistant's ◆ and the user's ❯.
String renderToolCall(String name, Map<String, dynamic>? args)
Render a tool call block.
String renderToolCallRef(ToolCallRenderState? state)
Renders a tool call header with a phase-dependent status suffix.
The [ToolCallRenderState.phase] determines what appears after the tool name — for example (preparing…), (running…), or nothing at all when the phase is [ToolCallPhase.done].
When [state] is null (e.g. the call ID wasn't found), renders a placeholder "Tool: ???" so the UI never breaks.
String renderToolResult(String content, {bool success = true})
Render a tool result block.
String renderError(String message)
Render an error block.
String renderSubagent(String text)
Render a subagent activity entry (indented + dimmed to show hierarchy).
String renderSystem(String text)
Render a system message block.