feat(settings): default agents to provider-native visual tools

[joshfcc]

T3 currently mounts its Preview MCP server into provider sessions and injects Preview-first Codex instructions unconditionally. That prevents users from reliably choosing Codex, Claude, or another provider's native visual tools.

This adds a persisted Agent visual tools setting that defaults to Provider native. The server gates Preview credentials once before adapter dispatch, covering Codex, Claude, Cursor, Grok, and OpenCode; explicitly selecting T3 Preview restores the existing MCP mounts and Codex collaborative-browser instructions. The setting is available in General Settings, applies to newly started sessions, and is documented for Codex and Claude.

Verification:

• 7 focused test files, 202 tests passed
• contracts, server, and web targeted typechecks passed
• independent adversarial review passed after verifying the T3 Preview instruction output remains byte-equivalent to the previous behavior
• no desktop packaging or updater paths changed

Before

After

Built with GPT-5.6 Sol in the Codex harness, with Cursor Grok implementation assistance and Claude Opus adversarial review.

---

Note

Medium Risk
Changes provider session startup, MCP credential lifecycle, and Codex system instructions; mitigated by defaulting to provider-native, fail-closed settings reads, and clearing stale MCP state.

Overview
Newly started provider sessions no longer always get the T3 Preview (t3-code) MCP server and Codex collaborative-browser developer instructions. A persisted agentVisualToolsMode setting defaults to provider-native; t3-preview restores the prior behavior for new sessions only.

Server: ProviderService reads the setting before issuing MCP credentials—fail-closed to provider-native if settings cannot be loaded. In provider-native mode it skips credential issuance and revokes/clears stale MCP state so threads do not inherit preview tools. Adapters (Claude, Codex, etc.) mount t3-code only when an MCP provider session exists.

Codex: T3 Preview routing text is appended to collaboration-mode instructions only when includeT3PreviewTools is true, detected via hasConfiguredT3CodeMcpServer (not generic MCP args). Base plan/default instruction exports stay preview-free.

Product: General settings UI, search catalog, contract schema/defaults, and Codex/Claude user docs describe the control and that already-running sessions are unaffected.

^{Reviewed by Cursor Bugbot for commit 8a68a5b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Default agents to provider-native visual tools with a settings toggle for T3 Preview mode

• Adds a new agentVisualToolsMode server setting ('provider-native' | 't3-preview', default 'provider-native') in settings.ts.
• When in 'provider-native' mode, ProviderService clears any stale MCP session and skips T3 Preview credential issuance; in 't3-preview' mode it issues credentials and mounts the MCP session as before.
• Codex session turns include T3 Preview routing in developer_instructions only when the merged app-server args configure the t3-code MCP server, gated by the new hasConfiguredT3CodeMcpServer util in CodexSessionRuntime.ts.
• Adds an "Agent visual tools" select control to the General settings panel so users can switch modes and restore the default.
• Behavioral Change: agents that previously received T3 Preview routing instructions by default will now run provider-native unless the setting is explicitly switched to 't3-preview'.

^{Macroscope summarized 8a68a5b.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4204f63a-8b45-4f3d-a475-5928cc3a7927

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new user-configurable feature that controls which visual tools (provider-native vs T3 Preview MCP) agent sessions receive. New features affecting agent capabilities and session configuration warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}