ClaudeDo/docs/superpowers/specs/2026-06-04-inherited-settings-and-turns-design.md

Inherited settings display, per-task overrides, and Turns

Date: 2026-06-04 Status: Approved (design)

Problem

Config inheritance is three-tier (Task → List → Global app settings). Today the UI only signals inheritance with a placeholder sentinel ((inherit) for tasks, (default) for lists) and, for tasks, a faint "Effective if inherited: {value}" hint under Model and Agent. Two gaps:

1. You can't see the actual resolved value an inherited field will use, nor where it comes from (List vs Global).
2. Max turns is global-only (AppSettingsEntity.DefaultMaxTurns = 100). It is not overridable per list or per task, unlike Model / SystemPrompt / AgentPath.

Goals

• Show the real inherited value in-place, muted, with a source-aware marker (inherited · List vs inherited · Global). Picking a value turns it into an override; a reset affordance clears it back to inherited.
• Add Turns (max turns) as an overridable field at both List and Task levels, inheriting from the global default. Numeric box; empty = inherit.
• Keep SystemPrompt as-is (it is additive, not override) but show what gets prepended.

Non-goals

• No change to SystemPrompt merge semantics (stays additive/concatenated).
• No new global settings; DefaultMaxTurns already exists.
• No change to PermissionMode handling.

Inheritance semantics (reference)

Resolved in TaskRunner.BuildRunConfig (~line 388):

Field	Semantics	Resolution
Model	override	task.Model ?? listConfig?.Model ?? global.DefaultModel
AgentPath	override	task.AgentPath ?? listConfig?.AgentPath (no global)
MaxTurns	override	new: task.MaxTurns ?? listConfig?.MaxTurns ?? global.DefaultMaxTurns
SystemPrompt	additive	merged: global + list + task + agent (unchanged)

Lists inherit only from Global (no tier above them), so a list's inherited marker is always inherited · Global.

Design

1. Data layer

• ListConfigEntity: add int? MaxTurns.
• TaskEntity: add int? MaxTurns (nullable override).
• EF Core migration adding max_turns column to list_config and tasks (nullable, no default — null = inherit).
• TaskRunner BuildRunConfig: MaxTurns: task.MaxTurns ?? listConfig?.MaxTurns ?? global.DefaultMaxTurns. ClaudeRunConfig.MaxTurns and ClaudeArgsBuilder already accept/emit --max-turns when > 0 — no change needed there.
• ListRepository.SetConfigAsync (upsert) and TaskRepository.UpdateAgentSettingsAsync extend to carry maxTurns.

2. DTOs / transport

Add int? MaxTurns to (Worker + Ui copies kept in sync):

• UpdateListConfigDto, ListConfigDto (WorkerHub.cs + WorkerClient.cs)
• UpdateTaskAgentSettingsDto (WorkerHub.cs + WorkerClient.cs)
• TaskConfigDto (ConfigMcpTools.cs)

WorkerHub.UpdateListConfig / UpdateTaskAgentSettings persist the new field via the repositories above. MCP SetListConfig / SetTaskConfig gain an optional maxTurns parameter to keep the agent-facing API at parity with the UI.

3. Resolution helper (Ui)

A small helper that, given (taskValue, listValue, globalValue), returns (effectiveValue, source) where source ∈ { Override, List, Global }. Drives the marker text and muted/normal styling for Model, Agent, and Turns so the logic isn't duplicated per field or per editor. Lives in the Ui layer beside its consumers.

4. UI rendering — inherited marker (source-aware)

For Model, Agent, Turns in both ListSettingsModalView and the DetailsIsland "Agent settings (overrides)" expander:

• Remove the (inherit) / (default) sentinel row from the control's item source.
• When no override is set: control shows the resolved value muted/greyed (dropdown shows e.g. "sonnet" dimmed; Turns box shows e.g. "100" as a muted placeholder), and a small badge beside the field label reads inherited · List or inherited · Global.
• On picking a value / typing a number: it becomes an override — text returns to normal color, the badge flips to override (or hides), and a small "↺ reset to inherited" affordance appears that clears the value back to null.
• List modal: source is always Global → badge reads inherited · Global; reset clears to the global default.
• Turns: numeric box, empty = inherit (muted resolved number as placeholder); a typed number is the override.

Rendering approach: a small reusable InheritedFieldHeader control (label + badge + reset button), fed by the resolution helper's source, wraps each field. Keeps the three fields consistent and avoids per-field XAML duplication. Badge / muted styling uses existing design tokens. Visual polish pass is the user's.

5. SystemPrompt (stays plain)

SystemPrompt keeps its plain multi-line text box (additive, not override). Below it, a small read-only, collapsed-by-default hint shows the inherited prompts that will be prepended (global + list), labeled e.g. "Prepended automatically:". No marker, no reset — it never replaces, only appends.

6. Localization

New keys in locales/en.json + locales/de.json (parity enforced by Localization.Tests): marker text (inherited · List, inherited · Global, override), reset affordance label, Turns field label, and the SystemPrompt "prepended automatically" hint. Retire the now-unused vm.details.effectiveIfInherited key (and its German counterpart) if nothing else references it.

Affected files (indicative)

• src/ClaudeDo.Data/Models/ListConfigEntity.cs, TaskEntity.cs
• src/ClaudeDo.Data/Migrations/ (new migration)
• src/ClaudeDo.Data/Repositories/ListRepository.cs, TaskRepository.cs
• src/ClaudeDo.Data/Configuration/ (column mapping for max_turns)
• src/ClaudeDo.Worker/Runner/TaskRunner.cs
• src/ClaudeDo.Worker/Hub/WorkerHub.cs
• src/ClaudeDo.Worker/External/ConfigMcpTools.cs
• src/ClaudeDo.Ui/Services/WorkerClient.cs (+ Interfaces/IWorkerClient.cs)
• src/ClaudeDo.Ui/ViewModels/Modals/ListSettingsModalViewModel.cs + view
• src/ClaudeDo.Ui/ViewModels/Islands/DetailsIslandViewModel.cs + DetailsIslandView.axaml
• src/ClaudeDo.Ui/Views/Controls/ (new InheritedFieldHeader)
• src/ClaudeDo.Ui/ resolution helper
• locales/en.json, locales/de.json

Testing

• Data: migration applies; MaxTurns round-trips through ListRepository.SetConfigAsync and TaskRepository.UpdateAgentSettingsAsync.
• Worker: BuildRunConfig resolves MaxTurns via task → list → global precedence (unit test on the resolution). Existing ClaudeArgsBuilder --max-turns behavior unchanged.
• Ui: resolution helper returns correct (value, source) for each of the override / list / global cases across Model, Agent, Turns.
• Localization: en/de key parity (existing Localization.Tests).
• Test fakes: update hand-rolled IWorkerClient fakes in both test projects for the new DTO fields (per known gotcha).
• Visual verification of the marker / muted styling: flagged for the user (cannot be asserted programmatically).

Open risks

• DTO/ctor changes ripple into hand-rolled test fakes in Worker.Tests and Ui.Tests — must be updated in the same change.
• Removing the sentinel row from dropdowns changes selection binding; ensure null/empty override state is represented without a sentinel item (e.g. dropdown SelectedItem null when inherited).