feat(#1756): Add dynamic agent color styling system

[aheritier]

Closes #1756

Summary

Assigns each agent in a multi-agent team a unique, deterministic color so users can visually distinguish agents across the entire TUI — message badges, sidebar entries, tab bar indicators, and handoff/transfer-task displays.

Colors are generated dynamically from hue values (0–360) defined per theme, with saturation and lightness auto-adapted based on the theme's background (dark → brighter, light → darker). This follows Option 2 from the design discussion, as agreed with @rumpl and @krissetto.

What changed

New: Color utility library (pkg/tui/styles/colorutil.go)

Shared color math extracted from tabbar/tab.go and theme.go, plus new functionality:

• Hex parsing, sRGB linearization, HSL ↔ RGB conversion
• WCAG 2.x luminance & contrast ratio (ContrastRatio, EnsureContrast, MutedContrastFg)
• Hue-based palette generation (GenerateBadgePalette, GenerateAccentPalette)
• CIE76 perceptual distance for validating color distinctness

New: Agent color registry (pkg/tui/styles/agent_colors.go)

Thread-safe, cached mapping from agent name → palette index:

• SetAgentOrder(names) — called when team info updates
• AgentBadgeStyleFor(name) / AgentAccentStyleFor(name) — return precomputed lipgloss styles
• InvalidateAgentColorCache() — called on theme change to regenerate styles
• Wraps around palette size for teams larger than 16 agents

Theme integration

• New optional agent_hues field in ThemeColors (list of hue values 0–360)
• Falls back to 16 well-spaced default hues (blue, purple, teal, orange, pink, green, etc.)
• Theme authors only need to provide hue values; saturation/lightness/contrast are handled automatically

TUI component updates

• Message badges — per-agent colored (AgentBadgeStyleFor(sender))
• Sidebar agent names — per-agent accent color (AgentAccentStyleFor(agent.Name))
• Handoff / transfer-task displays — both source and target agents get their own badge color
• Tab bar — color helpers (MutedContrastFg, EnsureContrast) consolidated into shared colorutil.go

Validation

All 10 built-in themes pass automated checks:

• ✅ WCAG AA badge contrast (fg/bg ≥ 4.5:1)
• ✅ WCAG AA accent contrast (vs background ≥ 3.0:1)
• ✅ CIE76 pairwise distinctness (ΔE ≥ 10 between all palette entries)
• Full color audit report available via go test -v ./pkg/tui/styles/...

Screenshots

Dark themes

Theme	Screenshot
default
tokyo-night
dracula
one-dark
nord
catppuccin-mocha
gruvbox-dark
solarized-dark

Light themes

Theme	Screenshot
catppuccin-latte
gruvbox-light

Files changed

File	Change
pkg/tui/styles/colorutil.go	New — shared color math & palette generation
pkg/tui/styles/colorutil_test.go	New — unit tests for all color utilities
pkg/tui/styles/agent_colors.go	New — agent color registry & cached style lookups
pkg/tui/styles/agent_colors_test.go	New — registry tests + WCAG/distinctness validation across all themes
pkg/tui/styles/theme.go	Add AgentHues field, remove duplicated color helpers, hook cache invalidation
pkg/tui/styles/theme_test.go	Update mergeColors test for new AgentHues slice field
pkg/tui/styles/themes/default.yaml	Add agent_hues with 16 default values
pkg/tui/service/sessionstate.go	Call SetAgentOrder when available agents change
pkg/tui/components/message/message.go	Use AgentBadgeStyleFor(sender)
pkg/tui/components/sidebar/sidebar.go	Use AgentAccentStyleFor(agent.Name)
pkg/tui/components/tabbar/tab.go	Remove ~100 lines of color helpers (moved to colorutil.go)
pkg/tui/components/tabbar/tabbar.go	Use shared MutedContrastFg / EnsureContrast
pkg/tui/components/tool/handoff/handoff.go	Per-agent badge colors for source/target
pkg/tui/components/tool/transfertask/transfertask.go	Per-agent badge colors for source/target

[rumpl]

Very cool idea, I just wonder how well this plays with our theme system?

[Copilot]

Pull request overview

Adds a dynamic, deterministic agent color system to the TUI so agent badges and sidebar accents are derived from a fixed palette based on the agent’s order (as reported by the runtime team info).

Changes:

• Introduces badge and accent color palettes plus helper APIs to render agent-specific styles.
• Tracks agent ordering via a shared registry updated from TeamInfoEvent/SetAvailableAgents.
• Updates multiple TUI components to render agent badges/names using the new dynamic style functions.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/tui/styles/agent_colors.go	Implements palettes, agent→index registry, and dynamic badge/accent style helpers.
pkg/tui/styles/agent_colors_test.go	Adds tests for agent ordering/indexing and determinism of generated styles.
pkg/tui/service/sessionstate.go	Updates agent-order registry when available agents are set from runtime events.
pkg/tui/components/tool/transfertask/transfertask.go	Switches to dynamic agent badge styling for sender/target agent.
pkg/tui/components/tool/handoff/handoff.go	Switches to dynamic agent badge styling for sender/target agent.
pkg/tui/components/sidebar/sidebar.go	Switches current-agent prefix and name rendering to dynamic accent styling per agent.
pkg/tui/components/message/message.go	Switches message sender prefix to dynamic agent badge styling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

AgentBadgeColorsFor recomputes contrast (hex parsing + luminance math) on every call. Since badge rendering can happen frequently (e.g., per message render), consider memoizing the resolved foreground per (theme ref, palette index/bgHex) or precomputing on theme changes to avoid repeated parsing and math in hot render paths.

[aheritier]

precomputed all badge/accent styles in rebuildAgentColorCache(), called from
SetAgentOrder and InvalidateAgentColorCache (hooked into ApplyTheme). The hot render path now reads from cached slices.

[aheritier]

Very cool idea, I just wonder how well this plays with our theme system?

not yet configurable, it's what I wanted to discuss with you.

[aheritier]

Not sure at all cc @rumpl @krissetto @dgageot :

Option 1: Add agent_colors section to ThemeColors

Add agent_badge_colors and agent_accent_colors as string arrays to ThemeColors. Theme authors can override the full palettes. The merge logic would be: if the override provides
a non-empty array, use it entirely; otherwise fall back to the default.

In theme YAML

colors:
  agent_badge_colors:
    - "#1e66f5"
    - "#8839ef"
    - "#40a02b"
    # ...
  agent_accent_colors:
    - "#1e66f5"
    - "#8839ef"
    # ...

Pros: Full control per theme, follows existing pattern, theme authors can curate exactly. Cons: Verbose (16×2 = 32 hex values to override), most theme authors won't bother, the
merge is all-or-nothing per palette.

Option 2: Derive agent colors from a single agent_base_hues list

Theme provides a list of hue values (0–360) or a few seed colors. The system generates the full palette by adjusting saturation/lightness based on the theme's background
lightness (dark theme → brighter badges, light theme → darker badges).

colors:
  agent_hues: [220, 280, 170, 30, 330, 140, 210, 270, 45, 0, 190, 25, 235, 295, 160, 350]

Pros: Compact, auto-adapts to dark/light backgrounds, fewer values to maintain. Cons: More complex implementation, less precise control, HSL→hex conversion needed.

Option 3: Theme provides a color_scale and system generates from it

Use the theme's existing status/accent colors as seeds — brand, success, error, warning, info, accent, highlight, badge_accent, badge_info, badge_success — and derive the rest
programmatically to fill the 16 slots.

• No new YAML fields needed — agent palette is derived from: brand, accent, success, error, warning, info, highlight, badge_accent, badge_info, badge_success + 6 generated fills

Pros: Zero config for theme authors — it "just works" with any theme. No new YAML fields. Cons: Less control, the generated fills may not be aesthetically ideal, hard to predict
exact output.

Option 4: Hybrid — auto-derive with optional override

Combine Option 3 (auto-derive from existing theme colors) as the default, with Option 1 (explicit array) as an optional override. If the theme YAML provides agent_badge_colors,
use it. Otherwise, derive from the theme's existing color definitions.

Pros: Works out of the box for all existing themes, theme authors who care can override. Cons: Two code paths to maintain, but the override path is trivial.

[aheritier]

copilot feedbacks were addressed

[rumpl]

My preference would be Option 2, WDYT @krissetto ?

[krissetto]

@rumpl I also prefer Option 2. Explicit theme values could be nice to have if someone wants to define them, but generating the hues is better IMHO since there could be n agents in a team.

Also @aheritier there is some code in tabbar/tab.go that does dynamic color selection for some bits of the UI that would've been too tedious to theme manually, we could adjust and consolidate the approach into something reusable across multiple places in the TUI as well so we end up with a consistent look and feel

[aheritier]

@rumpl @krissetto @dgageot please review with caution, it's bigger than I expected

[krissetto]

let's have the cagent bot take a pass at this :)

/review

[docker-agent]

Review Summary

Found 1 high-severity race condition in the agent color registry that could cause incorrect color assignments when agents are dynamically reordered.

The issue affects all three style lookup functions and could result in agents displaying the wrong colors or fallback colors during concurrent access.

Summary

• High severity: 1 (race condition in style lookups)
• Medium severity: 0
• Low severity: 0

The rest of the implementation looks solid - the color math, palette generation, and synchronization primitives are all correctly implemented.

[docker-agent]

🔴 HIGH SEVERITY: Race condition between agentIndex() call and style lookup

The function calls agentIndex() which releases its lock, then acquires a new RLock. Between these operations, SetAgentOrder() can rebuild the badgeStyles array, causing the returned idx to become stale.

Impact: While bounds checks prevent crashes, this causes incorrect color assignment:

1. If the new palette is smaller, idx may exceed the new array length, causing fallback to default blue instead of the agent's assigned color
2. If the new palette is larger, idx may point to a different agent's colors in the new palette

Same issue exists in:

• AgentBadgeStyleFor (line 143)
• AgentAccentStyleFor (line 160)

Fix: Change all three functions to hold the read lock across both the index lookup and array access:

func AgentBadgeColorsFor(agentName string) AgentBadgeColors {
	agentRegistry.RLock()
	defer agentRegistry.RUnlock()
	
	idx, ok := agentRegistry.indices[agentName]
	if !ok {
		return AgentBadgeColors{
			Fg: lipgloss.Color("#ffffff"),
			Bg: lipgloss.Color("#1D63ED"),
		}
	}
	
	size := len(agentRegistry.badgeStyles)
	if size > 0 && idx%size < len(agentRegistry.badgeStyles) {
		return agentRegistry.badgeStyles[idx%size].colors
	}
	
	return AgentBadgeColors{
		Fg: lipgloss.Color("#ffffff"),
		Bg: lipgloss.Color("#1D63ED"),
	}
}

Apply the same pattern to the other two functions.

[aheritier]

/review

is it better ? cc @rumpl @krissetto @dgageot

[krissetto]

/review

☝️ this will work for you once you're officially part of the org :)

[docker-agent]

Review Summary

✅ No issues found

This PR implements a well-designed dynamic agent color styling system with excellent code quality:

• Thread-safe implementation: Proper use of sync.RWMutex with RLock for reads and Lock for writes
• Safe initialization: Zero-initialized global struct with proper guards against empty arrays
• Robust color math: WCAG-compliant contrast ratios with guaranteed fallbacks to pure black/white
• Comprehensive testing: Full test coverage including WCAG AA contrast validation and CIE76 distinctness checks
• Lock-free atomic operations: CurrentTheme() uses atomic.Pointer.Load() to avoid race conditions
• Defensive programming: All array access protected by size > 0 checks before modulo operations

The code follows Go best practices and handles edge cases appropriately. The extensive test suite validates contrast ratios and color distinctness across all 10 built-in themes.

[aheritier]

Do you see others improvements / fixes / tests to do @dgageot @rumpl @rumpl ?