From 1e72407d7b93a89bbb2af768e5c7ce471cd5950d Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 13:50:27 -0700
Subject: [PATCH 01/11] =?UTF-8?q?feat(coc):=20agents=20canvas=20=E2=80=94?=
 =?UTF-8?q?=20data=20+=20layout=20layer?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation for a spatial "Agents" view of a chat's recursive sub-agent
runs (ported from the coc-chat design). Pure, UI-free modules so the
layout math and data adapter are unit-tested in isolation:

- types.ts — AgentRunNode tree (orchestrator root → sub-agent runs).
- layout.ts — tidy left→right tree layout (buildLayout), curved edge
  paths (edgePath), and per-depth spine colors (spineVars), ported
  verbatim from the prototype so spatial output matches.
- buildAgentRunTree.ts — adapts real conversation turns into the tree:
  the orchestrator is the root, each `Task` tool call becomes a
  sub-agent child (name/role from args, status/timing from the call),
  deduped across toolCalls + timeline and ordered by start time.

Tests cover layout geometry/edges/spine cycling and the adapter's
field mapping, prompt-name fallback, dedup, root-status derivation,
and ordering. No UI is wired yet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../chat/agent-canvas/buildAgentRunTree.ts    | 180 ++++++++++++++++++
 .../features/chat/agent-canvas/layout.ts      | 110 +++++++++++
 .../react/features/chat/agent-canvas/types.ts |  29 +++
 .../spa/client/agent-canvas-data.test.ts      | 135 +++++++++++++
 .../spa/client/agent-canvas-layout.test.ts    |  94 +++++++++
 5 files changed, 548 insertions(+)
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/layout.ts
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
 create mode 100644 packages/coc/test/server/spa/client/agent-canvas-data.test.ts
 create mode 100644 packages/coc/test/server/spa/client/agent-canvas-layout.test.ts

diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
new file mode 100644
index 000000000..bbbf92fb8
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -0,0 +1,180 @@
+// Adapts the dashboard's real conversation data into the recursive
+// AgentRunNode tree the canvas renders. The orchestrator (this conversation)
+// is the root; each `Task` tool call it issued becomes a sub-agent child.
+//
+// Sub-agent `Task` calls are the faithful, already-loaded source for the agent
+// tree — no extra fetch. The tree shape supports arbitrary depth, so deeper
+// recursion (a sub-agent's own children) can be layered on later without
+// touching the canvas.
+
+import type { ClientConversationTurn, ClientToolCall } from '../../../types/dashboard';
+import { normalizeToolName } from '../conversation/tool-calls/toolNormalization';
+import type { AgentRunNode, AgentRunStatus } from './types';
+
+export interface AgentRunRootMeta {
+    /** Root node id (defaults to 'root'). */
+    id?: string;
+    /** Root label (defaults to a generic orchestrator name). */
+    title?: string;
+    /** Overall conversation/process status — drives the root node's status. */
+    status?: string;
+}
+
+function parseTime(v: unknown): number | undefined {
+    if (typeof v === 'number') {
+        return Number.isFinite(v) ? v : undefined;
+    }
+    if (typeof v === 'string') {
+        const ms = Date.parse(v);
+        return Number.isFinite(ms) ? ms : undefined;
+    }
+    return undefined;
+}
+
+/** Tool-call status → run status. */
+function mapToolStatus(status: string | undefined): AgentRunStatus {
+    switch (status) {
+        case 'completed': return 'done';
+        case 'failed': return 'failed';
+        case 'pending': return 'queued';
+        case 'running':
+        default: return 'running';
+    }
+}
+
+/** AIProcess status → run status (for the orchestrator root). */
+function mapRootStatus(status: string | undefined): AgentRunStatus {
+    switch (status) {
+        case 'completed': return 'done';
+        case 'failed':
+        case 'cancelled': return 'failed';
+        case 'queued': return 'queued';
+        case 'running':
+        case 'cancelling': return 'running';
+        default: return 'done';
+    }
+}
+
+function firstLine(text: string): string {
+    const line = text.split('\n').map((l) => l.trim()).find(Boolean) || '';
+    return line.length > 120 ? `${line.slice(0, 117).trimEnd()}…` : line;
+}
+
+// How "advanced" a status is — used to keep the best snapshot when the same
+// tool-call id appears in both `turn.toolCalls` and the timeline.
+const STATUS_RANK: Record<string, number> = { pending: 0, running: 1, completed: 2, failed: 2 };
+
+/** Collect every tool call across turns, deduped by id, preferring terminal state. */
+function collectToolCalls(turns: ClientConversationTurn[]): ClientToolCall[] {
+    const byId = new Map<string, ClientToolCall>();
+    const consider = (tc: ClientToolCall | undefined): void => {
+        if (!tc || !tc.id) {
+            return;
+        }
+        const existing = byId.get(tc.id);
+        if (!existing) {
+            byId.set(tc.id, tc);
+            return;
+        }
+        const keepNew = (STATUS_RANK[tc.status] ?? 0) >= (STATUS_RANK[existing.status] ?? 0);
+        const better = keepNew ? tc : existing;
+        const worse = keepNew ? existing : tc;
+        byId.set(tc.id, {
+            ...worse,
+            ...better,
+            startTime: better.startTime ?? worse.startTime,
+            endTime: better.endTime ?? worse.endTime,
+            result: better.result ?? worse.result,
+            error: better.error ?? worse.error,
+        });
+    };
+    for (const turn of turns) {
+        if (Array.isArray(turn.toolCalls)) {
+            for (const tc of turn.toolCalls) {
+                consider(tc);
+            }
+        }
+        for (const item of turn.timeline || []) {
+            consider(item.toolCall);
+        }
+    }
+    return Array.from(byId.values());
+}
+
+/** Stable sort by start time; runs with no known start time keep their order, last. */
+function byStartedAt(a: AgentRunNode, b: AgentRunNode): number {
+    if (a.startedAt === undefined && b.startedAt === undefined) {
+        return 0;
+    }
+    if (a.startedAt === undefined) {
+        return 1;
+    }
+    if (b.startedAt === undefined) {
+        return -1;
+    }
+    return a.startedAt - b.startedAt;
+}
+
+function asRecord(v: unknown): Record<string, unknown> {
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+/** Build a sub-agent node from a normalized `Task` tool call. */
+function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
+    const args = asRecord(tc.args);
+    const agentType = typeof args.agent_type === 'string' ? args.agent_type
+        : typeof args.subagent_type === 'string' ? args.subagent_type
+            : '';
+    const description = typeof args.description === 'string' ? args.description.trim() : '';
+    const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
+    const name = description
+        || (prompt ? (prompt.length > 48 ? `${prompt.slice(0, 45).trimEnd()}…` : prompt) : '')
+        || 'sub-agent';
+    const summary = typeof tc.result === 'string' && tc.result.trim()
+        ? firstLine(tc.result)
+        : undefined;
+    return {
+        id: tc.id,
+        name,
+        role: agentType || 'agent',
+        status: mapToolStatus(tc.status),
+        startedAt: parseTime(tc.startTime),
+        completedAt: parseTime(tc.endTime),
+        summary,
+        children: [],
+    };
+}
+
+/**
+ * Build the agent-run tree from a conversation's turns. The root represents the
+ * orchestrator; its children are the `Task` sub-agents it spawned, ordered by
+ * start time. Returns a root with no children when the conversation issued none.
+ */
+export function buildAgentRunTreeFromTurns(
+    turns: ClientConversationTurn[] | undefined,
+    root?: AgentRunRootMeta,
+): AgentRunNode {
+    const taskCalls = collectToolCalls(turns || [])
+        .filter((tc) => normalizeToolName(tc.toolName) === 'task');
+
+    const children = taskCalls.map(nodeFromTaskCall);
+    children.sort(byStartedAt);
+
+    const rootStatus: AgentRunStatus = root?.status
+        ? mapRootStatus(root.status)
+        : (children.some((c) => c.status === 'running' || c.status === 'queued') ? 'running' : 'done');
+
+    return {
+        id: root?.id || 'root',
+        name: (root?.title && root.title.trim()) || 'CoC · orchestrator',
+        role: 'orchestrator',
+        status: rootStatus,
+        isRoot: true,
+        children,
+    };
+}
+
+/** Count every run in the tree, including the root. */
+export function countRuns(node: AgentRunNode): number {
+    return 1 + (node.children || []).reduce((sum, c) => sum + countRuns(c), 0);
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/layout.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/layout.ts
new file mode 100644
index 000000000..47e449249
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/layout.ts
@@ -0,0 +1,110 @@
+// Pure layout math for the Agents canvas — a tidy left→right tree over the
+// recursive agent-run tree. Ported verbatim from the design prototype
+// (coc-chat/agent-canvas.jsx) so the spatial output matches pixel-for-pixel.
+
+import type { AgentRunNode } from './types';
+
+// Geometry (px). COLW = horizontal stride per depth, ROWH = vertical stride per
+// leaf, NODE* = node box size, PAD = world padding around the tree.
+export const COLW = 250;
+export const ROWH = 78;
+export const NODEW = 202;
+export const NODEH = 56;
+export const PAD = 60;
+
+export interface PositionedNode {
+    x: number;
+    y: number;
+    depth: number;
+    node: AgentRunNode;
+}
+
+export interface CanvasEdge {
+    from: string;
+    to: string;
+    depth: number;
+}
+
+export interface CanvasLayout {
+    /** Positioned node keyed by node id. */
+    pos: Record<string, PositionedNode>;
+    /** Node ids in render order (root-first, depth-first). */
+    order: string[];
+    /** Parent→child connectors. */
+    edges: CanvasEdge[];
+    /** Intrinsic world size for fit-to-view. */
+    worldW: number;
+    worldH: number;
+}
+
+/**
+ * Tidy left→right layout over the run tree (including the synthetic root).
+ * Each parent is vertically centered over its children; leaves stack one row
+ * apart. x is driven purely by depth, so columns line up across branches.
+ */
+export function buildLayout(root: AgentRunNode): CanvasLayout {
+    const pos: Record<string, PositionedNode> = {};
+    const order: string[] = [];
+    const edges: CanvasEdge[] = [];
+    let cursorY = 0;
+
+    function rec(node: AgentRunNode, depth: number, parentId: string | null): number {
+        const x = depth * COLW;
+        const kids = node.children || [];
+        let y: number;
+        if (kids.length) {
+            const ys = kids.map((k) => rec(k, depth + 1, node.id));
+            y = (ys[0] + ys[ys.length - 1]) / 2;
+        } else {
+            y = cursorY;
+            cursorY += ROWH;
+        }
+        pos[node.id] = { x, y, depth, node };
+        order.push(node.id);
+        if (parentId !== null) {
+            edges.push({ from: parentId, to: node.id, depth });
+        }
+        return y;
+    }
+    rec(root, 0, null);
+
+    let maxX = 0;
+    let maxY = 0;
+    for (const p of Object.values(pos)) {
+        maxX = Math.max(maxX, p.x);
+        maxY = Math.max(maxY, p.y);
+    }
+    return {
+        pos,
+        order,
+        edges,
+        worldW: maxX + NODEW + PAD * 2,
+        worldH: maxY + NODEH + PAD * 2,
+    };
+}
+
+/** Curved connector from a parent's right-center to a child's left-center. */
+export function edgePath(a: PositionedNode, b: PositionedNode): string {
+    const x1 = a.x + NODEW + PAD;
+    const y1 = a.y + NODEH / 2 + PAD;
+    const x2 = b.x + PAD;
+    const y2 = b.y + NODEH / 2 + PAD;
+    const dx = Math.max(40, (x2 - x1) * 0.5);
+    return `M ${x1} ${y1} C ${x1 + dx} ${y1}, ${x2 - dx} ${y2}, ${x2} ${y2}`;
+}
+
+// Per-depth spine hue, cycling a ring — mirrors the thread's depth-spine colors
+// so a node's depth reads the same in both views.
+const DEPTH_HUES = [252, 292, 162, 28, 200];
+
+// CSS custom-property bag spread into a node's inline style. Built via bracket
+// assignment because `--`-prefixed keys aren't valid camelCase identifiers.
+export type SpineVars = Record<string, string>;
+
+export function spineVars(depth: number): SpineVars {
+    const h = DEPTH_HUES[depth % DEPTH_HUES.length];
+    const vars: SpineVars = {};
+    vars['--spine'] = `oklch(0.55 0.16 ${h})`;
+    vars['--spine-soft'] = `oklch(0.95 0.04 ${h})`;
+    return vars;
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
new file mode 100644
index 000000000..909e6f9de
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
@@ -0,0 +1,29 @@
+// Recursive agent-run tree consumed by the "Agents" canvas view — a spatial
+// map of the orchestrator and its (recursively spawned) sub-agent runs.
+//
+// Ported from the design prototype (coc-chat/agent-canvas.jsx), adapted to the
+// dashboard's real conversation data: every node is either the synthetic
+// orchestrator root or a sub-agent run derived from a `Task` tool call.
+
+/** Run lifecycle state, using the prototype's vocabulary so the CSS port maps 1:1. */
+export type AgentRunStatus = 'queued' | 'running' | 'done' | 'failed';
+
+export interface AgentRunNode {
+    /** Stable id — the tool-call id for sub-agents, 'root' for the orchestrator. */
+    id: string;
+    /** Display name: the sub-agent's description (or a truncated prompt). */
+    name: string;
+    /** Role label: the sub-agent type (e.g. 'Explore'), or 'orchestrator' for the root. */
+    role: string;
+    status: AgentRunStatus;
+    /** True only for the synthetic orchestrator root. */
+    isRoot?: boolean;
+    /** Epoch ms when the run started, if known. */
+    startedAt?: number;
+    /** Epoch ms when the run finished, if known. */
+    completedAt?: number;
+    /** One-line summary / conclusion, if available. */
+    summary?: string;
+    /** Recursively spawned child runs. */
+    children: AgentRunNode[];
+}
diff --git a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
new file mode 100644
index 000000000..d28f3e441
--- /dev/null
+++ b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import {
+    buildAgentRunTreeFromTurns,
+    countRuns,
+} from '../../../../src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree';
+import type { AgentRunNode } from '../../../../src/server/spa/client/react/features/chat/agent-canvas/types';
+import type { ClientConversationTurn, ClientToolCall } from '../../../../src/server/spa/client/react/types/dashboard';
+
+function tc(partial: Partial<ClientToolCall> & { id: string }): ClientToolCall {
+    return { toolName: 'Task', args: {}, status: 'completed', ...partial };
+}
+
+function assistantTurn(
+    toolCalls: ClientToolCall[],
+    timeline: ClientConversationTurn['timeline'] = [],
+): ClientConversationTurn {
+    return { role: 'assistant', content: '', timeline, toolCalls };
+}
+
+describe('buildAgentRunTreeFromTurns', () => {
+    it('returns a lone orchestrator root when there are no sub-agents', () => {
+        const root = buildAgentRunTreeFromTurns([], { title: 'Dark mode work', status: 'completed' });
+        expect(root).toMatchObject({
+            id: 'root',
+            isRoot: true,
+            role: 'orchestrator',
+            name: 'Dark mode work',
+            status: 'done',
+        });
+        expect(root.children).toEqual([]);
+        expect(countRuns(root)).toBe(1);
+    });
+
+    it('maps Task tool calls into sub-agent children with name/role/status/timing', () => {
+        const turns = [assistantTurn([
+            tc({
+                id: 't1',
+                args: { agent_type: 'Explore', description: 'map data model' },
+                status: 'running',
+                startTime: '2026-06-13T10:00:00.000Z',
+                endTime: undefined,
+            }),
+        ])];
+        const root = buildAgentRunTreeFromTurns(turns, { status: 'running' });
+        expect(root.status).toBe('running');
+        expect(root.children).toHaveLength(1);
+        expect(root.children[0]).toMatchObject({
+            id: 't1',
+            name: 'map data model',
+            role: 'Explore',
+            status: 'running',
+            startedAt: Date.parse('2026-06-13T10:00:00.000Z'),
+        });
+        expect(root.children[0].completedAt).toBeUndefined();
+    });
+
+    it('falls back to a truncated prompt when no description is present', () => {
+        const longPrompt = 'investigate the entire conversation timeline rendering pipeline end to end';
+        const turns = [assistantTurn([
+            tc({ id: 't1', args: { agent_type: 'general-purpose', prompt: longPrompt } }),
+        ])];
+        const root = buildAgentRunTreeFromTurns(turns);
+        expect(root.children[0].name).toBe('investigate the entire conversation timeline…');
+        expect(root.children[0].role).toBe('general-purpose');
+    });
+
+    it('also reads subagent_type as the role', () => {
+        const turns = [assistantTurn([
+            tc({ id: 't1', args: { subagent_type: 'rust-code-reviewer', description: 'review' } }),
+        ])];
+        expect(buildAgentRunTreeFromTurns(turns).children[0].role).toBe('rust-code-reviewer');
+    });
+
+    it('ignores non-Task tool calls', () => {
+        const turns = [assistantTurn([
+            tc({ id: 'r1', toolName: 'Read', args: { file_path: '/a.ts' } }),
+            tc({ id: 'b1', toolName: 'Bash', args: { command: 'ls' } }),
+        ])];
+        expect(buildAgentRunTreeFromTurns(turns).children).toEqual([]);
+    });
+
+    it('dedupes a tool call seen in both toolCalls and the timeline, preferring terminal state', () => {
+        const turns = [assistantTurn(
+            [tc({ id: 't1', args: { description: 'x' }, status: 'running' })],
+            [{
+                type: 'tool-complete',
+                timestamp: '2026-06-13T10:00:00.000Z',
+                toolCall: tc({ id: 't1', args: { description: 'x' }, status: 'completed', result: 'all green\nmore' }),
+            }],
+        )];
+        const root = buildAgentRunTreeFromTurns(turns);
+        expect(root.children).toHaveLength(1);
+        expect(root.children[0].status).toBe('done');
+        expect(root.children[0].summary).toBe('all green');
+    });
+
+    it('derives root status from children when no explicit status is given', () => {
+        const running = [assistantTurn([tc({ id: 't1', args: { description: 'x' }, status: 'running' })])];
+        expect(buildAgentRunTreeFromTurns(running).status).toBe('running');
+
+        const allDone = [assistantTurn([tc({ id: 't1', args: { description: 'x' }, status: 'completed' })])];
+        expect(buildAgentRunTreeFromTurns(allDone).status).toBe('done');
+    });
+
+    it('maps failed/cancelled root status to failed and queued to queued', () => {
+        expect(buildAgentRunTreeFromTurns([], { status: 'failed' }).status).toBe('failed');
+        expect(buildAgentRunTreeFromTurns([], { status: 'cancelled' }).status).toBe('failed');
+        expect(buildAgentRunTreeFromTurns([], { status: 'queued' }).status).toBe('queued');
+    });
+
+    it('orders children by start time, placing unknown start times last', () => {
+        const turns = [assistantTurn([
+            tc({ id: 'late', args: { description: 'late' }, startTime: '2026-06-13T10:05:00.000Z' }),
+            tc({ id: 'early', args: { description: 'early' }, startTime: '2026-06-13T10:01:00.000Z' }),
+            tc({ id: 'unknown', args: { description: 'unknown' } }),
+        ])];
+        const ids = buildAgentRunTreeFromTurns(turns).children.map((c) => c.id);
+        expect(ids).toEqual(['early', 'late', 'unknown']);
+    });
+});
+
+describe('countRuns', () => {
+    it('counts every run including the root', () => {
+        const tree: AgentRunNode = {
+            id: 'root', name: 'r', role: 'orchestrator', status: 'done',
+            children: [
+                { id: 'a', name: 'a', role: 'agent', status: 'done', children: [
+                    { id: 'a1', name: 'a1', role: 'agent', status: 'done', children: [] },
+                ] },
+                { id: 'b', name: 'b', role: 'agent', status: 'done', children: [] },
+            ],
+        };
+        expect(countRuns(tree)).toBe(4);
+    });
+});
diff --git a/packages/coc/test/server/spa/client/agent-canvas-layout.test.ts b/packages/coc/test/server/spa/client/agent-canvas-layout.test.ts
new file mode 100644
index 000000000..be7bf3770
--- /dev/null
+++ b/packages/coc/test/server/spa/client/agent-canvas-layout.test.ts
@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import {
+    buildLayout,
+    edgePath,
+    spineVars,
+    COLW,
+    ROWH,
+    NODEW,
+    NODEH,
+    PAD,
+} from '../../../../src/server/spa/client/react/features/chat/agent-canvas/layout';
+import type { AgentRunNode } from '../../../../src/server/spa/client/react/features/chat/agent-canvas/types';
+
+function node(id: string, children: AgentRunNode[] = []): AgentRunNode {
+    return { id, name: id, role: 'agent', status: 'done', children };
+}
+
+describe('buildLayout', () => {
+    it('lays out a lone root at the origin with padded world size', () => {
+        const layout = buildLayout(node('root'));
+        expect(layout.order).toEqual(['root']);
+        expect(layout.edges).toEqual([]);
+        expect(layout.pos.root).toMatchObject({ x: 0, y: 0, depth: 0 });
+        expect(layout.worldW).toBe(NODEW + PAD * 2);
+        expect(layout.worldH).toBe(NODEH + PAD * 2);
+    });
+
+    it('stacks leaf children one row apart and centers the parent over them', () => {
+        const root = node('root', [node('a'), node('b')]);
+        const layout = buildLayout(root);
+
+        // children sit at depth 1 (x = COLW), stacked ROWH apart
+        expect(layout.pos.a).toMatchObject({ x: COLW, y: 0, depth: 1 });
+        expect(layout.pos.b).toMatchObject({ x: COLW, y: ROWH, depth: 1 });
+        // parent is vertically centered over its children
+        expect(layout.pos.root).toMatchObject({ x: 0, y: ROWH / 2, depth: 0 });
+
+        // post-order: children before parent
+        expect(layout.order).toEqual(['a', 'b', 'root']);
+        expect(layout.edges).toEqual([
+            { from: 'root', to: 'a', depth: 1 },
+            { from: 'root', to: 'b', depth: 1 },
+        ]);
+        expect(layout.worldW).toBe(COLW + NODEW + PAD * 2);
+        expect(layout.worldH).toBe(ROWH + NODEH + PAD * 2);
+    });
+
+    it('handles arbitrary nesting depth', () => {
+        const root = node('root', [node('a', [node('a1'), node('a2')])]);
+        const layout = buildLayout(root);
+
+        expect(layout.pos.a1).toMatchObject({ x: COLW * 2, y: 0, depth: 2 });
+        expect(layout.pos.a2).toMatchObject({ x: COLW * 2, y: ROWH, depth: 2 });
+        expect(layout.pos.a).toMatchObject({ x: COLW, y: ROWH / 2, depth: 1 });
+        expect(layout.pos.root).toMatchObject({ x: 0, y: ROWH / 2, depth: 0 });
+
+        expect(layout.order).toEqual(['a1', 'a2', 'a', 'root']);
+        expect(layout.edges).toContainEqual({ from: 'a', to: 'a1', depth: 2 });
+        expect(layout.edges).toContainEqual({ from: 'a', to: 'a2', depth: 2 });
+        expect(layout.edges).toContainEqual({ from: 'root', to: 'a', depth: 1 });
+        expect(layout.worldW).toBe(COLW * 2 + NODEW + PAD * 2);
+    });
+});
+
+describe('edgePath', () => {
+    it('draws a cubic bezier from parent right-center to child left-center', () => {
+        const a = { x: 0, y: ROWH / 2, depth: 0, node: node('root') };
+        const b = { x: COLW, y: 0, depth: 1, node: node('a') };
+        // x1 = 0+202+60=262, y1 = 39+28+60=127, x2 = 250+60=310, y2 = 0+28+60=88, dx=max(40,24)=40
+        expect(edgePath(a, b)).toBe('M 262 127 C 302 127, 270 88, 310 88');
+    });
+
+    it('uses a minimum horizontal control offset of 40', () => {
+        const a = { x: 0, y: 0, depth: 0, node: node('root') };
+        const b = { x: 0, y: 0, depth: 1, node: node('a') };
+        // dx clamps to 40 even when columns overlap: x1=262, x2=60 → controls 302 and 20
+        expect(edgePath(a, b)).toBe('M 262 88 C 302 88, 20 88, 60 88');
+    });
+});
+
+describe('spineVars', () => {
+    it('returns oklch spine colors keyed off depth', () => {
+        expect(spineVars(0)).toEqual({
+            '--spine': 'oklch(0.55 0.16 252)',
+            '--spine-soft': 'oklch(0.95 0.04 252)',
+        });
+        expect(spineVars(1)['--spine']).toBe('oklch(0.55 0.16 292)');
+    });
+
+    it('cycles the hue ring (5 hues) for deep nesting', () => {
+        expect(spineVars(5)).toEqual(spineVars(0));
+        expect(spineVars(6)).toEqual(spineVars(1));
+    });
+});

From b1e8540e38950842472408f8bd95166502510983 Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 13:59:01 -0700
Subject: [PATCH 02/11] =?UTF-8?q?feat(coc):=20agents=20canvas=20=E2=80=94?=
 =?UTF-8?q?=20AgentCanvas=20component=20+=20scoped=20styles?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pannable/zoomable spatial tree view, ported from the coc-chat
design and adapted to the app:

- AgentCanvas.tsx — renders the run tree from buildLayout: curved SVG
  edges (animated for running, dashed for queued) + absolutely-placed
  HTML node cards. Each card shows a role glyph, name, role · live
  elapsed, a spawn-count pill, a status dot, and a progress bar. Pan/
  zoom is delegated to the shared useZoomPan hook; auto-fit on mount
  and on resize until the user takes over, with a re-arming Fit button.
  A live 1s clock ticks running nodes' elapsed time; an empty state
  shows when the chat spawned no sub-agents.
- icons.tsx — line-icon set (roles, spawn, zoom, view nav) ported from
  the design, plus a keyword→role glyph picker for free-form agent types.
- agent-canvas.css — design's canvas styles, namespaced under
  `.agent-canvas` with light/dark token sets (dark via `.dark`).
- index.ts — barrel for the feature.

Render tests cover node rendering, the spawn pill, empty state,
selection highlight, onSelect, the zoom toolbar, and status flags.
Not wired into the chat yet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../chat/agent-canvas/AgentCanvas.tsx         | 229 +++++++++++
 .../chat/agent-canvas/agent-canvas.css        | 361 ++++++++++++++++++
 .../features/chat/agent-canvas/icons.tsx      |  74 ++++
 .../react/features/chat/agent-canvas/index.ts |   5 +
 .../coc/test/spa/react/AgentCanvas.test.tsx   |  64 ++++
 5 files changed, 733 insertions(+)
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
 create mode 100644 packages/coc/test/spa/react/AgentCanvas.test.tsx

diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
new file mode 100644
index 000000000..8a1882cb0
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
@@ -0,0 +1,229 @@
+// AgentCanvas — a pannable / zoomable spatial map of a chat's recursive
+// sub-agent runs. The orchestrator root branches left→right into its
+// sub-agents, recursively. Driven by live run status; clicking a node calls
+// onSelect (the host scrolls the thread to the matching turn).
+//
+// Ported from the coc-chat design (agent-canvas.jsx), with pan/zoom delegated
+// to the repo's shared useZoomPan hook and the prototype's clock scrubber
+// dropped (the real app is live-streaming, not replayable).
+
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
+import { useZoomPan } from '../../../hooks/ui/useZoomPan';
+import { buildLayout, edgePath, spineVars, PAD, type PositionedNode } from './layout';
+import type { AgentRunNode } from './types';
+import { AcIcons, roleIcon } from './icons';
+import './agent-canvas.css';
+
+export interface AgentCanvasProps {
+    /** The orchestrator root whose subtree is the agent run tree. */
+    root: AgentRunNode;
+    /** Currently selected run id (highlighted), or null. */
+    selectedId?: string | null;
+    /** Called when a node is clicked. */
+    onSelect?: (node: AgentRunNode) => void;
+}
+
+function fmtDuration(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000));
+    const m = Math.floor(s / 60);
+    return `${m}:${String(s % 60).padStart(2, '0')}`;
+}
+
+function anyRunning(node: AgentRunNode): boolean {
+    if (node.status === 'running') {
+        return true;
+    }
+    return (node.children || []).some(anyRunning);
+}
+
+/** Short status/elapsed label shown under a node's name. */
+function nodeTimeText(node: AgentRunNode, now: number): string {
+    if (node.isRoot) {
+        if (node.status === 'running') {
+            return 'live';
+        }
+        return node.status === 'failed' ? 'failed' : 'done';
+    }
+    switch (node.status) {
+        case 'running':
+            return node.startedAt ? fmtDuration((now || node.startedAt) - node.startedAt) : 'running';
+        case 'done':
+            return node.startedAt && node.completedAt ? fmtDuration(node.completedAt - node.startedAt) : 'done';
+        case 'failed':
+            return 'failed';
+        case 'queued':
+            return 'queued';
+        default:
+            return '';
+    }
+}
+
+function CanvasNode({ entry, selected, onSelect, now }: {
+    entry: PositionedNode;
+    selected: boolean;
+    onSelect?: (node: AgentRunNode) => void;
+    now: number;
+}) {
+    const { node, depth } = entry;
+    const isRoot = !!node.isRoot;
+    const status = node.status;
+    const RoleIcon = isRoot ? AcIcons.Orchestr : roleIcon(node.role);
+    const kids = node.children || [];
+    const pct = status === 'queued' ? 0 : 100;
+    const styleVars = spineVars(depth) as CSSProperties;
+
+    return (
+        <button
+            type="button"
+            className={'cnode' + (selected ? ' sel' : '') + (isRoot ? ' root' : '')}
+            data-status={status}
+            data-testid={`agent-canvas-node-${node.id}`}
+            style={{ left: entry.x + PAD, top: entry.y + PAD, ...styleVars }}
+            onClick={(e) => { e.stopPropagation(); onSelect?.(node); }}
+        >
+            <span className="cn-badge"><RoleIcon size={15} /></span>
+            <span className="cn-body">
+                <span className="cn-name">{node.name}</span>
+                <span className="cn-sub">
+                    <span className="cn-role">{isRoot ? 'orchestrator' : node.role}</span>
+                    <span className="cn-dot">·</span>
+                    <span className="cn-t">{nodeTimeText(node, now)}</span>
+                </span>
+            </span>
+            {kids.length > 0 && (
+                <span className="cn-spawn" title={`${kids.length} spawned`}>
+                    <AcIcons.Spawn size={11} />{kids.length}
+                </span>
+            )}
+            <span className="cn-state" data-status={status} />
+            <span className="cn-bar"><i style={{ width: `${pct}%` }} /></span>
+        </button>
+    );
+}
+
+export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
+    const layout = useMemo(() => buildLayout(root), [root]);
+
+    const { containerRef, state, zoomIn, zoomOut, fitToView, zoomLabel } = useZoomPan({
+        contentWidth: layout.worldW,
+        contentHeight: layout.worldH,
+        minZoom: 0.25,
+        maxZoom: 2.2,
+    });
+
+    // Auto-fit on mount and whenever the tree resizes — until the user takes
+    // over the view (wheel/drag/zoom). The Fit button re-arms auto-fit.
+    const interactedRef = useRef(false);
+
+    useLayoutEffect(() => {
+        if (!interactedRef.current) {
+            fitToView();
+        }
+    }, [layout.worldW, layout.worldH, fitToView]);
+
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el) {
+            return;
+        }
+        const markInteracted = () => { interactedRef.current = true; };
+        el.addEventListener('wheel', markInteracted, { passive: true });
+        el.addEventListener('pointerdown', markInteracted);
+        const ro = new ResizeObserver(() => {
+            if (!interactedRef.current) {
+                fitToView();
+            }
+        });
+        ro.observe(el);
+        return () => {
+            el.removeEventListener('wheel', markInteracted);
+            el.removeEventListener('pointerdown', markInteracted);
+            ro.disconnect();
+        };
+    }, [containerRef, fitToView]);
+
+    // Live clock so running nodes' elapsed time ticks; idle when nothing runs.
+    const hasRunning = useMemo(() => anyRunning(root), [root]);
+    const [now, setNow] = useState(0);
+    useEffect(() => {
+        if (!hasRunning) {
+            return;
+        }
+        setNow(Date.now());
+        const id = window.setInterval(() => setNow(Date.now()), 1000);
+        return () => window.clearInterval(id);
+    }, [hasRunning]);
+
+    const worldTransform = `translate(${state.translateX}px, ${state.translateY}px) scale(${state.scale})`;
+
+    return (
+        <div
+            className="agent-canvas"
+            ref={containerRef}
+            data-testid="agent-canvas"
+            style={{ cursor: state.isDragging ? 'grabbing' : 'grab' }}
+        >
+            <div className="world" style={{ transform: worldTransform }}>
+                <svg className="canvas-edges" width={layout.worldW} height={layout.worldH}>
+                    {layout.edges.map((e) => {
+                        const a = layout.pos[e.from];
+                        const b = layout.pos[e.to];
+                        const childStatus = b.node.status;
+                        const active = childStatus === 'running';
+                        const queued = childStatus === 'queued';
+                        const spine = spineVars(e.depth)['--spine'];
+                        return (
+                            <path
+                                key={e.to}
+                                d={edgePath(a, b)}
+                                fill="none"
+                                stroke={queued ? 'var(--border-strong)' : spine}
+                                strokeWidth={2}
+                                strokeOpacity={queued ? 0.5 : 0.85}
+                                strokeDasharray={active ? '6 5' : queued ? '3 4' : undefined}
+                                className={active ? 'edge-active' : undefined}
+                            />
+                        );
+                    })}
+                </svg>
+                {layout.order.map((id) => (
+                    <CanvasNode
+                        key={id}
+                        entry={layout.pos[id]}
+                        now={now}
+                        selected={selectedId === id}
+                        onSelect={onSelect}
+                    />
+                ))}
+            </div>
+
+            {root.children.length === 0 && (
+                <div className="canvas-empty">
+                    <span className="ce-title">No sub-agent runs</span>
+                    <span>Agents this chat spawns will appear here as a tree.</span>
+                </div>
+            )}
+
+            <div className="canvas-toolbar" data-no-drag>
+                <button type="button" onClick={zoomOut} title="Zoom out"><AcIcons.Collapse size={14} /></button>
+                <span className="cz">{zoomLabel}</span>
+                <button type="button" onClick={zoomIn} title="Zoom in"><AcIcons.Expand size={14} /></button>
+                <span className="cz-sep" />
+                <button
+                    type="button"
+                    onClick={() => { interactedRef.current = false; fitToView(); }}
+                    title="Fit to screen"
+                >
+                    <AcIcons.Replay size={14} />Fit
+                </button>
+            </div>
+
+            <div className="canvas-legend" data-no-drag>
+                <span className="cl-item"><span className="cl-dot" data-status="running" />running</span>
+                <span className="cl-item"><span className="cl-dot" data-status="done" />done</span>
+                <span className="cl-item"><span className="cl-dot" data-status="queued" />queued</span>
+                <span className="cl-hint">drag to pan · scroll to zoom</span>
+            </div>
+        </div>
+    );
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
new file mode 100644
index 000000000..b4ae5318b
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
@@ -0,0 +1,361 @@
+/* =========================================================
+   Agents canvas — spatial tree map of a chat's sub-agent runs.
+   Ported from the coc-chat design (coc-chat-styles.css). Every rule is
+   namespaced under `.agent-canvas`, and the design's theme tokens are
+   scoped there too (light by default, dark under `.dark`), so nothing
+   leaks into the surrounding app.
+   ========================================================= */
+
+.agent-canvas {
+    /* theme tokens (light) */
+    --bg: #f6f6f6;
+    --bg-2: #efefef;
+    --panel: #ffffff;
+    --text: #1f1f1f;
+    --muted: #6b6b6b;
+    --faint: #8c8c8c;
+    --border: #e2e2e2;
+    --border-strong: #c6c6c6;
+    --hover: #f0f0f0;
+    --accent: oklch(0.55 0.18 252);
+    --success: oklch(0.60 0.13 155);
+    --danger: oklch(0.58 0.19 24);
+    --radius: 10px;
+    --font-mono: "Geist Mono", "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+    /* spine defaults; per-node values come from inline style (spineVars). */
+    --spine: var(--accent);
+    --spine-soft: oklch(0.96 0.04 252);
+
+    position: relative;
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+    cursor: grab;
+    background-color: var(--bg);
+    background-image: radial-gradient(circle, color-mix(in oklab, var(--border-strong) 60%, transparent) 1px, transparent 1.4px);
+    background-size: 22px 22px;
+    user-select: none;
+}
+
+.dark .agent-canvas {
+    --bg: #1e1e1e;
+    --bg-2: #2a2a2b;
+    --panel: #252526;
+    --text: #cccccc;
+    --muted: #9d9d9d;
+    --faint: #6e6e6e;
+    --border: #3a3a3c;
+    --border-strong: #565659;
+    --hover: #2a2d2e;
+    --accent: oklch(0.68 0.16 252);
+    --success: oklch(0.72 0.16 152);
+    --danger: oklch(0.68 0.19 22);
+    --spine-soft: oklch(0.32 0.07 252);
+}
+
+.agent-canvas .world {
+    position: absolute;
+    top: 0;
+    left: 0;
+    transform-origin: 0 0;
+    will-change: transform;
+}
+
+.agent-canvas .canvas-edges {
+    position: absolute;
+    top: 0;
+    left: 0;
+    overflow: visible;
+    pointer-events: none;
+}
+
+.agent-canvas .edge-active {
+    animation: ac-edgeflow 0.7s linear infinite;
+}
+
+@keyframes ac-edgeflow {
+    to { stroke-dashoffset: -11; }
+}
+
+.agent-canvas .cnode {
+    position: absolute;
+    width: 202px;
+    height: 56px;
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    padding: 0 11px;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    background: var(--panel);
+    box-shadow: 0 1px 2px rgb(20 30 60 / 0.06);
+    cursor: pointer;
+    text-align: left;
+    color: var(--text);
+    transition: box-shadow 0.14s, border-color 0.14s, transform 0.14s;
+    animation: ac-nodeIn 0.42s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+@keyframes ac-nodeIn {
+    from { transform: scale(0.9); }
+    to { transform: none; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .agent-canvas .cnode { animation: none; }
+}
+
+.agent-canvas .cnode:hover {
+    border-color: var(--border-strong);
+    box-shadow: 0 3px 10px rgb(20 30 60 / 0.12);
+    transform: translateY(-1px);
+}
+
+.agent-canvas .cnode.sel {
+    border-color: var(--spine);
+    box-shadow: 0 0 0 3px var(--spine-soft), 0 3px 10px rgb(20 30 60 / 0.12);
+}
+
+.agent-canvas .cnode.root {
+    background: linear-gradient(180deg, var(--panel), var(--bg-2));
+    border-color: var(--border-strong);
+}
+
+.agent-canvas .cnode[data-status="running"] {
+    border-color: color-mix(in oklab, var(--spine) 45%, var(--border));
+}
+
+.agent-canvas .cnode[data-status="queued"] {
+    border-style: dashed;
+    opacity: 0.72;
+}
+
+.agent-canvas .cn-badge {
+    width: 28px;
+    height: 28px;
+    border-radius: 7px;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--spine-soft);
+    color: var(--spine);
+}
+
+.agent-canvas .cn-body {
+    min-width: 0;
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+
+.agent-canvas .cn-name {
+    font-size: 12.5px;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.agent-canvas .cn-sub {
+    font-size: 10px;
+    font-family: var(--font-mono);
+    color: var(--faint);
+    display: flex;
+    align-items: center;
+    gap: 4px;
+}
+
+.agent-canvas .cn-sub .cn-role {
+    color: var(--spine);
+    font-weight: 500;
+}
+
+.agent-canvas .cn-spawn {
+    position: absolute;
+    top: -8px;
+    right: 10px;
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    font-size: 9.5px;
+    font-family: var(--font-mono);
+    color: var(--muted);
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 999px;
+    padding: 1px 6px;
+}
+
+.agent-canvas .cn-spawn svg {
+    width: 10px;
+    height: 10px;
+    opacity: 0.8;
+}
+
+.agent-canvas .cn-state {
+    position: absolute;
+    top: 9px;
+    right: 10px;
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    flex-shrink: 0;
+}
+
+.agent-canvas .cn-state[data-status="running"] {
+    background: var(--spine);
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--spine) 22%, transparent);
+    animation: ac-nodepulse 1.6s infinite;
+}
+
+.agent-canvas .cn-state[data-status="done"] { background: var(--success); }
+.agent-canvas .cn-state[data-status="failed"] { background: var(--danger); }
+.agent-canvas .cn-state[data-status="queued"] { background: var(--faint); }
+
+@keyframes ac-nodepulse {
+    0%, 100% { box-shadow: 0 0 0 3px color-mix(in oklab, var(--spine) 22%, transparent); }
+    50% { box-shadow: 0 0 0 6px color-mix(in oklab, var(--spine) 6%, transparent); }
+}
+
+.agent-canvas .cn-bar {
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    height: 3px;
+    border-radius: 0 0 var(--radius) var(--radius);
+    background: var(--hover);
+    overflow: hidden;
+}
+
+.agent-canvas .cn-bar > i {
+    display: block;
+    height: 100%;
+    background: var(--spine);
+    transition: width 0.4s ease;
+}
+
+.agent-canvas .cnode[data-status="running"] .cn-bar > i {
+    animation: ac-barpulse 1.6s ease-in-out infinite;
+}
+
+.agent-canvas .cnode[data-status="done"] .cn-bar > i { background: var(--success); }
+
+@keyframes ac-barpulse {
+    0%, 100% { opacity: 0.65; }
+    50% { opacity: 1; }
+}
+
+.agent-canvas .canvas-toolbar {
+    position: absolute;
+    left: 16px;
+    bottom: 16px;
+    display: flex;
+    align-items: center;
+    gap: 2px;
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 9px;
+    padding: 4px;
+    box-shadow: 0 2px 8px rgb(20 30 60 / 0.10);
+}
+
+.agent-canvas .canvas-toolbar button {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    height: 28px;
+    padding: 0 9px;
+    border: none;
+    background: transparent;
+    color: var(--muted);
+    border-radius: 6px;
+    cursor: pointer;
+    font-size: 12px;
+    font-weight: 500;
+}
+
+.agent-canvas .canvas-toolbar button:hover {
+    background: var(--hover);
+    color: var(--text);
+}
+
+.agent-canvas .canvas-toolbar .cz {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--muted);
+    width: 40px;
+    text-align: center;
+}
+
+.agent-canvas .canvas-toolbar .cz-sep {
+    width: 1px;
+    height: 18px;
+    background: var(--border);
+    margin: 0 3px;
+}
+
+.agent-canvas .canvas-legend {
+    position: absolute;
+    right: 16px;
+    top: 16px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    background: color-mix(in oklab, var(--panel) 88%, transparent);
+    backdrop-filter: blur(8px);
+    border: 1px solid var(--border);
+    border-radius: 9px;
+    padding: 7px 12px;
+    font-size: 11px;
+    color: var(--muted);
+}
+
+.agent-canvas .canvas-legend .cl-item {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+}
+
+.agent-canvas .canvas-legend .cl-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 999px;
+}
+
+.agent-canvas .canvas-legend .cl-dot[data-status="running"] { background: var(--accent); }
+.agent-canvas .canvas-legend .cl-dot[data-status="done"] { background: var(--success); }
+.agent-canvas .canvas-legend .cl-dot[data-status="queued"] {
+    background: var(--faint);
+    border: 1px dashed var(--border-strong);
+}
+
+.agent-canvas .canvas-legend .cl-hint {
+    color: var(--faint);
+    font-family: var(--font-mono);
+    font-size: 10px;
+    border-left: 1px solid var(--border);
+    padding-left: 12px;
+}
+
+/* Empty state — no sub-agents in this conversation. */
+.agent-canvas .canvas-empty {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    color: var(--faint);
+    font-size: 13px;
+    pointer-events: none;
+}
+
+.agent-canvas .canvas-empty .ce-title {
+    color: var(--muted);
+    font-weight: 600;
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
new file mode 100644
index 000000000..4379b16e4
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
@@ -0,0 +1,74 @@
+// Line-icon set for the Agents canvas — agent roles, spawn, and view nav.
+// Ported from the coc-chat design (chat-icons.jsx) so glyphs match the mock.
+
+import type { ReactNode, SVGProps } from 'react';
+
+export interface AcIconProps extends Omit<SVGProps<SVGSVGElement>, 'stroke'> {
+    size?: number;
+    /** Stroke width (the icons are stroked, not filled). */
+    stroke?: number;
+}
+
+function mk(paths: ReactNode, viewBox = '0 0 16 16') {
+    return function Icon({ size = 16, stroke = 1.5, ...rest }: AcIconProps) {
+        return (
+            <svg
+                width={size}
+                height={size}
+                viewBox={viewBox}
+                fill="none"
+                stroke="currentColor"
+                strokeWidth={stroke}
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                {...rest}
+            >
+                {paths}
+            </svg>
+        );
+    };
+}
+
+export const AcIcons = {
+    // ── roles ──
+    Orchestr: mk(<><circle cx="8" cy="8" r="2" /><circle cx="8" cy="2.6" r="1.3" /><circle cx="3" cy="11.5" r="1.3" /><circle cx="13" cy="11.5" r="1.3" /><path d="M8 6V4M6.6 9.1l-2.3 1.5M9.4 9.1l2.3 1.5" /></>),
+    Explorer: mk(<><circle cx="7" cy="7" r="4.2" /><path d="M10.2 10.2L14 14" /></>),
+    Refactor: mk(<><path d="M3 6V4.5A1.5 1.5 0 014.5 3H6M3 10v1.5A1.5 1.5 0 004.5 13H6M13 6V4.5A1.5 1.5 0 0011.5 3H10M13 10v1.5a1.5 1.5 0 01-1.5 1.5H10" /><path d="M6 8h4" /></>),
+    Tester: mk(<><path d="M6 2h4M6.5 2v4L4 11.5a1.2 1.2 0 001.1 1.7h5.8A1.2 1.2 0 0012 11.5L9.5 6V2" /><path d="M5.4 9h5.2" /></>),
+    Reviewer: mk(<><path d="M1.5 8S4 3.5 8 3.5 14.5 8 14.5 8 12 12.5 8 12.5 1.5 8 1.5 8z" /><circle cx="8" cy="8" r="1.8" /></>),
+    Planner: mk(<><rect x="2.5" y="2.5" width="11" height="11" rx="2" /><path d="M5 6l1.2 1.2L8 5.5M5 10l1.2 1.2L8 9.5M10 6.2h1.5M10 10.2h1.5" /></>),
+    Doc: mk(<><path d="M4 2.5h5l3 3v8a1 1 0 01-1 1H4a1 1 0 01-1-1V3.5a1 1 0 011-1z" /><path d="M9 2.5V6h3.5" /></>),
+    Agent: mk(<><circle cx="8" cy="5.5" r="2.5" /><path d="M3.5 13a4.5 4.5 0 019 0" /></>),
+
+    // ── canvas controls / nav ──
+    Spawn: mk(<><circle cx="4" cy="4" r="1.5" /><circle cx="4" cy="12" r="1.5" /><circle cx="12" cy="12" r="1.5" /><path d="M4 5.5v3a2 2 0 002 2h4.2M4 9.4h.01" /><path d="M10 10.5l2 1.5" /></>),
+    Expand: mk(<><path d="M9.5 2.5H13.5V6.5M6.5 13.5H2.5V9.5M13.5 2.5l-4.5 4.5M2.5 13.5l4.5-4.5" /></>),
+    Collapse: mk(<><path d="M13 3l-3.5 3.5M9.5 6.5V3M9.5 6.5H13M3 13l3.5-3.5M6.5 9.5V13M6.5 9.5H3" /></>),
+    Replay: mk(<><path d="M3 8a5 5 0 105-5 5 5 0 00-3.6 1.5L3 5" /><path d="M3 2.5V5h2.5" /></>),
+    Thread: mk(<><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h7" /></>),
+    Tree: mk(<><rect x="2" y="6" width="4" height="4" rx="1" /><rect x="10.5" y="2.5" width="3.5" height="3.5" rx="1" /><rect x="10.5" y="10" width="3.5" height="3.5" rx="1" /><path d="M6 8h2.2M8.2 8V4.2h2.3M8.2 8v3.8h2.3" /></>),
+};
+
+// Keyword → role glyph, matched in order. Real sub-agent types are free-form
+// strings (e.g. 'Explore', 'general-purpose', 'rust-code-reviewer'), so we map
+// by substring rather than an exact enum.
+const ROLE_ICON_RULES: Array<[string[], (p: AcIconProps) => ReactNode]> = [
+    [['orchestr'], AcIcons.Orchestr],
+    [['explor', 'research', 'search'], AcIcons.Explorer],
+    [['review'], AcIcons.Reviewer],
+    [['test'], AcIcons.Tester],
+    [['plan'], AcIcons.Planner],
+    [['refactor', 'fix', 'impl', 'edit', 'code'], AcIcons.Refactor],
+    [['doc', 'write'], AcIcons.Doc],
+];
+
+/** Pick a role glyph by keyword, falling back to a generic agent icon. */
+export function roleIcon(role: string | undefined): (p: AcIconProps) => ReactNode {
+    const r = (role || '').toLowerCase();
+    for (const [keywords, icon] of ROLE_ICON_RULES) {
+        if (keywords.some((k) => r.includes(k))) {
+            return icon;
+        }
+    }
+    return AcIcons.Agent;
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
new file mode 100644
index 000000000..4b937f158
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
@@ -0,0 +1,5 @@
+export { AgentCanvas } from './AgentCanvas';
+export type { AgentCanvasProps } from './AgentCanvas';
+export { buildAgentRunTreeFromTurns, countRuns } from './buildAgentRunTree';
+export type { AgentRunRootMeta } from './buildAgentRunTree';
+export type { AgentRunNode, AgentRunStatus } from './types';
diff --git a/packages/coc/test/spa/react/AgentCanvas.test.tsx b/packages/coc/test/spa/react/AgentCanvas.test.tsx
new file mode 100644
index 000000000..82f858a4f
--- /dev/null
+++ b/packages/coc/test/spa/react/AgentCanvas.test.tsx
@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { AgentCanvas } from '../../../src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas';
+import type { AgentRunNode } from '../../../src/server/spa/client/react/features/chat/agent-canvas/types';
+
+function tree(children: AgentRunNode[] = []): AgentRunNode {
+    return { id: 'root', name: 'CoC · orchestrator', role: 'orchestrator', status: 'running', isRoot: true, children };
+}
+
+function sub(id: string, overrides: Partial<AgentRunNode> = {}): AgentRunNode {
+    return { id, name: id, role: 'Explore', status: 'done', children: [], ...overrides };
+}
+
+describe('AgentCanvas', () => {
+    it('renders the orchestrator root and every sub-agent node', () => {
+        render(<AgentCanvas root={tree([sub('explore'), sub('review', { role: 'reviewer' })])} />);
+        expect(screen.getByTestId('agent-canvas')).toBeTruthy();
+        expect(screen.getByTestId('agent-canvas-node-root')).toBeTruthy();
+        expect(screen.getByTestId('agent-canvas-node-explore')).toBeTruthy();
+        expect(screen.getByTestId('agent-canvas-node-review')).toBeTruthy();
+        expect(screen.getByText('CoC · orchestrator')).toBeTruthy();
+        expect(screen.getByText('explore')).toBeTruthy();
+    });
+
+    it('shows a spawn-count pill on the root reflecting its children', () => {
+        render(<AgentCanvas root={tree([sub('a'), sub('b'), sub('c')])} />);
+        const rootNode = screen.getByTestId('agent-canvas-node-root');
+        expect(rootNode.querySelector('.cn-spawn')?.textContent).toContain('3');
+    });
+
+    it('renders the empty-state hint when there are no sub-agents', () => {
+        render(<AgentCanvas root={tree([])} />);
+        expect(screen.getByText('No sub-agent runs')).toBeTruthy();
+        // the root node still renders
+        expect(screen.getByTestId('agent-canvas-node-root')).toBeTruthy();
+    });
+
+    it('calls onSelect with the clicked node', () => {
+        const onSelect = vi.fn();
+        render(<AgentCanvas root={tree([sub('explore')])} onSelect={onSelect} />);
+        fireEvent.click(screen.getByTestId('agent-canvas-node-explore'));
+        expect(onSelect).toHaveBeenCalledTimes(1);
+        expect(onSelect.mock.calls[0][0]).toMatchObject({ id: 'explore' });
+    });
+
+    it('marks the selected node with the sel class', () => {
+        render(<AgentCanvas root={tree([sub('explore')])} selectedId="explore" />);
+        expect(screen.getByTestId('agent-canvas-node-explore').className).toContain('sel');
+        expect(screen.getByTestId('agent-canvas-node-root').className).not.toContain('sel');
+    });
+
+    it('renders the zoom toolbar with a percentage label', () => {
+        render(<AgentCanvas root={tree([sub('explore')])} />);
+        const canvas = screen.getByTestId('agent-canvas');
+        expect(canvas.querySelector('.canvas-toolbar')).toBeTruthy();
+        expect(canvas.querySelector('.cz')?.textContent).toMatch(/%$/);
+    });
+
+    it('flags running children edges/nodes via data-status', () => {
+        render(<AgentCanvas root={tree([sub('busy', { status: 'running' })])} />);
+        expect(screen.getByTestId('agent-canvas-node-busy').getAttribute('data-status')).toBe('running');
+    });
+});

From 8a60d64a1cbce7ac20d8cb06498cd27aeb88c070 Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:11:08 -0700
Subject: [PATCH 03/11] feat(coc): wire Thread/Agents view toggle into the chat
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a Thread | Agents segmented toggle to the chat top bar and renders
the sub-agent canvas as a second view, leaving the thread untouched.

- ChatViewToggle — segmented control (Thread / Agents) styled with the
  app's light/dark tokens; exposed through a new optional `viewToggle`
  slot on ChatHeader.
- ChatDetail — owns `view` state (resets to thread on chat switch).
  Builds the agent tree from the loaded turns via
  buildAgentRunTreeFromTurns and, in Agents mode, swaps the
  ConversationArea inner row for <AgentCanvas>, keeping the composer/
  scratchpad and hiding thread-only flow cards (Ralph start, Implement
  plan). The toggle is hidden in the floating variant and while
  loading/pending.
- Node click → findTurnIndexForRun maps the run back to its issuing
  turn, switches to the thread, and scrolls to it.

Tests: findTurnIndexForRun (toolCalls/timeline/turnIndex/missing) and
ChatViewToggle (render, aria-pressed, onChange). build:client passes;
no new tsc/lint errors. Knowledge doc (dashboard-spa.md) updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../coc-knowledge/references/dashboard-spa.md | 26 +++++++++
 .../client/react/features/chat/ChatDetail.tsx | 58 +++++++++++++++++--
 .../client/react/features/chat/ChatHeader.tsx |  7 ++-
 .../chat/agent-canvas/ChatViewToggle.tsx      | 55 ++++++++++++++++++
 .../chat/agent-canvas/buildAgentRunTree.ts    | 23 ++++++++
 .../react/features/chat/agent-canvas/index.ts |  4 +-
 .../spa/client/agent-canvas-data.test.ts      | 33 +++++++++++
 .../test/spa/react/ChatViewToggle.test.tsx    | 25 ++++++++
 8 files changed, 224 insertions(+), 7 deletions(-)
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/ChatViewToggle.tsx
 create mode 100644 packages/coc/test/spa/react/ChatViewToggle.test.tsx

diff --git a/.github/skills/coc-knowledge/references/dashboard-spa.md b/.github/skills/coc-knowledge/references/dashboard-spa.md
index f209b99c8..cad815075 100644
--- a/.github/skills/coc-knowledge/references/dashboard-spa.md
+++ b/.github/skills/coc-knowledge/references/dashboard-spa.md
@@ -296,6 +296,32 @@ server/Forge layer); cells without a displayable USD value show explicit
 `USD pricing unavailable` copy instead of silently leaving cost blank. The UI
 does not render Copilot premium request units.
 
+### Agents view (sub-agent canvas)
+
+`ChatHeader` exposes a `Thread | Agents` segmented toggle (`ChatViewToggle`,
+under `features/chat/agent-canvas/`) via its `viewToggle` slot. `ChatDetail`
+owns the `view` state and, in `agents` mode, swaps the `ConversationArea` inner
+row for `AgentCanvas` — a pannable/zoomable spatial tree of the chat's
+recursive sub-agent runs — while keeping the composer/scratchpad and hiding the
+thread-only flow cards (Ralph start, Implement-plan). The toggle is hidden in
+the `floating` variant and while loading/pending; `view` resets to `thread` on
+chat switch.
+
+`buildAgentRunTreeFromTurns(turns, root)` derives the tree with no extra fetch:
+the orchestrator (this process) is the root and each `Task` tool call becomes a
+sub-agent child (name/role from args, status/timing from the call), deduped
+across `toolCalls`+timeline and ordered by start time. The `AgentRunNode` tree
+supports arbitrary depth, so deeper recursion can be layered on later.
+`AgentCanvas` reuses the shared `useZoomPan` hook (auto-fit until the user takes
+over; a Fit button re-arms it), renders curved SVG edges + node cards (role
+glyph, name, live elapsed, spawn-count pill, status dot, progress bar), and a
+live 1s clock for running nodes. Clicking a node calls `onSelect`; `ChatDetail`
+maps it back to the issuing turn via `findTurnIndexForRun`, switches to the
+thread, and scrolls there. Styles live in scoped `agent-canvas.css`
+(`.agent-canvas`, light/dark via `.dark`); there is no clock scrubber (the
+prototype's replay control is dropped — the real view is live). Distinct from
+the co-edited `CanvasPanel` side panel.
+
 ## Tool Call Rendering
 
 Inside `WhisperCollapsedGroup`, tool calls render as compact "whisper-row" variant:
diff --git a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
index 5c02e4139..f762f55db 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
@@ -44,6 +44,8 @@ import { buildEffortOptionsForModel } from './EffortPillSelector';
 import type { EffortLevel } from './EffortPillSelector';
 import type { RichTextInputHandle } from '../../shared/RichTextInput';
 import { ConversationMiniMap } from './conversation/ConversationMiniMap';
+import { AgentCanvas, ChatViewToggle, buildAgentRunTreeFromTurns, findTurnIndexForRun } from './agent-canvas';
+import type { AgentRunNode, ChatView } from './agent-canvas';
 import { useConversationSelection } from './hooks/useConversationSelection';
 import { snapshotConversation } from '../../utils/snapshot-copy-utils';
 import { copyHtmlToClipboard } from '../../utils/format';
@@ -179,6 +181,10 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
     const [activeCanvasId, setActiveCanvasId] = useState<string | null>(null);
     const [canvasLiveEvent, setCanvasLiveEvent] = useState<CanvasUpdatedEvent | null>(null);
     const [canvasPanelClosed, setCanvasPanelClosed] = useState(false);
+    // Thread vs. Agents (spatial sub-agent run tree) view.
+    const [view, setView] = useState<ChatView>('thread');
+    const [selectedAgentId, setSelectedAgentId] = useState<string | null>(null);
+    const [pendingScrollTurn, setPendingScrollTurn] = useState<number | null>(null);
     const [noteEdits, setNoteEdits] = useState<Array<{
         editId: string; notePath: string; preEditContent: string;
         postEditContent?: string; timestamp: string; turnIndex: number; tooLarge?: boolean;
@@ -303,6 +309,36 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
 
     const createdFiles = useMemo(() => scanTurnsForCreatedFiles(turns), [turns]);
 
+    // ── Agents view: spatial tree of this chat's recursive sub-agent runs ──
+    const agentRoot = useMemo<AgentRunNode>(() => buildAgentRunTreeFromTurns(turns, {
+        id: 'root',
+        title: (task?.customTitle as string | undefined) || title || task?.title || task?.displayName,
+        status: effectiveStatus,
+    }), [turns, task?.customTitle, task?.title, task?.displayName, title, effectiveStatus]);
+
+    // Clicking a canvas node jumps to the matching turn in the thread.
+    const handleAgentSelect = useCallback((node: AgentRunNode) => {
+        setSelectedAgentId(node.id);
+        const idx = node.isRoot
+            ? (turnsRef.current[0]?.turnIndex ?? 0)
+            : findTurnIndexForRun(turnsRef.current, node.id);
+        if (idx != null) {
+            setView('thread');
+            setPendingScrollTurn(idx);
+        }
+    }, []);
+
+    // After switching to the thread, scroll to the turn a canvas node pointed at.
+    useEffect(() => {
+        if (pendingScrollTurn == null || view !== 'thread') return;
+        const container = conversationContainerRef.current;
+        const target = container?.querySelector<HTMLElement>(`[data-turn-index="${pendingScrollTurn}"]`);
+        if (target) {
+            target.scrollIntoView({ block: 'start', behavior: 'smooth' });
+            setPendingScrollTurn(null);
+        }
+    }, [pendingScrollTurn, view, turns]);
+
     // Compute the follow-up mode pill set, optionally appending Ralph when
     // the chat is eligible for in-place promotion. Eligibility:
     //   - completed (no in-flight turn or queued follow-ups)
@@ -427,6 +463,9 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
         modelOverrideMountedRef.current = false;
         setEffortOverride(null);
         setInvalidScratchpadPaths(new Set());
+        setView('thread');
+        setSelectedAgentId(null);
+        setPendingScrollTurn(null);
     }, [taskId]);
 
     // ── Resolve existing implementation runs from task metadata ─────────
@@ -1609,6 +1648,9 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
                 onRenameTitle={processId ? () => setRenameOpen(true) : undefined}
                 onStartFreshSameContext={onStartFreshSameContext}
                 startingFreshSameContext={startingFreshSameContext}
+                viewToggle={!loading && !isPending && variant !== 'floating'
+                    ? <ChatViewToggle view={view} onChange={setView} />
+                    : undefined}
             />
             {loopPanelOpen && isLoopsEnabled() && (
                 <div className="relative">
@@ -1635,8 +1677,12 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
                         : { flex: '1 1 auto', minHeight: 0 }
                     }
                 >
-                    {/* Inner row: ConversationArea + MiniMap side by side */}
+                    {/* Inner row: ConversationArea + MiniMap, or the Agents canvas */}
                     <div className="relative flex flex-1 min-h-0 overflow-hidden min-w-0">
+                    {view === 'agents' ? (
+                    <AgentCanvas root={agentRoot} selectedId={selectedAgentId} onSelect={handleAgentSelect} />
+                    ) : (
+                    <>
                     <ConversationArea
                         loading={loading}
                         error={error}
@@ -1689,9 +1735,11 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
                             isStreaming={task?.status === 'running'}
                         />
                     )}
+                    </>
+                    )}
                     </div>
-                    {/* Ralph grilling complete — show Start Ralph panel */}
-                    {(() => {
+                    {/* Ralph grilling complete — show Start Ralph panel (thread view only) */}
+                    {view === 'thread' && (() => {
                         const ralphCtx = getRalphContext(task);
                         const goalPath = detectedGoalFile || (task?.metadata?.goalFilePath as string | undefined) || '';
                         // Path 1: traditional grilling-phase → start
@@ -1733,8 +1781,8 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
                         }
                         return null;
                     })()}
-                    {/* Plan file complete — offer one-click handoff to autopilot */}
-                    {isTerminal && !planChatBusy && resolveLoadedTaskMode(task) === 'ask' && effectivePlanPath && (
+                    {/* Plan file complete — offer one-click handoff to autopilot (thread view only) */}
+                    {view === 'thread' && isTerminal && !planChatBusy && resolveLoadedTaskMode(task) === 'ask' && effectivePlanPath && (
                         <ImplementPlanCard
                             planFilePath={effectivePlanPath}
                             workspaceId={workspaceId}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/ChatHeader.tsx b/packages/coc/src/server/spa/client/react/features/chat/ChatHeader.tsx
index b96eb55b6..2ce4d4356 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/ChatHeader.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/ChatHeader.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { ReferencesDropdown, ReferenceList, deduplicateReferenceFiles } from '../../ui/ReferencesDropdown';
 import { BottomSheet } from '../../ui/BottomSheet';
 import { ConversationMetadataPopover } from './conversation/ConversationMetadataPopover';
@@ -103,6 +103,8 @@ export interface ChatHeaderProps {
     onStartFreshSameContext?: () => Promise<boolean> | boolean | void;
     /** True while the lens chat fresh-context operation is in progress. */
     startingFreshSameContext?: boolean;
+    /** Optional control rendered at the start of the right-side action area (e.g. the Thread/Agents view toggle). */
+    viewToggle?: ReactNode;
 }
 
 /** Build overflow menu items based on what's hidden at the current container tier */
@@ -346,6 +348,7 @@ export function ChatHeader({
     onRenameTitle,
     onStartFreshSameContext,
     startingFreshSameContext = false,
+    viewToggle,
 }: ChatHeaderProps) {
     const { isMobile } = useBreakpoint();
     const { isFloating } = useFloatingChats();
@@ -494,6 +497,8 @@ export function ChatHeader({
 
             {/* Right side */}
             <div className="flex items-center flex-shrink-0">
+                {/* View toggle (Thread / Agents), when provided by the host. */}
+                {viewToggle}
                 {/*
                   Vertical divider visually separates the identity/status area
                   from the action group, matching the redesign mockup's
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/ChatViewToggle.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/ChatViewToggle.tsx
new file mode 100644
index 000000000..a678975bb
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/ChatViewToggle.tsx
@@ -0,0 +1,55 @@
+// Segmented Thread / Agents toggle for the chat top bar. Switches between the
+// linear transcript and the spatial agent-run canvas. Ported from the
+// coc-chat design's `.view-seg`, styled with the app's light/dark tokens.
+
+import { cn } from '../../../ui/cn';
+import { AcIcons } from './icons';
+
+export type ChatView = 'thread' | 'agents';
+
+interface ChatViewToggleProps {
+    view: ChatView;
+    onChange: (view: ChatView) => void;
+}
+
+function SegButton({ active, onClick, testid, children }: {
+    active: boolean;
+    onClick: () => void;
+    testid: string;
+    children: React.ReactNode;
+}) {
+    return (
+        <button
+            type="button"
+            data-testid={testid}
+            aria-pressed={active}
+            onClick={onClick}
+            className={cn(
+                'inline-flex items-center gap-1.5 px-2.5 py-1 rounded text-xs font-medium transition-colors',
+                active
+                    ? 'bg-white dark:bg-[#1e1e1e] text-[#1e1e1e] dark:text-[#cccccc] shadow-sm'
+                    : 'text-[#6b6b6b] dark:text-[#9d9d9d] hover:text-[#1e1e1e] dark:hover:text-[#cccccc]',
+            )}
+        >
+            {children}
+        </button>
+    );
+}
+
+export function ChatViewToggle({ view, onChange }: ChatViewToggleProps) {
+    return (
+        <div
+            role="group"
+            aria-label="Conversation view"
+            data-testid="chat-view-toggle"
+            className="inline-flex items-center rounded-md border border-[#e0e0e0] dark:border-[#3c3c3c] bg-[#f3f3f3] dark:bg-[#2a2a2b] p-0.5 mr-1"
+        >
+            <SegButton active={view === 'thread'} onClick={() => onChange('thread')} testid="chat-view-thread">
+                <AcIcons.Thread size={13} />Thread
+            </SegButton>
+            <SegButton active={view === 'agents'} onClick={() => onChange('agents')} testid="chat-view-agents">
+                <AcIcons.Tree size={13} />Agents
+            </SegButton>
+        </div>
+    );
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
index bbbf92fb8..ace1a1c21 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -178,3 +178,26 @@ export function buildAgentRunTreeFromTurns(
 export function countRuns(node: AgentRunNode): number {
     return 1 + (node.children || []).reduce((sum, c) => sum + countRuns(c), 0);
 }
+
+/**
+ * Find the `data-turn-index` of the turn that issued a given run (its `Task`
+ * tool-call id), so a canvas node click can scroll the thread to that turn.
+ * Mirrors ConversationArea's `turn.turnIndex ?? arrayIndex`.
+ */
+export function findTurnIndexForRun(
+    turns: ClientConversationTurn[] | undefined,
+    runId: string,
+): number | null {
+    if (!turns) {
+        return null;
+    }
+    for (let i = 0; i < turns.length; i++) {
+        const turn = turns[i];
+        const inToolCalls = Array.isArray(turn.toolCalls) && turn.toolCalls.some((tc) => tc.id === runId);
+        const inTimeline = (turn.timeline || []).some((item) => item.toolCall?.id === runId);
+        if (inToolCalls || inTimeline) {
+            return turn.turnIndex ?? i;
+        }
+    }
+    return null;
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
index 4b937f158..bc604ba76 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
@@ -1,5 +1,7 @@
 export { AgentCanvas } from './AgentCanvas';
 export type { AgentCanvasProps } from './AgentCanvas';
-export { buildAgentRunTreeFromTurns, countRuns } from './buildAgentRunTree';
+export { ChatViewToggle } from './ChatViewToggle';
+export type { ChatView } from './ChatViewToggle';
+export { buildAgentRunTreeFromTurns, countRuns, findTurnIndexForRun } from './buildAgentRunTree';
 export type { AgentRunRootMeta } from './buildAgentRunTree';
 export type { AgentRunNode, AgentRunStatus } from './types';
diff --git a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
index d28f3e441..a21d5b2fa 100644
--- a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
+++ b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import {
     buildAgentRunTreeFromTurns,
     countRuns,
+    findTurnIndexForRun,
 } from '../../../../src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree';
 import type { AgentRunNode } from '../../../../src/server/spa/client/react/features/chat/agent-canvas/types';
 import type { ClientConversationTurn, ClientToolCall } from '../../../../src/server/spa/client/react/types/dashboard';
@@ -119,6 +120,38 @@ describe('buildAgentRunTreeFromTurns', () => {
     });
 });
 
+describe('findTurnIndexForRun', () => {
+    it('returns the data-turn-index of the turn that issued the run', () => {
+        const turns = [
+            { role: 'user' as const, content: 'go', timeline: [], turnIndex: 0 },
+            assistantTurn([tc({ id: 't1', args: { description: 'x' } })], []),
+        ];
+        // second turn has no explicit turnIndex → falls back to array index 1
+        expect(findTurnIndexForRun(turns, 't1')).toBe(1);
+    });
+
+    it('prefers an explicit turn.turnIndex over the array index', () => {
+        const turns = [
+            { ...assistantTurn([tc({ id: 't1', args: { description: 'x' } })]), turnIndex: 7 },
+        ];
+        expect(findTurnIndexForRun(turns, 't1')).toBe(7);
+    });
+
+    it('matches a run found only in the timeline', () => {
+        const turns = [assistantTurn([], [{
+            type: 'tool-complete',
+            timestamp: '2026-06-13T10:00:00.000Z',
+            toolCall: tc({ id: 't9', args: {}, status: 'completed' }),
+        }])];
+        expect(findTurnIndexForRun(turns, 't9')).toBe(0);
+    });
+
+    it('returns null when the run is not present', () => {
+        expect(findTurnIndexForRun([assistantTurn([tc({ id: 't1', args: {} })])], 'missing')).toBeNull();
+        expect(findTurnIndexForRun(undefined, 't1')).toBeNull();
+    });
+});
+
 describe('countRuns', () => {
     it('counts every run including the root', () => {
         const tree: AgentRunNode = {
diff --git a/packages/coc/test/spa/react/ChatViewToggle.test.tsx b/packages/coc/test/spa/react/ChatViewToggle.test.tsx
new file mode 100644
index 000000000..bf9db8e0e
--- /dev/null
+++ b/packages/coc/test/spa/react/ChatViewToggle.test.tsx
@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ChatViewToggle } from '../../../src/server/spa/client/react/features/chat/agent-canvas/ChatViewToggle';
+
+describe('ChatViewToggle', () => {
+    it('renders Thread and Agents segments', () => {
+        render(<ChatViewToggle view="thread" onChange={vi.fn()} />);
+        expect(screen.getByTestId('chat-view-thread')).toBeTruthy();
+        expect(screen.getByTestId('chat-view-agents')).toBeTruthy();
+    });
+
+    it('reflects the active view via aria-pressed', () => {
+        render(<ChatViewToggle view="agents" onChange={vi.fn()} />);
+        expect(screen.getByTestId('chat-view-agents').getAttribute('aria-pressed')).toBe('true');
+        expect(screen.getByTestId('chat-view-thread').getAttribute('aria-pressed')).toBe('false');
+    });
+
+    it('calls onChange when a segment is clicked', () => {
+        const onChange = vi.fn();
+        render(<ChatViewToggle view="thread" onChange={onChange} />);
+        fireEvent.click(screen.getByTestId('chat-view-agents'));
+        expect(onChange).toHaveBeenCalledWith('agents');
+    });
+});

From d4f270109448676b089ed7f6599a32922687856b Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:31:37 -0700
Subject: [PATCH 04/11] fix(coc): keep agents canvas sub-agents after a chat
 completes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Live (SSE) tool calls carry `toolName`, but the persisted forge read
model (loaded by refreshConversation after completion) carries `name`
(and may use `parameters` instead of `args`). The agent-tree adapter
read `tc.toolName` directly, so once a chat finished and its turns were
refreshed from the server, `Task` calls were no longer recognized and
every sub-agent vanished from the canvas — leaving just the root.

Detect the tool name via `toolName ?? name` and read args via
`args ?? parameters`, so sub-agents render identically mid-run and after
completion. Tests cover the persisted (`name`) shape and `parameters`
fallback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../chat/agent-canvas/buildAgentRunTree.ts    | 15 +++++++++++--
 .../spa/client/agent-canvas-data.test.ts      | 21 +++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
index ace1a1c21..ee40b6134 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -119,9 +119,20 @@ function asRecord(v: unknown): Record<string, unknown> {
     return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
 }
 
+// Live (SSE) tool calls carry `toolName` + `args`; persisted ones (forge's
+// ToolCall read model) carry `name` + `args`/`parameters`. Read both so a
+// sub-agent is detected the same way mid-run and after the chat completes.
+function rawToolName(tc: ClientToolCall): string | undefined {
+    return tc.toolName ?? (tc as { name?: string }).name;
+}
+
+function rawArgs(tc: ClientToolCall): unknown {
+    return tc.args ?? (tc as { parameters?: unknown }).parameters;
+}
+
 /** Build a sub-agent node from a normalized `Task` tool call. */
 function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
-    const args = asRecord(tc.args);
+    const args = asRecord(rawArgs(tc));
     const agentType = typeof args.agent_type === 'string' ? args.agent_type
         : typeof args.subagent_type === 'string' ? args.subagent_type
             : '';
@@ -155,7 +166,7 @@ export function buildAgentRunTreeFromTurns(
     root?: AgentRunRootMeta,
 ): AgentRunNode {
     const taskCalls = collectToolCalls(turns || [])
-        .filter((tc) => normalizeToolName(tc.toolName) === 'task');
+        .filter((tc) => normalizeToolName(rawToolName(tc)) === 'task');
 
     const children = taskCalls.map(nodeFromTaskCall);
     children.sort(byStartedAt);
diff --git a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
index a21d5b2fa..7b7b6a4b2 100644
--- a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
+++ b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
@@ -80,6 +80,27 @@ describe('buildAgentRunTreeFromTurns', () => {
         expect(buildAgentRunTreeFromTurns(turns).children).toEqual([]);
     });
 
+    it('detects persisted Task calls that use `name` instead of `toolName`', () => {
+        // forge's persisted ToolCall read model carries `name`, not `toolName`,
+        // so sub-agents must still be found after the chat completes + refreshes.
+        const persisted = {
+            id: 't1', name: 'Task', status: 'completed', result: 'done',
+            args: { agent_type: 'Explore', description: 'map data model' },
+        } as unknown as ClientToolCall;
+        const root = buildAgentRunTreeFromTurns([assistantTurn([persisted])]);
+        expect(root.children).toHaveLength(1);
+        expect(root.children[0]).toMatchObject({ id: 't1', name: 'map data model', role: 'Explore', status: 'done' });
+    });
+
+    it('reads sub-agent args from `parameters` when `args` is absent', () => {
+        const persisted = {
+            id: 't1', name: 'Task', status: 'running',
+            parameters: { agent_type: 'general-purpose', description: 'research' },
+        } as unknown as ClientToolCall;
+        const root = buildAgentRunTreeFromTurns([assistantTurn([persisted])]);
+        expect(root.children[0]).toMatchObject({ id: 't1', name: 'research', role: 'general-purpose', status: 'running' });
+    });
+
     it('dedupes a tool call seen in both toolCalls and the timeline, preferring terminal state', () => {
         const turns = [assistantTurn(
             [tc({ id: 't1', args: { description: 'x' }, status: 'running' })],

From 9aa284cfa2b780c2b97bc5cf2853b991b4b5b15e Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:33:34 -0700
Subject: [PATCH 05/11] feat(coc): agents canvas defaults to 100% zoom,
 centered
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The canvas opened auto-fit (scaled down to fit the whole tree). Default
to 100% zoom with the content centered in the viewport instead, so nodes
render at full size on open and the user pans to explore.

- useZoomPan: add `centerContent(scale = 1)` — sets the given scale and
  centers content in the container (additive; existing consumers
  unaffected).
- AgentCanvas: use centerContent(1) for the default/auto view (mount,
  tree growth, resize) until the user takes over. The Fit button still
  zooms to fit the whole tree and now sticks (counts as an interaction)
  rather than re-arming auto-center.

Tests cover centerContent (centering math, no-container no-op, scale
clamping).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../chat/agent-canvas/AgentCanvas.tsx         | 17 ++++++-----
 .../spa/client/react/hooks/ui/useZoomPan.ts   | 17 ++++++++++-
 .../test/spa/react/hooks/useZoomPan.test.ts   | 30 +++++++++++++++++++
 3 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
index 8a1882cb0..a916a80a0 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
@@ -104,22 +104,23 @@ function CanvasNode({ entry, selected, onSelect, now }: {
 export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
     const layout = useMemo(() => buildLayout(root), [root]);
 
-    const { containerRef, state, zoomIn, zoomOut, fitToView, zoomLabel } = useZoomPan({
+    const { containerRef, state, zoomIn, zoomOut, fitToView, centerContent, zoomLabel } = useZoomPan({
         contentWidth: layout.worldW,
         contentHeight: layout.worldH,
         minZoom: 0.25,
         maxZoom: 2.2,
     });
 
-    // Auto-fit on mount and whenever the tree resizes — until the user takes
-    // over the view (wheel/drag/zoom). The Fit button re-arms auto-fit.
+    // Default view: 100% zoom, content centered in the viewport. Re-centers on
+    // mount, tree growth, and container resize — until the user takes over
+    // (wheel/drag/zoom or the Fit button).
     const interactedRef = useRef(false);
 
     useLayoutEffect(() => {
         if (!interactedRef.current) {
-            fitToView();
+            centerContent(1);
         }
-    }, [layout.worldW, layout.worldH, fitToView]);
+    }, [layout.worldW, layout.worldH, centerContent]);
 
     useEffect(() => {
         const el = containerRef.current;
@@ -131,7 +132,7 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
         el.addEventListener('pointerdown', markInteracted);
         const ro = new ResizeObserver(() => {
             if (!interactedRef.current) {
-                fitToView();
+                centerContent(1);
             }
         });
         ro.observe(el);
@@ -140,7 +141,7 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
             el.removeEventListener('pointerdown', markInteracted);
             ro.disconnect();
         };
-    }, [containerRef, fitToView]);
+    }, [containerRef, centerContent]);
 
     // Live clock so running nodes' elapsed time ticks; idle when nothing runs.
     const hasRunning = useMemo(() => anyRunning(root), [root]);
@@ -211,7 +212,7 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
                 <span className="cz-sep" />
                 <button
                     type="button"
-                    onClick={() => { interactedRef.current = false; fitToView(); }}
+                    onClick={() => { interactedRef.current = true; fitToView(); }}
                     title="Fit to screen"
                 >
                     <AcIcons.Replay size={14} />Fit
diff --git a/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts b/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
index b62df2137..0c9c6122e 100644
--- a/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
+++ b/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
@@ -45,6 +45,8 @@ export interface UseZoomPanReturn {
     reset: () => void;
     /** Auto-fit: calculate scale so all content fits the container. */
     fitToView: () => void;
+    /** Center the content in the container at a fixed scale (default 1 = 100%). */
+    centerContent: (scale?: number) => void;
     /** Formatted zoom percentage string, e.g. `"125%"`. */
     zoomLabel: string;
 }
@@ -196,5 +198,18 @@ export function useZoomPan(options: UseZoomPanOptions): UseZoomPanReturn {
         setState({ scale: fitScale, translateX: tx, translateY: ty, isDragging: false });
     }, [contentWidth, contentHeight, clampScale]);
 
-    return { containerRef, state, svgTransform, zoomIn, zoomOut, reset, fitToView, zoomLabel };
+    const centerContent = useCallback((targetScale = 1) => {
+        const el = containerRef.current;
+        if (!el || contentWidth <= 0 || contentHeight <= 0) return;
+        const rect = el.getBoundingClientRect();
+        const s = clampScale(targetScale);
+        setState({
+            scale: s,
+            translateX: (rect.width - contentWidth * s) / 2,
+            translateY: (rect.height - contentHeight * s) / 2,
+            isDragging: false,
+        });
+    }, [contentWidth, contentHeight, clampScale]);
+
+    return { containerRef, state, svgTransform, zoomIn, zoomOut, reset, fitToView, centerContent, zoomLabel };
 }
diff --git a/packages/coc/test/spa/react/hooks/useZoomPan.test.ts b/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
index 392a708ee..52636c0fa 100644
--- a/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
+++ b/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
@@ -129,4 +129,34 @@ describe('useZoomPan', () => {
         act(() => result.current.zoomOut());
         expect(result.current.state.scale).toBe(1);
     });
+
+    it('centerContent centers content at 100% using the container rect', () => {
+        const { result } = renderHook(() => useZoomPan(defaultOptions)); // content 400x200
+        act(() => {
+            (result.current.containerRef as { current: unknown }).current = {
+                getBoundingClientRect: () => ({ width: 800, height: 600 }),
+            };
+            result.current.centerContent(1);
+        });
+        expect(result.current.state.scale).toBe(1);
+        expect(result.current.state.translateX).toBe(200); // (800 - 400) / 2
+        expect(result.current.state.translateY).toBe(200); // (600 - 200) / 2
+    });
+
+    it('centerContent no-ops when there is no container', () => {
+        const { result } = renderHook(() => useZoomPan(defaultOptions));
+        act(() => result.current.centerContent(1));
+        expect(result.current.state).toEqual({ scale: 1, translateX: 0, translateY: 0, isDragging: false });
+    });
+
+    it('centerContent clamps the scale to the configured bounds', () => {
+        const { result } = renderHook(() => useZoomPan({ ...defaultOptions, maxZoom: 2 }));
+        act(() => {
+            (result.current.containerRef as { current: unknown }).current = {
+                getBoundingClientRect: () => ({ width: 800, height: 600 }),
+            };
+            result.current.centerContent(5); // above maxZoom
+        });
+        expect(result.current.state.scale).toBe(2);
+    });
 });

From b4d46f58d53c88bae752f4738a0621d47dcab42c Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:42:26 -0700
Subject: [PATCH 06/11] feat(coc): deep-link the agents view via a ?view=agents
 hash param
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Thread/Agents view is now shareable/bookmarkable. In the main inline
chat context the active view rides as a `?view=agents` query param on the
chat hash (`#repos/<ws>/<tab>/<taskId>?view=agents`):

- chatViewHash.ts — pure read/apply helpers for the `view` param
  (preserve path, leading #, and other params).
- ChatDetail — initializes `view` from the hash on mount (so a shared
  URL reopens straight into the canvas) and mirrors it back via
  history.replaceState on toggle. Gated to variant 'inline' &
  non-standalone. The per-chat reset honors a deep-linked view on first
  mount (ChatDetail is keyed per task, so the initializer re-reads the
  hash for each chat).
- Router — `parseActivityDeepLink` strips a trailing `?query` before
  extracting the taskId, so the new param never corrupts chat routing.

Tests cover chatViewHash (read/apply/round-trip, param preservation) and
the Router taskId query-strip. dashboard-spa.md updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../coc-knowledge/references/dashboard-spa.md | 33 +++++++----
 .../client/react/features/chat/ChatDetail.tsx | 34 +++++++++--
 .../chat/agent-canvas/chatViewHash.ts         | 43 ++++++++++++++
 .../react/features/chat/agent-canvas/index.ts |  1 +
 .../server/spa/client/react/layout/Router.tsx |  3 +-
 .../server/spa/client/chat-view-hash.test.ts  | 58 +++++++++++++++++++
 packages/coc/test/spa/react/Router.test.ts    |  5 ++
 7 files changed, 159 insertions(+), 18 deletions(-)
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/chatViewHash.ts
 create mode 100644 packages/coc/test/server/spa/client/chat-view-hash.test.ts

diff --git a/.github/skills/coc-knowledge/references/dashboard-spa.md b/.github/skills/coc-knowledge/references/dashboard-spa.md
index cad815075..83e412ef0 100644
--- a/.github/skills/coc-knowledge/references/dashboard-spa.md
+++ b/.github/skills/coc-knowledge/references/dashboard-spa.md
@@ -304,23 +304,32 @@ owns the `view` state and, in `agents` mode, swaps the `ConversationArea` inner
 row for `AgentCanvas` — a pannable/zoomable spatial tree of the chat's
 recursive sub-agent runs — while keeping the composer/scratchpad and hiding the
 thread-only flow cards (Ralph start, Implement-plan). The toggle is hidden in
-the `floating` variant and while loading/pending; `view` resets to `thread` on
-chat switch.
+the `floating` variant and while loading/pending. In the main inline context
+the view is deep-linked: a `?view=agents` query param on the chat hash
+(`#repos/<ws>/<tab>/<taskId>?view=agents`) is read on mount (so a
+shared/bookmarked URL reopens straight into the canvas) and written via
+`history.replaceState` on toggle (`chatViewHash.ts`). `parseActivityDeepLink`
+strips the `?query` so the param never corrupts the taskId. `view` resets to
+`thread` on chat switch (honoring a deep-linked view on first mount).
 
 `buildAgentRunTreeFromTurns(turns, root)` derives the tree with no extra fetch:
 the orchestrator (this process) is the root and each `Task` tool call becomes a
 sub-agent child (name/role from args, status/timing from the call), deduped
-across `toolCalls`+timeline and ordered by start time. The `AgentRunNode` tree
+across `toolCalls`+timeline and ordered by start time. Tool name/args are read
+via `toolName ?? name` and `args ?? parameters` so sub-agents are detected in
+both the live (SSE) shape and the persisted forge read model — they stay on the
+canvas after the chat completes and turns refresh. The `AgentRunNode` tree
 supports arbitrary depth, so deeper recursion can be layered on later.
-`AgentCanvas` reuses the shared `useZoomPan` hook (auto-fit until the user takes
-over; a Fit button re-arms it), renders curved SVG edges + node cards (role
-glyph, name, live elapsed, spawn-count pill, status dot, progress bar), and a
-live 1s clock for running nodes. Clicking a node calls `onSelect`; `ChatDetail`
-maps it back to the issuing turn via `findTurnIndexForRun`, switches to the
-thread, and scrolls there. Styles live in scoped `agent-canvas.css`
-(`.agent-canvas`, light/dark via `.dark`); there is no clock scrubber (the
-prototype's replay control is dropped — the real view is live). Distinct from
-the co-edited `CanvasPanel` side panel.
+`AgentCanvas` reuses the shared `useZoomPan` hook — it opens at 100% zoom,
+centered (`centerContent`), re-centering on mount/growth/resize until the user
+takes over; the Fit button zooms to fit the whole tree. It renders curved SVG
+edges + node cards (role glyph, name, live elapsed, spawn-count pill, status
+dot, progress bar) and a live 1s clock for running nodes. Clicking a node calls
+`onSelect`; `ChatDetail` maps it back to the issuing turn via
+`findTurnIndexForRun`, switches to the thread, and scrolls there. Styles live in
+scoped `agent-canvas.css` (`.agent-canvas`, light/dark via `.dark`); there is no
+clock scrubber (the prototype's replay control is dropped — the real view is
+live). Distinct from the co-edited `CanvasPanel` side panel.
 
 ## Tool Call Rendering
 
diff --git a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
index f762f55db..8956375cf 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
@@ -44,7 +44,7 @@ import { buildEffortOptionsForModel } from './EffortPillSelector';
 import type { EffortLevel } from './EffortPillSelector';
 import type { RichTextInputHandle } from '../../shared/RichTextInput';
 import { ConversationMiniMap } from './conversation/ConversationMiniMap';
-import { AgentCanvas, ChatViewToggle, buildAgentRunTreeFromTurns, findTurnIndexForRun } from './agent-canvas';
+import { AgentCanvas, ChatViewToggle, buildAgentRunTreeFromTurns, findTurnIndexForRun, readChatViewFromHash, applyChatViewToHash } from './agent-canvas';
 import type { AgentRunNode, ChatView } from './agent-canvas';
 import { useConversationSelection } from './hooks/useConversationSelection';
 import { snapshotConversation } from '../../utils/snapshot-copy-utils';
@@ -181,8 +181,11 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
     const [activeCanvasId, setActiveCanvasId] = useState<string | null>(null);
     const [canvasLiveEvent, setCanvasLiveEvent] = useState<CanvasUpdatedEvent | null>(null);
     const [canvasPanelClosed, setCanvasPanelClosed] = useState(false);
-    // Thread vs. Agents (spatial sub-agent run tree) view.
-    const [view, setView] = useState<ChatView>('thread');
+    // Thread vs. Agents (spatial sub-agent run tree) view. In the main inline
+    // context the view is deep-linked via a `?view=agents` hash param, so a
+    // shared/bookmarked URL reopens straight into the canvas.
+    const hashViewSync = variant === 'inline' && !standalone;
+    const [view, setView] = useState<ChatView>(() => (hashViewSync ? (readChatViewFromHash(window.location.hash) ?? 'thread') : 'thread'));
     const [selectedAgentId, setSelectedAgentId] = useState<string | null>(null);
     const [pendingScrollTurn, setPendingScrollTurn] = useState<number | null>(null);
     const [noteEdits, setNoteEdits] = useState<Array<{
@@ -463,10 +466,31 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
         modelOverrideMountedRef.current = false;
         setEffortOverride(null);
         setInvalidScratchpadPaths(new Set());
-        setView('thread');
+    }, [taskId]);
+
+    // Reset the Agents view when switching chats, but honor a deep-linked view
+    // on first mount (the useState initializer already read it from the hash).
+    const viewResetMountRef = useRef(true);
+    useEffect(() => {
+        if (viewResetMountRef.current) {
+            viewResetMountRef.current = false;
+            return;
+        }
+        setView(hashViewSync ? (readChatViewFromHash(window.location.hash) ?? 'thread') : 'thread');
         setSelectedAgentId(null);
         setPendingScrollTurn(null);
-    }, [taskId]);
+    }, [taskId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    // Mirror the active view into the chat hash (`?view=agents`) so it can be
+    // shared/bookmarked. replaceState avoids history spam and doesn't refire
+    // the router's hashchange handler.
+    useEffect(() => {
+        if (!hashViewSync || !window.location.hash) return;
+        const next = applyChatViewToHash(window.location.hash, view);
+        if (next !== window.location.hash) {
+            window.history.replaceState(null, '', next);
+        }
+    }, [view, hashViewSync]);
 
     // ── Resolve existing implementation runs from task metadata ─────────
     const rawImplementations: ImplementationRecord[] = useMemo(() => {
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/chatViewHash.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/chatViewHash.ts
new file mode 100644
index 000000000..a399d52d8
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/chatViewHash.ts
@@ -0,0 +1,43 @@
+// Deep-link helpers for the chat's Thread/Agents view. The view rides as a
+// `?view=agents` query param on the existing chat hash
+// (`#repos/<ws>/<tab>/<taskId>`), read on mount and written on toggle. Pure
+// string functions so they're unit-testable and SSR/embed-safe.
+
+import type { ChatView } from './ChatViewToggle';
+
+/** Read the chat view from a raw `location.hash` string, or null if unset/invalid. */
+export function readChatViewFromHash(rawHash: string): ChatView | null {
+    const qIndex = rawHash.indexOf('?');
+    if (qIndex < 0) {
+        return null;
+    }
+    const view = new URLSearchParams(rawHash.slice(qIndex + 1)).get('view');
+    if (view === 'agents') {
+        return 'agents';
+    }
+    if (view === 'thread') {
+        return 'thread';
+    }
+    return null;
+}
+
+/**
+ * Return `rawHash` with the `view` param set for the agents view and removed
+ * for thread (the default). Preserves the path, leading `#`, and any other
+ * query params. Returns a value directly comparable to `location.hash`.
+ */
+export function applyChatViewToHash(rawHash: string, view: ChatView): string {
+    const hasLeadingHash = rawHash.startsWith('#');
+    const body = hasLeadingHash ? rawHash.slice(1) : rawHash;
+    const qIndex = body.indexOf('?');
+    const path = qIndex < 0 ? body : body.slice(0, qIndex);
+    const params = new URLSearchParams(qIndex < 0 ? '' : body.slice(qIndex + 1));
+    if (view === 'agents') {
+        params.set('view', 'agents');
+    } else {
+        params.delete('view');
+    }
+    const query = params.toString();
+    const result = query ? `${path}?${query}` : path;
+    return (hasLeadingHash ? '#' : '') + result;
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
index bc604ba76..592aa8afc 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/index.ts
@@ -2,6 +2,7 @@ export { AgentCanvas } from './AgentCanvas';
 export type { AgentCanvasProps } from './AgentCanvas';
 export { ChatViewToggle } from './ChatViewToggle';
 export type { ChatView } from './ChatViewToggle';
+export { readChatViewFromHash, applyChatViewToHash } from './chatViewHash';
 export { buildAgentRunTreeFromTurns, countRuns, findTurnIndexForRun } from './buildAgentRunTree';
 export type { AgentRunRootMeta } from './buildAgentRunTree';
 export type { AgentRunNode, AgentRunStatus } from './types';
diff --git a/packages/coc/src/server/spa/client/react/layout/Router.tsx b/packages/coc/src/server/spa/client/react/layout/Router.tsx
index 5586f38d9..2ff13bcad 100644
--- a/packages/coc/src/server/spa/client/react/layout/Router.tsx
+++ b/packages/coc/src/server/spa/client/react/layout/Router.tsx
@@ -180,7 +180,8 @@ export function parsePrDetailTab(hash: string): PrDetailTab {
 }
 
 export function parseActivityDeepLink(hash: string): string | null {
-    const cleaned = hash.replace(/^#/, '');
+    // Strip any `?query` (e.g. `?view=agents`) so it never bleeds into the taskId.
+    const cleaned = hash.replace(/^#/, '').split('?')[0];
     const parts = cleaned.split('/');
     if (parts[0] === 'repos' && parts[1] && (parts[2] === 'chats' || parts[2] === 'activity') && parts[3]) {
         if (parts[3] === 'ralph' || parts[3] === 'for-each' || parts[3] === 'map-reduce') return null;
diff --git a/packages/coc/test/server/spa/client/chat-view-hash.test.ts b/packages/coc/test/server/spa/client/chat-view-hash.test.ts
new file mode 100644
index 000000000..9a165f2ff
--- /dev/null
+++ b/packages/coc/test/server/spa/client/chat-view-hash.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import {
+    readChatViewFromHash,
+    applyChatViewToHash,
+} from '../../../../src/server/spa/client/react/features/chat/agent-canvas/chatViewHash';
+
+const BASE = '#repos/ws-1/activity/task-9';
+
+describe('readChatViewFromHash', () => {
+    it('returns null when there is no query', () => {
+        expect(readChatViewFromHash(BASE)).toBeNull();
+        expect(readChatViewFromHash('')).toBeNull();
+    });
+
+    it('reads view=agents and view=thread', () => {
+        expect(readChatViewFromHash(`${BASE}?view=agents`)).toBe('agents');
+        expect(readChatViewFromHash(`${BASE}?view=thread`)).toBe('thread');
+    });
+
+    it('returns null for unknown or unrelated params', () => {
+        expect(readChatViewFromHash(`${BASE}?view=bogus`)).toBeNull();
+        expect(readChatViewFromHash(`${BASE}?mode=source`)).toBeNull();
+    });
+
+    it('reads view alongside other params', () => {
+        expect(readChatViewFromHash(`${BASE}?mode=source&view=agents`)).toBe('agents');
+    });
+});
+
+describe('applyChatViewToHash', () => {
+    it('adds the param for the agents view', () => {
+        expect(applyChatViewToHash(BASE, 'agents')).toBe(`${BASE}?view=agents`);
+    });
+
+    it('removes the param for the (default) thread view', () => {
+        expect(applyChatViewToHash(`${BASE}?view=agents`, 'thread')).toBe(BASE);
+    });
+
+    it('is a no-op when thread view has no param', () => {
+        expect(applyChatViewToHash(BASE, 'thread')).toBe(BASE);
+    });
+
+    it('preserves the path, leading #, and other query params', () => {
+        expect(applyChatViewToHash(`${BASE}?mode=source`, 'agents')).toBe(`${BASE}?mode=source&view=agents`);
+        expect(applyChatViewToHash(`${BASE}?mode=source&view=agents`, 'thread')).toBe(`${BASE}?mode=source`);
+    });
+
+    it('handles a hash with no leading #', () => {
+        expect(applyChatViewToHash('repos/ws/activity/x', 'agents')).toBe('repos/ws/activity/x?view=agents');
+    });
+
+    it('round-trips with readChatViewFromHash', () => {
+        const withAgents = applyChatViewToHash(BASE, 'agents');
+        expect(readChatViewFromHash(withAgents)).toBe('agents');
+        const backToThread = applyChatViewToHash(withAgents, 'thread');
+        expect(readChatViewFromHash(backToThread)).toBeNull();
+    });
+});
diff --git a/packages/coc/test/spa/react/Router.test.ts b/packages/coc/test/spa/react/Router.test.ts
index 195b2c078..807f30f7d 100644
--- a/packages/coc/test/spa/react/Router.test.ts
+++ b/packages/coc/test/spa/react/Router.test.ts
@@ -781,6 +781,11 @@ describe('parseActivityDeepLink', () => {
         expect(parseActivityDeepLink('#repos/my-repo/activity/task%2F1')).toBe('task/1');
     });
 
+    it('strips a trailing ?query (e.g. ?view=agents) from the task ID', () => {
+        expect(parseActivityDeepLink('#repos/my-repo/activity/task-1?view=agents')).toBe('task-1');
+        expect(parseActivityDeepLink('#repos/my-repo/chats/task-1?view=thread')).toBe('task-1');
+    });
+
     it('returns null when task ID is missing', () => {
         expect(parseActivityDeepLink('#repos/my-repo/activity')).toBeNull();
     });

From 624a768a79f94c264fac09c5f7f7ae5a491fdf1a Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:50:18 -0700
Subject: [PATCH 07/11] feat(coc): zoom preset menu on the agents canvas
 toolbar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The toolbar's % label is now a dropdown of preset zoom levels
(25/50/75/100/150/200%) plus "Fit to screen". Picking a level zooms
about the viewport center.

- useZoomPan: add `zoomTo(scale)` — zooms to an exact scale while
  keeping the world point under the viewport center fixed (additive).
- AgentCanvas: the % becomes a menu button; the active level is marked;
  the menu closes on pick or outside click. Picking a level counts as a
  user interaction (stops auto-centering).

Tests cover zoomTo (center-fixed math, clamping, no-container) and the
menu (opens from %, lists presets + Fit, closes on pick).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../chat/agent-canvas/AgentCanvas.tsx         | 58 +++++++++++++++-
 .../chat/agent-canvas/agent-canvas.css        | 66 ++++++++++++++++++-
 .../spa/client/react/hooks/ui/useZoomPan.ts   | 19 +++++-
 .../coc/test/spa/react/AgentCanvas.test.tsx   | 19 +++++-
 .../test/spa/react/hooks/useZoomPan.test.ts   | 21 ++++++
 5 files changed, 178 insertions(+), 5 deletions(-)

diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
index a916a80a0..85541a0f5 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
@@ -23,6 +23,9 @@ export interface AgentCanvasProps {
     onSelect?: (node: AgentRunNode) => void;
 }
 
+// Preset zoom levels offered by the % menu (within useZoomPan's 25%–220% range).
+const ZOOM_PRESETS = [25, 50, 75, 100, 150, 200];
+
 function fmtDuration(ms: number): string {
     const s = Math.max(0, Math.round(ms / 1000));
     const m = Math.floor(s / 60);
@@ -104,13 +107,28 @@ function CanvasNode({ entry, selected, onSelect, now }: {
 export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
     const layout = useMemo(() => buildLayout(root), [root]);
 
-    const { containerRef, state, zoomIn, zoomOut, fitToView, centerContent, zoomLabel } = useZoomPan({
+    const { containerRef, state, zoomIn, zoomOut, fitToView, centerContent, zoomTo, zoomLabel } = useZoomPan({
         contentWidth: layout.worldW,
         contentHeight: layout.worldH,
         minZoom: 0.25,
         maxZoom: 2.2,
     });
 
+    const [zoomMenuOpen, setZoomMenuOpen] = useState(false);
+    useEffect(() => {
+        if (!zoomMenuOpen) {
+            return;
+        }
+        const close = (e: MouseEvent) => {
+            if (!(e.target as HTMLElement).closest('.cz-wrap')) {
+                setZoomMenuOpen(false);
+            }
+        };
+        document.addEventListener('mousedown', close);
+        return () => document.removeEventListener('mousedown', close);
+    }, [zoomMenuOpen]);
+    const currentPct = Math.round(state.scale * 100);
+
     // Default view: 100% zoom, content centered in the viewport. Re-centers on
     // mount, tree growth, and container resize — until the user takes over
     // (wheel/drag/zoom or the Fit button).
@@ -207,7 +225,43 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
 
             <div className="canvas-toolbar" data-no-drag>
                 <button type="button" onClick={zoomOut} title="Zoom out"><AcIcons.Collapse size={14} /></button>
-                <span className="cz">{zoomLabel}</span>
+                <span className="cz-wrap">
+                    <button
+                        type="button"
+                        className="cz"
+                        aria-haspopup="menu"
+                        aria-expanded={zoomMenuOpen}
+                        onClick={() => setZoomMenuOpen((o) => !o)}
+                        title="Set zoom level"
+                        data-testid="agent-canvas-zoom-label"
+                    >
+                        {zoomLabel}
+                    </button>
+                    {zoomMenuOpen && (
+                        <div className="canvas-zoom-menu" role="menu" data-testid="agent-canvas-zoom-menu">
+                            {ZOOM_PRESETS.map((p) => (
+                                <button
+                                    key={p}
+                                    type="button"
+                                    role="menuitemradio"
+                                    aria-checked={currentPct === p}
+                                    className={currentPct === p ? 'on' : ''}
+                                    onClick={() => { interactedRef.current = true; zoomTo(p / 100); setZoomMenuOpen(false); }}
+                                >
+                                    {p}%
+                                </button>
+                            ))}
+                            <span className="czm-sep" />
+                            <button
+                                type="button"
+                                role="menuitem"
+                                onClick={() => { interactedRef.current = true; fitToView(); setZoomMenuOpen(false); }}
+                            >
+                                Fit to screen
+                            </button>
+                        </div>
+                    )}
+                </span>
                 <button type="button" onClick={zoomIn} title="Zoom in"><AcIcons.Expand size={14} /></button>
                 <span className="cz-sep" />
                 <button
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
index b4ae5318b..082ffccc7 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
@@ -283,12 +283,76 @@
     color: var(--text);
 }
 
+.agent-canvas .canvas-toolbar .cz-wrap {
+    position: relative;
+    display: inline-flex;
+}
+
 .agent-canvas .canvas-toolbar .cz {
     font-family: var(--font-mono);
     font-size: 11px;
     color: var(--muted);
-    width: 40px;
+    min-width: 46px;
     text-align: center;
+    border: none;
+    background: transparent;
+    border-radius: 6px;
+    padding: 4px 6px;
+    cursor: pointer;
+}
+
+.agent-canvas .canvas-toolbar .cz:hover {
+    background: var(--hover);
+    color: var(--text);
+}
+
+.agent-canvas .canvas-zoom-menu {
+    position: absolute;
+    bottom: calc(100% + 8px);
+    left: 50%;
+    transform: translateX(-50%);
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 116px;
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 9px;
+    padding: 4px;
+    box-shadow: 0 6px 20px rgb(20 30 60 / 0.16);
+    z-index: 5;
+}
+
+.agent-canvas .canvas-zoom-menu button {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    border: none;
+    background: transparent;
+    color: var(--muted);
+    cursor: pointer;
+    font-size: 12px;
+    font-weight: 500;
+    font-family: var(--font-mono);
+    padding: 5px 9px;
+    border-radius: 6px;
+    text-align: left;
+}
+
+.agent-canvas .canvas-zoom-menu button:hover {
+    background: var(--hover);
+    color: var(--text);
+}
+
+.agent-canvas .canvas-zoom-menu button.on {
+    color: var(--accent);
+    font-weight: 600;
+}
+
+.agent-canvas .canvas-zoom-menu .czm-sep {
+    height: 1px;
+    background: var(--border);
+    margin: 3px 4px;
 }
 
 .agent-canvas .canvas-toolbar .cz-sep {
diff --git a/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts b/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
index 0c9c6122e..7446fd6a1 100644
--- a/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
+++ b/packages/coc/src/server/spa/client/react/hooks/ui/useZoomPan.ts
@@ -47,6 +47,8 @@ export interface UseZoomPanReturn {
     fitToView: () => void;
     /** Center the content in the container at a fixed scale (default 1 = 100%). */
     centerContent: (scale?: number) => void;
+    /** Zoom to a specific scale, keeping the viewport center fixed. */
+    zoomTo: (scale: number) => void;
     /** Formatted zoom percentage string, e.g. `"125%"`. */
     zoomLabel: string;
 }
@@ -211,5 +213,20 @@ export function useZoomPan(options: UseZoomPanOptions): UseZoomPanReturn {
         });
     }, [contentWidth, contentHeight, clampScale]);
 
-    return { containerRef, state, svgTransform, zoomIn, zoomOut, reset, fitToView, centerContent, zoomLabel };
+    const zoomTo = useCallback((targetScale: number) => {
+        const s = clampScale(targetScale);
+        setState(prev => {
+            const el = containerRef.current;
+            if (!el) return { ...prev, scale: s };
+            const rect = el.getBoundingClientRect();
+            const cx = rect.width / 2;
+            const cy = rect.height / 2;
+            // Keep the world point under the viewport center fixed while scaling.
+            const px = (cx - prev.translateX) / prev.scale;
+            const py = (cy - prev.translateY) / prev.scale;
+            return { ...prev, scale: s, translateX: cx - px * s, translateY: cy - py * s };
+        });
+    }, [clampScale]);
+
+    return { containerRef, state, svgTransform, zoomIn, zoomOut, reset, fitToView, centerContent, zoomTo, zoomLabel };
 }
diff --git a/packages/coc/test/spa/react/AgentCanvas.test.tsx b/packages/coc/test/spa/react/AgentCanvas.test.tsx
index 82f858a4f..c487d6f98 100644
--- a/packages/coc/test/spa/react/AgentCanvas.test.tsx
+++ b/packages/coc/test/spa/react/AgentCanvas.test.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen, fireEvent, within } from '@testing-library/react';
 import { AgentCanvas } from '../../../src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas';
 import type { AgentRunNode } from '../../../src/server/spa/client/react/features/chat/agent-canvas/types';
 
@@ -61,4 +61,21 @@ describe('AgentCanvas', () => {
         render(<AgentCanvas root={tree([sub('busy', { status: 'running' })])} />);
         expect(screen.getByTestId('agent-canvas-node-busy').getAttribute('data-status')).toBe('running');
     });
+
+    it('opens a zoom preset menu from the % label', () => {
+        render(<AgentCanvas root={tree([sub('a')])} />);
+        expect(screen.queryByTestId('agent-canvas-zoom-menu')).toBeNull();
+        fireEvent.click(screen.getByTestId('agent-canvas-zoom-label'));
+        const menu = screen.getByTestId('agent-canvas-zoom-menu');
+        expect(within(menu).getByText('50%')).toBeTruthy();
+        expect(within(menu).getByText('200%')).toBeTruthy();
+        expect(within(menu).getByText('Fit to screen')).toBeTruthy();
+    });
+
+    it('closes the zoom menu after picking a preset', () => {
+        render(<AgentCanvas root={tree([sub('a')])} />);
+        fireEvent.click(screen.getByTestId('agent-canvas-zoom-label'));
+        fireEvent.click(within(screen.getByTestId('agent-canvas-zoom-menu')).getByText('50%'));
+        expect(screen.queryByTestId('agent-canvas-zoom-menu')).toBeNull();
+    });
 });
diff --git a/packages/coc/test/spa/react/hooks/useZoomPan.test.ts b/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
index 52636c0fa..0a7b00617 100644
--- a/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
+++ b/packages/coc/test/spa/react/hooks/useZoomPan.test.ts
@@ -159,4 +159,25 @@ describe('useZoomPan', () => {
         });
         expect(result.current.state.scale).toBe(2);
     });
+
+    it('zoomTo zooms about the viewport center, keeping that point fixed', () => {
+        const { result } = renderHook(() => useZoomPan(defaultOptions));
+        act(() => {
+            (result.current.containerRef as { current: unknown }).current = {
+                getBoundingClientRect: () => ({ width: 800, height: 600 }),
+            };
+            result.current.zoomTo(2);
+        });
+        expect(result.current.state.scale).toBe(2);
+        // center (400,300) under world point (400,300); tx = 400 - 400*2, ty = 300 - 300*2
+        expect(result.current.state.translateX).toBe(-400);
+        expect(result.current.state.translateY).toBe(-300);
+    });
+
+    it('zoomTo clamps the scale and works without a container', () => {
+        const { result } = renderHook(() => useZoomPan({ ...defaultOptions, maxZoom: 2 }));
+        act(() => result.current.zoomTo(5));
+        expect(result.current.state.scale).toBe(2);
+        expect(result.current.state.translateX).toBe(0);
+    });
 });

From 046d0f3287b68d23b53acaeddcb44df83e45f443 Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 14:58:28 -0700
Subject: [PATCH 08/11] feat(coc): sub-agent inspector on the agents canvas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clicking a sub-agent node now opens a detail panel instead of jumping
back to the thread.

- AgentInspector — right-side panel showing the run's role, status,
  elapsed/duration, the task prompt it was handed, its result/conclusion,
  and its child runs (clickable to drill in). An explicit "Open in
  thread" button preserves the jump-to-turn action.
- AgentCanvas owns selection internally: clicking a sub-agent opens the
  inspector and highlights the node; clicking the orchestrator root or
  the close button dismisses it; the legend hides while it's open. New
  `onOpenInThread` prop replaces the old `onSelect`/`selectedId` props.
- buildAgentRunTree now captures each run's `prompt` (task) and `result`
  for the inspector; duration helpers handle a 0 timestamp.
- ChatDetail passes `onOpenInThread` (the former jump-to-turn handler);
  the internal selected-agent state is gone.
- icons: add Clock + X.

Tests cover the inspector (status/duration/task/result, child drill-in,
close, root has no result/open-in-thread) and the canvas wiring (open on
sub-agent click, highlight, close on root/close, onOpenInThread).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../coc-knowledge/references/dashboard-spa.md |  22 +-
 .../client/react/features/chat/ChatDetail.tsx |  10 +-
 .../chat/agent-canvas/AgentCanvas.tsx         |  68 ++++--
 .../chat/agent-canvas/AgentInspector.tsx      | 124 ++++++++++
 .../chat/agent-canvas/agent-canvas.css        | 230 ++++++++++++++++++
 .../chat/agent-canvas/buildAgentRunTree.ts    |   8 +-
 .../features/chat/agent-canvas/icons.tsx      |   2 +
 .../react/features/chat/agent-canvas/types.ts |   4 +
 .../coc/test/spa/react/AgentCanvas.test.tsx   |  39 ++-
 .../test/spa/react/AgentInspector.test.tsx    |  61 +++++
 10 files changed, 525 insertions(+), 43 deletions(-)
 create mode 100644 packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
 create mode 100644 packages/coc/test/spa/react/AgentInspector.test.tsx

diff --git a/.github/skills/coc-knowledge/references/dashboard-spa.md b/.github/skills/coc-knowledge/references/dashboard-spa.md
index 83e412ef0..7fb39b3a8 100644
--- a/.github/skills/coc-knowledge/references/dashboard-spa.md
+++ b/.github/skills/coc-knowledge/references/dashboard-spa.md
@@ -322,13 +322,21 @@ canvas after the chat completes and turns refresh. The `AgentRunNode` tree
 supports arbitrary depth, so deeper recursion can be layered on later.
 `AgentCanvas` reuses the shared `useZoomPan` hook — it opens at 100% zoom,
 centered (`centerContent`), re-centering on mount/growth/resize until the user
-takes over; the Fit button zooms to fit the whole tree. It renders curved SVG
-edges + node cards (role glyph, name, live elapsed, spawn-count pill, status
-dot, progress bar) and a live 1s clock for running nodes. Clicking a node calls
-`onSelect`; `ChatDetail` maps it back to the issuing turn via
-`findTurnIndexForRun`, switches to the thread, and scrolls there. Styles live in
-scoped `agent-canvas.css` (`.agent-canvas`, light/dark via `.dark`); there is no
-clock scrubber (the prototype's replay control is dropped — the real view is
+takes over. The toolbar's % is a dropdown of preset levels
+(25/50/75/100/150/200% + Fit) backed by `useZoomPan`'s `zoomTo(scale)`
+(zooms about the viewport center); the Fit button zooms to fit the whole tree.
+It renders curved SVG edges + node cards (role glyph, name, live elapsed,
+spawn-count pill, status dot, progress bar) and a live 1s clock for running
+nodes. Clicking a sub-agent node opens `AgentInspector` — a right-side panel
+with the run's role/status/elapsed, the task prompt, its result, and its
+children (clickable to drill in); clicking the orchestrator root closes it.
+`AgentCanvas` owns the selection; the inspector's "Open in thread" button calls
+`onOpenInThread`, which `ChatDetail` maps back to the issuing turn via
+`findTurnIndexForRun`, switching to the thread and scrolling there.
+`buildAgentRunTreeFromTurns` also captures each run's `prompt` and `result` for
+the inspector. Styles live in scoped `agent-canvas.css` (`.agent-canvas`,
+light/dark via `.dark`); there is no clock scrubber (the prototype's replay
+control is dropped — the real view is
 live). Distinct from the co-edited `CanvasPanel` side panel.
 
 ## Tool Call Rendering
diff --git a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
index 8956375cf..41c5f480c 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/ChatDetail.tsx
@@ -186,7 +186,6 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
     // shared/bookmarked URL reopens straight into the canvas.
     const hashViewSync = variant === 'inline' && !standalone;
     const [view, setView] = useState<ChatView>(() => (hashViewSync ? (readChatViewFromHash(window.location.hash) ?? 'thread') : 'thread'));
-    const [selectedAgentId, setSelectedAgentId] = useState<string | null>(null);
     const [pendingScrollTurn, setPendingScrollTurn] = useState<number | null>(null);
     const [noteEdits, setNoteEdits] = useState<Array<{
         editId: string; notePath: string; preEditContent: string;
@@ -319,9 +318,9 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
         status: effectiveStatus,
     }), [turns, task?.customTitle, task?.title, task?.displayName, title, effectiveStatus]);
 
-    // Clicking a canvas node jumps to the matching turn in the thread.
-    const handleAgentSelect = useCallback((node: AgentRunNode) => {
-        setSelectedAgentId(node.id);
+    // The inspector's "Open in thread" action: switch to the thread and scroll
+    // to the run's turn.
+    const openAgentInThread = useCallback((node: AgentRunNode) => {
         const idx = node.isRoot
             ? (turnsRef.current[0]?.turnIndex ?? 0)
             : findTurnIndexForRun(turnsRef.current, node.id);
@@ -477,7 +476,6 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
             return;
         }
         setView(hashViewSync ? (readChatViewFromHash(window.location.hash) ?? 'thread') : 'thread');
-        setSelectedAgentId(null);
         setPendingScrollTurn(null);
     }, [taskId]); // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -1704,7 +1702,7 @@ export function ChatDetail({ taskId, onBack, workspaceId, isPopOut = false, vari
                     {/* Inner row: ConversationArea + MiniMap, or the Agents canvas */}
                     <div className="relative flex flex-1 min-h-0 overflow-hidden min-w-0">
                     {view === 'agents' ? (
-                    <AgentCanvas root={agentRoot} selectedId={selectedAgentId} onSelect={handleAgentSelect} />
+                    <AgentCanvas root={agentRoot} onOpenInThread={openAgentInThread} />
                     ) : (
                     <>
                     <ConversationArea
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
index 85541a0f5..195c9f7c6 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentCanvas.tsx
@@ -1,26 +1,39 @@
 // AgentCanvas — a pannable / zoomable spatial map of a chat's recursive
 // sub-agent runs. The orchestrator root branches left→right into its
-// sub-agents, recursively. Driven by live run status; clicking a node calls
-// onSelect (the host scrolls the thread to the matching turn).
+// sub-agents, recursively. Driven by live run status; clicking a node opens an
+// inspector with that run's details (clicking the root closes it).
 //
 // Ported from the coc-chat design (agent-canvas.jsx), with pan/zoom delegated
 // to the repo's shared useZoomPan hook and the prototype's clock scrubber
 // dropped (the real app is live-streaming, not replayable).
 
-import { useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
 import { useZoomPan } from '../../../hooks/ui/useZoomPan';
 import { buildLayout, edgePath, spineVars, PAD, type PositionedNode } from './layout';
 import type { AgentRunNode } from './types';
 import { AcIcons, roleIcon } from './icons';
+import { AgentInspector } from './AgentInspector';
 import './agent-canvas.css';
 
 export interface AgentCanvasProps {
     /** The orchestrator root whose subtree is the agent run tree. */
     root: AgentRunNode;
-    /** Currently selected run id (highlighted), or null. */
-    selectedId?: string | null;
-    /** Called when a node is clicked. */
-    onSelect?: (node: AgentRunNode) => void;
+    /** Jump to a run's turn in the linear thread (the inspector's "Open in thread"). */
+    onOpenInThread?: (node: AgentRunNode) => void;
+}
+
+/** Depth-first lookup of a node by id within the run tree. */
+function findNode(node: AgentRunNode, id: string): AgentRunNode | null {
+    if (node.id === id) {
+        return node;
+    }
+    for (const child of node.children || []) {
+        const found = findNode(child, id);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
 }
 
 // Preset zoom levels offered by the % menu (within useZoomPan's 25%–220% range).
@@ -49,9 +62,9 @@ function nodeTimeText(node: AgentRunNode, now: number): string {
     }
     switch (node.status) {
         case 'running':
-            return node.startedAt ? fmtDuration((now || node.startedAt) - node.startedAt) : 'running';
+            return node.startedAt !== undefined ? fmtDuration((now || node.startedAt) - node.startedAt) : 'running';
         case 'done':
-            return node.startedAt && node.completedAt ? fmtDuration(node.completedAt - node.startedAt) : 'done';
+            return node.startedAt !== undefined && node.completedAt !== undefined ? fmtDuration(node.completedAt - node.startedAt) : 'done';
         case 'failed':
             return 'failed';
         case 'queued':
@@ -104,9 +117,18 @@ function CanvasNode({ entry, selected, onSelect, now }: {
     );
 }
 
-export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
+export function AgentCanvas({ root, onOpenInThread }: AgentCanvasProps) {
     const layout = useMemo(() => buildLayout(root), [root]);
 
+    // Selected run drives the inspector. Resolve from the live tree so a node
+    // that disappears (e.g. tree changes) simply closes the panel.
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+    const selectedNode = useMemo(() => (selectedId ? findNode(root, selectedId) : null), [root, selectedId]);
+    const handleNodeClick = useCallback((node: AgentRunNode) => {
+        // The root (orchestrator) closes the inspector; a sub-agent opens it.
+        setSelectedId(node.isRoot ? null : node.id);
+    }, []);
+
     const { containerRef, state, zoomIn, zoomOut, fitToView, centerContent, zoomTo, zoomLabel } = useZoomPan({
         contentWidth: layout.worldW,
         contentHeight: layout.worldH,
@@ -211,7 +233,7 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
                         entry={layout.pos[id]}
                         now={now}
                         selected={selectedId === id}
-                        onSelect={onSelect}
+                        onSelect={handleNodeClick}
                     />
                 ))}
             </div>
@@ -223,6 +245,16 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
                 </div>
             )}
 
+            {selectedNode && (
+                <AgentInspector
+                    node={selectedNode}
+                    now={now}
+                    onClose={() => setSelectedId(null)}
+                    onSelectChild={(child) => setSelectedId(child.id)}
+                    onOpenInThread={onOpenInThread}
+                />
+            )}
+
             <div className="canvas-toolbar" data-no-drag>
                 <button type="button" onClick={zoomOut} title="Zoom out"><AcIcons.Collapse size={14} /></button>
                 <span className="cz-wrap">
@@ -273,12 +305,14 @@ export function AgentCanvas({ root, selectedId, onSelect }: AgentCanvasProps) {
                 </button>
             </div>
 
-            <div className="canvas-legend" data-no-drag>
-                <span className="cl-item"><span className="cl-dot" data-status="running" />running</span>
-                <span className="cl-item"><span className="cl-dot" data-status="done" />done</span>
-                <span className="cl-item"><span className="cl-dot" data-status="queued" />queued</span>
-                <span className="cl-hint">drag to pan · scroll to zoom</span>
-            </div>
+            {!selectedNode && (
+                <div className="canvas-legend" data-no-drag>
+                    <span className="cl-item"><span className="cl-dot" data-status="running" />running</span>
+                    <span className="cl-item"><span className="cl-dot" data-status="done" />done</span>
+                    <span className="cl-item"><span className="cl-dot" data-status="queued" />queued</span>
+                    <span className="cl-hint">drag to pan · scroll to zoom</span>
+                </div>
+            )}
         </div>
     );
 }
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
new file mode 100644
index 000000000..7aac1e465
--- /dev/null
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
@@ -0,0 +1,124 @@
+// AgentInspector — a right-side detail panel for a selected run on the Agents
+// canvas. Shows the run's role/status/timing, the task it was handed, its
+// result/conclusion, and its spawned children (clickable to drill in).
+
+import { AcIcons, roleIcon } from './icons';
+import type { AgentRunNode, AgentRunStatus } from './types';
+
+const STATUS_LABEL: Record<AgentRunStatus, string> = {
+    running: 'Running',
+    done: 'Done',
+    failed: 'Failed',
+    queued: 'Queued',
+};
+
+function fmtDuration(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000));
+    const m = Math.floor(s / 60);
+    return `${m}:${String(s % 60).padStart(2, '0')}`;
+}
+
+function durationText(node: AgentRunNode, now: number): string | null {
+    if (node.status === 'running' && node.startedAt !== undefined) {
+        return fmtDuration((now || node.startedAt) - node.startedAt);
+    }
+    if (node.startedAt !== undefined && node.completedAt !== undefined) {
+        return fmtDuration(node.completedAt - node.startedAt);
+    }
+    return null;
+}
+
+function resultText(node: AgentRunNode): string {
+    if (node.result) {
+        return node.result;
+    }
+    if (node.status === 'running') {
+        return 'Running…';
+    }
+    if (node.status === 'queued') {
+        return 'Queued — waiting for a worker.';
+    }
+    return 'No result recorded.';
+}
+
+export interface AgentInspectorProps {
+    node: AgentRunNode;
+    /** Live clock (epoch ms) so a running node's elapsed time ticks. */
+    now: number;
+    onClose: () => void;
+    /** Select a child run (drill in). */
+    onSelectChild?: (node: AgentRunNode) => void;
+    /** Jump to this run's turn in the linear thread. */
+    onOpenInThread?: (node: AgentRunNode) => void;
+}
+
+export function AgentInspector({ node, now, onClose, onSelectChild, onOpenInThread }: AgentInspectorProps) {
+    const isRoot = !!node.isRoot;
+    const RoleIcon = isRoot ? AcIcons.Orchestr : roleIcon(node.role);
+    const kids = node.children || [];
+    const dur = durationText(node, now);
+    const terminal = node.status === 'done' || node.status === 'failed';
+
+    return (
+        <aside className="agent-inspector" data-testid="agent-inspector" data-no-drag>
+            <div className="ai-head">
+                <span className="ai-badge"><RoleIcon size={16} /></span>
+                <div className="ai-title">
+                    <div className="ai-name" title={node.name}>{node.name}</div>
+                    <div className="ai-role">{isRoot ? 'orchestrator' : node.role}</div>
+                </div>
+                <button type="button" className="ai-close" onClick={onClose} title="Close" aria-label="Close inspector">
+                    <AcIcons.X size={14} />
+                </button>
+            </div>
+
+            <div className="ai-meta">
+                <span className="ai-pill" data-status={node.status}>
+                    <span className="ai-dot" data-status={node.status} />{STATUS_LABEL[node.status]}
+                </span>
+                {dur && <span className="ai-stat"><AcIcons.Clock size={12} />{dur}</span>}
+                {kids.length > 0 && <span className="ai-stat"><AcIcons.Spawn size={12} />{kids.length} spawned</span>}
+            </div>
+
+            {node.prompt && (
+                <section className="ai-section">
+                    <h4>Task</h4>
+                    <p className="ai-text">{node.prompt}</p>
+                </section>
+            )}
+
+            {!isRoot && (
+                <section className="ai-section">
+                    <h4>{terminal ? 'Result' : 'Status'}</h4>
+                    <p className="ai-text">{resultText(node)}</p>
+                </section>
+            )}
+
+            {kids.length > 0 && (
+                <section className="ai-section">
+                    <h4>Sub-agents · {kids.length}</h4>
+                    <ul className="ai-children">
+                        {kids.map((k) => {
+                            const KidIcon = roleIcon(k.role);
+                            return (
+                                <li key={k.id}>
+                                    <button type="button" onClick={() => onSelectChild?.(k)} data-testid={`agent-inspector-child-${k.id}`}>
+                                        <span className="ai-cbadge"><KidIcon size={12} /></span>
+                                        <span className="ai-cname" title={k.name}>{k.name}</span>
+                                        <span className="ai-cstate" data-status={k.status} />
+                                    </button>
+                                </li>
+                            );
+                        })}
+                    </ul>
+                </section>
+            )}
+
+            {onOpenInThread && !isRoot && (
+                <button type="button" className="ai-open-thread" onClick={() => onOpenInThread(node)} data-testid="agent-inspector-open-thread">
+                    <AcIcons.Thread size={13} />Open in thread
+                </button>
+            )}
+        </aside>
+    );
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
index 082ffccc7..0708826c7 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
@@ -423,3 +423,233 @@
     color: var(--muted);
     font-weight: 600;
 }
+
+/* Inspector — right-side detail panel for a selected run. */
+.agent-canvas .agent-inspector {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    width: 340px;
+    max-width: 86%;
+    display: flex;
+    flex-direction: column;
+    background: var(--panel);
+    border-left: 1px solid var(--border);
+    box-shadow: -8px 0 24px rgb(20 30 60 / 0.10);
+    overflow-y: auto;
+    z-index: 6;
+    cursor: default;
+}
+
+.agent-canvas .agent-inspector .ai-head {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 14px 14px 12px;
+    border-bottom: 1px solid var(--border);
+    position: sticky;
+    top: 0;
+    background: var(--panel);
+}
+
+.agent-canvas .agent-inspector .ai-badge {
+    width: 30px;
+    height: 30px;
+    border-radius: 8px;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--spine-soft);
+    color: var(--accent);
+}
+
+.agent-canvas .agent-inspector .ai-title {
+    min-width: 0;
+    flex: 1;
+}
+
+.agent-canvas .agent-inspector .ai-name {
+    font-size: 13.5px;
+    font-weight: 600;
+    color: var(--text);
+    letter-spacing: -0.01em;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.agent-canvas .agent-inspector .ai-role {
+    font-size: 10.5px;
+    font-family: var(--font-mono);
+    color: var(--accent);
+    margin-top: 1px;
+}
+
+.agent-canvas .agent-inspector .ai-close {
+    flex-shrink: 0;
+    width: 26px;
+    height: 26px;
+    border-radius: 6px;
+    border: none;
+    background: transparent;
+    color: var(--muted);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.agent-canvas .agent-inspector .ai-close:hover {
+    background: var(--hover);
+    color: var(--text);
+}
+
+.agent-canvas .agent-inspector .ai-meta {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px;
+    padding: 12px 14px;
+}
+
+.agent-canvas .agent-inspector .ai-pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11px;
+    font-weight: 600;
+    padding: 3px 9px;
+    border-radius: 999px;
+    background: var(--hover);
+    color: var(--muted);
+}
+
+.agent-canvas .agent-inspector .ai-dot {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+}
+
+.agent-canvas .agent-inspector .ai-dot[data-status="running"] { background: var(--accent); }
+.agent-canvas .agent-inspector .ai-dot[data-status="done"] { background: var(--success); }
+.agent-canvas .agent-inspector .ai-dot[data-status="failed"] { background: var(--danger); }
+.agent-canvas .agent-inspector .ai-dot[data-status="queued"] { background: var(--faint); }
+
+.agent-canvas .agent-inspector .ai-stat {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    font-size: 11px;
+    font-family: var(--font-mono);
+    color: var(--muted);
+}
+
+.agent-canvas .agent-inspector .ai-stat svg { opacity: 0.8; }
+
+.agent-canvas .agent-inspector .ai-section {
+    padding: 2px 14px 14px;
+    border-top: 1px solid var(--border);
+}
+
+.agent-canvas .agent-inspector .ai-section h4 {
+    margin: 12px 0 6px;
+    font-size: 10.5px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--faint);
+}
+
+.agent-canvas .agent-inspector .ai-text {
+    font-size: 12.5px;
+    line-height: 1.5;
+    color: var(--text);
+    white-space: pre-wrap;
+    word-break: break-word;
+    margin: 0;
+}
+
+.agent-canvas .agent-inspector .ai-children {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+}
+
+.agent-canvas .agent-inspector .ai-children button {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+    text-align: left;
+    border: 1px solid var(--border);
+    background: var(--panel);
+    border-radius: 8px;
+    padding: 7px 9px;
+    cursor: pointer;
+}
+
+.agent-canvas .agent-inspector .ai-children button:hover {
+    background: var(--hover);
+    border-color: var(--border-strong);
+}
+
+.agent-canvas .agent-inspector .ai-cbadge {
+    width: 20px;
+    height: 20px;
+    border-radius: 5px;
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--spine-soft);
+    color: var(--accent);
+}
+
+.agent-canvas .agent-inspector .ai-cname {
+    flex: 1;
+    min-width: 0;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--text);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.agent-canvas .agent-inspector .ai-cstate {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    flex-shrink: 0;
+}
+
+.agent-canvas .agent-inspector .ai-cstate[data-status="running"] { background: var(--accent); }
+.agent-canvas .agent-inspector .ai-cstate[data-status="done"] { background: var(--success); }
+.agent-canvas .agent-inspector .ai-cstate[data-status="failed"] { background: var(--danger); }
+.agent-canvas .agent-inspector .ai-cstate[data-status="queued"] { background: var(--faint); }
+
+.agent-canvas .agent-inspector .ai-open-thread {
+    margin: 4px 14px 16px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 7px;
+    border: 1px solid var(--border);
+    background: var(--panel);
+    color: var(--text);
+    border-radius: 8px;
+    padding: 9px;
+    font-size: 12px;
+    font-weight: 500;
+    cursor: pointer;
+}
+
+.agent-canvas .agent-inspector .ai-open-thread:hover {
+    background: var(--hover);
+    border-color: var(--border-strong);
+}
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
index ee40b6134..08f264048 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -141,9 +141,7 @@ function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
     const name = description
         || (prompt ? (prompt.length > 48 ? `${prompt.slice(0, 45).trimEnd()}…` : prompt) : '')
         || 'sub-agent';
-    const summary = typeof tc.result === 'string' && tc.result.trim()
-        ? firstLine(tc.result)
-        : undefined;
+    const result = typeof tc.result === 'string' && tc.result.trim() ? tc.result.trim() : undefined;
     return {
         id: tc.id,
         name,
@@ -151,7 +149,9 @@ function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
         status: mapToolStatus(tc.status),
         startedAt: parseTime(tc.startTime),
         completedAt: parseTime(tc.endTime),
-        summary,
+        summary: result ? firstLine(result) : undefined,
+        prompt: prompt || undefined,
+        result,
         children: [],
     };
 }
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
index 4379b16e4..849b35aa7 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/icons.tsx
@@ -42,6 +42,8 @@ export const AcIcons = {
 
     // ── canvas controls / nav ──
     Spawn: mk(<><circle cx="4" cy="4" r="1.5" /><circle cx="4" cy="12" r="1.5" /><circle cx="12" cy="12" r="1.5" /><path d="M4 5.5v3a2 2 0 002 2h4.2M4 9.4h.01" /><path d="M10 10.5l2 1.5" /></>),
+    Clock: mk(<><circle cx="8" cy="8" r="5.5" /><path d="M8 5v3.2l2 1.3" /></>),
+    X: mk(<><path d="M4 4l8 8M12 4l-8 8" /></>),
     Expand: mk(<><path d="M9.5 2.5H13.5V6.5M6.5 13.5H2.5V9.5M13.5 2.5l-4.5 4.5M2.5 13.5l4.5-4.5" /></>),
     Collapse: mk(<><path d="M13 3l-3.5 3.5M9.5 6.5V3M9.5 6.5H13M3 13l3.5-3.5M6.5 9.5V13M6.5 9.5H3" /></>),
     Replay: mk(<><path d="M3 8a5 5 0 105-5 5 5 0 00-3.6 1.5L3 5" /><path d="M3 2.5V5h2.5" /></>),
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
index 909e6f9de..483f88a77 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
@@ -24,6 +24,10 @@ export interface AgentRunNode {
     completedAt?: number;
     /** One-line summary / conclusion, if available. */
     summary?: string;
+    /** Full task/instruction handed to this sub-agent (the Task tool's prompt). */
+    prompt?: string;
+    /** Full result/output the run produced, if available. */
+    result?: string;
     /** Recursively spawned child runs. */
     children: AgentRunNode[];
 }
diff --git a/packages/coc/test/spa/react/AgentCanvas.test.tsx b/packages/coc/test/spa/react/AgentCanvas.test.tsx
index c487d6f98..d4b84b543 100644
--- a/packages/coc/test/spa/react/AgentCanvas.test.tsx
+++ b/packages/coc/test/spa/react/AgentCanvas.test.tsx
@@ -36,18 +36,39 @@ describe('AgentCanvas', () => {
         expect(screen.getByTestId('agent-canvas-node-root')).toBeTruthy();
     });
 
-    it('calls onSelect with the clicked node', () => {
-        const onSelect = vi.fn();
-        render(<AgentCanvas root={tree([sub('explore')])} onSelect={onSelect} />);
+    it('opens the inspector with the clicked sub-agent details and highlights the node', () => {
+        render(<AgentCanvas root={tree([sub('explore', { name: 'map data', prompt: 'go map it', result: 'mapped ok' })])} />);
+        expect(screen.queryByTestId('agent-inspector')).toBeNull();
         fireEvent.click(screen.getByTestId('agent-canvas-node-explore'));
-        expect(onSelect).toHaveBeenCalledTimes(1);
-        expect(onSelect.mock.calls[0][0]).toMatchObject({ id: 'explore' });
+        const inspector = screen.getByTestId('agent-inspector');
+        expect(within(inspector).getByText('map data')).toBeTruthy();
+        expect(within(inspector).getByText('go map it')).toBeTruthy();
+        expect(within(inspector).getByText('mapped ok')).toBeTruthy();
+        expect(screen.getByTestId('agent-canvas-node-explore').className).toContain('sel');
     });
 
-    it('marks the selected node with the sel class', () => {
-        render(<AgentCanvas root={tree([sub('explore')])} selectedId="explore" />);
-        expect(screen.getByTestId('agent-canvas-node-explore').className).toContain('sel');
-        expect(screen.getByTestId('agent-canvas-node-root').className).not.toContain('sel');
+    it('closes the inspector when the root node is clicked', () => {
+        render(<AgentCanvas root={tree([sub('explore')])} />);
+        fireEvent.click(screen.getByTestId('agent-canvas-node-explore'));
+        expect(screen.getByTestId('agent-inspector')).toBeTruthy();
+        fireEvent.click(screen.getByTestId('agent-canvas-node-root'));
+        expect(screen.queryByTestId('agent-inspector')).toBeNull();
+    });
+
+    it('closes the inspector via the close button', () => {
+        render(<AgentCanvas root={tree([sub('explore')])} />);
+        fireEvent.click(screen.getByTestId('agent-canvas-node-explore'));
+        fireEvent.click(within(screen.getByTestId('agent-inspector')).getByLabelText('Close inspector'));
+        expect(screen.queryByTestId('agent-inspector')).toBeNull();
+    });
+
+    it('calls onOpenInThread from the inspector', () => {
+        const onOpenInThread = vi.fn();
+        render(<AgentCanvas root={tree([sub('explore')])} onOpenInThread={onOpenInThread} />);
+        fireEvent.click(screen.getByTestId('agent-canvas-node-explore'));
+        fireEvent.click(screen.getByTestId('agent-inspector-open-thread'));
+        expect(onOpenInThread).toHaveBeenCalledTimes(1);
+        expect(onOpenInThread.mock.calls[0][0]).toMatchObject({ id: 'explore' });
     });
 
     it('renders the zoom toolbar with a percentage label', () => {
diff --git a/packages/coc/test/spa/react/AgentInspector.test.tsx b/packages/coc/test/spa/react/AgentInspector.test.tsx
new file mode 100644
index 000000000..deabab6e2
--- /dev/null
+++ b/packages/coc/test/spa/react/AgentInspector.test.tsx
@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { AgentInspector } from '../../../src/server/spa/client/react/features/chat/agent-canvas/AgentInspector';
+import type { AgentRunNode } from '../../../src/server/spa/client/react/features/chat/agent-canvas/types';
+
+function node(overrides: Partial<AgentRunNode> = {}): AgentRunNode {
+    return { id: 'r1', name: 'explore-thing', role: 'Explore', status: 'done', children: [], ...overrides };
+}
+
+describe('AgentInspector', () => {
+    it('renders name, role, status, duration, task and result for a finished run', () => {
+        render(<AgentInspector node={node({ prompt: 'do the thing', result: 'did it', startedAt: 1000, completedAt: 10000 })} now={0} onClose={vi.fn()} />);
+        expect(screen.getByText('explore-thing')).toBeTruthy();
+        expect(screen.getByText('Explore')).toBeTruthy();
+        expect(screen.getByText('Done')).toBeTruthy();
+        expect(screen.getByText('0:09')).toBeTruthy(); // (9000-0)ms
+        expect(screen.getByText('do the thing')).toBeTruthy();
+        expect(screen.getByText('did it')).toBeTruthy();
+    });
+
+    it('shows a running placeholder when there is no result yet', () => {
+        render(<AgentInspector node={node({ status: 'running', startedAt: 1000 })} now={1000} onClose={vi.fn()} />);
+        expect(screen.getByText('Running…')).toBeTruthy();
+    });
+
+    it('shows a queued message for queued runs', () => {
+        render(<AgentInspector node={node({ status: 'queued' })} now={0} onClose={vi.fn()} />);
+        expect(screen.getByText(/waiting for a worker/)).toBeTruthy();
+    });
+
+    it('lists children and drills into one when clicked', () => {
+        const onSelectChild = vi.fn();
+        const root: AgentRunNode = {
+            id: 'root', name: 'CoC', role: 'orchestrator', status: 'running', isRoot: true,
+            children: [node({ id: 'a', name: 'child-a' }), node({ id: 'b', name: 'child-b' })],
+        };
+        render(<AgentInspector node={root} now={0} onClose={vi.fn()} onSelectChild={onSelectChild} />);
+        expect(screen.getByText('child-a')).toBeTruthy();
+        fireEvent.click(screen.getByTestId('agent-inspector-child-b'));
+        expect(onSelectChild).toHaveBeenCalledTimes(1);
+        expect(onSelectChild.mock.calls[0][0]).toMatchObject({ id: 'b' });
+    });
+
+    it('calls onClose from the close button', () => {
+        const onClose = vi.fn();
+        render(<AgentInspector node={node()} now={0} onClose={onClose} />);
+        fireEvent.click(screen.getByLabelText('Close inspector'));
+        expect(onClose).toHaveBeenCalledTimes(1);
+    });
+
+    it('hides the result section and Open-in-thread for the orchestrator root', () => {
+        const onOpenInThread = vi.fn();
+        const root: AgentRunNode = {
+            id: 'root', name: 'CoC', role: 'orchestrator', status: 'running', isRoot: true, children: [],
+        };
+        render(<AgentInspector node={root} now={0} onClose={vi.fn()} onOpenInThread={onOpenInThread} />);
+        expect(screen.queryByTestId('agent-inspector-open-thread')).toBeNull();
+        expect(screen.queryByText('Result')).toBeNull();
+    });
+});

From 634b13573d1059ba25ca4ed5a700e21cffc60bdb Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 15:53:54 -0700
Subject: [PATCH 09/11] feat(coc): show sub-agent name/type/model/mode in the
 inspector

The Task tool's args carry richer fields than were surfaced. Capture and
display them:

- buildAgentRunTree: read `name` (the agent's name) as the node title
  (falling back to description/prompt), plus `model`, `mode`, and keep
  `description` when it adds something beyond the name.
- AgentInspector: add a details list (Model / Mode / Summary) under the
  status meta. Type is the role shown in the header, name is the title.

So a node like { name: "time-agent-1", agent_type: "explore",
model: "claude-sonnet-4.6", mode: "background", description: "Query
current time" } now reads clearly in the panel.

Tests cover the new arg capture (name title, model/mode/description) and
the inspector rendering them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../coc-knowledge/references/dashboard-spa.md | 15 ++++----
 .../chat/agent-canvas/AgentInspector.tsx      |  8 +++++
 .../chat/agent-canvas/agent-canvas.css        | 25 +++++++++++++
 .../chat/agent-canvas/buildAgentRunTree.ts    | 24 +++++++++----
 .../react/features/chat/agent-canvas/types.ts |  8 ++++-
 .../spa/client/agent-canvas-data.test.ts      | 35 +++++++++++++++++++
 .../test/spa/react/AgentInspector.test.tsx    | 13 +++++++
 7 files changed, 115 insertions(+), 13 deletions(-)

diff --git a/.github/skills/coc-knowledge/references/dashboard-spa.md b/.github/skills/coc-knowledge/references/dashboard-spa.md
index 7fb39b3a8..eb3fd223e 100644
--- a/.github/skills/coc-knowledge/references/dashboard-spa.md
+++ b/.github/skills/coc-knowledge/references/dashboard-spa.md
@@ -314,8 +314,11 @@ strips the `?query` so the param never corrupts the taskId. `view` resets to
 
 `buildAgentRunTreeFromTurns(turns, root)` derives the tree with no extra fetch:
 the orchestrator (this process) is the root and each `Task` tool call becomes a
-sub-agent child (name/role from args, status/timing from the call), deduped
-across `toolCalls`+timeline and ordered by start time. Tool name/args are read
+sub-agent child. From the call's args it captures the agent name (`args.name`,
+falling back to `description`/`prompt`), type (`agent_type`/`subagent_type`),
+`model`, `mode`, `description`, and `prompt`; status/timing come from the call.
+Children are deduped across `toolCalls`+timeline and ordered by start time.
+Tool name/args are read
 via `toolName ?? name` and `args ?? parameters` so sub-agents are detected in
 both the live (SSE) shape and the persisted forge read model — they stay on the
 canvas after the chat completes and turns refresh. The `AgentRunNode` tree
@@ -328,13 +331,13 @@ takes over. The toolbar's % is a dropdown of preset levels
 It renders curved SVG edges + node cards (role glyph, name, live elapsed,
 spawn-count pill, status dot, progress bar) and a live 1s clock for running
 nodes. Clicking a sub-agent node opens `AgentInspector` — a right-side panel
-with the run's role/status/elapsed, the task prompt, its result, and its
-children (clickable to drill in); clicking the orchestrator root closes it.
+with the run's name/type/status/elapsed, a details list (model, mode, summary),
+the task prompt, its result, and its children (clickable to drill in); clicking
+the orchestrator root closes it.
 `AgentCanvas` owns the selection; the inspector's "Open in thread" button calls
 `onOpenInThread`, which `ChatDetail` maps back to the issuing turn via
 `findTurnIndexForRun`, switching to the thread and scrolling there.
-`buildAgentRunTreeFromTurns` also captures each run's `prompt` and `result` for
-the inspector. Styles live in scoped `agent-canvas.css` (`.agent-canvas`,
+Styles live in scoped `agent-canvas.css` (`.agent-canvas`,
 light/dark via `.dark`); there is no clock scrubber (the prototype's replay
 control is dropped — the real view is
 live). Distinct from the co-edited `CanvasPanel` side panel.
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
index 7aac1e465..5a3e3302f 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/AgentInspector.tsx
@@ -80,6 +80,14 @@ export function AgentInspector({ node, now, onClose, onSelectChild, onOpenInThre
                 {kids.length > 0 && <span className="ai-stat"><AcIcons.Spawn size={12} />{kids.length} spawned</span>}
             </div>
 
+            {(node.model || node.mode || node.description) && (
+                <dl className="ai-fields">
+                    {node.model && (<><dt>Model</dt><dd>{node.model}</dd></>)}
+                    {node.mode && (<><dt>Mode</dt><dd>{node.mode}</dd></>)}
+                    {node.description && (<><dt>Summary</dt><dd>{node.description}</dd></>)}
+                </dl>
+            )}
+
             {node.prompt && (
                 <section className="ai-section">
                     <h4>Task</h4>
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
index 0708826c7..6085a947f 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/agent-canvas.css
@@ -548,6 +548,31 @@
 
 .agent-canvas .agent-inspector .ai-stat svg { opacity: 0.8; }
 
+.agent-canvas .agent-inspector .ai-fields {
+    margin: 0;
+    padding: 0 14px 12px;
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: 5px 12px;
+    align-items: baseline;
+}
+
+.agent-canvas .agent-inspector .ai-fields dt {
+    font-size: 10.5px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--faint);
+}
+
+.agent-canvas .agent-inspector .ai-fields dd {
+    margin: 0;
+    font-size: 12px;
+    color: var(--text);
+    font-family: var(--font-mono);
+    word-break: break-word;
+}
+
 .agent-canvas .agent-inspector .ai-section {
     padding: 2px 14px 14px;
     border-top: 1px solid var(--border);
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
index 08f264048..a6678a926 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -130,15 +130,23 @@ function rawArgs(tc: ClientToolCall): unknown {
     return tc.args ?? (tc as { parameters?: unknown }).parameters;
 }
 
+function asString(v: unknown): string {
+    return typeof v === 'string' ? v.trim() : '';
+}
+
 /** Build a sub-agent node from a normalized `Task` tool call. */
 function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
     const args = asRecord(rawArgs(tc));
-    const agentType = typeof args.agent_type === 'string' ? args.agent_type
-        : typeof args.subagent_type === 'string' ? args.subagent_type
-            : '';
-    const description = typeof args.description === 'string' ? args.description.trim() : '';
-    const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
-    const name = description
+    const agentType = asString(args.agent_type) || asString(args.subagent_type);
+    const agentName = asString(args.name);
+    const description = asString(args.description);
+    const prompt = asString(args.prompt);
+    const model = asString(args.model);
+    const mode = asString(args.mode);
+    // Prefer the explicit agent name; fall back to the description, then a
+    // truncated prompt.
+    const name = agentName
+        || description
         || (prompt ? (prompt.length > 48 ? `${prompt.slice(0, 45).trimEnd()}…` : prompt) : '')
         || 'sub-agent';
     const result = typeof tc.result === 'string' && tc.result.trim() ? tc.result.trim() : undefined;
@@ -146,6 +154,10 @@ function nodeFromTaskCall(tc: ClientToolCall): AgentRunNode {
         id: tc.id,
         name,
         role: agentType || 'agent',
+        // Keep the description only when it adds something beyond the name.
+        description: description && description !== name ? description : undefined,
+        model: model || undefined,
+        mode: mode || undefined,
         status: mapToolStatus(tc.status),
         startedAt: parseTime(tc.startTime),
         completedAt: parseTime(tc.endTime),
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
index 483f88a77..cc4326e15 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/types.ts
@@ -13,8 +13,14 @@ export interface AgentRunNode {
     id: string;
     /** Display name: the sub-agent's description (or a truncated prompt). */
     name: string;
-    /** Role label: the sub-agent type (e.g. 'Explore'), or 'orchestrator' for the root. */
+    /** Role label: the sub-agent type (e.g. 'explore'), or 'orchestrator' for the root. */
     role: string;
+    /** Short description of the run's task, when distinct from the name. */
+    description?: string;
+    /** Model the sub-agent runs on (e.g. 'claude-sonnet-4.6'), if specified. */
+    model?: string;
+    /** Execution mode (e.g. 'background'), if specified. */
+    mode?: string;
     status: AgentRunStatus;
     /** True only for the synthetic orchestrator root. */
     isRoot?: boolean;
diff --git a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
index 7b7b6a4b2..997da19b4 100644
--- a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
+++ b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
@@ -72,6 +72,41 @@ describe('buildAgentRunTreeFromTurns', () => {
         expect(buildAgentRunTreeFromTurns(turns).children[0].role).toBe('rust-code-reviewer');
     });
 
+    it('captures name, type, model, mode and description from Task args', () => {
+        const turns = [assistantTurn([tc({
+            id: 't1',
+            status: 'running',
+            args: {
+                agent_type: 'explore',
+                name: 'time-agent-1',
+                description: 'Query current time',
+                model: 'claude-sonnet-4.6',
+                mode: 'background',
+                prompt: 'Query the current date and time.',
+            },
+        })])];
+        expect(buildAgentRunTreeFromTurns(turns).children[0]).toMatchObject({
+            id: 't1',
+            name: 'time-agent-1',
+            role: 'explore',
+            description: 'Query current time',
+            model: 'claude-sonnet-4.6',
+            mode: 'background',
+            prompt: 'Query the current date and time.',
+        });
+    });
+
+    it('uses the agent name as the title and drops a redundant description', () => {
+        // No explicit name → title falls back to description, which is then cleared
+        // so the inspector does not show it twice.
+        const child = buildAgentRunTreeFromTurns([
+            assistantTurn([tc({ id: 't1', args: { agent_type: 'explore', description: 'map data' } })]),
+        ]).children[0];
+        expect(child.name).toBe('map data');
+        expect(child.description).toBeUndefined();
+        expect(child.model).toBeUndefined();
+    });
+
     it('ignores non-Task tool calls', () => {
         const turns = [assistantTurn([
             tc({ id: 'r1', toolName: 'Read', args: { file_path: '/a.ts' } }),
diff --git a/packages/coc/test/spa/react/AgentInspector.test.tsx b/packages/coc/test/spa/react/AgentInspector.test.tsx
index deabab6e2..22e702c77 100644
--- a/packages/coc/test/spa/react/AgentInspector.test.tsx
+++ b/packages/coc/test/spa/react/AgentInspector.test.tsx
@@ -19,6 +19,19 @@ describe('AgentInspector', () => {
         expect(screen.getByText('did it')).toBeTruthy();
     });
 
+    it('shows the agent type, model, mode and summary', () => {
+        render(<AgentInspector
+            node={node({ name: 'time-agent-1', role: 'explore', model: 'claude-sonnet-4.6', mode: 'background', description: 'Query current time' })}
+            now={0}
+            onClose={vi.fn()}
+        />);
+        expect(screen.getByText('time-agent-1')).toBeTruthy();
+        expect(screen.getByText('explore')).toBeTruthy(); // type, shown as the role in the head
+        expect(screen.getByText('claude-sonnet-4.6')).toBeTruthy();
+        expect(screen.getByText('background')).toBeTruthy();
+        expect(screen.getByText('Query current time')).toBeTruthy();
+    });
+
     it('shows a running placeholder when there is no result yet', () => {
         render(<AgentInspector node={node({ status: 'running', startedAt: 1000 })} now={1000} onClose={vi.fn()} />);
         expect(screen.getByText('Running…')).toBeTruthy();

From f531fd2eade36177d301426f4c19163c6bca8433 Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 16:25:43 -0700
Subject: [PATCH 10/11] fix(coc): keep sub-agent name/model/type when
 tool-complete has empty args
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each Task call appears three times in a completed conversation: toolCalls
(full args), timeline tool-start (full args), and timeline tool-complete
(same terminal status, but EMPTY args). The dedup preferred the latest
equal-rank snapshot — the empty-args tool-complete — so every node fell
back to "sub-agent"/"agent" with no model/mode.

collectToolCalls now keeps whichever snapshot has non-empty args
(nonEmptyArgs helper), so the name/type/model/mode survive. Verified
against the live "3 subagents" chat: nodes now resolve to
time-agent-1/2/3 · explore · claude-sonnet-4.6 · background.

Regression test replicates the three-snapshot shape.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../coc-knowledge/references/dashboard-spa.md |  4 +++-
 .../chat/agent-canvas/buildAgentRunTree.ts    | 13 ++++++++++++
 .../spa/client/agent-canvas-data.test.ts      | 21 +++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/.github/skills/coc-knowledge/references/dashboard-spa.md b/.github/skills/coc-knowledge/references/dashboard-spa.md
index eb3fd223e..f7bdbdb93 100644
--- a/.github/skills/coc-knowledge/references/dashboard-spa.md
+++ b/.github/skills/coc-knowledge/references/dashboard-spa.md
@@ -317,7 +317,9 @@ the orchestrator (this process) is the root and each `Task` tool call becomes a
 sub-agent child. From the call's args it captures the agent name (`args.name`,
 falling back to `description`/`prompt`), type (`agent_type`/`subagent_type`),
 `model`, `mode`, `description`, and `prompt`; status/timing come from the call.
-Children are deduped across `toolCalls`+timeline and ordered by start time.
+Children are deduped across `toolCalls`+timeline — keeping the snapshot with
+non-empty args, since a terminal `tool-complete` often carries empty args while
+an earlier snapshot holds the full invocation — and ordered by start time.
 Tool name/args are read
 via `toolName ?? name` and `args ?? parameters` so sub-agents are detected in
 both the live (SSE) shape and the persisted forge read model — they stay on the
diff --git a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
index a6678a926..0a723eeb5 100644
--- a/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
+++ b/packages/coc/src/server/spa/client/react/features/chat/agent-canvas/buildAgentRunTree.ts
@@ -79,9 +79,14 @@ function collectToolCalls(turns: ClientConversationTurn[]): ClientToolCall[] {
         const keepNew = (STATUS_RANK[tc.status] ?? 0) >= (STATUS_RANK[existing.status] ?? 0);
         const better = keepNew ? tc : existing;
         const worse = keepNew ? existing : tc;
+        // The terminal snapshot (e.g. a timeline `tool-complete`) often carries
+        // EMPTY args while an earlier snapshot has the full invocation args —
+        // keep whichever args are non-empty so name/model/type survive.
+        const mergedArgs = nonEmptyArgs(better) ?? nonEmptyArgs(worse);
         byId.set(tc.id, {
             ...worse,
             ...better,
+            ...(mergedArgs ? { args: mergedArgs } : {}),
             startTime: better.startTime ?? worse.startTime,
             endTime: better.endTime ?? worse.endTime,
             result: better.result ?? worse.result,
@@ -130,6 +135,14 @@ function rawArgs(tc: ClientToolCall): unknown {
     return tc.args ?? (tc as { parameters?: unknown }).parameters;
 }
 
+/** The tool call's args (or parameters) only when it's a non-empty object. */
+function nonEmptyArgs(tc: ClientToolCall): Record<string, unknown> | undefined {
+    const a = rawArgs(tc);
+    return a && typeof a === 'object' && !Array.isArray(a) && Object.keys(a).length > 0
+        ? (a as Record<string, unknown>)
+        : undefined;
+}
+
 function asString(v: unknown): string {
     return typeof v === 'string' ? v.trim() : '';
 }
diff --git a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
index 997da19b4..cc3d90a7a 100644
--- a/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
+++ b/packages/coc/test/server/spa/client/agent-canvas-data.test.ts
@@ -151,6 +151,27 @@ describe('buildAgentRunTreeFromTurns', () => {
         expect(root.children[0].summary).toBe('all green');
     });
 
+    it('keeps full args when a later tool-complete snapshot has empty args', () => {
+        // Real shape: toolCalls + timeline tool-start carry full args, but the
+        // timeline tool-complete (same id, same terminal status) has empty args.
+        const fullArgs = {
+            agent_type: 'explore', name: 'time-agent-1',
+            model: 'claude-sonnet-4.6', mode: 'background', description: 'Query current time',
+        };
+        const turns = [assistantTurn(
+            [tc({ id: 't1', args: fullArgs, status: 'completed', result: 'ok' })],
+            [
+                { type: 'tool-start', timestamp: '2026-06-13T21:18:04.000Z', toolCall: tc({ id: 't1', args: fullArgs, status: 'running' }) },
+                { type: 'tool-complete', timestamp: '2026-06-13T21:18:09.000Z', toolCall: tc({ id: 't1', args: {}, status: 'completed', result: 'ok' }) },
+            ],
+        )];
+        const child = buildAgentRunTreeFromTurns(turns).children[0];
+        expect(child).toMatchObject({
+            id: 't1', name: 'time-agent-1', role: 'explore',
+            model: 'claude-sonnet-4.6', mode: 'background', status: 'done',
+        });
+    });
+
     it('derives root status from children when no explicit status is given', () => {
         const running = [assistantTurn([tc({ id: 't1', args: { description: 'x' }, status: 'running' })])];
         expect(buildAgentRunTreeFromTurns(running).status).toBe('running');

From 2f33236e7e196c6fa465b8209f12731e1f9cf02e Mon Sep 17 00:00:00 2001
From: Yiheng Tao <ruby092977@gmail.com>
Date: Sat, 13 Jun 2026 18:58:04 -0700
Subject: [PATCH 11/11] fix(coc): strip ?query from the hash before routing so
 deep-links work
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Router's hashchange handler split the raw hash into path parts
without removing a trailing `?query`, so a deep-link like
`#repos/<ws>/activity/<taskId>?view=agents` parsed the task id as
`<taskId>?view=agents` — the wrong id, which broke landing directly on
the Agents view (and any other `?`-carrying chat deep-link).

Strip the query once where the handler reads the hash, so every routed
segment (repoId, sub-tab, taskId) is clean. The query stays on
`location.hash`, so components that read it directly (ChatDetail's
`?view`, TaskPreview's `?mode`) still work. Mirrors the existing
`parseActivityDeepLink` query-strip (already tested).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/coc/src/server/spa/client/react/layout/Router.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/coc/src/server/spa/client/react/layout/Router.tsx b/packages/coc/src/server/spa/client/react/layout/Router.tsx
index 2ff13bcad..d2175af1a 100644
--- a/packages/coc/src/server/spa/client/react/layout/Router.tsx
+++ b/packages/coc/src/server/spa/client/react/layout/Router.tsx
@@ -508,7 +508,10 @@ export function Router() {
     // blank-page flash when navigating directly to a deep-link (e.g. on refresh).
     useLayoutEffect(() => {
         const handleHash = () => {
-            const hash = location.hash.replace(/^#/, '');
+            // Strip any `?query` (e.g. `?view=agents`) before parsing the path —
+            // it's metadata for components (which read it from location.hash
+            // directly), never part of the routed path or a task id.
+            const hash = location.hash.replace(/^#/, '').split('?')[0];
             const tab = tabFromHash('#' + hash);
             if (tab) {
                 dispatch({ type: 'SET_ACTIVE_TAB', tab });