galaxy/specs/REMOTE-1573/TECH.md

REMOTE-1573 — Tech spec

Context

This spec implements the behavior described in specs/REMOTE-1573/PRODUCT.md. The work touches five areas:

1. New AI settings — two booleans (cloud_handoff_enabled, ampersand_handoff_enabled) in the AISettings settings group (app/src/settings/ai.rs:710-1463).
2. Settings UI — a new widget section on the AI settings page (app/src/settings_view/ai_page.rs) following the pattern of CloudAgentComputerUseWidget (line 6191).
3. Handoff surface gating — using the effective setting value to gate the & prefix (app/src/terminal/input.rs:3721-3751), the /handoff slash command (app/src/terminal/input/slash_commands/mod.rs:882-910), the footer chip (app/src/ai/blocklist/agent_view/agent_input_footer/mod.rs:2043-2053), and the workspace action handler (app/src/workspace/view.rs:20681-20691).
4. Snapshot gating — adding snapshot_disabled to SpawnAgentRequest and setting it from the cloud-conversation-storage state in every client-side spawn path (app/src/terminal/view/ambient_agent/model.rs:967-994, build_handoff_spawn_request at line 569).

How the effective handoff value is derived

The effective value is false when any of these is true (PRODUCT.md invariant 9):

• AISettings::is_any_ai_enabled() returns false
• Cloud conversation storage is effectively disabled (user-level is_cloud_conversation_storage_enabled == false on PrivacySettings, or org-level cloud_conversation_storage_settings == Disable on WorkspaceSettings)
• Feature flags OzHandoff or HandoffLocalCloud are off (existing gate in is_local_to_cloud_handoff_available() at app/src/ai/blocklist/mod.rs:11-16)
• The user has toggled the setting off

This should be computed as a single helper function so all four gating sites share the same logic.

How snapshot_disabled propagates

SpawnAgentRequest is serialized to JSON and sent to POST /agent/run. The server stores it on the queued execution input. The cloud agent reads it from task metadata in AgentSDK::fetch_secrets_and_attachments (app/src/ai/agent_sdk/mod.rs:957) and wires it into AgentDriverOptions.snapshot_disabled. The existing run_snapshot_upload (app/src/ai/agent_sdk/driver.rs:2368-2427) already respects this field. So the only client-side work is adding the field to SpawnAgentRequest and setting it before spawn.

We pass snapshot_disabled through the spawn request rather than checking PrivacySettings directly in the driver because the driver never reads user-configurable settings singletons (PrivacySettings, AISettings, UserWorkspaces). All its configuration flows in through AgentDriverOptions, which is populated from CLI args and server task metadata. The only singletons the driver accesses are FeatureFlag (compile-time/runtime flags) and ServerApiProvider (for API calls). Passing snapshot_disabled on the request keeps the driver's existing input-driven pattern intact.

Proposed changes

1. Add settings to AISettings

app/src/settings/ai.rs: Add two new entries to define_settings_group!(AISettings, ...), following the pattern of orchestration_enabled:

• cloud_handoff_enabled: CloudHandoffEnabled — bool, default true, TOML path agents.warp_agent.other.cloud_handoff_enabled, desktop-only, cloud-synced.
• ampersand_handoff_enabled: AmpersandHandoffEnabled — bool, default true, TOML path agents.warp_agent.other.ampersand_handoff_enabled, desktop-only, cloud-synced.

Add two derived helpers on AISettings:

• is_cloud_handoff_enabled(&self, app) -> bool — returns false when any prerequisite is missing: AI disabled, setting off, feature flags off (delegates to is_local_to_cloud_handoff_available()), or cloud conversation storage off (user-level via PrivacySettings or org-level via AdminEnablementSetting::Disable).
• is_ampersand_handoff_enabled(&self, app) -> bool — returns is_cloud_handoff_enabled(app) && *self.ampersand_handoff_enabled.

2. Add snapshot_disabled to SpawnAgentRequest

inside SpawnAgentRequest: Add an Option<bool> field snapshot_disabled after initial_snapshot_token, with skip_serializing_if = "Option::is_none".

3. Set snapshot_disabled at spawn time

