fix(transcript): the mascot follows the run, and a named agent labels it

docs/notes/frontend.md

@@ -1935,6 +1935,62 @@ that line introduced, folding behind it once it moves on.
 
 Fonte: `src/surfaces/AgentTranscript.tsx:SubagentPanel`
 
+<a id="subagent-mascot-follows-the-run"></a>
+
+### The mascot follows the run, not the label
+
+Three runs on one screen were three identical rows: the sprite was hashed from
+the row's name, and a run the provider never named is always called "Subagent",
+so the hash had nothing to tell apart. The comment beside the component claimed
+the opposite -- that settled runs stay distinct by name-hashed mascot -- and the
+claim was false for exactly the runs that need telling apart.
+
+`ProjectMascot` takes an `identity` for this, kept apart from `project` so
+nothing downstream reads a run key as a path. Overloading `project` would have
+been the shorter change, and would have made every other caller of the component
+carry a field that means two things.
+
+The row passes `block.tool?.callId ?? block.id`, the identity the row already
+uses for its colour, so shape and colour come from one field and cannot
+disagree. A row that cannot be told from its neighbours says nothing, which is
+the whole complaint.
+
+`resolveEffectiveMascot` is untouched, and that is load-bearing: it is what keeps
+the project rail and the tab groups on the hash they always had, and it is the
+stability test in `customPets.test.ts` that would have caught an over-eager
+change there.
+
+Ten sprites hashed from a key can collide, so the regression test pins "not all
+the same" rather than "all different". The bug collapsed every run onto one
+sprite; shuffling them is not a promise a hash into ten can keep.
+
+Fonte: `src/surfaces/AgentTranscript.tsx:SubagentMascot`
+
+<a id="subagent-name-before-generic-label"></a>
+
+### A named agent beats the generic label
+
+The row's name came from the brief, then from the tool title, then from the
+literal "Subagent", and the event field that could have carried the real name
+was never populated by the adapter. The name was on the wire the whole time: V2
+announces it on `session.agent.selected`, which the fork already turned into a
+"Switched agent to build" status line and then dropped, and `message.updated`
+carries the same `info.agent` that was only read to detect hidden agents.
+
+Both now reach `agent.step` as `agentName`, which the reducer already preferred
+over everything else, so no consumer changed.
+
+The V2 switch rides the `extra` field for the same reason the model switch
+already did: `role` is what admits the event to that path, and the main session
+stops at `systemNotice` before `role` is read, so a notice can never stream as
+assistant prose. The `message.updated` name is the one that survives a replay,
+where no switch event is sent.
+
+The generic label stays as the last link, because a provider that names nothing
+still streams.
+
+Fonte: `src/lib/harness/opencode.ts:subagentNameOf`
+
 <a id="briefs-dont-push-row"></a>
 
 ### Long briefs never push the row off the pane

src/chrome/ProjectMascot.tsx

