| 1 | # Session experience |
| 2 | |
| 3 | The desktop Settings page uses one **Session experience** preference to control how work in progress is presented in a transcript. |
| 4 | |
| 5 | ## Modes |
| 6 | |
| 7 | | Mode | While a turn is running | After the turn completes | |
| 8 | | --- | --- | --- | |
| 9 | | **Standard** | Work in progress is visible. | Completed work is collapsed by default; expand it from the message when needed. | |
| 10 | | **Deep** | The complete work process is shown in real time. | Completed work remains expanded; individual sections can still be collapsed manually. | |
| 11 | |
| 12 | This preference applies to reasoning, tool calls, sub-task progress, work-process cards, approvals, validation, and the active turn. It changes presentation only. It does not change the selected model, reasoning strength, provider request, cost, context window, or saved transcript data. |
| 13 | |
| 14 | Manual expand/collapse is a message-level reading action and is retained for the message row. It does not create another global setting. |
| 15 | Overrides are keyed by session and stable process-segment identity in a bounded in-memory cache. They survive React re-renders and transcript window recycling, but intentionally do not persist across application restarts. |
| 16 | |
| 17 | Warnings, approvals, readiness states, extension cards, and other items that require user action remain outside the completed work-process fold, so standard execution never makes an action unreachable. |
| 18 | |
| 19 | ## Configuration and compatibility |
| 20 | |
| 21 | The canonical desktop configuration is: |
| 22 | |
| 23 | ```toml |
| 24 | [desktop] |
| 25 | session_experience = "standard" |
| 26 | ``` |
| 27 | |
| 28 | The only valid values are `standard` and `deep`; missing or invalid values use `standard`. The Go Settings and startup snapshots are authoritative. The TypeScript field remains optional for one release so older backends and historical fixtures fall back to Standard; local storage is never allowed to override a backend snapshot. |
| 29 | |
| 30 | Older setters and fields remain compatibility mirrors for one complete release cycle: |
| 31 | |
| 32 | | Legacy write | Canonical result | |
| 33 | | --- | --- | |
| 34 | | `SetDisplayMode(*)` | Standard | |
| 35 | | `SetReasoningDisplayMode("expanded")` | Deep | |
| 36 | | any other reasoning value | Standard | |
| 37 | | `SetExpandThinking(*)` | Standard | |
| 38 | | process fold `expanded` / `auto` | Deep / Standard | |
| 39 | |
| 40 | Every canonical write mirrors `display=standard` and `reasoning=auto|expanded` for rollback compatibility. These fields, setters, events, and local-storage mirrors may be removed only after the next complete release has shipped and downgrade support is no longer required. |
| 41 | |
| 42 | Older binaries can discard unknown fields when rewriting configuration. Compatibility mirrors support old readers; concurrent old/new writers do not guarantee preservation of the new preference. |
| 43 |