kandev/docs/specs/ui/acp-model-configuration-summary.md

status, created, owner

status	created	owner
shipped	2026-07-15	kandev

ACP Model Configuration Summary

Why

ACP agents can advertise an arbitrary ordered set of model-adjacent session configuration options. Showing every selected value in the task chat model trigger makes the compact chat toolbar difficult to scan, while showing values without their provider-supplied context makes unfamiliar modes hard to understand. Users need a compact indication of configuration changes without Kandev hard-coding provider-specific option knowledge.

What

• Kandev records a write-once baseline of the initial ACP select-option values advertised by the provider before agent-profile or runtime overrides are applied. The baseline is stored in the task-session database metadata and survives backend restart, process recreation, and ACP session resume.
• The provider-default baseline is separate from mutable runtime configuration and is never used to restore provider state. A profile-selected value that differs from the provider default is therefore shown as changed as soon as the task session starts.
• Workflow restoration uses a separate immutable original effective configuration captured after profile settings settle. It does not change the comparison-only ownership of the provider-default baseline. See Conditional Workflow Session Settings and ADR-2026-08-01-workflow-session-original-configuration.
• In the task chat input and task context surfaces, the closed model selector always shows the current model name followed by every non-model config value whose raw current value differs from its baseline value, in ACP-provided option order. Values are joined by a slash with surrounding spaces; option names are omitted. Example: GPT-5.6-Sol / Low / On.
• Until a session baseline is available, the closed task selector shows every current non-model value rather than hiding options whose changed state cannot yet be determined.
• A value that returns to its baseline disappears from the closed summary. A currently advertised option with no baseline entry is treated as changed. Baseline entries for options the provider no longer advertises are ignored.
• Hovering or focusing the closed task selector shows a compact tooltip containing every currently rendered selector option as provider-supplied Name: Value rows, including baseline-matching values. The tooltip contains no descriptions or inferred provider knowledge. Opening the selector shows compact option names and selected values; entering an option submenu shows that option's provider description and the provider descriptions of its selectable values when supplied.
• Kandev preserves optional ACP descriptions for both top-level config options and selectable values throughout the adapter, backend event, WebSocket, store, and selector pipeline. Missing descriptions produce no invented or hard-coded explanatory text.
• Task-detail boot data includes the last persisted model list, live config options, and provider-default baseline so the compact label is complete on the first render instead of repainting after WebSocket reconnection.
• Resetting agent context creates a fresh provider-native conversation without changing the task session's effective ACP runtime configuration.
• Before the reset, Kandev captures the effective model, permission mode, and every selected ACP configuration option.
• After the reset, Kandev reapplies the captured model, mode, and options before it sends another prompt.
• Fresh-session default events cannot replace the captured restoration intent. Provider convergence events remain the source of truth for accepted state, persistence, and UI hydration.
• During process resume, each task session keeps its last persisted model until that session reports its settled startup configuration.
• An unsettled provider-default event cannot replace durable runtime configuration or relabel an unnamed session tab.
• A session tab and its task selector use one authoritative current model. Contradictory intermediate option data cannot give these surfaces different labels.
• An unnamed agent tab derives its title from the task session's authoritative current model. Live config values may identify the current model, but non-model config values and the session mode are never appended to the tab title. The title updates when the model changes and remains correct after a task-detail refresh; a user-supplied session name continues to override the derived title.
• Each turn stores an immutable configuration snapshot when the turn is created. The snapshot contains the effective model, mode, ordered selected config values with their provider-supplied display names, and the task-session provider-default baseline used for comparison. Agent-message metadata renders from this turn snapshot instead of the session's latest mutable runtime configuration.
• Agent-message metadata always shows the attributed model and shows only non-model config values that differ from the turn's captured baseline. It keeps option names in the compact row because message attribution is read outside the selector context. Baseline-matching values and the session mode are omitted from the compact row; the mode remains available in turn metadata.
• Prompt-usage metadata may refine the turn's attributed model when the provider reports the actual model used, but it does not replace the turn's captured config values or baseline.
• Legacy turns without a configuration snapshot show their available message- or turn-level model attribution only. They never borrow current session options, because doing so would relabel historical output.
• The compact baseline-aware summary applies only to task chat input and task context model selectors. Shared selector uses such as agent-profile settings and utility configuration continue to list every selected value in the closed trigger.
• Dynamic config_option_update payloads replace the live option set while retaining the original persisted baseline. Provider-added, removed, reordered, or dependent options are compared by stable option ID and raw value.
• Legacy task sessions that have no stored baseline establish one from their first fully settled provider configuration after this feature is deployed. They do not attempt to reconstruct historical defaults.

Decision: ADR-2026-08-18-context-reset-preserves-runtime-configuration.

Scenarios

