feat(team): render teammate reports as a compact notification line

A teammate's report was injected into the leader's conversation as a raw <teammate_message_<nonce>> envelope and rendered verbatim as a user bubble — a large, scaffolding-heavy block on screen for what is often the biggest payload in the feature. Adopt the two-text split the notification queue already uses: the full nonce-tagged envelope still goes to the leader's model, but the user now sees a compact "● <name> reported back" line in its place. The verbatim USER bubble is suppressed for SendMessageType.Teammate exactly as it is for Cron, and coordination-error notices get the same treatment. The leader callback now delivers both the model text and a display string built in TeamManager (where the structured sender/summary live), so the UI never parses the envelope. Headless is unchanged — it ignores the extra arg.
tanzhenxin · Jun 10, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
commit 8e3be23d5a949c1b3e2fcaebd5701cf12c0a21bf
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
@@ -412,6 +412,60 @@ describe('useGeminiStream', () => {
     });
   });
 
+  it('renders teammate reports as a compact notification, not a raw envelope bubble', async () => {
+    const mockManager = { setLeaderMessageCallback: vi.fn() };
+    (mockConfig.getTeamManager as unknown as Mock).mockReturnValue(mockManager);
+
+    const { mockSendMessageStream } = renderTestHook();
+
+    await waitFor(() => {
+      expect(mockManager.setLeaderMessageCallback).toHaveBeenCalledWith(
+        expect.any(Function),
+      );
+    });
+
+    const display = '**scout-cli** reported back';
+    const modelText =
+      '<teammate_message_abcdef0123456789 from="scout-cli">\n' +
+      'a very long report that should never reach the UI verbatim\n' +
+      '</teammate_message_abcdef0123456789>';
+
+    const callback = (mockManager.setLeaderMessageCallback as Mock).mock
+      .calls[0][0] as (modelText: string, display: string) => void;
+
+    act(() => {
+      callback(modelText, display);
+    });
+
+    // The compact display line is added to history…
+    await waitFor(() => {
+      expect(mockAddItem).toHaveBeenCalledWith(
+        { type: 'notification', text: display },
+        expect.any(Number),
+      );
+    });
+
+    // …and the full envelope is sent to the model as a Teammate turn.
+    await waitFor(() => {
+      expect(mockSendMessageStream).toHaveBeenCalledWith(
+        modelText,
+        expect.any(AbortSignal),
+        expect.any(String),
+        expect.objectContaining({
+          type: SendMessageType.Teammate,
+          notificationDisplayText: display,
+        }),
+      );
+    });
+
+    // The raw envelope is never rendered as a history item (no `> …`
+    // user bubble dumping the whole report on screen).
+    const addedTexts = (mockAddItem as Mock).mock.calls
+      .map((c) => (c[0] as { text?: string })?.text)
+      .filter((t): t is string => typeof t === 'string');
+    expect(addedTexts.some((t) => t.includes('teammate_message'))).toBe(false);
+  });
+
   it('should not submit tool responses if not all tool calls are completed', () => {
     const toolCalls: TrackedToolCall[] = [
       {

diff --git a/packages/cli/src/ui/hooks/useGeminiStream.ts b/packages/cli/src/ui/hooks/useGeminiStream.ts
@@ -796,10 +796,15 @@ export const useGeminiStream = (
 
         localQueryToSendToGemini = trimmedQuery;
 
-        // Cron prompts are already rendered as a `● Cron: …` notification by
-        // the queue drain, so skip the user-message history item to avoid
-        // a duplicate `> …` line. Preprocessing (@/slash/shell) still runs.
-        if (submitType !== SendMessageType.Cron) {
+        // Cron prompts and teammate reports are already rendered as a
+        // `● …` notification by their queue drains, so skip the
+        // user-message history item to avoid a duplicate `> …` line (and,
+        // for teammates, dumping the whole nonce-tagged envelope on screen).
+        // Preprocessing (@/slash/shell) still runs.
+        if (
+          submitType !== SendMessageType.Cron &&
+          submitType !== SendMessageType.Teammate
+        ) {
           const insertedId = addItem(
             {
               type: MessageType.USER,
@@ -2628,7 +2633,14 @@ export const useGeminiStream = (
   }, [streamingState, submitQuery, notificationTrigger, addItem]);
 
   // ─── Teammate message integration ─────────────────────────
-  const teammateQueueRef = useRef<string[]>([]);
+  // Each entry carries the full nonce-tagged envelope (`modelText`,
+  // sent to the leader's model) and a compact `display` line (shown
+  // to the user in its place) — the same two-text split the unified
+  // notification queue uses, so teammate reports no longer dump the
+  // whole raw envelope into the conversation as a user bubble.
+  const teammateQueueRef = useRef<
+    Array<{ modelText: string; display: string }>
+  >([]);
   const [teammateTrigger, setTeammateTrigger] = useState(0);
 
   // Subscribe to TeamManager's leader message callback.
@@ -2654,10 +2666,12 @@ export const useGeminiStream = (
       }
       boundManager = manager;
       if (manager) {
-        manager.setLeaderMessageCallback((formatted: string) => {
-          teammateQueueRef.current.push(formatted);
-          setTeammateTrigger((n) => n + 1);
-        });
+        manager.setLeaderMessageCallback(
+          (modelText: string, display: string) => {
+            teammateQueueRef.current.push({ modelText, display });
+            setTeammateTrigger((n) => n + 1);
+          },
+        );
       }
     };
 
@@ -2691,9 +2705,22 @@ export const useGeminiStream = (
       teammateQueueRef.current.length > 0
     ) {
       const batch = teammateQueueRef.current.splice(0);
-      submitQuery(batch.join('\n\n'), SendMessageType.Teammate);
+      // Render one compact `● …` line per teammate report; the full
+      // envelope goes only to the model (the USER bubble is suppressed
+      // for SendMessageType.Teammate in prepareQueryForGemini).
+      for (const entry of batch) {
+        addItem(
+          { type: 'notification' as const, text: entry.display },
+          Date.now(),
+        );
+      }
+      const modelText = batch.map((e) => e.modelText).join('\n\n');
+      const display = batch.map((e) => e.display).join('; ');
+      submitQuery(modelText, SendMessageType.Teammate, undefined, {
+        notificationDisplayText: display,
+      });
     }
-  }, [streamingState, submitQuery, teammateTrigger]);
+  }, [streamingState, submitQuery, teammateTrigger, addItem]);
 
   return {
     streamingState,

@@ -140,8 +140,16 @@ export class TeamManager {
   /** Leader inbox polling interval. */
   private pollingInterval: ReturnType<typeof setInterval> | null = null;
 
-  /** Callback to inject teammate messages into the leader. */
-  private leaderMessageCallback: ((message: string) => void) | null = null;
+  /**
+   * Callback to inject teammate messages into the leader. Receives the
+   * full model-bound text (the nonce-tagged envelope) and a compact,
+   * human-readable `display` line for the leader's UI — the two-text
+   * split that lets the on-screen line stay short while the model still
+   * gets the whole report.
+   */
+  private leaderMessageCallback:
+    | ((message: string, display: string) => void)
+    | null = null;
 
   /** Tracks how far we've read in the leader inbox. */
   private lastInboxOffset = 0;
@@ -650,7 +658,9 @@ export class TeamManager {
    * to the leader's conversation. Called by the CLI layer.
    * Pass `null` to detach a previously-installed callback.
    */
-  setLeaderMessageCallback(cb: ((message: string) => void) | null): void {
+  setLeaderMessageCallback(
+    cb: ((message: string, display: string) => void) | null,
+  ): void {
     this.leaderMessageCallback = cb;
   }
 
@@ -725,7 +735,10 @@ export class TeamManager {
     // is being torn down or replaced.
     const callback = this.leaderMessageCallback;
     if (callback) {
-      callback(this.formatLeaderEnvelope(newMessages).join('\n\n'));
+      callback(
+        this.formatLeaderEnvelope(newMessages).join('\n\n'),
+        this.formatLeaderDisplay(newMessages),
+      );
     }
   }
 
@@ -750,6 +763,34 @@ export class TeamManager {
     );
   }
 
+  /**
+   * Build a compact, one-line summary of a batch of teammate→leader
+   * messages for the leader's UI. The full `formatLeaderEnvelope` text
+   * still goes to the model; this is the short line the user sees in
+   * its place (rendered as a `●` notification), so the conversation
+   * isn't flooded with the entire raw report.
+   *
+   * Uses each message's `summary` when the teammate provided one, else
+   * a "{name} reported back" fallback. Names are wrapped in `**` so the
+   * UI's inline-markdown renderer bolds them. Kept separate from
+   * `formatLeaderEnvelope` so the model payload and the on-screen line
+   * can diverge.
+   */
+  formatLeaderDisplay(
+    messages: ReadonlyArray<{ from: string; summary?: string }>,
+  ): string {
+    const first = messages[0];
+    if (messages.length === 1 && first) {
+      return first.summary
+        ? `**${first.from}**: ${first.summary}`
+        : `**${first.from}** reported back`;
+    }
+    const names = [...new Set(messages.map((m) => m.from))];
+    return names.length > 0
+      ? `**${names.join('**, **')}** reported back`
+      : 'Teammate reported back';
+  }
+
   /**
    * Returns true if any teammate is still actively working or
    * has pending messages/tasks to process. An IDLE teammate
@@ -844,15 +885,15 @@ export class TeamManager {
 
         // Resolve when a message is delivered.
         const origCb = this.leaderMessageCallback;
-        const wrappedCallback = (msg: string) => {
+        const wrappedCallback = (msg: string, display: string) => {
           // Restore early so a second message doesn't re-enter the
           // wrapper after we've already finished. Same identity-
           // check as in finish() — don't stomp on an externally-set
           // callback.
           if (this.leaderMessageCallback === wrappedCallback) {
             this.leaderMessageCallback = origCb;
           }
-          origCb?.(msg);
+          origCb?.(msg, display);
           finish('message');
         };
         this.leaderMessageCallback = wrappedCallback;
@@ -1049,6 +1090,7 @@ export class TeamManager {
       try {
         this.leaderMessageCallback?.(
           `<team_error>Coordination step "${label}" failed: ${msg}</team_error>`,
+          `Team coordination step "${label}" failed`,
         );
       } catch (cbErr) {
         const cbMsg = cbErr instanceof Error ? cbErr.message : String(cbErr);

@@ -461,5 +461,52 @@ describe('TeamCoordinationHarness', () => {
       // inside the envelope (not interpreted as a closing tag).
       expect(formatted).toContain(spoof);
     });
+
+    it('delivers a compact display line alongside the full envelope', async () => {
+      const h = await createHarness();
+      await h.spawnTeammate('worker');
+
+      const captured: Array<{ modelText: string; display: string }> = [];
+      h.teamManager.setLeaderMessageCallback((modelText, display) =>
+        captured.push({ modelText, display }),
+      );
+
+      const report = 'a very long report '.repeat(50);
+      await h.teamManager.sendMessage('leader', report, 'worker');
+      await h.teamManager.drainLeaderInbox();
+
+      expect(captured).toHaveLength(1);
+      const { modelText, display } = captured[0]!;
+      // The model still receives the full nonce-tagged envelope + body.
+      expect(modelText).toMatch(
+        /^<teammate_message_[a-f0-9]{16} from="worker"/,
+      );
+      expect(modelText).toContain('a very long report');
+      // The UI display line is compact: names the sender only — no
+      // envelope scaffolding, no report body.
+      expect(display).toBe('**worker** reported back');
+      expect(display).not.toContain('teammate_message');
+      expect(display).not.toContain('a very long report');
+    });
+
+    it('formatLeaderDisplay summarizes one, many, and summarized batches', async () => {
+      const h = await createHarness();
+      const fmt = (msgs: Array<{ from: string; summary?: string }>) =>
+        h.teamManager.formatLeaderDisplay(msgs);
+
+      expect(fmt([{ from: 'scout' }])).toBe('**scout** reported back');
+      // A teammate-provided summary is surfaced verbatim.
+      expect(fmt([{ from: 'scout', summary: 'core pkg done' }])).toBe(
+        '**scout**: core pkg done',
+      );
+      // Multiple distinct senders are listed.
+      expect(fmt([{ from: 'a' }, { from: 'b' }])).toBe(
+        '**a**, **b** reported back',
+      );
+      // Duplicate senders collapse to one name.
+      expect(fmt([{ from: 'a' }, { from: 'a' }])).toBe('**a** reported back');
+      // Defensive fallback for an empty batch.
+      expect(fmt([])).toBe('Teammate reported back');
+    });
   });
 });