feat(tui): mark sub-agent returns in the transcript

When a forwarded sub-agent (transfer_task / run_skill) handed control back
to its caller, the only cue was the next parent badge, so a run of
delegations read as one undifferentiated wall. Insert an explicit return
marker — "↩ child → parent ───" in the child's accent color — when
AgentSwitching(false, child, parent) fires, i.e. the deferred restore in
runForwarding. By design only the EXIT is bracketed; the existing
transfer_task card remains the entry. Background agents and permanent
handoffs never emit this event, so they are unaffected.

The marker is a static, cacheable MessageTypeDelegationReturn list item; it
is not spinner-driven.

Refs #3102

Author: aheritier

pkg/tui/components/message/message.go

@@ -375,6 +375,13 @@ func (mv *messageModel) render(width int) string {
 		return msg.Content
 	case types.MessageTypeCancelled:
 		return styles.WarningStyle.Render("⚠ stream cancelled ⚠")
+	case types.MessageTypeDelegationReturn:
+		label := "↩ " + msg.Sender + " → " + msg.Content
+		styled := styles.AgentAccentStyleFor(msg.Sender).Render(label)
+		// Trailing faded rule out to width, mirroring the collapsed-sidebar divider.
+		ruleW := max(width-ansi.StringWidth(styled)-3, 0)
+		rule := styles.FadingStyle.Render(" " + strings.Repeat("─", ruleW))
+		return styles.NoStyle.MarginLeft(2).Render(styled + rule)
 	case types.MessageTypeWelcome:
 		messageStyle := styles.WelcomeMessageStyle
 		// Convert explicit newlines to markdown hard line breaks (two trailing spaces)

pkg/tui/components/message/message_test.go

@@ -324,3 +324,21 @@ func TestBareSpinnerKeepsPlayfulView(t *testing.T) {
 	assert.True(t, mv.isSpinnerDriven())
 	assert.Equal(t, mv.spinner.View(), mv.View(), "empty label must keep the default spinner rendering")
 }
+
+// TestDelegationReturnMarkerRenders covers the transcript return marker inserted
+// when a forwarded sub-agent (child) hands control back to its caller (parent):
+// it renders "↩ child → parent" and, being static, is NOT spinner-driven so it
+// caches normally.
+func TestDelegationReturnMarkerRenders(t *testing.T) {
+	t.Parallel()
+
+	// Sender holds the child (drives the accent color); Content holds the parent.
+	msg := types.DelegationReturn("librarian", "root")
+	mv := New(msg, nil)
+	mv.SetSize(80, 0)
+
+	assert.False(t, mv.isSpinnerDriven(), "static return marker must be cacheable, not spinner-driven")
+
+	out := stripANSI(mv.View())
+	assert.Contains(t, out, "↩ librarian → root", "marker should read ↩ child → parent")
+}

pkg/tui/components/messages/messages.go

@@ -57,6 +57,7 @@ type Model interface {
 	AddErrorMessage(content string) tea.Cmd
 	AddAssistantMessage(sender, label string) tea.Cmd
 	AddCancelledMessage() tea.Cmd
+	AddDelegationReturn(child, parent string) tea.Cmd
 	AddWelcomeMessage(content string) tea.Cmd
 	AddOrUpdateToolCall(agentName string, toolCall tools.ToolCall, toolDef tools.Tool, status types.ToolStatus) tea.Cmd
 	AppendToolOutput(msg *runtime.ToolCallOutputEvent) tea.Cmd
@@ -1025,6 +1026,9 @@ func (m *model) shouldCacheMessage(index int) bool {
 		return false
 	case types.MessageTypeUser:
 		return true
+	case types.MessageTypeDelegationReturn:
+		// Static divider line; safe to cache like a user message.
+		return true
 	default:
 		return false
 	}
@@ -1255,6 +1259,10 @@ func (m *model) AddCancelledMessage() tea.Cmd {
 	return view.Init()
 }
 
+func (m *model) AddDelegationReturn(child, parent string) tea.Cmd {
+	return m.addMessage(types.DelegationReturn(child, parent))
+}
+
 func (m *model) AddWelcomeMessage(content string) tea.Cmd {
 	if content == "" || len(m.views) > 0 {
 		return nil

pkg/tui/components/messages/messages_test.go

@@ -39,6 +39,27 @@ func TestViewDoesNotWrapWideLines(t *testing.T) {
 	}
 }
 
+// TestAddDelegationReturnAppendsMarker verifies AddDelegationReturn appends a
+// single MessageTypeDelegationReturn item (Sender=child, Content=parent) and
+// that it renders the "↩ child → parent" divider.
+func TestAddDelegationReturnAppendsMarker(t *testing.T) {
+	t.Parallel()
+
+	sessionState := &service.SessionState{}
+	m := NewScrollableView(80, 24, sessionState).(*model)
+	m.SetSize(80, 24)
+
+	cmd := m.AddDelegationReturn("librarian", "root")
+	require.NotNil(t, cmd, "appending the marker auto-scrolls a fresh transcript, yielding a cmd")
+
+	require.Len(t, m.messages, 1)
+	assert.Equal(t, types.MessageTypeDelegationReturn, m.messages[0].Type)
+	assert.Equal(t, "librarian", m.messages[0].Sender)
+	assert.Equal(t, "root", m.messages[0].Content)
+
+	assert.Contains(t, ansi.Strip(m.View()), "↩ librarian → root")
+}
+
 func TestMouseClickOnURLOpensURL(t *testing.T) {
 	t.Parallel()
 

pkg/tui/page/chat/runtime_events.go

@@ -122,6 +122,11 @@ func (p *chatPage) handleRuntimeEvent(msg tea.Msg) (bool, tea.Cmd) {
 
 	case *runtime.AgentSwitchingEvent:
 		p.sidebar.SetAgentSwitching(msg.Switching)
+		if !msg.Switching && msg.FromAgent != "" && msg.ToAgent != "" {
+			// A forwarded sub-agent (FromAgent) just returned control to its
+			// caller (ToAgent); bracket the exit with a transcript marker.
+			return true, p.messages.AddDelegationReturn(msg.FromAgent, msg.ToAgent)
+		}
 		return true, nil
 
 	case *runtime.ToolsetInfoEvent:

pkg/tui/page/chat/runtime_events_test.go

@@ -0,0 +1,79 @@
+package chat
+
+import (
+	"testing"
+
+	"github.com/charmbracelet/x/ansi"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/docker/docker-agent/pkg/runtime"
+	"github.com/docker/docker-agent/pkg/tui/components/messages"
+	"github.com/docker/docker-agent/pkg/tui/components/sidebar"
+	"github.com/docker/docker-agent/pkg/tui/service"
+)
+
+func newDelegationMarkerTestPage() *chatPage {
+	sessionState := &service.SessionState{}
+	msgs := messages.NewScrollableView(80, 24, sessionState)
+	msgs.SetSize(80, 24)
+	return &chatPage{
+		sidebar:      sidebar.New(sessionState),
+		messages:     msgs,
+		sessionState: sessionState,
+	}
+}
+
+// TestAgentSwitchingInsertsReturnMarker covers the Phase 2 design decision to
+// bracket only the EXIT of a forwarded sub-agent. AgentSwitching(false, child,
+// parent) — emitted when a transfer_task/run_skill sub-session returns — inserts
+// a "↩ child → parent" marker, while the entry event AgentSwitching(true, ...)
+// inserts nothing (the transfer_task card is the visible entry).
+func TestAgentSwitchingInsertsReturnMarker(t *testing.T) {
+	t.Parallel()
+
+	t.Run("return (Switching=false) inserts a marker", func(t *testing.T) {
+		t.Parallel()
+		p := newDelegationMarkerTestPage()
+
+		handled, cmd := p.handleRuntimeEvent(&runtime.AgentSwitchingEvent{
+			Switching: false,
+			FromAgent: "librarian",
+			ToAgent:   "root",
+		})
+
+		require.True(t, handled)
+		require.NotNil(t, cmd, "a returning sub-agent should insert a marker")
+		assert.Contains(t, ansi.Strip(p.messages.View()), "↩ librarian → root")
+	})
+
+	t.Run("entry (Switching=true) inserts nothing", func(t *testing.T) {
+		t.Parallel()
+		p := newDelegationMarkerTestPage()
+
+		handled, cmd := p.handleRuntimeEvent(&runtime.AgentSwitchingEvent{
+			Switching: true,
+			FromAgent: "root",
+			ToAgent:   "librarian",
+		})
+
+		require.True(t, handled)
+		assert.Nil(t, cmd, "entering a delegation must not insert a return marker")
+		assert.NotContains(t, ansi.Strip(p.messages.View()), "↩")
+	})
+
+	t.Run("missing agent names insert nothing", func(t *testing.T) {
+		t.Parallel()
+		p := newDelegationMarkerTestPage()
+
+		handled, cmd := p.handleRuntimeEvent(&runtime.AgentSwitchingEvent{
+			Switching: false,
+			FromAgent: "",
+			ToAgent:   "root",
+		})
+
+		require.True(t, handled)
+		assert.Nil(t, cmd)
+		assert.NotContains(t, ansi.Strip(p.messages.View()), "↩")
+	})
+}

pkg/tui/types/types.go

@@ -22,6 +22,7 @@ const (
 	MessageTypeToolResult
 	MessageTypeWelcome
 	MessageTypeLoading
+	MessageTypeDelegationReturn // "↩ child → parent" divider when a sub-agent returns
 )
 
 const (
@@ -110,6 +111,13 @@ func Cancelled() *Message {
 	}
 }
 
+// DelegationReturn marks control returning from a sub-agent (child) to its
+// caller (parent). Sender holds the child (drives the accent color); Content
+// holds the parent name.
+func DelegationReturn(child, parent string) *Message {
+	return &Message{Type: MessageTypeDelegationReturn, Sender: child, Content: parent}
+}
+
 func Welcome(content string) *Message {
 	return &Message{
 		Type:    MessageTypeWelcome,