@@ -3,6 +3,15 @@ import { resolveEffectiveMascot } from "../lib/customPets";
 
 type Props = {
   project: string;
+  /**
+   * What the sprite is drawn from when the row is not a project.
+   *
+   * A subagent run has to be told apart from another run that happens to carry
+   * the same name, and the name is a label rather than an identity. Kept apart
+   * from `project` so nothing downstream reads this as a path, and so the
+   * project rail and the tab groups keep hashing the project they always did.
+   */
+  identity?: string;
   /** Project color; omit to inherit the surrounding text color. */
   color?: string;
   /** Explicit pick from the project menu; falls back to the hashed one. */
@@ -20,12 +29,13 @@ type Props = {
  * looks lumpy. Prefer `size-4`; never pass a fractional size. */
 export function ProjectMascot({
   project,
+  identity,
   color,
   name,
   className = "size-4 shrink-0",
   active = false,
 }: Props) {
-  const mascot = resolveEffectiveMascot(project, name);
+  const mascot = resolveEffectiveMascot(identity ?? project, name);
   return (
     <svg
       aria-hidden

src/lib/harness/opencode.ts

@@ -95,6 +95,8 @@ type Live = {
   /** Child session id -> the agent tool row that spawned it. */
   subagentSessions: Map<string, string>;
   subagentModels: Map<string, string>;
+  /** The agent a subagent session runs under, when the server names one. */
+  subagentNames: Map<string, string>;
   /** Child parts that arrived before their row was known. */
   pendingSubagent: Map<string, OpenCodePart[]>;
   partById: Map<string, OpenCodePart>;
@@ -457,6 +459,7 @@ async function ensureLive(input: HarnessSessionInput): Promise<Live> {
       sessionParentById: new Map(),
       subagentSessions: new Map(),
       subagentModels: new Map(),
+      subagentNames: new Map(),
       pendingSubagent: new Map(),
       partById: new Map(),
       emittedTextByPartId: new Map(),
@@ -1076,6 +1079,22 @@ function rememberPartRole(
   live.messageRoleById.set(id, role);
 }
 
+/**
+ * The agent's own name for a step, when the server has named one.
+ *
+ * Without it the row falls back to the literal "Subagent", and three unnamed
+ * runs on one screen are three identical rows. The name is optional here and in
+ * the event: a provider that never names an agent still streams, it just does
+ * not get a label.
+ */
+function subagentNameOf(
+  live: Live,
+  sessionId: string,
+): { agentName?: string } {
+  const name = live.subagentNames.get(sessionId);
+  return name ? { agentName: name } : {};
+}
+
 function handleSubagentEvent(
   live: Live,
   sessionId: string,
@@ -1104,6 +1123,10 @@ function handleSubagentEvent(
       const callId = live.subagentSessions.get(sessionId);
       if (callId) live.onEvent({ type: "tool.updated", callId, kind: "agent", agentModel: model });
     }
+    // Nota: docs/notes/frontend.md#subagent-name-before-generic-label
+    if (agent && !KNOWN_HIDDEN_AGENTS.has(agent)) {
+      live.subagentNames.set(sessionId, agent);
+    }
     if (id && (role === "user" || role === "assistant")) {
       live.messageRoleById.set(id, agent && KNOWN_HIDDEN_AGENTS.has(agent) ? "hidden" : role);
       // Nota: docs/notes/harness.md#message-metadata-after-parts
@@ -1185,6 +1208,8 @@ function emitSubagentStep(
       stepId: `${sessionId}:${part.id}`,
       kind: part.type === "reasoning" ? "reasoning" : "message",
       text,
+      // Nota: docs/notes/frontend.md#subagent-name-before-generic-label
+      ...subagentNameOf(live, sessionId),
     });
     return;
   }
@@ -1212,6 +1237,8 @@ function emitSubagentStep(
     stepId: `${sessionId}:${part.callID ?? part.id}`,
     kind: "tool",
     text: title,
+    // Nota: docs/notes/frontend.md#subagent-name-before-generic-label
+    ...subagentNameOf(live, sessionId),
     toolKind: kind,
     status:
       status === "error"

src/lib/harness/opencodeLive.test.ts

@@ -365,6 +365,81 @@ describe("OpenCode subagent trails", () => {
     ).toBe(false);
   });
 
+  it("labels a subagent row with the agent the server names", async () => {
+    // Without a name, every row fell back to the literal "Subagent", so three
+    // runs on one screen were three rows saying the same thing. V2 announces the
+    // agent on its own `session.agent.selected`, which the fork narrated into a
+    // status line and then dropped; the message event carries the same name.
+    openCodeVersion = "opencode 2.0.0";
+    const events: HarnessEvent[] = [];
+    const { done } = await startTurn(events);
+    task("a", "child");
+    sessionCreated("child", "session_1");
+    onSseEvent?.({
+      id: "evt_agent",
+      type: "session.agent.selected",
+      created: 1,
+      data: { sessionID: "child", agent: "build" },
+    });
+    message("child", "msg_a");
+    part("child", { id: "prose", messageID: "msg_a", type: "text", text: "Compilando" });
+    idle();
+    await done;
+
+    const session = events.reduce(applyHarnessEvent, newSession("opencode", "/repo"));
+    const run = session.blocks.find((block) => block.tool?.callId === "a")?.agentRun;
+    expect(run?.name).toBe("build");
+    expect(run?.steps.map((step) => step.text)).toEqual(["Compilando"]);
+  });
+
+  it("takes the name from the message event when no switch event arrives", async () => {
+    // The other of the two places the name lives. A resumed or replayed turn has
+    // no `session.agent.selected` to narrate, so the message event's `agent` --
+    // read until now only to spot hidden agents -- is what names the row.
+    const events: HarnessEvent[] = [];
+    const { done } = await startTurn(events);
+    task("a", "child");
+    sessionCreated("child", "session_1");
+    message("child", "msg_a", "assistant", "plan");
+    part("child", { id: "prose", messageID: "msg_a", type: "text", text: "Rascunho" });
+    idle();
+    await done;
+
+    const session = events.reduce(applyHarnessEvent, newSession("opencode", "/repo"));
+    expect(
+      session.blocks.find((block) => block.tool?.callId === "a")?.agentRun?.name,
+    ).toBe("plan");
+  });
+
+  it("names an unnamed run after its brief, and two such runs alike", async () => {
+    // The reported state, kept: a provider that never names an agent gives every
+    // run the same label, which is why the sprite cannot come from the name.
+    const names: Array<string | undefined> = [];
+    for (const callID of ["a", "b"]) {
+      const events: HarnessEvent[] = [];
+      const { done } = await startTurn(events);
+      // No title: the reported state is a run the provider never named, and a
+      // title is a name.
+      part("session_1", {
+        id: `part_${callID}`, type: "tool", tool: "task", callID,
+        state: { status: "running", metadata: { sessionId: `child_${callID}` } },
+      });
+      sessionCreated(`child_${callID}`, "session_1");
+      message(`child_${callID}`, `msg_${callID}`);
+      part(`child_${callID}`, {
+        id: `prose_${callID}`, messageID: `msg_${callID}`, type: "text", text: "Trabalhando",
+      });
+      idle();
+      await done;
+      const session = events.reduce(applyHarnessEvent, newSession("opencode", "/repo"));
+      names.push(
+        session.blocks.find((block) => block.tool?.callId === callID)?.agentRun?.name,
+      );
+    }
+    expect(names[0]).toBeTruthy();
+    expect(names[1]).toBe(names[0]);
+  });
+
   it("carries a V2 subagent model switch onto the row that shows it", async () => {
     // V2 reports the switch as its own `session.model.selected` event, and the
     // translation turns it into a contentless assistant message so the row can

src/lib/harness/opencodeV2.ts

@@ -759,7 +759,10 @@ function v2NoticeEvent(
 ): { notice: string; extra?: Record<string, unknown> } | undefined {
   if (type === "session.agent.selected") {
     const agent = stringField(data, "agent");
-    return agent ? { notice: `Switched agent to ${agent}` } : undefined;
+    // Nota: docs/notes/frontend.md#subagent-name-before-generic-label
+    return agent
+      ? { notice: `Switched agent to ${agent}`, extra: { role: "assistant", agent } }
+      : undefined;
   }
   if (type === "session.model.selected") {
     const label = v2ModelLabel(asRecord(data.model));

src/surfaces/AgentTranscript.mascot.test.ts

@@ -0,0 +1,124 @@
+// @vitest-environment happy-dom
+/**
+ * Three subagents on one screen used to be three identical rows: same name,
+ * same sprite. The sprite was hashed from the name, and an unnamed run is always
+ * called "Subagent", so the hash had nothing to tell apart.
+ *
+ * Each run is rendered on its own because a turn with several runs folds them
+ * into one summary row ("Ran 3 subagents") until the reader opens it. The
+ * sprite a run draws is decided per row, so one render per run is the same
+ * question the grouped view asks once it is open.
+ */
+import { createElement, type ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveEffectiveMascot } from "../lib/customPets";
+import type { Block } from "../lib/session";
+import { AgentTranscript } from "./AgentTranscript";
+
+function stubExperimentalAnimations(value: string) {
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) =>
+      key === "monocode.experimentalAnimations" ? value : null,
+    setItem: () => {},
+    removeItem: () => {},
+  } as unknown as Storage);
+}
+
+beforeEach(() => {
+  stubExperimentalAnimations("1");
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+/** A settled subagent run, which is the state the report was about. */
+function run(id: string, callId: string, name: string): Block {
+  return {
+    id,
+    role: "tool",
+    text: name,
+    tool: { callId, kind: "agent", status: "completed" },
+    agentRun: { name, steps: [] },
+  };
+}
+
+function render(blocks: Block[]): string {
+  return renderToStaticMarkup(
+    createElement(AgentTranscript, {
+      blocks,
+      busy: false,
+      latestTurnAccessory: null as ReactNode,
+    }),
+  );
+}
+
+/**
+ * The mascot's outline.
+ *
+ * Matched on the sprite's own viewBox rather than on the first `d` in the
+ * markup, because the row carries other icons (the disclosure chevron, the
+ * status glyph) that would otherwise be read as the mascot.
+ */
+function mascot(markup: string): string | undefined {
+  const match = /<svg[^>]*viewBox="0 0 8 8"[^>]*>\s*<path d="([^"]+)"/.exec(
+    markup,
+  );
+  return match?.[1];
+}
+
+/** One sprite per run, in the order given. */
+function sprites(runs: Block[]): Array<string | undefined> {
+  return runs.map((block) => mascot(render([block])));
+}
+
+const UNNAMED: Array<[string, string]> = [
+  ["r1", "call_task_1"],
+  ["r2", "call_task_2"],
+  ["r3", "call_task_3"],
+];
+
+describe("subagent mascots", () => {
+  it("tells three runs with the same name apart", () => {
+    // The reported defect: three rows, all called "Subagent", all with the same
+    // face. Asserted as "not all the same" rather than "all different" because
+    // the roster is ten sprites and a hash into ten can collide; what the bug
+    // did was collapse every run onto one sprite, not shuffle them.
+    const drawn = sprites(
+      UNNAMED.map(([id, callId]) => run(id, callId, "Subagent")),
+    );
+    expect(drawn.every(Boolean)).toBe(true);
+    expect(new Set(drawn).size).toBeGreaterThan(1);
+  });
+
+  it("gives the same run the same face twice", () => {
+    // A run's sprite has to survive a re-render, or every stream makes the
+    // mascot flicker to a different face.
+    const [block] = UNNAMED.map(([id, callId]) => run(id, callId, "Subagent"));
+    expect(mascot(render([block]))).toBe(mascot(render([block])));
+  });
+
+  it("keeps a settled run distinct from an earlier one with the same name", () => {
+    // The contract the component used to claim in a comment: two agents in a row
+    // stay distinguishable through the session. Ten sprites hashed from a key
+    // can collide, so the pair is chosen not to (`call_task_a` lands on 4,
+    // `call_task_b` on 5). A roster change that collides them says so here
+    // rather than passing quietly.
+    const [first, second] = sprites([
+      run("r1", "call_task_a", "Subagent"),
+      run("r2", "call_task_b", "Subagent"),
+    ]);
+    expect(first).toBeTruthy();
+    expect(second).toBeTruthy();
+    expect(second).not.toBe(first);
+  });
+
+  it("draws the sprite from the run's key, not from the label", () => {
+    // The sharp form of the contract: the sprite is whatever the run's own key
+    // hashes to. Pinning it to the resolver also means a project mascot, which
+    // has no key, keeps hashing its path, so the sidebar does not move.
+    const [sprite] = sprites([run("r1", "call_task_1", "Subagent")]);
+    expect(sprite).toBe(resolveEffectiveMascot("call_task_1").restPath);
+  });
+});