Feature: Add “Switch Provider” (safe migrate) for existing agent sessions

[stephanchenette]

Summary

Users cannot change an existing session’s provider without creating a separate agent manually. Add a first-class Switch Provider action
that feels like hot-swap, but is implemented as a safe migration to a new session under the target provider.

Problem

Current behavior locks provider after session creation and provider identity is deeply coupled to runtime/session internals.

Code references:

• src/renderer/components/NewInstanceModal.tsx:1190
• src/renderer/components/NewInstanceModal.tsx:1595
• src/renderer/App.tsx:5951
• src/renderer/App.tsx:6053
• src/main/utils/agent-args.ts:80
• src/main/ipc/handlers/agentSessions.ts:399

Goal

Provide a one-click workflow to switch an existing session to another provider with context continuity, without mutating the original
session’s toolType in place.

Non-Goals

• In-place mutation of session.toolType.
• Reuse of source provider session/thread IDs on target provider.
• Cross-provider normalization of every provider-specific config flag in v1.

Proposed Solution

1. Add a new UI action: Switch Provider... in Edit Agent modal and session quick actions.
2. Implement orchestration API: switchProvider(sourceSessionId, targetProvider, options).
3. Internally reuse existing transfer pipeline from useSendToAgent to create a new session with toolType: targetProvider.
4. Preserve source session unchanged and link provenance metadata on the new session.
5. Auto-focus new session after success and show clear success/failure toasts.

UX Requirements

1. Entry points:

• Edit Agent modal near provider field (read-only stays read-only).
• Session context menu / quick actions.

2. Confirmation modal includes:

• Source provider.
• Target provider.
• Option: Groom context for target provider (default on).
• Option: Archive source session after successful switch (default off).

3. Success behavior:

• Create new session.
• Navigate to new session.
• Add transfer notice in logs.
• Keep source session available unless archive option selected.

4. Failure behavior:

• Source session unchanged.
• No partial mutation.
• Error toast with retry action.

Data Contract (v1)

New fields on Session:

• migratedFromSessionId?: string
• migratedFromProvider?: ToolType
• migrationTimestamp?: number

Portable fields to copy:

• name (or generated “(Provider)” variant if collision)
• projectRoot, cwd
• nudgeMessage
• sessionSshRemoteConfig
• transfer context/logs

Fields not copied directly:

• provider-specific agentSessionId
• provider-specific command args/env where unsafe to map automatically

Acceptance Criteria

1. User can trigger Switch Provider... from Edit Agent and session menu.
2. Switching Claude -> Codex creates a new Codex session with transferred context.
3. Switching Codex -> Claude creates a new Claude session with transferred context.
4. Source session toolType remains unchanged in all cases.
5. New session receives fresh target-provider session/thread ID on first run.
6. Failure in target creation/spawn leaves source session fully intact.
7. Optional archive setting archives source only after successful target creation.
8. Provenance fields are persisted on the new session.
9. Works for local and SSH-enabled sessions.
10. Unit/integration tests cover happy path, failure path, and provenance persistence.

Task Breakdown

1. UI wiring:

• Add Switch Provider... action in NewInstanceModal and session actions.
• Add switch confirmation modal with options.

2. Orchestration:

• Add switchProvider(...) service/hook.
• Reuse useSendToAgent transfer logic instead of duplicating flow.

3. Session metadata:

• Extend Session type with migration provenance fields.
• Persist fields through existing session persistence.

4. Config handling:

• Implement safe portable-copy function for session fields.
• Explicitly exclude provider-specific resume/session identifiers.

5. Archive behavior:

• Add post-success optional archive operation on source session.

6. Telemetry/logging:

• Add structured logs for start/success/failure of switch operations.

7. Tests:

• Add renderer tests for modal/action behavior.
• Add orchestration tests for success/failure semantics.
• Add persistence tests for provenance fields.

Test Plan

1. Manual:

• Start session with provider A, run conversation, switch to provider B, confirm context transfer and new provider execution.
• Repeat with grooming off.
• Repeat with SSH-enabled session.

2. Automated:

