Preview: reliable screenshots/inspection for tool-conservative models like Fable 5

[mlcyclops]

The report

Some model modes (Claude Fable 5 in particular) "just watch tool calls" instead of verifying their UI in the Preview panel or taking screenshots.

Root cause

Not a vision gap (Fable 5 has high-res vision) and not a missing tool — preview_open/preview_screenshot/preview_inspect are loaded uniformly for every model. Two real causes:

1. Fable 5 reaches for custom tools less than Opus/Sonnet, and sometimes narrates intent ("I'll screenshot it") without emitting the call. Anthropic documents both traits.
2. The screenshot could return empty when the agent preview lane wasn't the front panel (capturePage sees on-screen pixels only), and the model dead-ended there.

The fix

• harness/omp/preview_extension.ts — rewrote the three preview tool descriptions to be trigger-prescriptive ("call this right after you write/edit a UI file… a build/design task isn't done until you've looked at it"). This is Anthropic's recommended lever for Fable 5 — prescriptive at the tool-description level beats piling scaffolding into the system prompt (which hurts Fable 5). The screenshot tool's empty-cache replies now self-correct, routing to preview_open (re-surface) or preview_inspect (reads the rendered DOM via the postMessage bridge — works even when the panel isn't front) instead of dead-ending.
• desktop/renderer/app.ts kickPreviewShotSoon() — captures a fresh shot the moment the agent preview lane surfaces (onPreviewAvailable + switch-to-agent), so a preview_open → preview_screenshot sequence finds a current image without waiting a full 1.5s freshness tick.

Deliberately unchanged: the capturePage on-screen-pixels constraint (a hidden agent lane still can't be screenshotted — that's what preview_inspect is for) and Fable 5's vision.

Verification

• preview_extension 24/24 + demo-P-PREVIEW.3a / .3a-shot green; desktop + root tsc clean.
• Live smoke test (dev server + in-app browser): renderer boots clean, switching to the Agent lane fires kickPreviewShotSoon() with no console errors (capture no-ops gracefully when isElectron is false), and the preview pipeline renders an HTML file end-to-end.
• QA-gated (needs a real environment): the actual capturePage screenshot (Electron main process) and whether Fable 5 now calls the tools (a live Fable 5 session).

Reconciliation

No overlap with the open PRs (#322/#323/#324 are all Dependabot bumps).

🤖 Generated with Claude Code