• GIVEN a provider advertises reasoning Medium by default and the selected agent profile requests High, WHEN the task session starts, THEN the closed task-chat selector shows GPT-5.6-Sol / High.
• GIVEN a task session starts with provider-default collaboration Default, reasoning Medium, and fast mode Off, WHEN no profile or runtime option changes, THEN the closed task-chat selector shows only the model name.
• GIVEN that baseline, WHEN reasoning changes to Low, THEN the closed task-chat selector shows GPT-5.6-Sol / Low.
• GIVEN reasoning is Low and fast mode is On, WHEN the selector is closed, THEN it shows GPT-5.6-Sol / Low / On in ACP option order without collapsing the changed values into a count.
• GIVEN a changed value is returned to its baseline, WHEN the selector rerenders, THEN that value is removed from the closed summary.
• GIVEN a task session has changed values, WHEN the backend restarts and recreates or resumes the ACP session, THEN the same baseline is loaded from task-session metadata and the closed summary still identifies the changes.
• GIVEN an ACP option or value supplies a description, WHEN the user enters that option's submenu, THEN Kandev shows the provider text. The closed trigger and top-level option list remain compact, and missing descriptions leave the description region absent.
• GIVEN a task selector has current model and config values, WHEN the user hovers or focuses its closed trigger, THEN a compact tooltip lists every selector option as Name: Value without provider descriptions, including values omitted from the changed-only trigger label.
• GIVEN a task session has persisted dynamic model configuration, WHEN the task-detail page is refreshed, THEN the first rendered selector label includes all changed values without waiting for a WebSocket event.
• GIVEN a task session uses a non-default model, permission mode, and reasoning option, WHEN a workflow step resets context, THEN the fresh ACP session uses all three values before the next prompt.
• GIVEN a fresh ACP session reports provider defaults during reset, WHEN restoration runs, THEN Kandev applies the configuration captured before reset instead of those defaults.
• GIVEN a successful reset restores the complete runtime configuration, WHEN the task page reloads, THEN the model selector and permission selector show the restored values.
• GIVEN a task has Luna and Sol sessions, WHEN restart resumes both and each agent first reports Luna, THEN each tab keeps its persisted model until settlement.
• GIVEN a resumed session has a persisted model, WHEN an unsettled startup event reports another model, THEN the event does not replace durable runtime state or clear model-specific UI state.
• GIVEN a resumed session has settled, WHEN the user changes its model, THEN the tab and task selector both show the new model.
• GIVEN an unnamed agent tab whose selected model changes during the session, WHEN the model update converges or the task-detail page is refreshed, THEN the existing tab title shows only the current selected model instead of the agent profile's original model label or any session mode and non-model config values.
• GIVEN turn A runs with reasoning High, WHEN reasoning changes to Low before turn B, THEN turn A continues to show Reasoning effort: High and turn B shows Reasoning effort: Low.
• GIVEN a turn uses only provider-default options, WHEN its agent-message metadata renders, THEN the compact row shows only the attributed model.
• GIVEN a legacy turn has no configuration snapshot, WHEN the session's runtime options later change, THEN the legacy turn does not display those current options.
• GIVEN the same shared selector is rendered in agent-profile settings, WHEN it is closed, THEN it continues to list all selected values regardless of the task-session baseline.
• GIVEN a narrow touch viewport, WHEN the user taps the selector, THEN all current options and available descriptions remain reachable without hover or horizontal page scrolling.

Data Model

• Task-session metadata contains a dedicated write-once ACP provider-default baseline keyed by config option ID with raw selected values.
• Task-session metadata also contains the latest complete ACP model selector state needed for task-detail boot hydration, including provider-supplied model and option metadata.
• The provider's latest mutable state remains in runtime configuration metadata. Explicit user selections are stored separately and applied as overrides after that provider state, preventing delayed provider events from replacing resume intent. Baseline, live state, and explicit overrides have distinct ownership and lifecycle semantics.
• During STARTING, unsettled provider events do not replace the last settled runtime configuration or selector snapshot. The settled startup event replaces both records.
• Turn metadata contains a minimal immutable configuration snapshot. Selected option IDs and raw values support baseline comparison; captured option/value names and order preserve the provider's display semantics without depending on later session state.
• ACP config option and option-value transport types carry optional descriptions.

Failure Modes

• Failure to persist the first baseline must not prevent the session from running or configuration from being changed. Kandev reports the persistence failure and retries on a later settled configuration event without overwriting a baseline that was successfully stored.
• If the provider rejects a captured model, mode, or configuration option, the conversation reset remains complete and Kandev reports a restoration error.
• A workflow does not send its automatic prompt after a partial restoration. Provider-reported state remains authoritative for values that the provider accepted.
• Unknown option types remain ignored according to existing ACP graceful-degradation behavior.
• Missing option names, value names, or descriptions fall back only to existing raw identifiers/values; Kandev does not infer provider semantics.

Persistence Guarantees

• Once stored, the baseline is not replaced by later ACP updates, user selections, agent-initiated selections, backend restarts, or session resume.
• The complete effective runtime configuration is captured before a context reset can emit fresh provider defaults.
• A fresh default event cannot redefine the model, mode, or option values that Kandev restores.
• A backend restart does not make an unsettled startup event durable when a prior settled model exists.
• Baseline comparison is scoped to the task session, not the agent profile or provider globally.
• Once a turn is created, its configuration snapshot is not changed by later session configuration events. Only provider-reported attribution fields such as the actual model and usage may be added to the turn.

Out of Scope

• Defining or inferring provider defaults beyond the task session's initial provider-advertised configuration.
• Hard-coded descriptions, aliases, importance rankings, or default values for individual ACP providers.
• Reconstructing configuration snapshots for turns created before this behavior shipped.
• Changing the closed-label behavior in agent-profile settings or other non-task selector surfaces.
• Adding support for ACP input control types that Kandev does not otherwise render.
• Changing the mobile task layout or adding a mobile dock-tab surface.