• Unit tests for portable-copy mapper and provenance fields.
• Integration tests for orchestration success/failure rollback semantics.
• UI tests for action visibility and modal flow.

Rollout Plan

1. Ship behind feature flag: ENABLE_SWITCH_PROVIDER.
2. Dogfood in internal builds.
3. Remove flag after stability + test coverage meets threshold.

Risks

• Context transfer quality variance across providers.
• Provider-specific config leakage if copy mapping is too permissive.
• User confusion if old and new sessions look identical.

Mitigations

• Clear transfer notice in new session logs.
• Conservative config copy policy in v1.
• Explicit success message: “New session created; original preserved.”

Definition of Done

• Acceptance criteria met.
• Tests added and passing.
• Feature flag enabled for internal testing.
• Docs updated in user-facing session management docs.

4. Add labels if they exist:

• enhancement
• ux
• multi-provider

[pedramamini]

Why not create two agents, different providers, same working directory?

[openasocket]

@stephanchenette check out this PR #391

[stephanchenette]

I could, but that couples model/provider to agent identity, and I’m trying to decouple those. If I create two agents (different providers, same working directory), I’m effectively creating two identities that I now have to coordinate, track, and reconcile. What I’m aiming for is one persistent agent identity whose execution layer (model/provider) can be swapped dynamically. The goal is: model = implementation detail, not identity.

…

