[Bug]: html_render can't reuse a previewed page, so agents re-emit the full HTML on every call

[nbrosei]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/server

Steps to reproduce

1. In a Claude Code thread (Opus 5.5), ask for an example inline visualization.
2. The agent follows the tool descriptions: it builds one self-contained page, checks it with html_preview, then publishes it with html_render.
3. Look at the tool calls. The agent previewed dark mode, then light mode at phone width, then published. All 3 calls carry the full document (~9 KB) in html, because neither tool accepts a reference to a page T3 already has.

Expected behavior

Once T3 holds a page from html_preview, publishing it should not require the agent to emit it again. Output tokens are the slowest and most expensive part of a turn, so the preview → publish loop should send the page once.

Possible fix: html_preview returns a previewId, and html_render accepts it in place of html. The server already holds that document, so this adds no filesystem access. A workspace-scoped path parameter would also save tokens across preview iterations, but it runs into the concern from the #15916 security review (server reads of agent-chosen paths without caller authorization), so previewId looks like the smaller step.

Related: #17466 (Ideas: reuse a published render with new data) has the same root cause in a different case, across runs instead of within one turn. #16651 was a similar token-cost report.

Actual behavior

The same ~9 KB page went out 3 times as tool input, roughly 3K output tokens per copy (estimated at ~3 characters per token), where one copy would do. The turn took close to 4 minutes for a simple "show me an example" request. I have no per-step timings, but re-emitting the page was likely the largest share.

The waste grows with page size × number of checks, so it penalizes exactly the preview-before-publish loop the tool descriptions ask for. To save tokens, an agent has to skip previews.

Impact

Minor bug or occasional failure

Version or commit

t3 v0.0.45

Environment

macOS 26.6.2, Claude Code 2.1.296, claude-opus-5-5

Logs or stack traces

# Current tool inputs (t3 v0.0.45). The page can only be passed inline.
html_preview: html (required), appearance, width
html_render:  html (required), title, height

Screenshots, recordings, or supporting files

No response

Workaround

None that keeps the check. The agent can preview only once, run its previews in parallel, or skip previewing, which gives up the verification the tools recommend.

---

Drafted by Claude Opus 5.5 in Claude Code (via T3 Code); reviewed and posted by @nbrosei.

[PrinceJunkie]

Still present in t3 v0.1.0 (macOS 26.7.1, Claude Code 2.1.303, claude-opus-5-5). Both tools still accept the page only as inline html.

These numbers come from one turn and are measured, not estimated: they're the API usage in the Claude Code transcript, with thinking tokens subtracted from output tokens.

Call	Page size	Output tokens for the page
html_preview	25,088 chars	~13,270
html_render	25,031 chars	~13,240

That works out to about 1.9 characters per token for a page with inline JSON data and minified JS. The ~3 chars/token estimate above understates the cost by roughly 1.6x for pages heavy on data. Both copies also stay in context for the rest of the thread, so one preview plus one render added about 26.5K tokens.

+1 to previewId as the first step.

[b1uegh0st]

I know this is a small token-efficiency item, but small stuff adds up — and with large inline HTML renders (which I often prefer to ASCII/markdown, especially reading on mobile) the double write is the dominant cost of a visual.

Independent repro, still present: T3 0.1.6-nightly.20261030 on Windows 11, Claude Code / Opus 5.5. Across 10 recent html_preview/html_render calls in 3 sessions, the same page (2.6k–15k chars) was emitted 2–3× per visual. Output tokens are the expensive and slow part of a turn, so this roughly doubles a visual's cost.

No agent-side workaround exists: pointing the page at a local file (<iframe src="file:///…"> or fetch()) is blocked by the renderer ("Not allowed to load local resource"), so the agent has to re-type the HTML.

Possible fixes (either would solve it):

1. previewId, as specified in feat(server): html_preview and html_render reuse a previewed page by id #18528: preview returns an id, and render (or a second preview) takes the id instead of html.
2. path: render/preview accept an absolute path to a local HTML file that the server reads. That also lets an agent show an HTML report it already wrote to disk at zero extra output tokens, which is the bigger win for long reports.

Happy to help test either. Would a maintainer be open to approving the direction so #18528 (or a path variant) can be reopened?