@workerdeck/ui 0.16.0 → 0.18.0

package/src/components/agent/SubagentStrip.tsx

@@ -0,0 +1,134 @@
+import { ArrowLeft } from 'lucide-react'
+import type { TranscriptItem } from '@workerdeck/react'
+import { cn } from '../../lib/utils.ts'
+import { formatDuration } from '../../lib/format.ts'
+import { Button } from '../ui/Button.tsx'
+import { Ink, Row } from '../terminal/row.tsx'
+import { TerminalSurface } from '../terminal/surface.tsx'
+import { taskBusy, taskFailed, taskIdentity } from '../terminal/tool-run.ts'
+import type { ToolCallItem } from '../terminal/blocks.ts'
+import { usePulse } from './pulse.tsx'
+import { useTicker } from '../terminal/items.tsx'
+
+/**
+ * The one line above a sub-agent takeover: who this is, how it is doing, and the
+ * way back.
+ *
+ * **It claims exactly what the `TaskRow` it was opened from claims** — the same
+ * `taskBusy` / `taskFailed` / tool count over the same items — and deliberately
+ * *not* `SubagentInfo.status`. Protocol documents those two as divergent on
+ * purpose (`index.ts:1476-1487`), but that divergence is transcript-versus-*list*
+ * and this surface **is** the transcript. The disagreement that must not exist
+ * here is between a header and the rows directly beneath it.
+ *
+ * The rollup is still allowed one job — naming an agent whose `Task` call is not
+ * in the transcript — because a label is not content, and `SessionInfo.subagents`
+ * keeps only eight settled records (`SUBAGENT_HISTORY`), so it can never be the
+ * source of what a frame *shows*.
+ *
+ * Both variants, because the panel has two and a strip that only existed in one
+ * would make the takeover a terminal-theme feature rather than a session feature.
+ */
+export function SubagentStrip({
+  task,
+  items,
+  label,
+  onBack,
+  terminal,
+  fontSize,
+  lineHeight,
+}: {
+  /** The spawning call. Absent when the transcript does not have it — the strip
+   *  still draws, because the way back must exist even when the content cannot. */
+  task: ToolCallItem | undefined
+  /** The frame's items, for the busy reading and the tool count. */
+  items: readonly TranscriptItem[]
+  /** Fallback name when there is no task item. */
+  label: string
+  onBack: () => void
+  terminal: boolean
+  fontSize?: number
+  lineHeight?: number
+}) {
+  const busy = task ? taskBusy(task, items) : false
+  const failed = task ? taskFailed(task) : false
+  const pulse = usePulse(busy)
+  const tools = items.reduce((n, item) => n + (item.kind === 'tool_call' ? 1 : 0), 0)
+  // Ticks only while it works, off the same once-a-second clock the working
+  // line uses. A settled agent has no end timestamp to measure against, and
+  // "N tools" is the settled reading anyway — a frozen clock would read as a
+  // stall. Absent `ts` (an item from before the reducer stamped it) simply
+  // draws no elapsed rather than counting from the epoch.
+  const startedAt = busy ? task?.ts : undefined
+  const now = useTicker(startedAt !== undefined)
+  const elapsed = startedAt === undefined ? undefined : formatDuration(now - startedAt)
+
+  const name = task ? taskIdentity(task) : label
+  /**
+   * Running or finished, in the theme's own words rather than new ones:
+   * `taskSummary` already says `working…` and `done` for exactly this state one
+   * row over, and a header that said "running"/"completed" about the same agent
+   * would be a second vocabulary for one fact. The trailing ellipsis is the
+   * theme's in-flight signal; the pulse beside it is the beat.
+   *
+   * Unknown when the transcript has no `Task` call to read — better silent than
+   * confidently wrong about an agent we cannot see.
+   */
+  const status = !task ? undefined : failed ? 'failed' : busy ? `${pulse} working…` : 'done'
+  const detail = [tools > 0 ? `${tools} tool${tools === 1 ? '' : 's'}` : undefined, elapsed]
+    .filter(Boolean)
+    .join(' · ')
+
+  if (terminal) {
+    return (
+      <TerminalSurface fontSize={fontSize} lineHeight={lineHeight} className='shrink-0'>
+        {/* A row on the grid, not a chrome bar: the takeover is a mode of the
+            transcript, and a toolbar in some other metric above it would read as
+            a different application's. The whole line is the target — there is
+            exactly one thing to do here. */}
+        <button
+          type='button'
+          onClick={onBack}
+          aria-label='Back to the session'
+          className='block w-full cursor-pointer text-left'>
+          {/* The arrow is in the gutter unconditionally. It used to give way to
+              the pulse while the agent worked, which put the way *out* of the
+              frame on a timer — the one control here should not come and go.
+              The beat moved into the status instead. `indent` because this is a
+              frame around the rows rather than one of them, and a marker flush
+              against the panel edge reads as a clipped row. */}
+          <Row glyph='←' glyphTone='dim' indent={1} tone={failed ? 'red' : 'green'}>
+            {name}
+            {status ? (
+              <Ink tone={failed ? 'red' : busy ? 'mark' : 'dim'}> · {status}</Ink>
+            ) : null}
+            {detail ? <Ink tone='faint'> · {detail}</Ink> : null}
+          </Row>
+        </button>
+      </TerminalSurface>
+    )
+  }
+
+  return (
+    <div className='flex shrink-0 items-center gap-2 border-b border-border px-3 py-1.5'>
+      <Button variant='ghost' size='sm' onClick={onBack} className='h-6 gap-1 px-1.5'>
+        <ArrowLeft className='size-3.5' />
+        Back
+      </Button>
+      <span
+        className={cn('min-w-0 flex-1 truncate text-body-sm', failed ? 'text-danger' : 'text-fg-2')}>
+        {name}
+      </span>
+      {status ? (
+        <span
+          className={cn(
+            'shrink-0 text-label',
+            failed ? 'text-danger' : busy ? 'text-accent' : 'text-fg-3',
+          )}>
+          {status}
+        </span>
+      ) : null}
+      {detail ? <span className='shrink-0 text-label text-fg-4'>{detail}</span> : null}
+    </div>
+  )
+}

