3 files changed, 50 insertions, 2 deletions

diff --git a/packages/core/src/agent/agent.ts b/packages/core/src/agent/agent.ts
index c6f1322..4bfa7eb 100644
--- a/packages/core/src/agent/agent.ts
+++ b/packages/core/src/agent/agent.ts
diff --git a/packages/core/src/agents/loader.ts b/packages/core/src/agents/loader.ts
index f4a6c5a..9971803 100644
--- a/packages/core/src/agents/loader.ts
+++ b/packages/core/src/agents/loader.ts
@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parse as parseTOML, stringify as stringifyTOML } from "smol-toml";
-import type { AgentDefinition, AgentModelEntry } from "../types/index.js";
+import { type AgentDefinition, type AgentModelEntry, isReasoningEffort } from "../types/index.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────
 
@@ -192,6 +192,7 @@ export function saveAgent(agent: AgentDefinition): void {
 		tomlContent.models = agent.models.map((m) => ({
 			key_id: m.key_id,
 			model_id: m.model_id,
+			...(m.effort ? { effort: m.effort } : {}),
 		}));
 	}
 
@@ -246,9 +247,14 @@ function loadAgentsFromDir(dir: string, scope: string): AgentDefinition[] {
 			if (Array.isArray(parsed.models)) {
 				for (const m of parsed.models) {
 					if (m && typeof m === "object" && "key_id" in m && "model_id" in m) {
+						const rawEffort = (m as Record<string, unknown>).effort;
 						models.push({
 							key_id: String((m as Record<string, unknown>).key_id),
 							model_id: String((m as Record<string, unknown>).model_id),
+							// Only carry `effort` when it's a recognised level; an
+							// unset or invalid value falls back to the per-tab /
+							// default effort at the call site.
+							...(isReasoningEffort(rawEffort) ? { effort: rawEffort } : {}),
 						});
 					}
 				}
diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts
index ced3dc2..bab17f1 100644
--- a/packages/core/src/types/index.ts
+++ b/packages/core/src/types/index.ts
@@ -308,7 +308,43 @@ export interface ToolDefinition {
 
 // ─── Agent Configuration ─────────────────────────────────────────
 
-export type ReasoningEffort = "none" | "low" | "medium" | "high" | "max";
+/**
+ * Canonical, ordered list of reasoning-effort levels — the SINGLE SOURCE OF
+ * TRUTH for effort values across the whole codebase (core LLM call site, API
+ * validation, agent TOML persistence, and the frontend UI). Ordered from least
+ * to most effort.
+ *
+ * `none` disables reasoning. `low`/`medium`/`high`/`xhigh` are forwarded
+ * verbatim to providers that accept them (OpenAI-compatible `reasoning_effort`,
+ * Anthropic adaptive `effort`) — `xhigh` is accepted by newer OpenAI reasoning
+ * models. `max` is Dispatch's own top tier, mapped per-provider at the call
+ * site (e.g. classic-thinking Claude budget tokens).
+ */
+export const REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"] as const;
+
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+/**
+ * Default effort applied when nothing more specific is configured (no per-model
+ * effort and no per-tab selection). Resolution order is
+ * per-model → per-tab → this default.
+ */
+export const DEFAULT_REASONING_EFFORT: ReasoningEffort = "high";
+
+/** Human-readable labels for each effort level (UI display). */
+export const REASONING_EFFORT_LABELS: Record<ReasoningEffort, string> = {
+	none: "Off",
+	low: "Low",
+	medium: "Medium",
+	high: "High",
+	xhigh: "X-High",
+	max: "Max",
+};
+
+/** Runtime type guard for narrowing an arbitrary value to a `ReasoningEffort`. */
+export function isReasoningEffort(value: unknown): value is ReasoningEffort {
+	return typeof value === "string" && (REASONING_EFFORTS as readonly string[]).includes(value);
+}
 
 export interface AgentConfig {
 	model: string;
@@ -416,6 +452,12 @@ export interface QueueCallbacks {
 export interface AgentModelEntry {
 	key_id: string;
 	model_id: string;
+	/**
+	 * Per-model/key reasoning effort. When set, overrides the per-tab effort
+	 * selector for generations that use this entry (resolution order:
+	 * per-model → per-tab → DEFAULT_REASONING_EFFORT). Omitted when unset.
+	 */
+	effort?: ReasoningEffort;
 }
 
 export interface AgentDefinition {