@@ -421,6 +421,7 @@ jobs:
           packages/ui/src/components/session/provider-usage-panel.test.ts
           packages/ui/src/lib/hooks/use-active-session-message-load.test.ts
           packages/ui/src/lib/sdk-manager.test.ts
+          packages/ui/src/lib/tool-content.test.ts
           packages/ui/src/lib/background-read-queue.test.ts
           packages/ui/src/lib/prioritized-read.test.ts
           packages/ui/src/stores/instance-startup-priority.test.ts
 
@@ -9,6 +9,7 @@ Message content visibility and presets, token lines, tool renderers, native sess
 - Status Tokens are independent of message token visibility. A collapsed section uses the non-interactive `renderSummary` slot for one ellipsized session input/output/cost line; expanded content shows session metrics then descendant-inclusive totals as separate wrapping groups. Keep this layout in `styles/panels/status-tokens.css`.
 - Message token disclosures keep one row in both states: collapsed shows the input/output/cost summary chips on a single ellipsized line; expanded swaps the same row to all six chips beside the chevron, which wrap onto further lines when narrow instead of truncating (expansion exists to read every value). Keep the metric renderer local and chip/row styles in `styles/messaging/message-usage.css`.
 - Tool-result images retain native `state.content` and render through the shared `components/tool-call/output-images.tsx` surface, including MCP and specialized tools. Keep image bytes out of text projections (copy/search/speech); image styles live in `styles/messaging/tool-call/images.css`.
+- Transcript pages carry large tool images by reference: the UI's native message list reads (`lib/sdk-manager.ts`) and history windows (`fetchHistoryWindow`) send the `x-codenomad-media: deferred` opt-in (`server/src/opencode/session-media-contract.ts`), and the server replaces each tool image data URI over `INLINE_MEDIA_LIMIT` (32 KiB) with a `/api/workspaces/<id>/session-media/<session>/<message>/<part>/<index>/<sha256>` path (`opencode/session-media.ts`). `toolImageSource` resolves that path on the API base, so the lazy `<img>` loads only shown images; `routes/session-media.ts` serves the bytes of the owned session's native message, pinned by the digest and refused at or after an undo boundary, as an immutable sandboxed image. Single-message reads (`session.message.get`: pruning revisions, previews), live events, user attachments and requests without the opt-in stay whole, so revisions hash native content.
 - Code Mode reads native `metadata.toolCalls` in `tool-call/renderers/execute-data.ts`; keep call-list styling in `styles/messaging/tool-call/execute.css`, with native image/output ownership in the shared tool shell.
 - Native websearch text is parsed conservatively by `tool-call/renderers/websearch-data.ts`; unknown/oversized responses use the shared raw renderer. Recognized provider-consent Forms retain the generic schema/answer path, with layout in `styles/messaging/tool-call/websearch.css`.
 - Session lifecycle features use OpenCode V2's published signals: one `session.execution.{succeeded,failed,interrupted}` per busy period (`lib/native-execution-events.ts`) and `session.retry.scheduled` for provider backoff. The schema-declared `session.idle`/`session.status` are never published; never wire a feature only to them. A terminal event is a hint until `session.active` confirms settlement, which alone announces "A session finished", only for root sessions ending in success, failure or an inactivity stop. Transcript reducers retire at settlement, deferred while prompts stay parked in their inbox or a user shell or unsettled tool call still needs reconciling there. Token/cost lines (`components/message-usage.tsx`) appear once per agent message: the row of an assistant message's final text (the one carrying "delete tools and reasoning") renders, once that message has native usage, the sum (`sumMessageUsage`) of its own usage and of every message holding a tool or reasoning part that cleanup selects (`technicalCleanupParts`). Reuse that selection rather than a separate projection. The line renders inside the content row, so it never shifts `<Index>` items or splits a technical group (whose Delete needs two tools); tool-only steps get no line. A message whose text is followed by tools also counts in the next message's line, as its tools belong to that selection. Sums cover the loaded transcript window only, like cleanup. Capture real streams with `scripts/test-session-lifecycle-native.mjs`.
 
