Harness: add support for setting the `HarnessAgent`'s `mode` including mid-session switching

[felixarntz]

While HarnessAgent supports permissionMode, that property is only about how the harness handles approvals for built-in tools by default. However harnesses also typically support multiple modes which aren't about tool approvals, but rather specific instructions and availability of tools, e.g. regular mode vs plan mode.

HarnessAgent doesn't support an abstraction for that yet, and the individual harness adapters don't provide manual control over it either. We should add a top-level mode concept, given how prevalent it is across harness adapters.

Originally reported as part of #19755.

[ai-sdk-factory]

Feature Analysis

Feature is not available.

Feature Description

• Allow callers to select a harness-specific operational mode, such as regular/build or plan, independently of permissionMode and to change that mode on an existing HarnessAgent session.
• On origin/main at commit ed18394, HarnessAgentSettings and HarnessV1StartOptions have no mode field, while HarnessAgentSession and HarnessV1Session have no mode-switching method.
• A focused @ai-sdk/harness type probe confirmed that HarnessAgentSettings['mode'] and HarnessAgentSession['setMode'] are absent; the ACP adapter's internal setMode and setConfigOption calls are used only to map permissionMode during startup and are not exposed to callers.

AI SDK Fit

• The capability fits the harness adapter architecture because multiple runtimes expose an operational mode that changes instructions and tool availability, while HarnessAgent is intended to normalize common session configuration across adapters.
• Mode must remain distinct from permissionMode: permissionMode controls approval defaults, whereas an operational mode can alter the runtime's prompt, workflow, and available tools.
• Initial selection and later switching are lifecycle phases of the same user-facing session-mode contract; splitting them would leave the same concept arbitrarily immutable after session creation and would not satisfy the explicit mid-session behavior.
• The abstraction satisfies the project's rule-of-three guidance through existing mode concepts in ACP, Claude Code, and OpenCode, but provider-specific identifiers and semantics should remain adapter-owned.

Implications / Considerations

• @ai-sdk/harness would likely need an optional initial mode on HarnessAgentSettings and HarnessV1StartOptions plus a HarnessAgentSession method backed by a new HarnessV1Session mode-control capability; mode values could remain harness-specific strings like model identifiers or become adapter-inferred unions.
• The internal HarnessV1 specification and shared bridge protocol need additive mode fields and control messages; optional adapter methods with HarnessCapabilityUnsupportedError would preserve compatibility for existing and third-party adapters that cannot switch modes.
• Mode must be persisted across detach, stop, suspend, resume, and lossy rerun paths, with explicit precedence between the agent's configured default and the current mode saved in lifecycle state.
• The API must define whether switching is restricted to idle periods, applies at the next turn, or can occur while generation is active; active-turn switching needs ordering and continuation semantics because HarnessAgent currently freezes turn settings for unfinished turns.
• The ACP adapter should use a category: mode session config option through session/set_config_option when advertised and fall back to the older session modes API; it should validate values, track config_option_update or current_mode_update notifications, and avoid reusing permissionModeMapping as the public mode abstraction.
• Claude Code needs careful composition because its native plan state is represented through the same permission-mode channel used for approval policy; entering plan mode and restoring regular mode must retain the configured HarnessAgent permissionMode rather than accidentally widening permissions.
• OpenCode can map the abstraction to its selectable primary agents, including build and plan; ACP-backed Cursor, fx, and Grok Build may inherit support when their runtimes advertise mode configuration, while Codex, Cline, Deep Agents, Pi, and other adapters require individual capability audits.
• Mode changes must not bypass activeTools, inactiveTools, toolApproval, or permissionMode; when mode and approval policies conflict, the stricter restriction should remain effective because switching to a powerful mode can otherwise become a privilege escalation.
• No public API change in the ai package appears necessary because HarnessAgent and HarnessAgentSession are exported by @ai-sdk/harness; generalizing mode to every AI SDK Agent would be a separate, broader design decision.
• AI SDK UI message types and framework integrations need no mandatory change for a command-only session API, but exposing available modes, current mode, or provider-initiated transitions to browser clients may require application state or typed data parts.
• Tests should cover type inference, initial forwarding, successful and unsupported switching, invalid modes, permission interactions, active-turn races, lifecycle restoration, and every supported adapter; examples should demonstrate regular-to-plan-to-regular switching, and HarnessAgent, adapter-capability, and provider documentation should be updated.
• No external protocol extension is required because ACP already standardizes mutable session configuration, but the exact common mode contract remains uncertain where providers conflate mode with permissions or expose only startup-time configuration.

Relevant Documentation

• HarnessAgent
• Harness Adapters
• Agent Client Protocol
• Claude Code
• Session Config Options
• Claude Code CLI Reference
• OpenCode Agents