package/src/components/agent/ToolCallCard.tsx

@@ -7,6 +7,14 @@ import { Spinner } from '../ui/Spinner.tsx'
 import { cn } from '../../lib/utils.ts'
 import { toolInputPreview } from '../../lib/format.ts'
 import { toolIcon } from '../../lib/tool-icon.ts'
+import { useToolResultFetcher } from './tool-result-fetch.tsx'
+import { useToolResultImageSrc } from './tool-result-image.tsx'
+// From the terminal folder, which is where the box's one spelling lives: the
+// height calculator is the reason it is a constant at all, and a second copy
+// here would be a second thing to keep in step for no gain. Cards has no
+// calculator — this frame is about not reflowing a virtualized list when the
+// bytes land, which is a claim both themes make.
+import { IMAGE_UNAVAILABLE, imagePlaceholder } from '../terminal/image-box.ts'
 
 export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
 
@@ -81,6 +89,8 @@ type Status = keyof typeof STATE_BADGE
 export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps) {
   const [open, setOpen] = useState(false)
   const [fullResult, setFullResult] = useState(false)
+  const [fetching, setFetching] = useState(false)
+  const fetchResult = useToolResultFetcher()
   const imagePath = imagePathOf(item)
   const status: Status = item.status ?? (item.result === undefined ? 'running' : 'settled')
   const badge = STATE_BADGE[status]
@@ -88,8 +98,14 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
   const Icon = toolIcon(item.name)
 
   const resultText = item.result?.text ?? ''
-  const truncated = !fullResult && resultText.length > RESULT_PREVIEW_CHARS
-  const shownResult = truncated ? resultText.slice(0, RESULT_PREVIEW_CHARS) : resultText
+  const clipped = !fullResult && resultText.length > RESULT_PREVIEW_CHARS
+  const shownResult = clipped ? resultText.slice(0, RESULT_PREVIEW_CHARS) : resultText
+  // The replay sent a head (see protocol's `ToolResultBlock.truncated`): what is
+  // on screen is not merely clipped, it is all this client was given. The press
+  // therefore fetches rather than only lifting the clip, and the count has to be
+  // the real one — `resultText.length` here is the head's.
+  const headOnly = item.result?.truncated === true
+  const totalChars = item.result?.totalChars ?? resultText.length
 
   const details = open ? (
     <div className='flex flex-col gap-2 border-t border-border p-2.5'>
@@ -109,12 +125,21 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
             label={isError ? 'Error' : 'Result'}
                 className={cn(isError && 'border-danger/40 [&_pre]:text-danger')}
           />
-          {truncated ? (
+          {fetching ? (
+            <p className='mt-1 text-label text-fg-3'>
+              Fetching {totalChars.toLocaleString()} chars…
+            </p>
+          ) : clipped || headOnly ? (
             <button
               type='button'
               className='mt-1 text-label text-fg-3 underline-offset-2 hover:underline'
-              onClick={() => setFullResult(true)}>
-              Show all {resultText.length.toLocaleString()} chars
+              onClick={() => {
+                setFullResult(true)
+                if (!headOnly) return
+                setFetching(true)
+                void fetchResult(item.id).finally(() => setFetching(false))
+              }}>
+              Show all {totalChars.toLocaleString()} chars
             </button>
           ) : null}
         </div>
@@ -126,6 +151,18 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
   // tool's own output would be if the engine had sent bytes.
   const image = imagePath && hostImage ? <HostImage path={imagePath} load={hostImage} /> : null
 
+  // Beside the host-path picture above, never instead of it: that one is a file
+  // the engine wrote, read back through `/produced` or `/fs`; these are image
+  // parts of the result itself, addressed by `(seq, toolUseId, part)`. Different
+  // store, different route, and a call can plausibly have both.
+  const resultImages = item.result?.images?.length ? (
+    <div className='flex flex-col gap-2 border-t border-border p-2.5'>
+      {item.result.images.map((ref) => (
+        <ResultImage key={ref.partIndex} toolUseId={item.id} image={ref} />
+      ))}
+    </div>
+  ) : null
+
   return (
     <div
       data-slot='tool-call'
@@ -158,6 +195,7 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
         />
       </button>
       {image}
+      {resultImages}
       {details}
     </div>
   )
@@ -178,6 +216,35 @@ function PlainPayload({
   return <CodeBlock code={code} label={label} variant='panel' className={className} />
 }
 
+/** One image part of a tool result, as the reducer holds it. */
+type ToolResultImage = NonNullable<NonNullable<ToolCallItem['result']>['images']>[number]
+
+/**
+ * An image part of the result, fetched by reference.
+ *
+ * The frame is a **fixed height in all three states** — placeholder, picture,
+ * failure — which is the one rule this shares with the terminal theme and the
+ * only reason it is worth a component: the transcript is virtualized in both,
+ * and a box that appears when the bytes land shoves every row below it down
+ * while the reader is mid-sentence. Unlike `HostImage`, a failure here is *said*
+ * rather than swallowed: there is no host path in the result text to fall back
+ * on, so silence would be a blank frame with no account of itself.
+ */
+function ResultImage({ toolUseId, image }: { toolUseId: string; image: ToolResultImage }) {
+  const { src, failed } = useToolResultImageSrc({ toolUseId, ...image })
+  return (
+    <div className='flex h-60 items-start overflow-hidden rounded-md border border-border bg-surface-hover'>
+      {src ? (
+        <img src={src} alt={imagePlaceholder(image)} className='h-full max-w-full object-contain' />
+      ) : (
+        <span className='p-2 text-label text-fg-4'>
+          {failed ? IMAGE_UNAVAILABLE : imagePlaceholder(image)}
+        </span>
+      )}
+    </div>
+  )
+}
+
 /**
  * A picture that lives on the host, fetched through the gateway's host-file
  * route and shown inline.

package/src/components/agent/Transcript.tsx

@@ -25,15 +25,18 @@ import { Response } from './Response.tsx'
 import { SessionEmptyState } from './SessionEmptyState.tsx'
 import { ToolCallCard } from './ToolCallCard.tsx'
 import { resolveAffordances, type TerminalAffordances } from '../terminal/affordances.tsx'
-import { ToolRunRow, WorkingRow, terminalBlocks } from '../terminal/items.tsx'
-import { estimateBlockPx } from '../terminal/height.ts'
+import { ToolRunRow, WorkingRow, parentOf, terminalBlocks } from '../terminal/items.tsx'
+import { subagentItems, type ToolCallItem } from '../terminal/blocks.ts'
+import { taskBrief } from '../terminal/tool-run.ts'
+import { taskBusy } from '../terminal/tool-run.ts'
+import { briefPx, estimateBlockPx } from '../terminal/height.ts'
 import { TerminalScrubber } from '../terminal/scrubber.tsx'
-import { gapBefore, rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
+import { gapBefore, positionInRow, rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
 import { useHeightEpoch } from './use-height-epoch.ts'
 import { useTranscriptJumps } from './use-transcript-jumps.ts'
 import { Row } from '../terminal/row.tsx'
 import { TerminalSurface } from '../terminal/surface.tsx'
-import { TerminalItemView } from '../terminal/TerminalTranscript.tsx'
+import { BriefRow, TaskRow, TerminalItemView } from '../terminal/TerminalTranscript.tsx'
 import {
   ROW_GAP,
   TranscriptVariantProvider,
@@ -300,9 +303,15 @@ function read(boundary: number | undefined, index: number): boolean {
 
 /** Rows produced inside a subagent (`parentToolUseId != null`) are stepped in
  * behind a rule, so a Task's own output reads as belonging to the tool call
- * above it rather than as the main thread carrying on. */
-function nestedClass(item: TranscriptItem): string | undefined {
-  const nested = 'parentToolUseId' in item && item.parentToolUseId != null
+ * above it rather than as the main thread carrying on.
+ *
+ * **Except inside that sub-agent's own frame**, where those same items are the
+ * top level and there is no main thread to be an aside from — stepping every row
+ * in would draw a rule down the whole surface saying "this happened somewhere
+ * else" about the only thing on screen. */
+function nestedClass(item: TranscriptItem, frameParentId?: string): string | undefined {
+  const parent = 'parentToolUseId' in item ? item.parentToolUseId : undefined
+  const nested = parent != null && parent !== frameParentId
   return nested ? 'border-l-2 border-border pl-3' : undefined
 }
 
@@ -430,6 +439,8 @@ function TranscriptRows({
   terminal,
   replaying,
   stickyPrompt,
+  frameParentId,
+  onOpenSubagent,
   gap,
   fontSize,
   lineHeight,
@@ -443,6 +454,7 @@ function TranscriptRows({
   hostImage,
   jumpToRecapRef,
   repinRef,
+  reveal,
 }: {
   rows: TranscriptRow[]
   boundary: number | undefined
@@ -467,12 +479,18 @@ function TranscriptRows({
   /** Mount the overview-ruler rail (terminal theme only). */
   scrubber?: boolean
   scrubberMarks?: readonly number[]
+  /** Set when these rows are a sub-agent's frame — the id everything here was
+   *  produced inside. Only `nestedClass` needs it: inside the frame those items
+   *  are the top level and must not be stepped in. */
+  frameParentId?: string
+  onOpenSubagent?: (toolUseId: string) => void
   affordances?: TerminalAffordances | boolean
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
   hostImage?: (path: string) => Promise<string | undefined>
   jumpToRecapRef?: RefObject<(() => void) | null>
   repinRef?: RefObject<(() => void) | null>
+  reveal?: { toolUseId: string; nonce: number }
 }) {
   const stick = useStickToBottomContext()
   // The scroll element belongs to an ancestor — `StickToBottom.Content`
@@ -487,7 +505,15 @@ function TranscriptRows({
   // changes, so the per-scroll work below is a walk over prompts rather than
   // over the transcript.
   const promptRows = useMemo(
-    () => rows.flatMap((row, index) => ('item' in row && row.item.kind === 'user' ? [index] : [])),
+    // Top-level prompts only: a subagent's brief is a `user` item too, and one
+    // that escaped absorption (an orphan) must not become the pinned prompt —
+    // it is not what the answer on screen belongs to.
+    () =>
+      rows.flatMap((row, index) =>
+        'item' in row && row.item.kind === 'user' && parentOf(row.item) === undefined
+          ? [index]
+          : [],
+      ),
     [rows],
   )
   // The pinned row must stay mounted even when it is far above the window, so
@@ -603,7 +629,13 @@ function TranscriptRows({
       if (terminal && epoch) {
         const row = rows[index]
         const gapPx = index > 0 && gapBefore(rows, index) ? epoch.line : 0
-        if (row && ('item' in row || 'run' in row))
+        if (row && 'text' in row && row.key === 'brief')
+          // Collapsed by default and clipped to BRIEF_LINES, so its height is
+          // known before it mounts — the same discipline the task row keeps by
+          // always being collapsed when unmounted. Expanding is local state on
+          // a mounted row, which the virtualizer re-measures.
+          return briefPx(row.text, epoch) + gapPx
+        if (row && !('line' in row))
           return estimateBlockPx(row, epoch) + gapPx
         return epoch.line + gapPx // recap: one Row, one line
       }
@@ -715,6 +747,34 @@ function TranscriptRows({
     repinRef,
   })
 
+  // Reveal a tool call from outside the transcript — a sub-agent picked in a
+  // sessions list, whose `Task` row is the thing the reader asked for.
+  //
+  // Keyed on the **nonce**, never on the id: asking for the same sub-agent twice
+  // is a second request, and a props-equal effect would answer only the first.
+  // The lookup goes through `rowIndexForItem` for the reason that function
+  // exists — a row covers a *membership*, not a contiguous span, so a Task's id
+  // resolves to the folded row that absorbed it rather than to a position. That
+  // also makes a nested child's id work, which is what a client holding only a
+  // `parentToolUseId` can offer.
+  //
+  // `'start'`, like the recap seam and the scrubber's marks: the sub-agent's
+  // work runs *downward* from its row, so the reader wants the screen below it.
+  const revealNonce = reveal?.nonce
+  const revealId = reveal?.toolUseId
+  useEffect(() => {
+    if (revealId === undefined) return
+    const itemIndex = items.findIndex(
+      (item) => item.kind === 'tool_call' && item.id === revealId,
+    )
+    // Not here: a compaction, a `/clear`, or simply a client whose list knows
+    // about a Task this transcript has not replayed yet. Staying put beats
+    // jumping somewhere arbitrary.
+    if (itemIndex < 0) return
+    jumpToRow(rowIndexForItem(rows, itemIndex), 'start')
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- the nonce IS the trigger
+  }, [revealNonce])
+
   // The scrubber. Interactivity follows the hover affordance — with
   // `affordances={false}` the rail is passive paint (pointer-events off) and
   // the native scrollbar stays; interactive, the rail IS the scrollbar, so the
@@ -799,7 +859,7 @@ function TranscriptRows({
               <ToolRunRow items={row.run} />
             </div>
           ) : 'item' in row ? (
-            <div className={cn(read(boundary, row.index) && 'opacity-45', nestedClass(row.item))}>
+            <div className={cn(read(boundary, row.index) && 'opacity-45', nestedClass(row.item, frameParentId))}>
               <TranscriptItemView
                 item={row.item}
                 fileUrl={fileUrl}
@@ -808,8 +868,18 @@ function TranscriptRows({
                 terminal={terminal}
               />
             </div>
-          ) : (
+          ) : 'text' in row && row.key === 'brief' ? (
+            <BriefRow text={row.text} terminal={terminal} />
+          ) : 'line' in row ? (
             <RecapRow line={row.line} since={since} terminal={terminal} />
+          ) : (
+            // A task block. No `nestedClass` here: the rule belongs *inside*
+            // the row, around the children it opens onto — the collapsed line
+            // is the main thread's, and stepping it in would say a `Task` call
+            // happened somewhere else.
+            <div className={cn(read(boundary, row.index) && 'opacity-45')}>
+              <TaskRow block={row} fileUrl={fileUrl} onOpenSubagent={onOpenSubagent} />
+            </div>
           )
         // A prompt row's sticky lane — see the pinned-prompt comment above.
         // The lane is sized to the turn; the sticky **head** (one clipped
@@ -824,7 +894,15 @@ function TranscriptRows({
         // paint-only, so under a translate the head would stick against the
         // lane's un-translated box at the top of the list — observed as the
         // row clamped to its lane's bottom edge, never pinning at all.
-        if (terminal && stickyPrompt && 'item' in row && row.item.kind === 'user') {
+        // Same predicate as `promptRows` above — the lane and the forced range
+        // must agree on which rows are prompts.
+        if (
+          terminal &&
+          stickyPrompt &&
+          'item' in row &&
+          row.item.kind === 'user' &&
+          parentOf(row.item) === undefined
+        ) {
           const next = promptRows.find((index) => index > virtualRow.index)
           const laneEnd =
             next === undefined
@@ -867,7 +945,9 @@ function TranscriptRows({
               pendingApprovals={pendingApprovals}
               recapRow={recapRow}
               bookmarks={scrubberMarks ?? []}
+              frameParentId={frameParentId}
               rowIndexFor={(itemIndex) => rowIndexForItem(rows, itemIndex)}
+              positionInRow={(itemIndex) => positionInRow(rows, itemIndex)}
               // The public memoized measurements array — `getTotalSize()` just
               // above refreshed it, and with the calculator feeding
               // `estimateSize` these starts are honest for unmounted rows too.
@@ -976,6 +1056,52 @@ export interface TranscriptProps {
    * message look like it did nothing at all.
    */
   repinRef?: RefObject<(() => void) | null>
+  /**
+   * Scroll a tool call into view — bump `nonce` to ask again for the same one.
+   *
+   * The seam a *list* needs: sub-agent work is nested inside the `Task` call
+   * that spawned it, so "open that sub-agent" can only ever mean "take me to its
+   * row". A `parentToolUseId` works here as well as the Task's own id, since the
+   * lookup resolves an absorbed child to the row that folded it.
+   *
+   * A prop rather than a ref (the shape `jumpToRecapRef` uses) because the asker
+   * is outside this webview entirely and the request travels as data; a ref
+   * would need a live closure at the other end of a postMessage bridge.
+   */
+  reveal?: { toolUseId: string; nonce: number }
+  /**
+   * Render **only** the work one sub-agent did, rather than the conversation —
+   * the sub-agent takeover's frame.
+   *
+   * Membership is `subagentItems` (`terminal/blocks.ts`), which is also the rule
+   * iOS will mirror: everything the agent produced, and not the spawning `Task`
+   * call itself, which *is* the frame rather than a row in it.
+   *
+   * Features are switched off internally whenever it is set, and the gate lives
+   * here rather than at the call site on purpose: each is keyed to a
+   * **full-transcript item index**, so a host that passed a frame and a catch-up
+   * boundary together would not be making a strange choice, it would be making
+   * an incoherent one. Those are the catch-up boundary and its recap row, the
+   * sticky prompt, `reveal`, and the scrubber's **bookmarks** (host indices in
+   * full-transcript space).
+   *
+   * The **scrubber itself stays**, and the distinction is the point: the rail
+   * derives every one of its inputs from the rows it is given, and inside a
+   * frame those are the sub-agent's own — so it marks that agent's prompts,
+   * answers and failures at that agent's offsets. It was originally gated with
+   * the marks, on the reasonable-looking argument that they are one feature;
+   * they are two, and a fifty-tool agent run is exactly where a rail earns its
+   * keep. What stays besides is everything that makes a long stream readable —
+   * virtualization, the height epoch, the follow spring, the replay hold.
+   */
+  frame?: { parentToolUseId: string }
+  /**
+   * Raise the takeover from a `Task` row. Absent draws no affordance, which is
+   * what the plain renderer and the cards variant get: cards folds nothing, so
+   * it has no task blocks to hang this on, and reaches the takeover from the
+   * sessions list instead.
+   */
+  onOpenSubagent?: (toolUseId: string) => void
   className?: string
 }
 
@@ -997,9 +1123,31 @@ export function Transcript({
   catchUp,
   jumpToRecapRef,
   repinRef,
+  reveal,
+  frame,
+  onOpenSubagent,
   className,
 }: TranscriptProps) {
   const terminal = variant === 'terminal'
+  // The frame's own item list, and the single place the takeover's content is
+  // decided. Everything below reads `items` rather than `state.items`, so the
+  // row build, the empty state and the loader all describe the same surface.
+  const items = useMemo(
+    () => (frame ? subagentItems(state.items, frame.parentToolUseId) : state.items),
+    [state.items, frame],
+  )
+  // The spawning call, for the header's claim and to tell "not here yet" from
+  // "not in this transcript" — see the frame placeholder below.
+  const frameTask = useMemo(
+    () =>
+      frame
+        ? state.items.find(
+            (item): item is ToolCallItem =>
+              item.kind === 'tool_call' && item.id === frame.parentToolUseId,
+          )
+        : undefined,
+    [state.items, frame],
+  )
   const gap = ROW_GAP[variant][density]
   const runStartedAt = useRunStart(state.status)
   // A boundary at (or past) the end means nothing is new — no row, no dimming.
@@ -1014,24 +1162,40 @@ export function Transcript({
   // cannot say what you missed. Clamping it would land on `items.length` and
   // read as "nothing is new" — the same outcome, told less truthfully.
   const boundary =
-    catchUp && catchUp.from > 0 && catchUp.from < state.items.length ? catchUp.from : undefined
+    !frame && catchUp && catchUp.from > 0 && catchUp.from < state.items.length
+      ? catchUp.from
+      : undefined
   const recap = useMemo(
     () => (boundary === undefined ? undefined : recapLine(summarizeSince(state, boundary))),
     [state, boundary],
   )
+  // What this agent was asked, when the stream does not already say. A
+  // foreground `Task` forwards its brief as a real nested user message and it is
+  // already the frame's first row; a background agent forwards nothing, and
+  // without this the takeover shows an answer with the question missing. Hence
+  // the guard rather than an unconditional splice — drawn both ways, the reader
+  // would see the same instruction twice.
+  const brief = useMemo(
+    () =>
+      frame && frameTask && !items.some((item) => item.kind === 'user')
+        ? taskBrief(frameTask)
+        : undefined,
+    [frame, frameTask, items],
+  )
   const rows = useMemo<TranscriptRow[]>(() => {
     const fold = (from: number, to: number) =>
-      terminalBlocks(state.items.slice(from, to), from, terminal)
-    if (boundary === undefined || !recap) return fold(0, state.items.length)
+      terminalBlocks(items.slice(from, to), from, terminal)
+    const lead: TranscriptRow[] = brief ? [{ key: 'brief' as const, text: brief }] : []
+    if (boundary === undefined || !recap) return [...lead, ...fold(0, items.length)]
     // Each side of the boundary folds separately, so a shell run never spans it:
     // "what happened while you were away" must not hide inside a count that also
     // covers what you have already read.
     return [
       ...fold(0, boundary),
       { key: 'recap' as const, line: recap },
-      ...fold(boundary, state.items.length),
+      ...fold(boundary, items.length),
     ]
-  }, [state.items, boundary, recap, terminal])
+  }, [items, boundary, recap, terminal, brief])
   return (
     <TranscriptVariantProvider value={variant}>
       {/* The replay hold hides by VISIBILITY, never by not mounting. The rows
@@ -1052,37 +1216,62 @@ export function Transcript({
             fontSize={fontSize}
             lineHeight={lineHeight}
             affordances={affordances}>
-          {state.items.length === 0 && state.status !== 'starting' ? (
+          {frame ? (
+            // The frame's own empty states, and they are two different facts.
+            // A task that is present with nothing under it yet is simply an
+            // agent that has not spoken — the loader below says so. A task the
+            // transcript does not have is either still replaying (say nothing,
+            // the hold is up) or genuinely absent: a `/clear` retired the
+            // conversation it lived in, or the id was never this session's.
+            // **Never auto-exit on that** — navigating out from under a reader
+            // is worse than one honest line they can leave when they choose.
+            frameTask === undefined && !replaying ? (
+              <div className={cn(terminal ? 'term-row text-fg-4' : 'p-4 text-body-sm text-fg-4')}>
+                This sub-agent's work is not in this transcript.
+              </div>
+            ) : null
+          ) : items.length === 0 && state.status !== 'starting' ? (
             <SessionEmptyState
               cwd={state.cwd}
               hasCommands={!!state.commands?.length}
               hasSkills={!!state.skills?.some((s) => s.enabled)}
               canBrowseFiles={canBrowseFiles}
             />
-          ) : (
+          ) : null}
+          {frame && frameTask === undefined && !replaying ? null : (
             <TranscriptRows
               rows={rows}
               boundary={boundary}
               since={catchUp?.since}
               terminal={terminal}
               replaying={replaying}
-              stickyPrompt={stickyPrompt}
+              stickyPrompt={!frame && stickyPrompt}
               gap={gap}
               fontSize={fontSize}
               lineHeight={lineHeight}
-              items={state.items}
+              items={items}
               pendingApprovals={state.pendingApprovals}
+              /* The rail rides the frame's OWN rows, so inside a takeover it
+                 marks the sub-agent's prompts, answers and failures — the thing
+                 a long agent run most needs, and coherent because every input
+                 it takes (`items`, `rowIndexFor`, `offsetOfRow`) is the frame's.
+                 The **bookmarks are not**: those indices are the host's, in
+                 full-transcript space, and painting them here would put marks
+                 at meaningless offsets. See `frame`'s doc for the rest. */
               scrubber={scrubber}
-              scrubberMarks={scrubberMarks}
+              scrubberMarks={frame ? undefined : scrubberMarks}
               affordances={affordances}
               fileUrl={fileUrl}
               attachmentUrl={attachmentUrl}
               hostImage={hostImage}
               jumpToRecapRef={jumpToRecapRef}
               repinRef={repinRef}
+              reveal={frame ? undefined : reveal}
+              frameParentId={frame?.parentToolUseId}
+              onOpenSubagent={frame ? undefined : onOpenSubagent}
             />
           )}
-          {showLoader(state) ? (
+          {(frame ? frameTask !== undefined && taskBusy(frameTask, items) : showLoader(state)) ? (
             terminal ? (
               // The CLI's own working line, and it is a *row of the transcript*
               // rather than a spinner floating over it — one blank line down,