feat: visual replies become an opt-in beta setting

[t3dotgg]

Visual replies (#15968) shipped on for everyone. It is new and only lightly tested in real clients, so it should start as an opt-in beta, like the Working section.

Visual replies (beta) is now a switch in Settings → General (web and desktop) and Settings → Thread behavior (mobile). It is off by default and syncs across environments like the other shared preferences.

• The setting grants a new html MCP capability when T3 prepares the provider session, the same way agent browser access works. A changed value applies when an agent session next starts.
• Without the capability, html_preview and html_render refuse. The message tells the agent to answer in text and not to try again.
• The always-on "Showing visuals" prompt section moved into the html_render description, so no provider adapter has to know about the setting.
• Pages already in threads still show when the setting is off.

Limitation: the tools still appear in every session's tool list, as the device_* tools do when device access is off. Effect's MCP server lists the same tools for every session. When the setting is off, the agent still sees about 1k tokens of tool descriptions, but it can't use the tools.

Verified: focused tests for the capability grant, the refusal, and the shared settings keys pass, and server, web, and mobile typecheck. I have not tested the switch in a real client.

Made by Claude Opus 5.5 in Claude Code, driven through T3 Code.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes visual replies from an existing default-on behavior to a new default-off, opt-in beta setting, affecting provider session capabilities and HTML tool availability across web and mobile. The persistent setting and shared-environment propagation warrant human review of the product-default change.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: 9ad3d0a3-5f92-4e49-93ab-78697831d089

📥 Commits

Reviewing files that changed from the base of the PR and between 25d5c7c and 4adb9a6.

📒 Files selected for processing (14)

• apps/mobile/src/features/settings/SettingsThreadsRouteScreen.tsx
• apps/server/src/mcp/McpInvocationContext.ts
• apps/server/src/mcp/toolkits/core.test.ts
• apps/server/src/mcp/toolkits/html/handlers.ts
• apps/server/src/mcp/toolkits/html/tools.ts
• apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
• apps/server/src/orchestration-v2/ProviderSessionManager.ts
• apps/server/src/provider/T3OrchestrationInstructions.ts
• apps/web/src/components/settings/SettingsPanels.tsx
• apps/web/src/components/settings/settingsSearch.ts
• docs/user/html-renders.md
• packages/client-runtime/src/state/sharedSettings.test.ts
• packages/client-runtime/src/state/sharedSettings.ts
• packages/contracts/src/settings.ts

💤 Files with no reviewable changes (1)

• apps/server/src/provider/T3OrchestrationInstructions.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

A default-off enableHtmlRenders setting is available in web and mobile settings. Session setup uses it to grant the html MCP capability. HTML tool handlers deny calls when that capability is absent.

Changes

Visual replies setting and controls

Layer / File(s)	Summary
Setting contract and shared state packages/contracts/src/settings.ts, packages/client-runtime/src/state/sharedSettings.ts, packages/client-runtime/src/state/sharedSettings.test.ts	enableHtmlRenders is added to server settings with a default of false, to settings patches, and to shared server settings.
Web and mobile settings controls apps/web/src/components/settings/SettingsPanels.tsx, apps/web/src/components/settings/settingsSearch.ts, apps/mobile/src/features/settings/SettingsThreadsRouteScreen.tsx	Web and mobile settings add a “Visual replies (beta)” switch. Web settings include the option in restore-defaults handling and settings search.
User documentation docs/user/html-renders.md	The documentation says to enable Visual replies (beta) in settings and that the change applies when an agent session next starts.

Session capability and HTML tool access

Layer / File(s)	Summary
Session capability assignment and credential reuse apps/server/src/mcp/McpInvocationContext.ts, apps/server/src/orchestration-v2/ProviderSessionManager.ts, apps/server/src/orchestration-v2/ProviderSessionManager.test.ts	Session setup adds the html capability when enableHtmlRenders is enabled. If settings cannot be resolved, HTML access is disabled. Credential reuse also checks that the existing HTML capability matches the current setting.
HTML tool capability checks apps/server/src/mcp/toolkits/html/handlers.ts, apps/server/src/mcp/toolkits/core.test.ts	html_preview and html_render return capability_denied when the session lacks the html capability. Tests cover denied and permitted render calls.
HTML tool guidance apps/server/src/mcp/toolkits/html/tools.ts, apps/server/src/provider/T3OrchestrationInstructions.ts	The render tool description adds diagrams and image collages as examples. The “Showing visuals” orchestration guidance is removed.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ServerSettings
  participant ProviderSessionManager
  participant AgentSession
  participant HTMLHandlers
  ServerSettings->>ProviderSessionManager: provide enableHtmlRenders
  ProviderSessionManager->>AgentSession: include or withhold html capability
  AgentSession->>HTMLHandlers: call html_preview or html_render
  HTMLHandlers->>AgentSession: return capability_denied when html is absent

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 4adb9

No identified issue blocks merging. The switch has not yet been exercised in a real client.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 12 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: Visual replies become an opt-in beta setting.
Description check	✅ Passed	The description explains the problem, the cross-client setting and capability changes, the scope, and focused verification results. It also states that the switch was not tested in a real client. The …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 12 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

🧰 Additional context used

📚 Code guidelines (2)

docs/internals/effect-services.md — auto-discovered
AGENTS.md — auto-discovered

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful main measurement shown below.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	4.9 KiB	−23 B (−0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−23 B (−1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.8 KiB	−41 B (−0.2%)	29.3 KiB	✅
Codex	Live turn messages	2	1	−1 (−50.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	1	1	0 (0.0%)	8	✅

Baseline: 677d152 · PR result: 4adb9a6 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.