@@ -39,3 +39,29 @@ test("retiring the actual connection preserves complete and streamed native 401
     } finally { await service.shutdown(); await app.close(); await upstream.close() }
   }
 })
+
+test("a transform rewrites only successful JSON responses and releases each request once", async () => {
+  const upstream = Fastify()
+  upstream.get("/api/json", async () => ({ data: [{ uri: "inline" }] }))
+  upstream.get("/api/missing", async (_request, reply) => reply.code(404).send({ data: [{ uri: "inline" }] }))
+  upstream.get("/api/text", async (_request, reply) => reply.type("text/plain").send("plain"))
+  await upstream.listen({ host: "127.0.0.1", port: 0 })
+  const origin = `http://127.0.0.1:${(upstream.server.address() as { port: number }).port}`
+  const app = Fastify()
+  let releases = 0, invalidations = 0
+  app.get("/:path", (request, reply) => forwardRuntimeRequest({
+    request, reply, url: `${origin}/api/${(request.params as { path: string }).path}`, body: undefined, headers: {}, fetch,
+    invalidate: () => { invalidations++ }, release: () => { releases++ },
+    transform: body => { for (const item of (body as { data: Array<{ uri: string }> }).data) item.uri = "deferred" },
+  }))
+  try {
+    const json = await app.inject("/json")
+    assert.equal(json.statusCode, 200)
+    assert.match(String(json.headers["content-type"]), /^application\/json/)
+    assert.deepEqual(json.json(), { data: [{ uri: "deferred" }] })
+    assert.deepEqual((await app.inject("/missing")).json(), { data: [{ uri: "inline" }] }, "errors pass through")
+    assert.equal((await app.inject("/text")).body, "plain")
+    assert.equal(releases, 3)
+    assert.equal(invalidations, 0)
+  } finally { await app.close(); await upstream.close() }
+})
@@ -10,6 +10,8 @@ export async function forwardRuntimeRequest(args: {
   fetch: typeof fetch
   release?: () => void
   invalidate: () => void
+  /** Rewrites a successful JSON response in place before it is relayed whole. */
+  transform?: (body: unknown) => void
 }) {
   const controller = new AbortController()
   let released = false
@@ -47,6 +49,19 @@ export async function forwardRuntimeRequest(args: {
       if (value !== null) args.reply.header(name, value)
     }
     if (!response.body) { release(); return args.reply.send() }
+    if (args.transform && response.ok && /^application\/json\b/i.test(response.headers.get("content-type") ?? "")) {
+      let text: string
+      try { text = await response.text() } catch {
+        // Like an interrupted stream: the connection stays; only this response failed.
+        release()
+        return args.reply.code(502).send({ error: "OpenCode response was interrupted" })
+      }
+      release()
+      let value: unknown
+      try { value = JSON.parse(text) } catch { return args.reply.send(text) }
+      args.transform(value)
+      return args.reply.send(JSON.stringify(value))
+    }
     const stream = Readable.fromWeb(response.body as import("node:stream/web").ReadableStream)
     stream.once("end", release).once("close", release).once("error", release)
     return args.reply.send(stream)
 
@@ -0,0 +1,12 @@
+/**
+ * Opt-in request header of transcript page reads (native message list, history
+ * window): large tool images arrive as session-media paths instead of inline
+ * base64, and the renderer loads each one when it is shown. Shared with the UI.
+ */
+export const DEFERRED_MEDIA_HEADER = "x-codenomad-media"
+export const DEFERRED_MEDIA_VALUE = "deferred"
+
+/** `/api/workspaces/<id>/session-media/<session>/<message>/<part>/<index>/<sha256>` */
+export function isSessionMediaPath(value: string): boolean {
+  return /^\/api\/workspaces\/[^/?#]+\/session-media\/[^/?#]+\/[^/?#]+\/\d{1,6}\/\d{1,6}\/[a-f0-9]{64}$/.test(value)
+}
@@ -0,0 +1,35 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { deferToolMedia, INLINE_MEDIA_LIMIT, mediaDigest, toolFile } from "./session-media"
+import { isSessionMediaPath } from "./session-media-contract"
+
+const image = (bytes: number, mime = "image/png") => ({ type: "file", mime, name: "shot.png", uri: `data:${mime};base64,${"A".repeat(bytes)}` })
+
+test("large tool images become digest-pinned session-media paths; everything else stays inline", () => {
+  const large = image(INLINE_MEDIA_LIMIT), small = image(1024)
+  const mismatched = { ...image(INLINE_MEDIA_LIMIT), mime: "image/jpeg" }
+  const text = { type: "text", text: "A".repeat(INLINE_MEDIA_LIMIT * 2) }
+  const pdf = image(INLINE_MEDIA_LIMIT, "application/pdf")
+  const messages = [
+    { id: "msg_user", type: "user", text: "look", files: [image(INLINE_MEDIA_LIMIT)] },
+    { id: "msg_assistant", type: "assistant", content: [
+      { type: "text", text: "Reading" },
+      { type: "tool", id: "call", name: "read", state: { status: "completed", content: [text, structuredClone(large), small, mismatched, pdf] } },
+    ] },
+  ]
+  const before = structuredClone(messages)
+  deferToolMedia(messages, { workspaceId: "w/1", sessionId: "ses_1" })
+
+  const files = (messages[1] as any).content[1].state.content
+  const path = files[1].uri as string
+  assert.equal(path, `/api/workspaces/w%2F1/session-media/ses_1/msg_assistant/1/1/${mediaDigest(large.uri)}`)
+  assert.ok(isSessionMediaPath(path))
+  assert.deepEqual({ ...files[1], uri: large.uri }, large, "only the URI changes")
+  assert.deepEqual([files[0], files[2], files[3], files[4]], [text, small, mismatched, pdf])
+  assert.deepEqual(messages[0], before[0], "user attachments are not tool results")
+  assert.equal(toolFile(before[1], 1, 1), (before[1] as any).content[1].state.content[1])
+  assert.equal(toolFile(before[1], 0, 0), undefined)
+  for (const value of [undefined, null, {}, [null, { type: "assistant" }, { type: "assistant", id: "m", content: [null, { type: "tool" }] }]]) {
+    assert.doesNotThrow(() => deferToolMedia(value, { workspaceId: "w", sessionId: "s" }))
+  }
+})
@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto"
+import { DEFERRED_MEDIA_HEADER, DEFERRED_MEDIA_VALUE } from "./session-media-contract"
+
+export { DEFERRED_MEDIA_HEADER } from "./session-media-contract"
+/** Data URIs up to this length stay inline. */
+export const INLINE_MEDIA_LIMIT = 32 * 1024
+
+type ToolImage = { type: "file"; mime: string; uri: string }
+
+export function wantsDeferredMedia(headers: Record<string, string | string[] | undefined>): boolean {
+  return headers[DEFERRED_MEDIA_HEADER] === DEFERRED_MEDIA_VALUE
+}
+
+export function mediaDigest(uri: string): string {
+  return createHash("sha256").update(uri).digest("hex")
+}
+
+/** An image the renderer shows inline: a base64 data URI of its declared image type. */
+export function isRenderableToolImage(value: unknown): value is ToolImage {
+  const file = value as Partial<ToolImage> | null
+  if (file?.type !== "file" || typeof file.mime !== "string" || !/^image\/[\w.+-]+$/i.test(file.mime) || typeof file.uri !== "string") return false
+  const header = `data:${file.mime.toLowerCase()};base64,`
+  return file.uri.slice(0, header.length).toLowerCase() === header
+}
+
+export function sessionMediaPath(target: { workspaceId: string; sessionId: string; messageId: string; part: number; index: number; digest: string }): string {
+  const segment = encodeURIComponent
+  return `/api/workspaces/${segment(target.workspaceId)}/session-media/${segment(target.sessionId)}/${segment(target.messageId)}/${target.part}/${target.index}/${target.digest}`
+}
+
+/** A tool result file of a native assistant message, addressed by content positions. */
+export function toolFile(message: unknown, part: number, index: number): unknown {
+  const native = message as { type?: unknown; content?: unknown } | null
+  if (native?.type !== "assistant" || !Array.isArray(native.content)) return undefined
+  const tool = native.content[part] as { type?: unknown; state?: { content?: unknown } } | undefined
+  return tool?.type === "tool" && Array.isArray(tool.state?.content) ? tool.state.content[index] : undefined
+}
+
+/**
+ * Replaces, in place, tool images whose data URI exceeds INLINE_MEDIA_LIMIT in
+ * native messages with their session-media path. The digest pins the exact bytes.
+ */
+export function deferToolMedia(messages: unknown, scope: { workspaceId: string; sessionId: string }): void {
+  if (!Array.isArray(messages)) return
+  for (const message of messages) {
+    if (message?.type !== "assistant" || typeof message.id !== "string" || !Array.isArray(message.content)) continue
+    message.content.forEach((tool: { type?: unknown; state?: { content?: unknown } } | null, part: number) => {
+      if (tool?.type !== "tool" || !Array.isArray(tool.state?.content)) return
+      tool.state.content.forEach((file: unknown, index: number) => {
+        if (!isRenderableToolImage(file) || file.uri.length <= INLINE_MEDIA_LIMIT) return
+        file.uri = sessionMediaPath({ ...scope, messageId: message.id, part, index, digest: mediaDigest(file.uri) })
+      })
+    })
+  }
+}
@@ -60,6 +60,12 @@ async function harness(
       markDelayedUpstreamStarted()
       await new Promise<void>((resolve) => { releaseDelayedUpstream = resolve })
     }
+    if (request.headers["x-test-message-list"] === "1") {
+      const uri = `data:image/png;base64,${"A".repeat(64 * 1024)}`
+      return { data: [{ id: "msg_1", type: "assistant", content: [{ type: "tool", id: "call", name: "read",
+        state: { status: "completed", content: [{ type: "file", mime: "image/png", uri }] } }] }], cursor: {},
+        forwarded: request.headers["x-codenomad-media"] ?? null }
+    }
     reply.header("set-cookie", "upstream_session=secret; Path=/")
     reply.header("www-authenticate", 'Basic realm="OpenCode"')
     reply.header("proxy-authenticate", 'Basic realm="OpenCode proxy"')
@@ -307,6 +313,18 @@ describe("instance proxy location enforcement", () => {
     assert.equal(denied.statusCode, 403)
   })
 
+  it("defers large tool images only in opted-in transcript list reads, never forwarding the opt-in", async () => {
+    const { app } = await harness()
+    const read = async (path: string, optIn: boolean) => (await app.inject({ url: `/workspaces/workspace/instance/api/session/session/${path}`,
+      headers: { "x-test-message-list": "1", ...(optIn ? { "x-codenomad-media": "deferred" } : {}) } })).json()
+    const uri = (body: any) => body.data[0].content[0].state.content[0].uri as string
+    const deferred = await read("message?limit=200&order=desc", true)
+    assert.match(uri(deferred), /^\/api\/workspaces\/workspace\/session-media\/session\/msg_1\/0\/0\/[a-f0-9]{64}$/)
+    assert.equal(deferred.forwarded, null)
+    assert.match(uri(await read("message?limit=200", false)), /^data:image\/png;base64,/)
+    assert.match(uri(await read("message/msg_1", true)), /^data:image\/png;base64,/, "a single message read stays whole")
+  })
+
   it("forwards native execution settlement only for a session owned by the workspace", async () => {
     const { app, requestCount, sessionGets } = await harness()
     const response = await app.inject({ method: "POST", url: "/workspaces/workspace/instance/api/experimental/session/session/wait" })
 
@@ -28,6 +28,7 @@ import { registerYoloRoutes } from "./routes/yolo"
 import { registerPermissionReceiptRoutes } from "./routes/permission-receipts"
 import type { PermissionReceipts } from "../permissions/receipts"
 import { registerSessionPruningRoutes } from "./routes/session-pruning"
+import { registerSessionMediaRoutes } from "./routes/session-media"
 import { registerWorktreeRoutes } from "./routes/worktrees"
 import { registerPendingRequestRoutes } from "./routes/pending-requests"
 import { registerSpeechRoutes } from "./routes/speech"
@@ -74,6 +75,7 @@ import { buildPreviewRuntimeBridge, rewritePreviewImportMap, rewritePreviewJavaS
 import { forwardRuntimeRequest } from "../opencode/compatibility/proxy"
 import { requestAdmission } from "./request-admission"
 import { LOCATION_CONTEXT_HEADER, locationRequestOptions, readLocationContext } from "../opencode/compatibility/location"
+import { DEFERRED_MEDIA_HEADER, deferToolMedia, wantsDeferredMedia } from "../opencode/session-media"
 import { decodeSessionListScope, prepareLocationImport, readRequestLocations, type SessionListScope } from "../opencode/compatibility/proxy-locations"
 import type { RemoteProxySessionManager } from "./remote-proxy"
 import { createOpenCodeUpdateService } from "../opencode-update/service"
@@ -395,6 +397,7 @@ export function createHttpServer(deps: HttpServerDeps) {
   registerYoloRoutes(app, { yoloManager: deps.yoloManager })
   if (deps.permissionReceipts) registerPermissionReceiptRoutes(app, deps.permissionReceipts)
   registerSessionPruningRoutes(app, { workspaceManager: deps.workspaceManager, worktreeDeletionFence })
+  registerSessionMediaRoutes(app, { workspaceManager: deps.workspaceManager })
   registerInstanceProxyRoutes(app, { workspaceManager: deps.workspaceManager, logger: proxyLogger, worktreeDeletionFence, accounts, permissionReceipts: deps.permissionReceipts,
     humanAnswers: { auth: deps.authManager, manager: deps.workspaceManager, settings: deps.settings, bridgeToken: deps.automationBridgeToken,
       remoteDevices: deps.remoteControlManager } })
@@ -1169,7 +1172,13 @@ async function proxyWorkspaceAdmission(args: InstanceProxyRequestArgs, admission
       if (globalFormLocation) headers["x-opencode-directory"] = encodeURIComponent(translatedDirectories.get(globalFormLocation.directory)!)
       const runtimeFetch = connection?.fetch ?? await wait(workspaceManager.getSharedServiceFetch!())
       signal.throwIfAborted()
+      // A transcript page read by the UI: large tool images load on demand.
+      const deferMedia = request.method === "GET" && /^\/api\/session\/[^/]+\/message\/?$/.test(pathname)
+        && wantsDeferredMedia(request.headers)
       return await forwardRuntimeRequest({
+        transform: deferMedia && sessionId
+          ? body => deferToolMedia((body as { data?: unknown } | null)?.data, { workspaceId, sessionId })
+          : undefined,
         request, reply, url: targetUrl.toString(), body, headers,
         fetch: confirmPermission || confirmDeletion ? async (input, init) => {
           const response = await runtimeFetch(input, init)
@@ -1286,6 +1295,7 @@ function sanitizeInstanceProxyRequestHeaders(
     "x-forwarded-for", "x-forwarded-host", "x-forwarded-port", "x-forwarded-proto",
     LOCATION_CONTEXT_HEADER,
     HUMAN_ANSWER_HEADER,
+    DEFERRED_MEDIA_HEADER,
   ])
   const connection = headers.connection
   for (const name of (Array.isArray(connection) ? connection.join(",") : connection ?? "").split(",")) blocked.add(name.trim().toLowerCase())