On Wed, Feb 18, 2026 at 9:22 PM Dre ***@***.***> wrote: *openasocket* left a comment (RunMaestro/Maestro#408) <#408 (comment)> @stephanchenette <https://github.com/stephanchenette> check out this PR #391 <#391> — Reply to this email directly, view it on GitHub <#408 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALHXJGFOGOUQ6NRR3KWZN34MUT7JAVCNFSM6AAAAACVP7X64WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMRUGQ2TSNJTG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[openasocket]

let me see what i can do in the next day or two.

[openasocket]

Hey @stephanchenette — PR #391 (feat/virtuosos) should address this. Here's what's landed:

Provider Switching (Merge-Back): There's now a first-class "Switch Provider" action available from the agent context menu and Edit Agent modal. It creates a new session under the target provider with full context transfer, while preserving the original session unchanged. The source agent gets archived automatically with visual treatment (reduced opacity, hollow status circle, "Provider switched — archived" label).

Unarchive: If you need to restore an archived agent, there's a new "Unarchive" option in the right-click context menu. If another active agent with the same name and provider already exists, Maestro prompts you to archive or delete it first — so you never end up with duplicate active agents for the same slot.

Provider Health & Analytics: The Virtuosos modal now includes a Provider Health Dashboard with live error monitoring, and you can click into any provider for detailed analytics (daily/hourly charts, duration distribution, error breakdown, comparison benchmarks).

Everything is gated behind the Encore Features → Virtuosos toggle. Would love to know if this solves your use case — give it a spin and let us know!

[stephanchenette]

This looks like it will address my requirement. Has it been pushed to GA or is this for RC only? Stephan

…

On Thu, Feb 19, 2026 at 6:55 PM Dre ***@***.***> wrote: *openasocket* left a comment (RunMaestro/Maestro#408) <#408 (comment)> Hey @stephanchenette <https://github.com/stephanchenette> — PR #391 <#391> (feat/virtuosos) should address this. Here's what's landed: *Provider Switching (Merge-Back):* There's now a first-class "Switch Provider" action available from the agent context menu and Edit Agent modal. It creates a new session under the target provider with full context transfer, while preserving the original session unchanged. The source agent gets archived automatically with visual treatment (reduced opacity, hollow status circle, "Provider switched — archived" label). *Unarchive:* If you need to restore an archived agent, there's a new "Unarchive" option in the right-click context menu. If another active agent with the same name and provider already exists, Maestro prompts you to archive or delete it first — so you never end up with duplicate active agents for the same slot. *Provider Health & Analytics:* The Virtuosos modal now includes a Provider Health Dashboard with live error monitoring, and you can click into any provider for detailed analytics (daily/hourly charts, duration distribution, error breakdown, comparison benchmarks). Everything is gated behind the Encore Features → Virtuosos toggle. Would love to know if this solves your use case — give it a spin and let us know! — Reply to this email directly, view it on GitHub <#408 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALHXJGAUNARTHBRODQRX2D4MZLORAVCNFSM6AAAAACVP7X64WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMZQHE3TMNBVHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[stephanchenette]

Please push this capability. Anthropic is severely restricting it's rate limit and I want to be able to hot swap out my agents which have their own way outside of a claude sessio of knowing where to pick up work where the last claude session left off. On Thu, Feb 19, 2026 at 8:04 PM Stephan Chenette ***@***.***> wrote:

…

This looks like it will address my requirement. Has it been pushed to GA or is this for RC only? Stephan On Thu, Feb 19, 2026 at 6:55 PM Dre ***@***.***> wrote: > *openasocket* left a comment (RunMaestro/Maestro#408) > <#408 (comment)> > > Hey @stephanchenette <https://github.com/stephanchenette> — PR #391 > <#391> (feat/virtuosos) should > address this. Here's what's landed: > > *Provider Switching (Merge-Back):* There's now a first-class "Switch > Provider" action available from the agent context menu and Edit Agent > modal. It creates a new session under the target provider with full context > transfer, while preserving the original session unchanged. The source agent > gets archived automatically with visual treatment (reduced opacity, hollow > status circle, "Provider switched — archived" label). > > *Unarchive:* If you need to restore an archived agent, there's a new > "Unarchive" option in the right-click context menu. If another active agent > with the same name and provider already exists, Maestro prompts you to > archive or delete it first — so you never end up with duplicate active > agents for the same slot. > > *Provider Health & Analytics:* The Virtuosos modal now includes a > Provider Health Dashboard with live error monitoring, and you can click > into any provider for detailed analytics (daily/hourly charts, duration > distribution, error breakdown, comparison benchmarks). > > Everything is gated behind the Encore Features → Virtuosos toggle. Would > love to know if this solves your use case — give it a spin and let us know! > > — > Reply to this email directly, view it on GitHub > <#408 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AALHXJGAUNARTHBRODQRX2D4MZLORAVCNFSM6AAAAACVP7X64WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMZQHE3TMNBVHA> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

[pedramamini]

Swapping the agent is creates a mess of session logs being mixed up. Why not create a second agent with the same working directory? What's the value in switching providers in an agent?

[stephanchenette]

Hey Pedram, The value in switching providers inside the same agent is continuity of context and role identity. I rely heavily on my PAI-style directory structure (CLAUDE.md, AGENTS.md, memory files, learnings, etc.) to define the agent’s identity and operating model. To me, “Chief of Staff” is a role anchored to a working directory, not to a specific model provider. If I create two separate agents (Claude + Codex) pointing to the same working directory, I now have two logical instances of the same role in Maestro. That forces me to track: - ORG 1 – Chief of Staff (Claude) - ORG 1 – Chief of Staff (Codex) Which conceptually fractures the identity of the agent. When I’m in iTerm, I just cd Chief-of-Staff and run either codex or claude interchangeably. The role stays constant, only the provider changes. If Maestro can’t hot swap providers cleanly, then what I'll do is symlink two directories to a shared base and running two agents is the workaround. But that introduces extra coordination overhead I’m trying to avoid. So the core reason: I view provider as infrastructure. The agent’s identity should remain singular. Stephan

…

On Sun, Feb 22, 2026 at 11:32 AM Pedram Amini ***@***.***> wrote: *pedramamini* left a comment (RunMaestro/Maestro#408) <#408 (comment)> Swapping the agent is creates a mess of session logs being mixed up. Why not create a second agent with the same working directory? What's the value in switching providers in an agent? — Reply to this email directly, view it on GitHub <#408 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALHXJAOEJFM4POK4N7LW6T4NHR4VAVCNFSM6AAAAACVP7X64WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSNBRGQYTKMRQGE> . You are receiving this because you were mentioned.Message ID: ***@***.***>