app/src/terminal/view/ambient_agent/model.rs: In build_default_spawn_config, after computing computer_use_enabled, read cloud conversation storage state and set snapshot_disabled on the returned request. Since AgentConfigSnapshot doesn't carry snapshot_disabled (it's a SpawnAgentRequest-level field), the flag must be set in spawn_agent and build_handoff_spawn_request directly.

In spawn_agent (~line 968) and build_handoff_spawn_request (~line 569), set snapshot_disabled: should_disable_snapshot(ctx).then_some(true) on the SpawnAgentRequest.

Add a private helper should_disable_snapshot(ctx: &AppContext) -> bool that returns true when cloud conversation storage is off — either user-level (PrivacySettings::is_cloud_conversation_storage_enabled == false) or org-level (AdminEnablementSetting::Disable).

4. Gate handoff surfaces

All four sites switch from the current is_local_to_cloud_handoff_available() check to the new AISettings::is_cloud_handoff_enabled(app):

• & prefix (app/src/terminal/input.rs:3721-3733): can_activate_cloud_handoff_prefix — replace the is_local_to_cloud_handoff_available() call with AISettings::as_ref(ctx).is_ampersand_handoff_enabled(ctx).
• /handoff slash command (app/src/terminal/input/slash_commands/mod.rs:882-887): Replace the feature-flag check with AISettings::as_ref(ctx).is_cloud_handoff_enabled(ctx).
• Footer chip (app/src/ai/blocklist/agent_view/agent_input_footer/mod.rs:2043-2053): Replace is_local_to_cloud_handoff_available() with AISettings::as_ref(app).is_cloud_handoff_enabled(app).
• Workspace action (app/src/workspace/view.rs:13228): start_local_to_cloud_handoff — replace the feature-flag check with the setting check. This is the final safety net.

is_local_to_cloud_handoff_available() in app/src/ai/blocklist/mod.rs is retained as a pure feature-flag check and called internally by is_cloud_handoff_enabled. Existing callers are migrated to the new setting-aware helper.

5. Settings UI widget

app/src/settings_view/ai_page.rs: Add a new CloudHandoffWidget struct implementing SettingsWidget, placed in the "Experimental" section near CloudAgentComputerUseWidget. Pattern:

• should_render: return true when OzHandoff and HandoffLocalCloud flags are on. The widget handles the disabled state internally.
• render: Compute force-disabled state from cloud-conversation-storage. When force-disabled, render the toggle as disabled with a tooltip. Beneath the parent toggle, conditionally render the & sub-toggle only when the effective handoff value is true (hidden when parent is off).

Follow the exact pattern of AgentAttributionWidget (line 6093) for org-forced-disabled toggles with tooltips, and CloudAgentComputerUseWidget (line 6191) for the overall section layout.

Testing and validation

Unit tests (new file app/src/settings/ai_tests.rs or inline #[cfg(test)] block):

• is_cloud_handoff_enabled returns false when AI disabled, cloud convos off, or setting toggled off. Covers PRODUCT.md invariants 3, 9, 11.
• is_ampersand_handoff_enabled returns false when parent is off or sub-setting is off. Covers invariants 6, 7, 8.
• should_disable_snapshot returns true when cloud conversation storage is user-disabled or org-disabled. Covers invariants 16, 18.

Existing tests:

• app/src/terminal/input_tests.rs already has &-prefix tests (line 5733+). Add a case where cloud_handoff_enabled is false and verify & does not activate handoff compose.

Manual validation:

• Toggle handoff off in settings → verify &, /handoff, and footer chip are all suppressed.
• Disable cloud conversation storage → verify handoff toggle becomes force-disabled with tooltip.
• Spawn a cloud agent with cloud convos off → verify snapshot_disabled: true appears in the spawn request (network log or log::info in spawn_agent).
• Re-enable cloud convos → verify handoff toggle becomes interactive again.

Compilation: cargo check -p warp and cargo clippy --workspace --all-targets --all-features --tests -- -D warnings.

Parallelization

This task is not large enough to benefit from parallel sub-agents. The changes are tightly coupled (the setting definition feeds the UI widget, the gating sites, and the snapshot flag), and the total scope is ~200-300 LOC across ~8 files. Sequential implementation is the right approach.