diff --git a/docs/cli/configuration/settings.mdx b/docs/cli/configuration/settings.mdx
index 40854f807..f5d43a8a0 100644
--- a/docs/cli/configuration/settings.mdx
+++ b/docs/cli/configuration/settings.mdx
@@ -44,8 +44,8 @@ Local overrides merge on top of the corresponding `settings.json` at the same le
| Setting | Options | Default | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------- |
-| `model` | Any [available model ID](/models) | Product default | The default AI model used by droid |
-| `reasoningEffort` | `off`, `none`, `low`, `medium`, `high` (availability depends on the model) | Model-dependent default | Controls how much structured thinking the model performs. |
+| `sessionDefaultSettings.model` | Any [available model ID](/models) | Product default | The default AI model used by droid |
+| `sessionDefaultSettings.reasoningEffort` | Reasoning value (model-dependent) — see [Reasoning effort](#reasoning-effort) | Model-dependent default | Controls how much structured thinking the model performs. |
| `sessionDefaultSettings.interactionMode` | `auto`, `spec` | `auto` | Sets whether new sessions start in Auto or Spec Mode. |
| `sessionDefaultSettings.autonomyLevel` | `off`, `low`, `medium`, `high` | `off` | Sets the default [Autonomy Level](/cli/user-guides/auto-run) for new sessions. |
| `cloudSessionSync` | `true`, `false` | `true` | Mirror CLI sessions to Factory web. |
@@ -65,16 +65,25 @@ Local overrides merge on top of the corresponding `settings.json` at the same le
### Model
-Set `model` to a [model ID from Available Models](/models). For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview).
+Set `sessionDefaultSettings.model` to a [model ID from Available Models](/models). For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview).
+
+For backward compatibility, `model`, `reasoningEffort`, `autonomyMode`, `specModeModel`, and `specModeReasoningEffort` are also accepted as top-level keys; droid migrates them into `sessionDefaultSettings` on load. New configurations should nest them under `sessionDefaultSettings`.
### Reasoning effort
-`reasoningEffort` adjusts how much structured thinking the model performs before replying. Available values depend on the model, but typically include:
+`sessionDefaultSettings.reasoningEffort` controls how much structured thinking the model performs before replying. The model picker and the [Available Models](/models) **Reasoning** column show these levels as display labels; use the matching value below in `settings.json`:
-- **`off` / `none`** – disable structured reasoning (fastest).
-- **`low`**, **`medium`**, **`high`** – progressively increase deliberation time for more complex reasoning.
+| Label | `settings.json` value |
+| ------------ | --------------------- |
+| Off / None | `off` / `none` |
+| Minimal | `minimal` |
+| Low | `low` |
+| Medium | `medium` |
+| High | `high` |
+| Extra High | `xhigh` |
+| Max | `max` |
-Anthropic models default to `off`, while GPT-5 starts on `medium`.
+Higher effort increases latency and cost. Which levels are available — and which is the default — depend on the model, so check the **Reasoning** column in [Available Models](/models). Display labels can vary slightly by surface (for example, `max` may appear as **Max** or **Maximum**).
### Autonomy level
@@ -162,7 +171,7 @@ Defaults applied when a new session starts. See also `sessionDefaultSettings.int
| Setting | Type | Options | Default | Description |
| ------------------------------------------------ | ------ | ---------------------------------------- | -------------- | ---------------------------------------------------------- |
| `sessionDefaultSettings.specModeModel` | string | Any [available model ID](/models) | Inherits model | Override the model used when sessions start in Spec Mode. |
-| `sessionDefaultSettings.specModeReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort applied to the spec model. |
+| `sessionDefaultSettings.specModeReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort applied to the spec model. |
## Display and UI
@@ -192,13 +201,13 @@ Configure [Missions](/cli/features/missions) — multi-agent orchestration runs.
| Setting | Type | Options | Default | Description |
| ---------------------------------------------------- | ------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `missionModelSettings.workerModel` | string | Any [available model ID](/models) | Inherits | Default model used by mission worker subagents. |
-| `missionModelSettings.workerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for mission workers. |
+| `missionModelSettings.workerReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for mission workers. |
| `missionModelSettings.validationWorkerModel` | string | Any [available model ID](/models) | Inherits | Model used by mission validators (scrutiny / user-testing workers). |
-| `missionModelSettings.validationWorkerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for validation workers. |
+| `missionModelSettings.validationWorkerReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for validation workers. |
| `missionModelSettings.skipScrutiny` | boolean | `true`, `false` | `false` | Skip scrutiny validation milestones during missions. |
| `missionModelSettings.skipUserTesting` | boolean | `true`, `false` | `false` | Skip user-testing validation milestones during missions. |
| `missionOrchestratorModel` | string | Any [available model ID](/models) | Inherits | Model used by the mission orchestrator. |
-| `missionOrchestratorReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for the mission orchestrator. |
+| `missionOrchestratorReasoningEffort` | string | See [Reasoning effort](#reasoning-effort) | Model default | Reasoning effort for the mission orchestrator. |
| `keepSystemAwakeDuringMissions` | boolean | `true`, `false` | `true` | Prevent the OS from sleeping while a mission is running. |
## Context and compaction
@@ -254,8 +263,10 @@ System-level settings for status line, worktrees, and request timeouts.
```json
{
- "model": "claude-opus-4-7",
- "reasoningEffort": "low",
+ "sessionDefaultSettings": {
+ "model": "claude-opus-4-8",
+ "reasoningEffort": "high"
+ },
"diffMode": "github",
"cloudSessionSync": true,
"completionSound": "fx-ok01",
diff --git a/docs/reference/cli-reference.mdx b/docs/reference/cli-reference.mdx
index df0553520..1cde5c7ff 100644
--- a/docs/reference/cli-reference.mdx
+++ b/docs/reference/cli-reference.mdx
@@ -57,7 +57,7 @@ Customize droid's behavior with command-line flags:
| Flag | Description | Example |
| :-------------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------- |
| `-f, --file ` | Read prompt from a file | `droid exec -f plan.md` |
-| `-m, --model ` | Select a specific [model ID](/models) | `droid exec -m claude-opus-4-7` |
+| `-m, --model ` | Select a specific [model ID](/models) | `droid exec -m claude-opus-4-8` |
| `-s, --session-id ` | Continue an existing session | `droid exec -s session-abc123` |
| `--auto ` | Set [autonomy level](#autonomy-levels) (`low`, `medium`, `high`) | `droid exec --auto medium "run tests"` |
| `--enabled-tools ` | Force-enable specific tools (comma or space separated) | `droid exec --enabled-tools ApplyPatch,Bash` |
@@ -66,8 +66,8 @@ Customize droid's behavior with command-line flags:
| `-o, --output-format ` | Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`) | `droid exec -o json "document API"` |
| `--input-format ` | Input format (`stream-jsonrpc` for multi-turn) | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` |
| `-r, --resume [sessionId]` | Resume a previous session. In interactive mode, `-r` is `--resume`; in `droid exec`, `-r` is `--reasoning-effort`. | `droid -r` |
-| `-r, --reasoning-effort ` | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` |
-| `--spec-model ` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-opus-4-7` |
+| `-r, --reasoning-effort ` | Override reasoning effort; valid values are model-dependent (see [Reasoning effort](/cli/configuration/settings#reasoning-effort)). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` |
+| `--spec-model ` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-opus-4-8` |
| `--spec-reasoning-effort ` | Override reasoning effort for spec mode | `droid exec --use-spec --spec-reasoning-effort high` |
| `--use-spec` | Start in specification mode (plan before executing) | `droid exec --use-spec "add user profiles"` |
| `--skip-permissions-unsafe` | Skip all permission prompts (⚠️ use with extreme caution) | `droid exec --skip-permissions-unsafe` |
@@ -78,8 +78,8 @@ Customize droid's behavior with command-line flags:
| `--fork ` | Fork and resume an existing session into a new copy | `droid exec --fork session-abc123` |
| `--mission` | Run `droid exec` in [mission mode](/cli/features/missions) (multi-agent orchestration) | `droid exec --mission -f mission.md` |
| `--worker-model ` | Model used for mission worker agents | `droid exec --mission --worker-model claude-sonnet-4-6` |
-| `--worker-reasoning-effort ` | Reasoning effort for mission worker agents (`off`, `none`, `low`, `medium`, `high`) | `droid exec --mission --worker-reasoning-effort medium` |
-| `--validator-model ` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-7` |
+| `--worker-reasoning-effort ` | Reasoning effort for mission worker agents (model-dependent; see [Reasoning effort](/cli/configuration/settings#reasoning-effort)) | `droid exec --mission --worker-reasoning-effort medium` |
+| `--validator-model ` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-8` |
| `--validator-reasoning-effort ` | Reasoning effort for mission validator agents | `droid exec --mission --validator-reasoning-effort high` |
| `--append-system-prompt ` | Append custom text to the end of the system prompt | `droid --append-system-prompt "Always run tests."` |
| `--append-system-prompt-file ` | Append the contents of a file to the end of the system prompt | `droid --append-system-prompt-file .factory/system.md` |
@@ -149,7 +149,7 @@ The interactive REPL supports a rich set of keyboard shortcuts for navigation, o
| `Ctrl+J` | Toggle the changelog display (dismiss / restore) |
| `Ctrl+E` | Toggle the approval details view |
| `Ctrl+V` | Paste an image from the clipboard as an attachment |
-| `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) |
+| `Tab` | Cycle reasoning effort through the levels supported by the current model |
| `Shift+Tab` | Cycle interaction modes (Auto → Spec → Mission) |
| `@` | File path autocomplete — typing `@` triggers fuzzy file search |
| `Up` / `Down` | Navigate input history (cycle through previously submitted messages) |