Nested agent hierarchies: visual layer (#213, part 2 — WIP)

[cboos]

The visual layer for nested agent hierarchies — part 2 of #213 (part 1, the structural support, landed in #218). Rebased onto main; builds straight on the agent_depth the hierarchy pass now chases.

Four pieces, all driven by the per-message agent-nesting depth:

• Depth badge — a "Depth N" pill on a nested spawn card showing the depth of the sub-agent it opens (suppressed for top-level spawns, so shallow transcripts stay clean). Its colour matches the group line below.
• Per-depth colour ramp — the group line framing a depth-d transcript cycles every 5 levels (depth 1 = the existing tool-green; 2 blue, 3 purple, 4 orange, 5 teal), via an agent-ring-{1..5} bucket class.
• "≡ full transcript" marker — on a fully-collapsed nested spawn's result (the sub-agent answered directly, no tools, so what's shown is its whole transcript) — distinguishing it from a spawn that produced no transcript. Nested-only; trunk-level direct sub-agents keep their pre-Support hierarchies of agents #213 look.
• Deep-chain indent compression — 2em step for depths 1-5, compressed to 0.5em for depths 6+, so an 80-level chain stays on-screen (~1118px vs ~2560px); depth is then read from the badge + colour, not the indent.

Verified on a real 80-level nested session (the ramp cycles correctly through all levels; deep compression keeps it on-screen) and an interactive look-review. As-built reference: dev-docs/agents.md §5.4. New unit + runtime-CSS browser tests pin the contract; `just ci` green.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features
  • Added color-ramped “ring” borders for nested agent transcript groups, cycling through five colors by nesting depth.
  • Introduced “Depth N” badges on nested spawn cards (from deeper levels onward) to clarify how far a spawn is nested, including tooltips.
  • Added a “≡ full transcript” marker for fully-collapsed nested spawns so collapsed results stay clear.
  • Improved readability of very deep nesting by compressing indentation beyond early levels.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 33d374a0-39a6-40fd-873d-0c14fc84d67d

📥 Commits

Reviewing files that changed from the base of the PR and between a8b0e99 and b62f34a.

📒 Files selected for processing (1)

• work/agent-hierarchies-design.md

✅ Files skipped from review due to trivial changes (1)

• work/agent-hierarchies-design.md

---

📝 Walkthrough

Walkthrough

Adds a visual depth layer for nested agent transcripts: TemplateMessage gains agent_depth and spawns_collapsed_transcript fields populated during hierarchy build and sidechain dedup. CSS ring variables and depth-class utilities drive per-depth border coloring, indent compression, depth badge pills, and a collapsed-transcript marker rendered via new HTML title helpers.

Changes

Nested-agent visual depth layer

Layer / File(s)	Summary
TemplateMessage depth fields and population claude_code_log/renderer.py	TemplateMessage.__init__ adds agent_depth (int) and spawns_collapsed_transcript (bool). _build_message_hierarchy writes agent_depth from the computed level shift; sidechain cleanup sets spawns_collapsed_transcript=True when a nested spawn's children are fully eliminated by dedup.
CSS variables, depth class generation, and message styles claude_code_log/html/templates/components/global_styles.css, claude_code_log/html/utils.py, claude_code_log/html/templates/components/message_styles.css	Five --agent-ring-1..5 color variables added to :root. css_class_from_message appends agent-depth-{d}, agent-ring-{bucket}, and agent-deep (d≥6) from msg.agent_depth. message_styles.css expands the sidechain rule into per-depth border-left recoloring, .agent-deep indent compression, .agent-depth-badge ring pill, .spawn-collapsed-marker, and a responsive deep-chain override.
HTML title annotations: depth badge and collapsed marker claude_code_log/html/renderer.py	title_ToolResultMessage appends a ≡ full transcript span when spawns_collapsed_transcript is set. title_TaskInput appends _agent_depth_badge(message) alongside the async hint. New _agent_depth_badge helper returns empty for depth < 2, otherwise emits a ring-classed span with a Depth N tooltip.
Unit tests, browser tests, snapshots, and docs test/test_nested_agents.py, test/test_nested_agents_browser.py, test/__snapshots__/test_snapshot_html.ambr, dev-docs/agents.md, work/agent-hierarchies-design.md	TestNestedVisualLayer asserts agent_depth per message, which spawns are marked spawns_collapsed_transcript, and HTML badge/marker output. Browser tests verify ring color cycling by innerDepth, badge presence/color, and .spawn-collapsed-marker count. Snapshot updated with all new CSS. dev-docs/agents.md adds section 5.4 Visual layer and expands fixture notes; design doc adds PR2 scope checklist.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• daaain/claude-code-log#125: Modifies renderer.py's sidechain dedup and TemplateMessage lifecycle, the same hierarchy infrastructure this PR extends with agent_depth and spawns_collapsed_transcript.

Poem

🐇 Hop through the nested trees so deep,
Each agent ring a color to keep —
Badge at depth two, three, four, five!
Collapsed transcripts, marked alive.
≡ full transcript for the lost and found,
The rabbit stamps each depth around! 🌀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: implementing the visual layer for nested agent hierarchies as part 2 of issue #213, which aligns with the comprehensive visual enhancements across renderer, styles, and tests documented in the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/agent-hierarchies-visuals

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cboos]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.