The previous two posts covered how events flow from the SDK to the UI. This post focuses on visualizing one specific type of event: tool calls.
Tool invocations are the most frequent operations in an Agent application. A typical task might call tools twenty or thirty times—reading files, writing files, executing commands, searching code. If every tool call renders as the same gray block, it's hard for users to quickly tell "what command is Bash running" or "which file is Edit changing."
SwiftWork's solution is an extensible tool rendering system: each tool type registers a renderer, and ToolCardView looks up the matching renderer by tool name. When adding a new tool type, you only need to write a struct that implements the ToolRenderable protocol and register it with ToolRendererRegistry—no changes to TimelineView required.
Starting from the Problem: Why Not Use a Unified Tool View
The simplest approach is to use the same view for all tool calls—showing the tool name, input parameters, and output. The ToolCallView from post 2 serves this role:
struct ToolCallView: View {
let event: AgentEvent
var body: some View {
VStack(alignment: .leading, spacing: 4) {
HStack(spacing: 4) {
Image(systemName: "wrench.and.screwdriver")
Text(event.content) // 工具名称
}
Text(input) // 原始 JSON
}
}
}
This view treats all tools equally—the same wrench icon, the same JSON output. It works fine as a fallback, but has a few problems:
- For Bash calls, users want to see the command itself (
git status), not{"command": "git status"} - For Read calls, users want to see the file path (
src/main.swift), not the full JSON - Search tool results might contain multi-line matches, which need to be distinguished from single-line output
Each tool has different "most useful information." The Tool Card system lets each tool decide how to present itself.
The ToolRenderable Protocol
The protocol defines the contract for tool renderers:
protocol ToolRenderable: Sendable {
/// 此渲染器处理的工具名称（与 SDK ToolUseData.toolName 匹配）
static var toolName: String { get }
/// 工具类型主题色（左边条、图标着色）
static var accentColor: Color { get }
/// 工具类型 SF Symbol 图标名
static var icon: String { get }
/// 根据工具内容生成 SwiftUI 视图
@ViewBuilder @MainActor
func body(content: ToolContent) -> any View
/// 生成摘要标题（折叠状态显示）
func summaryTitle(content: ToolContent) -> String
/// 生成副标题（如文件路径、命令摘要）
func subtitle(content: ToolContent) -> String?
}
The protocol extension provides default values:
extension ToolRenderable {
static var accentColor: Color { .gray }
static var icon: String { "wrench.and.screwdriver" }
func summaryTitle(content: ToolContent) -> String {
content.toolName
}
func subtitle(content: ToolContent) -> String? {
nil
}
}
Six members, three with defaults. Implementers only need to provide toolName (the static routing key) and body (the rendered content). summaryTitle and subtitle can be overridden to provide more meaningful summaries, and accentColor and icon can be overridden for visual distinction.
ToolRendererRegistry
The registry is a [String: ToolRenderable] dictionary, keyed by toolName:
@MainActor
@Observable
final class ToolRendererRegistry {
private var renderers: [String: any ToolRenderable] = [:]
init() {
register(BashToolRenderer())
register(FileEditToolRenderer())
register(SearchToolRenderer())
register(ReadToolRenderer())
register(WriteToolRenderer())
}
func register(_ renderer: any ToolRenderable) {
renderers[type(of: renderer).toolName] = renderer
}
func renderer(for toolName: String) -> (any ToolRenderable)? {
renderers[toolName]
}
}
Five built-in renderers are pre-registered during init. Lookup is O(1) dictionary access. The @Observable annotation lets SwiftUI automatically refresh when new renderers are registered—though in current usage all renderers are registered at init time, dynamic registration is reserved for a future plugin system.
5 Built-in Renderers
BashToolRenderer — Terminal Commands
struct BashToolRenderer: ToolRenderable {
static let toolName = "Bash"
static let accentColor: Color = .green
static let icon: String = "terminal"
func summaryTitle(content: ToolContent) -> String {
// 从 input JSON 提取 command 字段
// {"command": "git status"} → "git status"
guard let json = parseInput(content),
let command = json["command"] as? String
else { return content.toolName }
return command
}
}
Green theme + terminal icon. summaryTitle extracts the command field from the input JSON—users see the running command directly in the collapsed state.
ReadToolRenderer — File Reading
struct ReadToolRenderer: ToolRenderable {
static let toolName = "Read"
static let accentColor: Color = .blue
static let icon: String = "doc.text"
func summaryTitle(content: ToolContent) -> String {
// {"file_path": "src/main.swift"} → "src/main.swift"
guard let json = parseInput(content),
let filePath = json["file_path"] as? String
else { return content.toolName }
return filePath
}
}
Blue theme + document icon. summaryTitle extracts the file path.
WriteToolRenderer — File Writing
struct WriteToolRenderer: ToolRenderable {
static let toolName = "Write"
static let accentColor: Color = .orange
static let icon: String = "pencil.and.outline"
func summaryTitle(content: ToolContent) -> String {
// 提取 file_path
}
func subtitle(content: ToolContent) -> String? {
// 提取 content 字段，截取前 80 字符
// {"content": "import Foundation\n..."} → "import Foundation..."
guard let json = parseInput(content),
let contentStr = json["content"] as? String, !contentStr.isEmpty
else { return nil }
return "\(contentStr.prefix(80))..."
}
}
Orange theme + pencil icon. It has one more field than Read—a subtitle showing the first 80 characters of the written content. Since written content is typically long, the subtitle gives users a quick preview.
FileEditToolRenderer — File Editing
struct FileEditToolRenderer: ToolRenderable {
static let toolName = "Edit"
static let accentColor: Color = .orange
static let icon: String = "pencil.line"
func summaryTitle(content: ToolContent) -> String {
// 提取 file_path
}
func subtitle(content: ToolContent) -> String? {
// 提取 old_string，截取前 50 字符
// {"old_string": "func hello() {"} → "Editing: func hello() {"
guard let json = parseInput(content),
let oldString = json["old_string"] as? String, !oldString.isEmpty
else { return nil }
return "Editing: \(oldString.prefix(50))"
}
}
Orange theme + edit icon. The subtitle displays the old text being replaced—so users know which line Edit is changing.
SearchToolRenderer — Code Search
struct SearchToolRenderer: ToolRenderable {
static let toolName = "Grep"
static let accentColor: Color = .purple
static let icon: String = "text.magnifyingglass"
func summaryTitle(content: ToolContent) -> String {
// 提取 pattern
}
func subtitle(content: ToolContent) -> String? {
// 提取 path
}
}
Purple theme + magnifying glass icon. summaryTitle shows the search pattern, and subtitle shows the search path.
Visual Distinction Summary
| Tool | Color | Icon | summaryTitle | subtitle |
|---|---|---|---|---|
| Bash | Green | terminal | Command | - |
| Read | Blue | doc.text | File path | - |
| Write | Orange | pencil.and.outline | File path | First 80 chars of content |
| Edit | Orange | pencil.line | File path | First 50 chars of replaced text |
| Grep | Purple | text.magnifyingglass | Search pattern | Search path |
All five tool types can be distinguished at a glance in the collapsed state: different colors, different icons, different summary text.
ToolCardView: The Container View
ToolCardView is the container for tool cards. It doesn't handle rendering itself—it delegates to the renderer looked up from the registry:
struct ToolCardView: View {
let content: ToolContent
let registry: ToolRendererRegistry
let isSelected: Bool
let onSelect: () -> Void
@State private var isExpanded = false
var body: some View {
HStack(spacing: 0) {
// 左边条（3px，渲染器的主题色）
RoundedRectangle(cornerRadius: 2)
.fill(toolAccentColor)
.frame(width: 3)
VStack(alignment: .leading, spacing: 0) {
titleRow // 始终可见
.onTapGesture {
onSelect()
withAnimation { isExpanded.toggle() }
}
if isExpanded {
expandedContent // 展开后可见
}
}
}
}
}
The card has two layers: titleRow (always visible) and expandedContent (shown on click to expand).
titleRow
private var titleRow: some View {
HStack(alignment: .top, spacing: 6) {
Image(systemName: toolIcon) // 渲染器的图标
.foregroundStyle(toolIconColor)
VStack(alignment: .leading, spacing: 2) {
HStack(spacing: 4) {
Text(resolvedSummaryTitle) // 渲染器的 summaryTitle
.fontWeight(.medium)
Spacer()
if content.status == .running {
ProgressView().controlSize(.mini) // 运行中转圈
}
Text(statusLabel) // pending / running / completed / failed
.font(.system(size: 9))
.background(statusColor.opacity(0.15))
}
Text(content.toolName) // 工具名称（小字）
if let subtitle = resolvedSubtitle { // 渲染器的 subtitle
Text(subtitle)
}
}
}
}
The title row gets its icon, color, summary title, and subtitle from the renderer. The status label (pending/running/completed/failed) is determined by ToolContent.status and is outside the renderer's control—it's a generic execution status, independent of tool type.
expandedContent
private var expandedContent: some View {
VStack(alignment: .leading, spacing: 8) {
Divider()
// 工具特定的 body（从渲染器获取）
if let renderer = registry.renderer(for: content.toolName) {
AnyView(renderer.body(content: content))
} else {
genericToolBody // fallback
}
// 通用 INPUT 区域
if !content.input.isEmpty {
HStack {
Text("INPUT")
Spacer()
CopyButton(text: content.input)
}
Text(content.input)
.font(.system(.caption, design: .monospaced))
}
// 通用 OUTPUT 区域
if let output = content.output, !output.isEmpty {
ToolResultContentView(output: output, isError: content.isError)
}
}
}
The expanded content has three sections:
-
The renderer's
body: Tool-specific custom content. The current 5 built-in renderers each display an icon summary block in theirbody—similar to the information intitleRowbut more detailed. In the future, more complex tools could provide richerbodycontent (such as code diff previews). - INPUT section: Generic raw input JSON display with a copy button.
-
OUTPUT section:
ToolResultContentView, covered in the next section.
genericToolBody is the fallback when no renderer is registered—it just shows the tool name and raw input.
ToolResultContentView: Output Rendering + Diff Detection
ToolResultContentView has a smart feature: it automatically detects whether the output content is in diff format, and if so, applies color highlighting.
private var isDiffContent: Bool {
let lines = output.components(separatedBy: "\n")
let diffLines = lines.filter { $0.hasPrefix("+") || $0.hasPrefix("-") || $0.hasPrefix("@@") }
return diffLines.count >= 2
}
Detection logic: if the output has at least two lines starting with +, -, or @@, it's treated as diff content. Simple but effective—the SDK's Edit tool outputs results in diff format.
Diff rendering adds background colors to each line:
private func diffLineView(_ line: String) -> some View {
Text(line)
.font(.system(.caption, design: .monospaced))
.padding(.horizontal, 4)
.background(diffLineBackground(line))
}
private func diffLineBackground(_ line: String) -> Color {
if line.hasPrefix("+") { return .green.opacity(0.15) } // 新增行
if line.hasPrefix("-") { return .red.opacity(0.15) } // 删除行
if line.hasPrefix("@@") { return .blue.opacity(0.1) } // 位置标记
return .clear
}
Non-diff content renders as plain text with truncation logic—it collapses when exceeding 5 lines or 200 characters, with an expand button.
How to Add a New Tool Renderer
Say the SDK adds a new WebFetch tool, and you want to give it a dedicated card style in SwiftWork. You only need two steps:
Step 1: Write the renderer
struct WebFetchToolRenderer: ToolRenderable {
static let toolName = "WebFetch"
static let accentColor: Color = .cyan
static let icon: String = "globe"
@MainActor
func body(content: ToolContent) -> any View {
// 自定义视图...
}
func summaryTitle(content: ToolContent) -> String {
// 从 input 提取 URL
guard let json = parseInput(content),
let url = json["url"] as? String
else { return content.toolName }
return url
}
}
Step 2: Register it
// ToolRendererRegistry.init()
register(WebFetchToolRenderer())
No need to modify TimelineView, ToolCardView, or any other file. ToolCardView looks up the renderer at render time via registry.renderer(for:)—if found, it uses it; if not, it falls back to the generic view.
Summary
The Tool Card system follows a protocol + registry design pattern:
| Component | Responsibility |
|---|---|
ToolRenderable |
Defines the rendering contract—tool name, color, icon, summary, custom view |
ToolRendererRegistry |
Dictionary lookup, toolName → ToolRenderable
|
ToolCardView |
Container view, delegates to renderer, handles generic logic (expand/collapse, status labels, INPUT/OUTPUT sections) |
ToolResultContentView |
Output rendering with automatic diff detection |
The benefit of this pattern is open for extension, closed for modification. TimelineView's dispatch logic (the toolCardView(for:) from post 2) doesn't need to know how many tool types exist—it only queries the registry. When adding a new tool type, the scope of changes is limited to the renderer file and the registry's init method.
The next and final post covers the data layer—SwiftData session/event persistence, app state restoration, Markdown rendering, and syntax highlighting.
Deep Dive into SwiftWork Series:
- Part 0: Building a macOS Agent Workbench with SwiftUI
- Part 1: SDK Integration — Bridging AsyncStream to SwiftUI
- Part 2: Event Timeline — Visualizing 18 Event Types
- Part 3: Tool Card — An Extensible Tool Visualization System
- Part 4: Data Layer and Services — SwiftData, State Restore, Markdown Rendering
GitHub: SwiftWork | Open Agent SDK