feat(persona,model,loop): 人格 thinking 配置 + 5 个死字段接线 + 推理旋钮（按 provider 映射）

按 DevDocs/design/01 §2.1/§2.2 与 design/04 §3.2 实现（规格含联网核过的官方依据：思考内容刻意不角色化、不写分步思考指令、思考控制只走参数级）。
- 人格 schema 新增 thinking：budgetTokens / effort / showToUser(*bool，省略=nil=保持现行为，显式 false=只落库) / mode(default|on|off→Enable 三态)；非法 mode/负预算 → ErrInvalidThinking（不静默）
- 5 个死字段接上注入：personality→values→speechStyle→catchphrase→background 拼为独立段落（带【】小标题，空值不拼）；**全空时输出与旧实现逐字节一致**（有专门测试）
- model.Request 新增 Thinking{ BudgetTokens, Enable } 与 ReasoningEffort；新增 model/reasoning.go：厂商识别（模型名→baseURL 兜底）、取值白名单（OpenAI 系 none…max / DeepSeek low|high|max）、非法值降级+WARN、**不支持一律 WARN 而非静默**；Anthropic 映射 thinking{budget_tokens} 并**保证 budget<max_tokens**（不足时抬高 max_tokens+WARN，正是历史上思考吃光预算→空回复那个坑）
- loop：新增 Options.ThinkingShowToUser(*bool) 仅门控 thinking_* 帧（正文/工具帧不受影响）；场景级 mute 语义不变
- 补一处任务清单外但必需的接线：persona→model.Request 的 thinking 映射（否则 budget/effort/mode 会变成新的死字段）；showToUser 刻意不产生 Thinking（纯呈现开关）
- 管理端：personaUpsertRequest 补 thinking DTO + 校验（400）；PUT 省略时**保留已存块**（防旧客户端抹配置）；写侧 yaml round-trip 已验证
- Docs/api-client v0.40→v0.41（可选请求字段）
- 测试：26 个新用例（loader 解析/拼接逐字节/映射、anthropic 非流式+流式预算约束、openai 透传/降级/丢弃、Qwen 诚实 WARN、loop 门控、DTO round-trip）；3 次变异验证（省略与 false 混同 / 去掉预算约束 / 短路门控 各自 FAIL）
- 验收：go build/vet/test 全绿（含 57 包）+ linux/darwin 交叉编译 + 前端 build；唯一 FAIL 是既有 flake TestInterruptCancelsTurnAndClearsPending（3/20 新代码 vs 3/20 纯 HEAD，已归因非本次引入）

Docs/api-client.md

@@ -110,7 +110,7 @@
 - Web 端镜像实现在 `frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 对未知值返回原值），权威仍以本端点为准。
 - **反漂移保证（后端）**：后端有测试断言「每个内置适配器的 `Name()` 都在 `platforms` 表内」「`moods` 与 persona 情绪状态机的内置状态一致」「`modes` 与前端 `MODES` 九模式一致」——漏登记即 CI FAIL，客户端拿到的表不会滞后于代码。
 
-> **契约版本 `v0.39`**（新增可选字段，向后兼容）。
+> **契约版本 `v0.41`**（新增可选字段，向后兼容；本条标记此前停留在 `v0.39`，本轮随人格 `thinking` 字段一并对齐到最新版本号）。
 
 ## 2. REST 端点（管理，`/api/v1/admin/*`）
 
@@ -171,8 +171,9 @@
 > **M10 前端契约补充（管理面板）**：`GET /api/v1/admin/users` · `GET /api/v1/admin/llm` · `GET /api/v1/admin/automations` · `GET /api/v1/admin/backthink` · `GET /api/v1/admin/rag` · `POST /api/v1/admin/rag/query` · `GET /api/v1/admin/observability/metrics` · `GET /api/v1/admin/observability/trace` · `GET /api/v1/admin/observability/audit` · `GET /api/v1/admin/observability/logs` · `GET /api/v1/admin/notifications` 已实现，返回真实数据（**日志 tail 见下方「可观测性契约」**；未注册 `GET /api/v1/admin/logs`）。**写操作已补齐**（见下方「管理面板写操作契约」）：人格/API key/设备控制/自动化/LLM 测试/渠道连接与识别测试/记忆检索/会话导出/插件卸载**真实持久化或真实生效**；**系统设置安全与存储类**（吊销 API key / 轮换 JWT 密钥 / 备份 / 恢复）也已**真实实现**（见下方「系统设置契约」）；仍为后置 M10：**新增用户**、**IoT 场景与规则**、**主人档案保存**、**编辑环境变量/重启服务/检查更新**——后端如实返回 `501 not_implemented`，不伪造成功。（**知识库删除已实现**：`POST /admin/rag/delete` 真实删除，见下方写操作契约；**插件安装已实现**：v1 为 MCP server 热安装。）
 
 **管理面板写操作契约**（`POST/PUT/DELETE /api/v1/admin/*`，均 **owner-only**，读为 owner/admin；写操作经 audit 落 `audit_logs`；成功 `{data}` / 失败 `{error:{code,message}}`）：
-- `POST /admin/personas` body `{id,name,role,systemPrompt?,characterRef?,modes?/mode?,memoryNamespace?}` → `201 {data:{id,name,character,isDefault,mode,memoryNamespace}}`（注册进 persona registry + 持久化到 `configs/personas/<id>.yaml`）；id 已存在回 `409 duplicate`。
+- `POST /admin/personas` body `{id,name,role,systemPrompt?,characterRef?,modes?/mode?,memoryNamespace?,thinking?}` → `201 {data:{id,name,character,isDefault,mode,memoryNamespace}}`（注册进 persona registry + 持久化到 `configs/personas/<id>.yaml`）；id 已存在回 `409 duplicate`。
 - `PUT /admin/personas/{id}` body 同上（不含 id）→ `200 {data:PersonaSummary}`；不存在回 `404`。
+- `thinking`（可选，design/01 §2.1）`{budgetTokens?,effort?,showToUser?,mode?}`：写入 YAML 的 `thinking` 节，驱动该人格的思考预算/开关/呈现。`mode` ∈ `default|on|off`（缺省 `default`），非法 `mode` 或负 `budgetTokens` 回 **`400 bad_request`**（`invalid thinking config: …`）。**`showToUser` 是 bool 且可缺省**：**缺省 = 保持现行为（thinking 帧照常推客户端）**；显式 `false` = 只落库不回显。**`PUT` 省略整个 `thinking` 对象时保留已存的 `thinking` 节**（不因客户端不认识该字段而抹掉）；显式传对象则整体替换（字段全缺省即清空）。该字段**不构成能力边界**。
 - `POST /admin/users` → `501 not_implemented`（**无用户表**：登录仅用 `.env` 单 admin `ADMIN_USERNAME`/`ADMIN_PASSWORD`，角色为 `owner>admin>viewer` 常量；多用户存储 + 登录接入需先设计——design/11 单用户为主。不做「建了却登不进」的假用户）。
 - `POST /admin/users/apikey` body `{role:"owner|admin|viewer"}` → `201 {data:{id:<掩码>, key:<明文·仅此一次>, role}}`。`key` 仅此响应出现一次。
 - `DELETE /admin/users/apikey/{id}`（`id`=列表掩码）→ `200 {data:{id,revoked:true}}`；未命中 `404`。
@@ -352,6 +353,7 @@
 - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
 
 ## 5. 变更记录
+- `v0.41`（**人格 `thinking` 配置 + 推理旋钮按 provider 映射**，对客户端**新增一个可选请求字段**，向后兼容）：① `POST /admin/personas` / `PUT /admin/personas/{id}` body 新增可选 **`thinking`** 对象 `{budgetTokens?,effort?,showToUser?,mode?}`（design/01 §2.1），原样写入并持久化到 `configs/personas/<id>.yaml` 的 `thinking` 节；非法 `mode`/负预算回 **`400 bad_request`**；**`PUT` 省略该对象时保留已存 `thinking`**（旧面板/脚本不会抹掉它）；该字段只描述**呈现/资源**，不构成能力边界。② **`showToUser` 语义**：**缺省 = 照常把 `thinking.*` 流帧推给客户端**（现行为），显式 `false` = 仅落库/剥离语义不变、**不推帧**（展示与落库解耦）。③ **服务端推理映射**（对客户端透明，仅影响上游请求）：Anthropic 系在 persona 配置 `budgetTokens`/`mode: on` 时发 `thinking:{type:"enabled",budget_tokens:N}`，并**保证 `budget_tokens + 正文留量 ≤ max_tokens`**（不足则抬高 `max_tokens` 并记 WARN，绝不把正文吃空）；OpenAI 兼容系按**识别到的厂商白名单**校验 `reasoning_effort`（OpenAI 系 `none…max`、DeepSeek 仅 `low/high/max`），非法值**降级到最近一档并记 WARN**；**未知 provider/未识别模型、以及 Qwen 的 `enable_thinking` 硬开关（协议无统一 wire 形状）** 一律记 **WARN（含 provider/字段/取值）并保持请求不变**，绝不静默无效。详见 design/04 §3.2。
 - `v0.40`（**`viewer` 角色真正接线：只读监控档**，对客户端**收紧/放宽若干 admin 读的鉴权**，无端点/字段形状变更）：此前 `viewer` 只是常量（`internal/auth` 的 `RoleViewer` 注释写着「只读 dashboard/logs/monitoring」）而**从未接线**——管理侧 24 条 GET 全走 owner/admin，`viewer` 一条都读不到（**全 403**）。本版新增第四道门 `viewerAuth = owner+admin+viewer`，并把 **12 条只读监控 GET** 从 owner/admin 放宽到 owner/admin/**viewer**：`GET /admin/personas`、`/admin/sessions`、`/admin/plugins`、`/admin/plugins/installed`、`/admin/channels`、`/admin/iot`、`/admin/automations`、`/admin/rag`、`/admin/observability/metrics`、`/admin/observability/trace`、`/admin/observability/logs`、`/admin/notifications`。**明确不放给 viewer**（含凭据获取路径、他人数据、完整消息/导出明文、审计流水，或 `admin` 也不给）：`GET /admin/memories`、`/admin/llm`、`/admin/users`、`/admin/backthink`、`/admin/observability/audit`、`/admin/channels/messages`、`/admin/channels/{platform}/messages`、`/admin/sessions/{id}/export`、`POST /admin/rag/query`（这 9 条 owner/admin）以及其余 **35 条 owner-only**（全部写操作 + `login-qr`/`login-status`/`view`/`friends`/渠道连接与配置/`plugins/*`/`users/*`/`system/*`）。**匿名**：任意 admin 路由仍 `401`（fail-closed）。**向后兼容**：`owner`/`admin` 语义不变（放行集合是超集），仅 `viewer` 的可见面从「全 403」变为 12 条只读监控；不依赖 `viewer` 的客户端行为不变。完整分档见 §2.0「管理侧权限矩阵」。
 - `v0.39`（**微信 iLink 会话被拒可见化 + 不再假 OK**，对客户端**新增两个可选字段、一处错误码**，向后兼容）：① **`GET /api/v1/admin/channels` 每平台行新增可选 `needsRescan`（bool，`omitempty`）+ `lastError`（string，`omitempty`）**——仅当适配器**真的**要求重新授权时出现（今天只有微信 iLink 返回 `errcode=-14` 这一种），取值来自适配器新增的**可选能力接口** `RescanRequired() (bool, string)`，网关**经类型断言**读取（主 `PlatformAdapter` 契约**不变**；未实现该能力的平台字段**缺省不出现**）。用途：把「需要重新扫码」与「主人自己关掉的未连接」区分开——后者仅 `connected:false`。② **`POST /admin/channels/open`** 对「iLink 已拒绝该会话」回 **`409 session_rejected`**（message 明确要求用「扫码登录」重新绑定），**不再**吞掉错误回 200；`409 needs_login`（尚无 token，v0.8 起）不变。③ **适配器行为**：iLink `errcode=-14` 进入**显式被拒态**——`IsConnected()` 恒 `false`；`Connect()` 返回被拒错误（**不再**对被拒会话报成功）；`HealthCheck` 区分「会话被拒」与「未连接」；并以 **`ERROR`** 级日志写明「本次会话已被 iLink 拒绝，需要重新扫码绑定」（只带 `bot_id` 等非敏感标识，**token 永不入日志**）。被拒态在读循环与发送两条路径**都会**置位，并仅在**扫码登录拿到新 token** 或**配置换了新 token**（保存 + 热重载）时清除。④ 扫码登录侧：被拒期间 `login-status` 报 **`failed` + 被拒原因**（**不再**假报 `confirmed`，否则面板会把已作废凭据当成功重新落盘）；`login-qr` 仍可正常出码（**不**回 `already_logged_in`，否则重新扫码这条路被堵死）；`get_bot_qrcode` 不再携带已被拒的 token（否则服务端以「已绑定」应答、**不**发新凭据）。**向后兼容**：只新增可选字段与一处更诚实的错误码；不读新字段、不处理 409 的客户端行为不变（此时面板显示「未连接」，仍可用「扫码登录」恢复）。**语义澄清（本次仅措辞，不改契约形状、不另起版本号——v0.39 尚未被任何客户端采用）**：iLink 的 bot token 是**长期凭据**（实测一个月前扫码得到的 token 仍可用），`errcode=-14` 表示 **iLink 侧拒绝/作废了该会话凭据**，**不是时间性过期**。详见 §2 行 6 与「微信 iLink『会话被拒』契约」。
 - `v0.38`（**B4 客户端共享枚举权威表 + 未知值回落约定**，对客户端**新增一个只读 REST 端点**）：新增 **`GET /api/v1/meta/enums`**（**任意已认证角色可读**，与 `GET /sessions` 同级；无 token `401`）→ `200 {data:{platforms,moods,modes,unknown}}`，每项 `{id,label}`：① **`platforms`**（6）= `web`/`kook`/`qq-obv11`/`weixin-ilink`/`telegram`/`webhook`——即各内置适配器 `Name()` + Web 主会话来源 `web`；② **`moods`**（5）= `calm`/`happy`/`excited`/`sad`/`angry`，与 persona 情绪状态机内置状态一致（该状态机**可扩展**，故非封闭集合）；③ **`modes`**（9）= `chat`/`code`/`home`/`work`/`docs`/`voice`/`vision`/`agents`/`settings`（design/07 §1）；④ **`unknown`** 恒 `"display-raw"` = **未知值回落约定机器可读**：客户端遇不在表中的取值**原样显示原始字符串**（**不丢弃、不报错、不占位符**），**服务端新增取值视为非破坏性变更**（forward-compatible）。**单一事实来源在 Go 侧**（`internal/contract/enums`），并有**反漂移测试**断言适配器 `Name()` / 情绪内置状态 / 前端九模式与三张表一致，漏登记即 CI FAIL。Web 侧镜像 `frontend/web/src/lib/enums.ts`（`labelFor` 未知值返回原值），顶栏/侧栏/消息气泡的「心情」标签已改用它渲染。**向后兼容**：仅新增端点，既有契约形状不变。详见 §1 行 15 与 §1.1。

cmd/cyrene/persona_prompt.go

@@ -0,0 +1,136 @@
+package main
+
+import (
+	"strings"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/persona/loader"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+// Section headers for the persona fields that design/01 §2.2 lists as previously
+// inert. They are appended as separate system-prompt sections after the identity
+// block so each one can be tuned without touching the identity text.
+const (
+	personalityHeader = "【性格】"
+	valuesHeader      = "【价值观】"
+	speechStyleHeader = "【说话风格】"
+	catchphraseHeader = "【口头禅】"
+	backgroundHeader  = "【背景】"
+)
+
+// personaSection is one appended block: a bracketed header plus its body.
+type personaSection struct {
+	header string
+	body   string
+}
+
+// defaultPersona returns the default character's persona, or false when no
+// character/persona is registered.
+func (a *app) defaultPersona() (*loader.Persona, bool) {
+	c, ok := a.personas.DefaultCharacter()
+	if !ok {
+		return nil, false
+	}
+	p, ok := a.personas.Persona(c.PersonaID)
+	if !ok || p == nil {
+		return nil, false
+	}
+	return p, true
+}
+
+// identityInstructionFor returns the persona's identity block — the only part
+// injected before design/01 §2.2: identity.systemPrompt, else identity.role, else
+// the minimal fallback.
+func identityInstructionFor(p *loader.Persona) string {
+	if p.Identity.SystemPrompt != "" {
+		return p.Identity.SystemPrompt
+	}
+	if p.Identity.Role != "" {
+		return p.Identity.Role
+	}
+	return fallbackInstruction
+}
+
+// instructionsFromPersona builds the persona's system instruction: the identity
+// block, followed by the personality/values/speechStyle/catchphrase/background
+// sections that used to have no consumer (design/01 §2.2). Blank fields are
+// skipped so no empty section is emitted, and a persona with none of them yields
+// exactly the identity block — byte for byte the pre-existing output.
+func instructionsFromPersona(p *loader.Persona) string {
+	base := identityInstructionFor(p)
+	sections := personaSections(p)
+	if len(sections) == 0 {
+		return base
+	}
+	var b strings.Builder
+	b.WriteString(base)
+	for _, s := range sections {
+		b.WriteString("\n\n")
+		b.WriteString(s.header)
+		b.WriteString("\n")
+		b.WriteString(s.body)
+	}
+	return b.String()
+}
+
+// personaSections renders the five optional sections in their fixed order
+// (personality → values → speechStyle → catchphrase → background), skipping any
+// that is blank.
+func personaSections(p *loader.Persona) []personaSection {
+	out := make([]personaSection, 0, 5)
+	appendSection := func(header, body string) {
+		if body = strings.TrimSpace(body); body == "" {
+			return
+		}
+		out = append(out, personaSection{header: header, body: body})
+	}
+	appendSection(personalityHeader, p.Personality)
+	appendSection(valuesHeader, bulletList(p.Values))
+	appendSection(speechStyleHeader, p.SpeechStyle)
+	appendSection(catchphraseHeader, p.Catchphrase)
+	appendSection(backgroundHeader, p.Background)
+	return out
+}
+
+// bulletList renders string items as a markdown bullet list, skipping blanks; an
+// all-blank list yields "" so its section disappears entirely.
+func bulletList(items []string) string {
+	lines := make([]string, 0, len(items))
+	for _, item := range items {
+		if item = strings.TrimSpace(item); item != "" {
+			lines = append(lines, "- "+item)
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
+// defaultThinkingOptions returns the reasoning knobs the loop should inject for
+// the default persona: the thinking directive, the reasoning_effort value and the
+// thinking-broadcast switch.
+//
+// The thinking directive is non-nil only when the persona configures something
+// that affects the request (a budget, an effort, or an explicit on/off mode).
+// showToUser deliberately does NOT create one: it is a presentation switch, and a
+// non-nil directive with no switch would enable provider thinking as a side
+// effect. All three are zero when no persona is registered, which leaves the
+// loop's pre-existing behavior untouched.
+func (a *app) defaultThinkingOptions() (*model.Thinking, string, *bool) {
+	p, ok := a.defaultPersona()
+	if !ok {
+		return nil, "", nil
+	}
+	thinking, effort := personaThinking(p)
+	return thinking, effort, p.Thinking.ShowToUser
+}
+
+// personaThinking maps the persona's `thinking` section onto the model-layer
+// knobs (design/01 §2.1 / design/04 §3.2). It returns (nil, "") when nothing
+// affects the request.
+func personaThinking(p *loader.Persona) (*model.Thinking, string) {
+	effort := strings.TrimSpace(p.Thinking.Effort)
+	enable := p.Thinking.Enable()
+	if p.Thinking.BudgetTokens == 0 && effort == "" && enable == nil {
+		return nil, ""
+	}
+	return &model.Thinking{BudgetTokens: p.Thinking.BudgetTokens, Enable: enable}, effort
+}

cmd/cyrene/persona_prompt_test.go

@@ -0,0 +1,240 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/persona/loader"
+	personareg "git.yeij.top/AskaEth/Cyrene_v2/internal/persona/registry"
+)
+
+// boolPtr returns a pointer to v, for the tri-state switch fields.
+func boolPtr(v bool) *bool { return &v }
+
+// TestInstructionsFromPersona_AllEmptyIsByteIdenticalToTheOldOutput locks the
+// backward-compatibility promise of design/01 §2.2: a persona that sets none of
+// the five previously-inert fields produces exactly what the old code produced
+// (the identity block alone, in its own precedence order).
+func TestInstructionsFromPersona_AllEmptyIsByteIdenticalToTheOldOutput(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		p    loader.Persona
+		want string
+	}{
+		{
+			name: "system prompt wins",
+			p:    loader.Persona{Identity: loader.Identity{SystemPrompt: "身份块", Role: "人设"}},
+			want: "身份块",
+		},
+		{
+			name: "role fallback",
+			p:    loader.Persona{Identity: loader.Identity{Role: "人设"}},
+			want: "人设",
+		},
+		{
+			name: "minimal fallback",
+			p:    loader.Persona{},
+			want: fallbackInstruction,
+		},
+	}
+	for _, tt := range cases {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := instructionsFromPersona(&tt.p); got != tt.want {
+				t.Fatalf("instructionsFromPersona() = %q, want %q (byte-identical)", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestInstructionsFromPersona_SectionOrderAndFormat pins the exact concatenation:
+// identity block first, then personality → values → speechStyle → catchphrase →
+// background, each with its bracketed header and no blank section.
+func TestInstructionsFromPersona_SectionOrderAndFormat(t *testing.T) {
+	t.Parallel()
+
+	p := loader.Persona{
+		Identity:    loader.Identity{SystemPrompt: "你是昔涟。"},
+		Personality: "温柔体贴",
+		Values:      []string{"陪伴", "真诚"},
+		SpeechStyle: "轻声细语",
+		Catchphrase: "嘿嘿♪",
+		Background:  "来自翁法罗斯。",
+	}
+	want := "你是昔涟。" +
+		"\n\n【性格】\n温柔体贴" +
+		"\n\n【价值观】\n- 陪伴\n- 真诚" +
+		"\n\n【说话风格】\n轻声细语" +
+		"\n\n【口头禅】\n嘿嘿♪" +
+		"\n\n【背景】\n来自翁法罗斯。"
+	got := instructionsFromPersona(&p)
+	if got != want {
+		t.Fatalf("instructionsFromPersona() = %q\nwant %q", got, want)
+	}
+	// The identity block must remain the first section, unchanged.
+	if !strings.HasPrefix(got, "你是昔涟。\n\n") {
+		t.Fatalf("identity block is not the leading section: %q", got)
+	}
+}
+
+// TestInstructionsFromPersona_BlankFieldsProduceNoSection asserts an unset (or
+// blank) field contributes no header and no empty paragraph, and that the
+// sections keep their relative order when only some are set.
+func TestInstructionsFromPersona_BlankFieldsProduceNoSection(t *testing.T) {
+	t.Parallel()
+
+	p := loader.Persona{
+		Identity:   loader.Identity{SystemPrompt: "身份"},
+		Values:     []string{"", "  ", "真诚"},
+		Background: "  ",
+	}
+	got := instructionsFromPersona(&p)
+	want := "身份\n\n【价值观】\n- 真诚"
+	if got != want {
+		t.Fatalf("instructionsFromPersona() = %q, want %q", got, want)
+	}
+	for _, header := range []string{personalityHeader, speechStyleHeader, catchphraseHeader, backgroundHeader} {
+		if strings.Contains(got, header) {
+			t.Errorf("output %q contains %s for a blank field", got, header)
+		}
+	}
+}
+
+// TestInstructionsFromPersona_RealDefaultPersona checks the shipped default
+// persona end to end: its five fields are now injected, in order, after the
+// identity block — and the identity block alone is still a strict prefix (so the
+// pre-existing prompt is preserved verbatim, nothing rewritten).
+func TestInstructionsFromPersona_RealDefaultPersona(t *testing.T) {
+	t.Parallel()
+
+	p, err := loader.Load("../../configs/personas/cyrene.yaml")
+	if err != nil {
+		t.Fatalf("Load(cyrene.yaml): %v", err)
+	}
+	got := instructionsFromPersona(p)
+	if !strings.HasPrefix(got, p.Identity.SystemPrompt) {
+		t.Fatal("identity.systemPrompt is not the leading block")
+	}
+	last := -1
+	for _, header := range []string{personalityHeader, valuesHeader, speechStyleHeader, catchphraseHeader, backgroundHeader} {
+		idx := strings.Index(got, header)
+		if idx < 0 {
+			t.Fatalf("output is missing %s", header)
+		}
+		if idx <= last {
+			t.Fatalf("%s is out of order (at %d, previous at %d)", header, idx, last)
+		}
+		last = idx
+	}
+}
+
+// TestPersonaThinking_MappingPinsTheKnobs asserts the persona → model.Thinking
+// mapping: only request-affecting fields create a directive (so a bare
+// showToUser, which is presentation-only, can never switch provider thinking on),
+// and mode=default never becomes an explicit switch.
+func TestPersonaThinking_MappingPinsTheKnobs(t *testing.T) {
+	t.Parallel()
+
+	show := false
+	cases := []struct {
+		name       string
+		thinking   loader.ThinkingParams
+		wantNil    bool
+		wantBudget int
+		wantEnable *bool
+		wantEffort string
+	}{
+		{name: "nothing", thinking: loader.ThinkingParams{}, wantNil: true},
+		{name: "default mode only", thinking: loader.ThinkingParams{Mode: loader.ThinkingModeDefault}, wantNil: true},
+		{name: "showToUser alone is presentation only", thinking: loader.ThinkingParams{ShowToUser: &show}, wantNil: true},
+		{name: "budget", thinking: loader.ThinkingParams{BudgetTokens: 4096}, wantBudget: 4096},
+		{name: "effort", thinking: loader.ThinkingParams{Effort: " medium "}, wantEffort: "medium"},
+		{name: "mode on", thinking: loader.ThinkingParams{Mode: loader.ThinkingModeOn}, wantEnable: boolPtr(true)},
+		{name: "mode off", thinking: loader.ThinkingParams{Mode: loader.ThinkingModeOff}, wantEnable: boolPtr(false)},
+	}
+	for _, tt := range cases {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			p := &loader.Persona{Thinking: tt.thinking}
+			got, effort := personaThinking(p)
+			if tt.wantNil {
+				if got != nil {
+					t.Fatalf("personaThinking() = %+v, want nil", got)
+				}
+				if effort != "" {
+					t.Fatalf("effort = %q, want empty", effort)
+				}
+				return
+			}
+			if got == nil {
+				t.Fatal("personaThinking() = nil, want a directive")
+			}
+			if got.BudgetTokens != tt.wantBudget {
+				t.Errorf("BudgetTokens = %d, want %d", got.BudgetTokens, tt.wantBudget)
+			}
+			if effort != tt.wantEffort {
+				t.Errorf("effort = %q, want %q", effort, tt.wantEffort)
+			}
+			switch {
+			case tt.wantEnable == nil && got.Enable != nil:
+				t.Errorf("Enable = %v, want nil", *got.Enable)
+			case tt.wantEnable != nil && got.Enable == nil:
+				t.Errorf("Enable = nil, want %v", *tt.wantEnable)
+			case tt.wantEnable != nil && *got.Enable != *tt.wantEnable:
+				t.Errorf("Enable = %v, want %v", *got.Enable, *tt.wantEnable)
+			}
+		})
+	}
+}
+
+// TestDefaultThinkingOptions_FromRegistry walks the wiring the composition root
+// uses: the default character's persona supplies the loop's knobs, and an
+// unregistered persona yields the zero options (pre-existing behavior).
+func TestDefaultThinkingOptions_FromRegistry(t *testing.T) {
+	t.Parallel()
+
+	reg := personareg.New()
+	show := false
+	p := &loader.Persona{
+		ID:       "xilian",
+		Name:     "昔涟",
+		Identity: loader.Identity{Role: "r", SystemPrompt: "s"},
+		Thinking: loader.ThinkingParams{BudgetTokens: 2048, Effort: "high", ShowToUser: &show, Mode: loader.ThinkingModeOn},
+	}
+	if err := reg.RegisterPersona(p); err != nil {
+		t.Fatalf("RegisterPersona: %v", err)
+	}
+	if err := reg.RegisterCharacter(&personareg.Character{ID: "xilian", Name: "昔涟", Default: true, PersonaID: "xilian"}); err != nil {
+		t.Fatalf("RegisterCharacter: %v", err)
+	}
+	a := &app{personas: reg}
+
+	thinking, effort, gotShow := a.defaultThinkingOptions()
+	if thinking == nil || thinking.BudgetTokens != 2048 {
+		t.Fatalf("thinking = %+v, want BudgetTokens 2048", thinking)
+	}
+	if thinking.Enable == nil || !*thinking.Enable {
+		t.Fatalf("thinking.Enable = %v, want true (mode: on)", thinking.Enable)
+	}
+	if effort != "high" {
+		t.Fatalf("effort = %q, want high", effort)
+	}
+	if gotShow == nil || *gotShow {
+		t.Fatalf("showToUser = %v, want an explicit false", gotShow)
+	}
+}
+
+// TestDefaultThinkingOptions_NoPersona keeps the no-registry case inert.
+func TestDefaultThinkingOptions_NoPersona(t *testing.T) {
+	t.Parallel()
+
+	a := &app{personas: personareg.New()}
+	thinking, effort, show := a.defaultThinkingOptions()
+	if thinking != nil || effort != "" || show != nil {
+		t.Fatalf("defaultThinkingOptions() = %+v/%q/%v, want the zero options", thinking, effort, show)
+	}
+}

cmd/cyrene/wire.go

@@ -410,28 +410,33 @@ func (a *app) wireRuntime() error {
 	// emotion machine and affection move, and the returned mood label is written
 	// onto Result.Mood and the assistant message (design/16 §3.3).
 	a.emotion = a.buildEmotionObserver()
+	// Reasoning knobs from the default persona (budget / effort / thinking broadcast).
+	thinking, reasoningEffort, thinkingShow := a.defaultThinkingOptions()
 
 	a.loop = loop.New(loop.Options{
-		Agent:         ag,
-		Tools:         a.dispatcher,
-		Capacity:      capDecider,
-		OnCapacity:    a.onCapacity,
-		OnAudit:       a.onToolAudit,
-		OnTurnEnd:     a.onTurnEnd,
-		Memory:        store,
-		Retriever:     a.retriever,
-		Extractor:     a.buildMemoryExtractor(personaID),
-		Checkpoint:    checkpoint,
-		Tracer:        tracer,
-		Flow:          flowPub,
-		Guards:        guards,
-		PersonaID:     personaID,
-		Timezone:      a.cfg.Timezone,
-		MaxRounds:     defaultMaxRounds,
-		WorkingMemory: memory.NewWorkingMemory(0),
-		OnStream:      a.streamChunk,
-		Vision:        visionResolver,
-		Log:           logger.WithSource(a.log, "runtime/loop"),
+		Agent:              ag,
+		Tools:              a.dispatcher,
+		Capacity:           capDecider,
+		OnCapacity:         a.onCapacity,
+		OnAudit:            a.onToolAudit,
+		OnTurnEnd:          a.onTurnEnd,
+		Memory:             store,
+		Retriever:          a.retriever,
+		Extractor:          a.buildMemoryExtractor(personaID),
+		Checkpoint:         checkpoint,
+		Tracer:             tracer,
+		Flow:               flowPub,
+		Guards:             guards,
+		PersonaID:          personaID,
+		Timezone:           a.cfg.Timezone,
+		MaxRounds:          defaultMaxRounds,
+		WorkingMemory:      memory.NewWorkingMemory(0),
+		OnStream:           a.streamChunk,
+		Vision:             visionResolver,
+		Thinking:           thinking,
+		ReasoningEffort:    reasoningEffort,
+		ThinkingShowToUser: thinkingShow,
+		Log:                logger.WithSource(a.log, "runtime/loop"),
 	})
 
 	a.scheduler = orchestration.New(orchestration.Options{
@@ -801,18 +806,13 @@ func (a *app) defaultPersonaID() string {
 	return "cyrene"
 }
 
-// defaultInstructions returns the default persona's system prompt, falling back
-// to its role text or a minimal instruction when neither is set.
+// defaultInstructions returns the default persona's system prompt followed by the
+// personality/values/speechStyle/catchphrase/background sections (design/01
+// §2.2), falling back to its role text or a minimal instruction when neither is
+// set.
 func (a *app) defaultInstructions() string {
-	if c, ok := a.personas.DefaultCharacter(); ok {
-		if p, ok := a.personas.Persona(c.PersonaID); ok {
-			if p.Identity.SystemPrompt != "" {
-				return p.Identity.SystemPrompt
-			}
-			if p.Identity.Role != "" {
-				return p.Identity.Role
-			}
-		}
+	if p, ok := a.defaultPersona(); ok {
+		return instructionsFromPersona(p)
 	}
 	return fallbackInstruction
 }

internal/persona/loader/load.go

@@ -80,6 +80,9 @@ func (p *Persona) validate() error {
 	if len(missing) > 0 {
 		return fmt.Errorf("%w %q: %s", ErrRequiredField, p.ID, strings.Join(missing, ", "))
 	}
+	if err := p.ValidateThinking(); err != nil {
+		return err
+	}
 	return nil
 }
 

internal/persona/loader/persona.go

@@ -5,6 +5,9 @@
 package loader
 
 import (
+	"errors"
+	"fmt"
+
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/persona/emotion"
 )
 
@@ -17,6 +20,22 @@ const (
 	defaultAffectionDelta = 5
 )
 
+// Thinking-move values accepted by ThinkingParams.Mode (design/01 §2.1). The
+// empty string is equivalent to ThinkingModeDefault.
+const (
+	// ThinkingModeDefault leaves the provider's own reasoning behavior alone.
+	ThinkingModeDefault = "default"
+	// ThinkingModeOn explicitly enables reasoning where the provider has a switch.
+	ThinkingModeOn = "on"
+	// ThinkingModeOff explicitly disables reasoning where the provider has a switch.
+	ThinkingModeOff = "off"
+)
+
+// ErrInvalidThinking is wrapped by the thinking-config validation error so a
+// caller can detect a bad `thinking` block (unknown mode, negative budget)
+// instead of seeing it silently ignored.
+var ErrInvalidThinking = errors.New("persona: invalid thinking config")
+
 // defaultMemoryNS is the namespace prefix used when a persona omits a concrete
 // memory namespace; the full namespace becomes prefix + "." + persona id.
 const defaultMemoryNS = "persona"
@@ -50,6 +69,45 @@ type AffectionParams struct {
 	Delta   int `yaml:"delta"`
 }
 
+// ThinkingParams is the persona's optional `thinking` section (design/01 §2.1).
+// It describes presentation/resource knobs only — never an ability bound — and
+// defaults are chosen so an absent section changes nothing. It is marshaled by
+// the admin persona write path, so every field is omitempty: a persona that
+// configures no thinking gets no `thinking:` key in its YAML.
+type ThinkingParams struct {
+	// BudgetTokens is the reasoning budget (Anthropic thinking.budget_tokens; the
+	// official semantic is a target, not a hard cap). Zero = unset.
+	BudgetTokens int `yaml:"budgetTokens,omitempty"`
+	// Effort is the OpenAI-compatible reasoning strength (reasoning_effort). The
+	// accepted values depend on the provider; the model layer validates them
+	// against its per-provider whitelist (design/04 §3.2).
+	Effort string `yaml:"effort,omitempty"`
+	// ShowToUser says whether streamed thinking frames are pushed to the client.
+	// It is a POINTER on purpose: a missing key means "keep the current behavior"
+	// (thinking frames are shown), while an explicit false means "store it, but
+	// do not push it". A plain bool would conflate "unset" with "off".
+	ShowToUser *bool `yaml:"showToUser,omitempty"`
+	// Mode is the explicit hard switch: default | on | off. Empty = default.
+	Mode string `yaml:"mode,omitempty"`
+}
+
+// Enable maps Mode onto the model layer's tri-state switch: "on" → true, "off" →
+// false, ""/"default" → nil (no explicit switch, leave it to the provider). The
+// reasoning knobs the model layer consumes never include a null switch, so
+// "default" cannot accidentally turn provider thinking on.
+func (t ThinkingParams) Enable() *bool {
+	switch t.Mode {
+	case ThinkingModeOn:
+		v := true
+		return &v
+	case ThinkingModeOff:
+		v := false
+		return &v
+	default:
+		return nil
+	}
+}
+
 // Persona is a loaded persona definition. It describes who a character is (the
 // identity, personality, speech style, catchphrase, background, values) and
 // never restricts what that character can do.
@@ -85,7 +143,10 @@ type Persona struct {
 	Values       []string        `yaml:"values"`
 	Emotion      EmotionParams   `yaml:"emotion"`
 	Affection    AffectionParams `yaml:"affection"`
-	Visual       PersonaVisual   `yaml:"visual,omitempty"`
+	// Thinking is the optional reasoning/presentation config (design/01 §2.1);
+	// omitted when the persona configures none, so no existing YAML gains noise.
+	Thinking ThinkingParams `yaml:"thinking,omitempty"`
+	Visual   PersonaVisual  `yaml:"visual,omitempty"`
 	// TriggerWords are the role-name words that, when a public-platform group
 	// message mentions one, route the message into the participation PROBING
 	// stage even without a direct @ (design/18 §2 触发②). Each persona defines its
@@ -143,3 +204,19 @@ func (p *Persona) AffectionStep() int {
 	}
 	return defaultAffectionDelta
 }
+
+// ValidateThinking checks the optional `thinking` section and returns a
+// %w-wrapped ErrInvalidThinking error for an unrecognized mode or a negative
+// budget, so a bad value is reported instead of silently ignored.
+func (p *Persona) ValidateThinking() error {
+	switch p.Thinking.Mode {
+	case "", ThinkingModeDefault, ThinkingModeOn, ThinkingModeOff:
+	default:
+		return fmt.Errorf("%w: mode %q (want %s|%s|%s)",
+			ErrInvalidThinking, p.Thinking.Mode, ThinkingModeDefault, ThinkingModeOn, ThinkingModeOff)
+	}
+	if p.Thinking.BudgetTokens < 0 {
+		return fmt.Errorf("%w: budgetTokens %d must not be negative", ErrInvalidThinking, p.Thinking.BudgetTokens)
+	}
+	return nil
+}

internal/persona/loader/thinking_test.go

@@ -0,0 +1,161 @@
+package loader
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+// thinkingPersonaYAML builds a minimal valid persona with an extra `thinking`
+// block appended verbatim (an empty extra means "no thinking section at all").
+func thinkingPersonaYAML(extra string) string {
+	return "id: xilian\nname: 昔涟\ncharacterRef: c\nidentity:\n  role: r\n  systemPrompt: s\n" + extra
+}
+
+// TestLoad_ThinkingAbsentKeepsCurrentBehavior locks the "optional section"
+// promise: without a `thinking` key every field stays at its zero value, the
+// showToUser pointer stays nil (the distinction the design calls out) and
+// re-marshaling the persona does NOT emit a thinking block, so the admin write
+// path cannot add noise to an existing persona file.
+func TestLoad_ThinkingAbsentKeepsCurrentBehavior(t *testing.T) {
+	t.Parallel()
+
+	path := writeFile(t, t.TempDir(), "xilian.yaml", thinkingPersonaYAML(""))
+	p, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if p.Thinking.BudgetTokens != 0 || p.Thinking.Effort != "" || p.Thinking.Mode != "" {
+		t.Fatalf("Thinking = %+v, want the zero value", p.Thinking)
+	}
+	if p.Thinking.ShowToUser != nil {
+		t.Fatalf("ShowToUser = %v, want nil (unset)", *p.Thinking.ShowToUser)
+	}
+	if p.Thinking.Enable() != nil {
+		t.Fatalf("Enable() = %v, want nil for an unset mode", *p.Thinking.Enable())
+	}
+	out, err := yaml.Marshal(p)
+	if err != nil {
+		t.Fatalf("Marshal() error: %v", err)
+	}
+	if strings.Contains(string(out), "thinking") {
+		t.Fatalf("marshal emitted a thinking block for an unset section:\n%s", out)
+	}
+}
+
+// TestLoad_ThinkingParsed asserts the documented YAML keys land on the struct.
+func TestLoad_ThinkingParsed(t *testing.T) {
+	t.Parallel()
+
+	yaml := thinkingPersonaYAML("thinking:\n  budgetTokens: 4096\n  effort: medium\n  showToUser: false\n  mode: on\n")
+	path := writeFile(t, t.TempDir(), "xilian.yaml", yaml)
+	p, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if p.Thinking.BudgetTokens != 4096 {
+		t.Errorf("BudgetTokens = %d, want 4096", p.Thinking.BudgetTokens)
+	}
+	if p.Thinking.Effort != "medium" {
+		t.Errorf("Effort = %q, want medium", p.Thinking.Effort)
+	}
+	if p.Thinking.Mode != ThinkingModeOn {
+		t.Errorf("Mode = %q, want on", p.Thinking.Mode)
+	}
+	if p.Thinking.ShowToUser == nil {
+		t.Fatal("ShowToUser = nil, want an explicit false")
+	}
+	if *p.Thinking.ShowToUser {
+		t.Error("ShowToUser = true, want false")
+	}
+	if en := p.Thinking.Enable(); en == nil || !*en {
+		t.Fatalf("Enable() = %v, want true for mode=on", en)
+	}
+}
+
+// TestLoad_ThinkingShowToUserFalseDiffersFromOmitted is the pointer contract:
+// omitting the key must keep the current behavior (nil, frames are shown) while
+// an explicit false must be distinguishable from it (store, don't push). A plain
+// bool field would collapse both into false and fail here.
+func TestLoad_ThinkingShowToUserFalseDiffersFromOmitted(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	omitted, err := Load(writeFile(t, dir, "omitted.yaml", thinkingPersonaYAML("thinking:\n  budgetTokens: 1024\n")))
+	if err != nil {
+		t.Fatalf("Load(omitted) error: %v", err)
+	}
+	off, err := Load(writeFile(t, dir, "off.yaml", thinkingPersonaYAML("thinking:\n  showToUser: false\n")))
+	if err != nil {
+		t.Fatalf("Load(off) error: %v", err)
+	}
+	if omitted.Thinking.ShowToUser != nil {
+		t.Fatalf("omitted ShowToUser = %v, want nil", *omitted.Thinking.ShowToUser)
+	}
+	if off.Thinking.ShowToUser == nil {
+		t.Fatal("explicit false ShowToUser = nil, want a pointer to false")
+	}
+	if *off.Thinking.ShowToUser {
+		t.Fatal("explicit false ShowToUser = true")
+	}
+}
+
+// TestLoad_ThinkingInvalidModeRejected asserts a bad mode is reported with its
+// own identifiable error instead of being silently ignored.
+func TestLoad_ThinkingInvalidModeRejected(t *testing.T) {
+	t.Parallel()
+
+	path := writeFile(t, t.TempDir(), "bad.yaml", thinkingPersonaYAML("thinking:\n  mode: sometimes\n"))
+	_, err := Load(path)
+	if err == nil {
+		t.Fatal("Load(mode: sometimes) want error, got nil")
+	}
+	if !errors.Is(err, ErrInvalidThinking) {
+		t.Fatalf("error = %v, want ErrInvalidThinking", err)
+	}
+	if !strings.Contains(err.Error(), "sometimes") {
+		t.Fatalf("error %q does not name the offending value", err)
+	}
+}
+
+// TestLoad_ThinkingNegativeBudgetRejected asserts a negative budget is rejected
+// (it would otherwise become a nonsensical provider request).
+func TestLoad_ThinkingNegativeBudgetRejected(t *testing.T) {
+	t.Parallel()
+
+	path := writeFile(t, t.TempDir(), "bad.yaml", thinkingPersonaYAML("thinking:\n  budgetTokens: -1\n"))
+	if _, err := Load(path); !errors.Is(err, ErrInvalidThinking) {
+		t.Fatalf("error = %v, want ErrInvalidThinking", err)
+	}
+}
+
+// TestThinkingParams_EnableModeMapping pins the tri-state mapping the model layer
+// depends on: only an explicit on/off produces a switch, default/unset yields nil
+// so provider thinking is never turned on as a side effect.
+func TestThinkingParams_EnableModeMapping(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		mode string
+		want *bool
+	}{
+		{mode: "", want: nil},
+		{mode: ThinkingModeDefault, want: nil},
+	}
+	for _, tt := range cases {
+		got := ThinkingParams{Mode: tt.mode}.Enable()
+		if got != nil {
+			t.Fatalf("Enable(%q) = %v, want nil", tt.mode, *got)
+		}
+	}
+	on := ThinkingParams{Mode: ThinkingModeOn}.Enable()
+	if on == nil || !*on {
+		t.Fatalf("Enable(on) = %v, want true", on)
+	}
+	off := ThinkingParams{Mode: ThinkingModeOff}.Enable()
+	if off == nil || *off {
+		t.Fatalf("Enable(off) = %v, want false", off)
+	}
+}

internal/runtime/loop/loop.go

@@ -104,6 +104,9 @@ type Loop struct {
 	toolParallelism  int
 	hooks            ToolLoopHooks
 	onStream         func(model.StreamEvent)
+	thinking         *model.Thinking
+	reasoningEffort  string
+	thinkingShow     *bool
 	onAudit          func(AuditEvent)
 	onTurnEnd        TurnEndHook
 	maxContextTokens int
@@ -157,6 +160,9 @@ func New(opts Options) *Loop {
 		toolParallelism:  toolParallelism,
 		hooks:            opts.Hooks,
 		onStream:         opts.OnStream,
+		thinking:         opts.Thinking,
+		reasoningEffort:  opts.ReasoningEffort,
+		thinkingShow:     opts.ThinkingShowToUser,
 		onAudit:          opts.OnAudit,
 		onTurnEnd:        opts.OnTurnEnd,
 		maxContextTokens: opts.MaxContextTokens,

internal/runtime/loop/options.go

@@ -89,6 +89,22 @@ type Options struct {
 	// forwarded to this callback (model.StreamEvent), so the frontend can render
 	// body text, tool calls and (eventually) reasoning segments independently.
 	OnStream func(model.StreamEvent)
+	// Thinking carries the reasoning knobs (budget / explicit switch) injected
+	// into every model request the loop builds. nil means "do not intervene",
+	// which is the pre-existing behavior. It is a loop option rather than a
+	// persona read inside the loop so the per-turn, per-role resolution a later
+	// multi-character batch adds only changes the wiring-time resolver.
+	Thinking *model.Thinking
+	// ReasoningEffort is the OpenAI-compatible strength knob injected into every
+	// model request. Empty means "do not intervene".
+	ReasoningEffort string
+	// ThinkingShowToUser gates the thinking frames the loop broadcasts: nil (the
+	// default) keeps the pre-existing behavior and pushes them; an explicit false
+	// keeps thinking_start/delta/end out of the client stream while text and tool
+	// frames are unaffected. The frames are still produced and still reach the
+	// model/transcript paths — only the UI broadcast is gated, so display and
+	// persistence stay decoupled (design/04 §3.2).
+	ThinkingShowToUser *bool
 	// ToolExecution selects how a batch of tool calls is run: "parallel" (the
 	// default) or "sequential". Empty means parallel.
 	ToolExecution string

internal/runtime/loop/request.go

@@ -13,12 +13,14 @@ import (
 // RunStep (leading instruction message, tool schemas, model routing).
 func (l *Loop) buildRequest(ctx context.Context, messages []model.Message) model.Request {
 	req := model.Request{
-		Model:       l.agent.Model(),
-		Messages:    l.assembleMessages(messages),
-		Temperature: l.temperature(),
-		MaxTokens:   l.agent.MaxTokens(),
-		Purpose:     l.agent.Purpose(),
-		Tools:       l.toolSchemas(ctx, messages),
+		Model:           l.agent.Model(),
+		Messages:        l.assembleMessages(messages),
+		Temperature:     l.temperature(),
+		MaxTokens:       l.agent.MaxTokens(),
+		Purpose:         l.agent.Purpose(),
+		Tools:           l.toolSchemas(ctx, messages),
+		Thinking:        l.thinking,
+		ReasoningEffort: l.reasoningEffort,
 	}
 	if l.agent.Router() != nil {
 		if m, _ := l.agent.Router().RouteRequest(req); m != "" {

internal/runtime/loop/stream.go

@@ -39,8 +39,11 @@ func (l *Loop) streamStep(ctx context.Context, messages []model.Message) (*stepO
 		ev.SessionID = loopSession(ctx)
 		ev.TurnID = loopTurn(ctx)
 		// Suppress UI broadcast for internal autonomous passes (backthink),
-		// whose intermediate reasoning must not leak into the chat stream.
-		if l.onStream != nil && !isMutedBroadcast(ctx) {
+		// whose intermediate reasoning must not leak into the chat stream, and for
+		// thinking frames when the bound persona turned them off (showToUser:
+		// false). Both gates are broadcast-only: the response the model produced is
+		// unchanged, so display and persistence stay decoupled.
+		if l.onStream != nil && !isMutedBroadcast(ctx) && l.broadcasts(ev) {
 			l.onStream(ev)
 		}
 	})
@@ -65,3 +68,25 @@ func (l *Loop) streamStep(ctx context.Context, messages []model.Message) (*stepO
 	return &stepOutcome{final: true, text: resp.Content, stopReason: agent.StopReasonStop,
 		modelStopReason: resp.StopReason, model: resp.Model}, nil
 }
+
+// broadcasts reports whether a streamed event may be pushed to the UI. Only
+// thinking frames are ever withheld, and only when the wiring resolved the
+// persona's showToUser to false; text, tool-call and tool-progress frames are
+// never affected, so turning thinking off cannot change what the client sees of
+// the answer itself.
+func (l *Loop) broadcasts(ev model.StreamEvent) bool {
+	if !isThinkingKind(ev.Kind) {
+		return true
+	}
+	return l.thinkingShow == nil || *l.thinkingShow
+}
+
+// isThinkingKind reports whether kind is one of the reasoning segment events.
+func isThinkingKind(kind model.StreamKind) bool {
+	switch kind {
+	case model.StreamKindThinkingStart, model.StreamKindThinkingDelta, model.StreamKindThinkingEnd:
+		return true
+	default:
+		return false
+	}
+}

internal/runtime/loop/thinking_gate_test.go

@@ -0,0 +1,152 @@
+package loop
+
+import (
+	"context"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+// thinkingAdapter emits one full thinking segment followed by one text segment,
+// and records every request it is handed so a test can assert the loop's
+// reasoning knobs actually reached the model call.
+type thinkingAdapter struct {
+	reqs []model.Request
+}
+
+func (a *thinkingAdapter) Name() string { return "thinking-mock" }
+
+func (a *thinkingAdapter) Chat(_ context.Context, req model.Request, _ model.Options) (model.Response, error) {
+	a.reqs = append(a.reqs, req)
+	return model.Response{Content: "Hello"}, nil
+}
+
+func (a *thinkingAdapter) ChatStream(_ context.Context, req model.Request, on func(model.StreamEvent)) (model.Response, error) {
+	a.reqs = append(a.reqs, req)
+	events := []model.StreamEvent{
+		{Kind: model.StreamKindThinkingStart},
+		{Kind: model.StreamKindThinkingDelta, Delta: "let me think"},
+		{Kind: model.StreamKindThinkingEnd},
+		{Kind: model.StreamKindTextStart},
+		{Kind: model.StreamKindTextDelta, Delta: "Hello"},
+		{Kind: model.StreamKindTextEnd},
+	}
+	for _, ev := range events {
+		if on != nil {
+			on(ev)
+		}
+	}
+	return model.Response{Content: "Hello"}, nil
+}
+
+// kindsOf returns the event kinds as a set for compact assertions.
+func kindsOf(events []model.StreamEvent) map[model.StreamKind]int {
+	out := make(map[model.StreamKind]int, len(events))
+	for _, ev := range events {
+		out[ev.Kind]++
+	}
+	return out
+}
+
+// runThinkingTurn drives one streaming turn through a loop configured with the
+// given broadcast switch and returns the events OnStream saw.
+func runThinkingTurn(t *testing.T, show *bool) ([]model.StreamEvent, *thinkingAdapter) {
+	t.Helper()
+	ad := &thinkingAdapter{}
+	onStream, streams := collectStream()
+	l := New(Options{
+		Agent:              newTestAgent(t, ad, nil),
+		OnStream:           onStream,
+		MaxRounds:          8,
+		ThinkingShowToUser: show,
+	})
+	if _, err := l.Run(context.Background(), "web", []model.Message{model.TextMessage(model.RoleUser, "hi")}); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	return streams(), ad
+}
+
+// TestRun_ThinkingShowToUserFalseWithholdsThinkingFrames is the showToUser=false
+// contract: thinking frames never reach the client callback while the body text
+// segment is delivered untouched (display is gated, the answer is not).
+func TestRun_ThinkingShowToUserFalseWithholdsThinkingFrames(t *testing.T) {
+	t.Parallel()
+
+	show := false
+	events, _ := runThinkingTurn(t, &show)
+	kinds := kindsOf(events)
+	for _, k := range []model.StreamKind{model.StreamKindThinkingStart, model.StreamKindThinkingDelta, model.StreamKindThinkingEnd} {
+		if n := kinds[k]; n != 0 {
+			t.Fatalf("event kind %q emitted %d time(s) with showToUser=false", k, n)
+		}
+	}
+	for _, k := range []model.StreamKind{model.StreamKindTextStart, model.StreamKindTextDelta, model.StreamKindTextEnd} {
+		if kinds[k] != 1 {
+			t.Fatalf("event kind %q emitted %d time(s), want 1 (body must be unaffected)", k, kinds[k])
+		}
+	}
+	if len(events) != 3 {
+		t.Fatalf("events = %d, want only the 3 text frames", len(events))
+	}
+}
+
+// TestRun_ThinkingShowToUserDefaultBroadcastsThinking keeps the pre-existing
+// behavior when the option is unset (nil): thinking frames are pushed.
+func TestRun_ThinkingShowToUserDefaultBroadcastsThinking(t *testing.T) {
+	t.Parallel()
+
+	events, _ := runThinkingTurn(t, nil)
+	kinds := kindsOf(events)
+	if kinds[model.StreamKindThinkingDelta] != 1 || kinds[model.StreamKindThinkingStart] != 1 || kinds[model.StreamKindThinkingEnd] != 1 {
+		t.Fatalf("thinking frames = %v, want start/delta/end each once with the option unset", kinds)
+	}
+	if len(events) != 6 {
+		t.Fatalf("events = %d, want all 6 frames", len(events))
+	}
+}
+
+// TestRun_ThinkingShowToUserTrueBroadcastsThinking asserts an explicit true
+// behaves like the default.
+func TestRun_ThinkingShowToUserTrueBroadcastsThinking(t *testing.T) {
+	t.Parallel()
+
+	show := true
+	events, _ := runThinkingTurn(t, &show)
+	if kinds := kindsOf(events); kinds[model.StreamKindThinkingDelta] != 1 {
+		t.Fatalf("thinking delta frames = %d, want 1 with showToUser=true", kinds[model.StreamKindThinkingDelta])
+	}
+}
+
+// TestRun_RequestCarriesThinkingKnobs asserts the loop injects its reasoning
+// options into every model request it builds, so a persona's thinking config is
+// actually applied rather than validated-and-ignored.
+func TestRun_RequestCarriesThinkingKnobs(t *testing.T) {
+	t.Parallel()
+
+	ad := &thinkingAdapter{}
+	onStream, _ := collectStream()
+	want := &model.Thinking{BudgetTokens: 4096}
+	l := New(Options{
+		Agent:           newTestAgent(t, ad, nil),
+		OnStream:        onStream,
+		MaxRounds:       8,
+		Thinking:        want,
+		ReasoningEffort: "low",
+	})
+	if _, err := l.Run(context.Background(), "web", []model.Message{model.TextMessage(model.RoleUser, "hi")}); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(ad.reqs) == 0 {
+		t.Fatal("no model request was recorded")
+	}
+	got := ad.reqs[0]
+	if got.Thinking != want {
+		t.Fatalf("request.Thinking = %+v, want %+v", got.Thinking, want)
+	}
+	if got.Thinking.BudgetTokens != 4096 {
+		t.Fatalf("request.Thinking.BudgetTokens = %d, want 4096", got.Thinking.BudgetTokens)
+	}
+	if got.ReasoningEffort != "low" {
+		t.Fatalf("request.ReasoningEffort = %q, want low", got.ReasoningEffort)
+	}
+}

internal/runtime/model/anthropic.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"
 	"strings"
 	"time"
@@ -24,8 +25,19 @@ const (
 	anthropicDefaultMaxTokens = 8192
 	// anthropicDataPrefix marks a payload embedded as a data: URI.
 	anthropicDataPrefix = "data:"
+	// anthropicThinkingTypeEnabled is the wire value of an enabled extended-
+	// thinking directive.
+	anthropicThinkingTypeEnabled = "enabled"
 )
 
+// anthropicThinking is the wire form of the extended-thinking directive. It is
+// omitted entirely when the caller did not ask for thinking (or asked for it to
+// be off), because Anthropic treats a missing field as "no thinking".
+type anthropicThinking struct {
+	Type         string `json:"type"`
+	BudgetTokens int    `json:"budget_tokens"`
+}
+
 // anthropicRequest is the body sent to /v1/messages. Messages carry Anthropic's
 // content-block model and the system prompt lives at the request root.
 type anthropicRequest struct {
@@ -36,6 +48,7 @@ type anthropicRequest struct {
 	ToolChoice  any                `json:"tool_choice,omitempty"`
 	Temperature *float64           `json:"temperature,omitempty"`
 	MaxTokens   int                `json:"max_tokens"`
+	Thinking    *anthropicThinking `json:"thinking,omitempty"`
 	Stream      bool               `json:"stream,omitempty"`
 }
 
@@ -90,6 +103,10 @@ type AnthropicChatAdapter struct {
 	model    string
 	client   *http.Client
 	recorder Recorder
+	// log reports reasoning adjustments and ignored directives. It is never nil:
+	// a discard logger tagged with this adapter's source is installed when the
+	// caller supplies none, so a provider decision is always traceable.
+	log *slog.Logger
 }
 
 // AnthropicOption configures an AnthropicChatAdapter.
@@ -111,6 +128,17 @@ func WithAnthropicModel(m string) AnthropicOption {
 	return func(a *AnthropicChatAdapter) { a.model = m }
 }
 
+// WithAnthropicLogger attaches the logger used to report reasoning adjustments
+// (budget raised to fit max_tokens, ignored directives). A nil logger is ignored
+// so the discard default stays in place.
+func WithAnthropicLogger(l *slog.Logger) AnthropicOption {
+	return func(a *AnthropicChatAdapter) {
+		if l != nil {
+			a.log = l
+		}
+	}
+}
+
 // NewAnthropicChat builds an Anthropic adapter from a supplier config. baseURL is
 // trimmed of any trailing slash before the /v1/messages path is appended.
 func NewAnthropicChat(cfg config.LLMConfig, opts ...AnthropicOption) *AnthropicChatAdapter {
@@ -123,6 +151,7 @@ func NewAnthropicChat(cfg config.LLMConfig, opts ...AnthropicOption) *AnthropicC
 			Transport: http.DefaultTransport,
 			Timeout:   defaultHTTPTimeout,
 		},
+		log: discardLogger("runtime/model/anthropic"),
 	}
 	for _, o := range opts {
 		o(a)
@@ -264,6 +293,9 @@ func (a *AnthropicChatAdapter) buildRequest(req Request, stream bool) ([]byte, e
 		return nil, err
 	}
 	tokenLimit := effectiveMaxTokens(req.MaxTokens, anthropicDefaultMaxTokens)
+	// Extended thinking shares max_tokens with the visible answer, so the budget
+	// is resolved together with the limit it requires (design/04 §3.2 red line).
+	tokenLimit, thinking := anthropicThinkingFor(req.Thinking, tokenLimit, a.log)
 	wire := anthropicRequest{
 		Model:       req.Model,
 		System:      system,
@@ -272,6 +304,7 @@ func (a *AnthropicChatAdapter) buildRequest(req Request, stream bool) ([]byte, e
 		ToolChoice:  req.ToolChoice,
 		Temperature: req.Temperature,
 		MaxTokens:   tokenLimit,
+		Thinking:    thinking,
 		Stream:      stream,
 	}
 	buf, err := json.Marshal(wire)

internal/runtime/model/factory.go

@@ -3,6 +3,7 @@ package model
 import (
 	"errors"
 	"fmt"
+	"log/slog"
 
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
 )
@@ -40,11 +41,19 @@ func NewChatAdapter(cfg config.LLMConfig) (Adapter, error) {
 // step is served by an adapter of the selected protocol. The empty provider
 // defaults to openai. An unrecognized provider returns ErrUnknownProvider.
 func NewChatChain(cfg config.LLMConfig) (*Chain, error) {
+	return NewChatChainWithLog(cfg, nil)
+}
+
+// NewChatChainWithLog is NewChatChain with a logger attached to every adapter it
+// builds, so a provider-level reasoning decision (a thinking budget raised to fit
+// max_tokens, a reasoning_effort value downgraded or ignored) is reported with
+// its module source. A nil logger leaves the adapters' discard default in place.
+func NewChatChainWithLog(cfg config.LLMConfig, log *slog.Logger) (*Chain, error) {
 	switch cfg.Provider {
 	case ProviderOpenAI, "":
-		return newOpenAIChain(cfg)
+		return newOpenAIChain(cfg, WithOpenAILogger(log))
 	case ProviderAnthropic:
-		return newAnthropicChain(cfg)
+		return newAnthropicChain(cfg, WithAnthropicLogger(log))
 	default:
 		return nil, fmt.Errorf("model: %w: provider %q", ErrUnknownProvider, cfg.Provider)
 	}
@@ -65,13 +74,13 @@ func newOpenAIChain(cfg config.LLMConfig, opts ...OpenAIOption) (*Chain, error)
 
 // newAnthropicChain builds a fallback chain from the Anthropic config block. Each
 // step is an AnthropicChatAdapter against the configured /v1/messages endpoint.
-func newAnthropicChain(cfg config.LLMConfig) (*Chain, error) {
+func newAnthropicChain(cfg config.LLMConfig, opts ...AnthropicOption) (*Chain, error) {
 	if cfg.AnthropicBaseURL == "" || cfg.AnthropicModel == "" {
 		return nil, ErrNoModel
 	}
-	steps := []Step{{Model: cfg.AnthropicModel, Adapter: NewAnthropicChat(cfg)}}
+	steps := []Step{{Model: cfg.AnthropicModel, Adapter: NewAnthropicChat(cfg, opts...)}}
 	if cfg.AnthropicFallback != "" && cfg.AnthropicFallback != cfg.AnthropicModel {
-		steps = append(steps, Step{Model: cfg.AnthropicFallback, Adapter: NewAnthropicChat(cfg)})
+		steps = append(steps, Step{Model: cfg.AnthropicFallback, Adapter: NewAnthropicChat(cfg, opts...)})
 	}
 	return NewChain(steps...), nil
 }

internal/runtime/model/model.go

@@ -170,6 +170,28 @@ type Request struct {
 	// "name":"x"}); empty means the provider default. Passed through verbatim to
 	// protocols that support it (Anthropic's tool_choice).
 	ToolChoice any
+	// Thinking controls the provider's reasoning budget/switch (design/04 §3.2).
+	// nil means "do not intervene" and uses the provider default. A provider
+	// whose protocol has no mapping for it logs a WARN rather than silently
+	// ignoring it.
+	Thinking *Thinking
+	// ReasoningEffort is the OpenAI-compatible reasoning strength knob
+	// (reasoning_effort). Empty means "do not intervene". The value is validated
+	// against the detected provider's whitelist; an unsupported value is
+	// downgraded to the nearest allowed tier (or dropped) with a WARN.
+	ReasoningEffort string
+}
+
+// Thinking carries the reasoning knobs a caller wants applied (design/04 §3.2).
+// Providers map the fields they actually support and report the rest; it only
+// controls budget/switch, never the thought content (design/01 §2.1 red line).
+type Thinking struct {
+	// BudgetTokens is the Anthropic thinking.budget_tokens target (the official
+	// semantic is a target, not a hard cap). Zero selects the adapter default.
+	BudgetTokens int
+	// Enable is an explicit on/off switch for providers that expose a boolean
+	// thinking flag. nil = no explicit switch.
+	Enable *bool
 }
 
 // Response is a normalized completion result.

internal/runtime/model/openai.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"
 	"strings"
 	"time"
@@ -39,6 +40,10 @@ type OpenAIChatAdapter struct {
 	model    string
 	client   *http.Client
 	recorder Recorder
+	// log reports reasoning_effort validation and ignored thinking directives. It
+	// is never nil: a discard logger tagged with this adapter's source is
+	// installed when the caller supplies none, so a decision is always traceable.
+	log *slog.Logger
 }
 
 // OpenAIOption configures an OpenAIChatAdapter.
@@ -60,6 +65,17 @@ func WithModel(m string) OpenAIOption {
 	return func(a *OpenAIChatAdapter) { a.model = m }
 }
 
+// WithOpenAILogger attaches the logger used to report reasoning_effort
+// validation and ignored thinking directives. A nil logger is ignored so the
+// discard default stays in place.
+func WithOpenAILogger(l *slog.Logger) OpenAIOption {
+	return func(a *OpenAIChatAdapter) {
+		if l != nil {
+			a.log = l
+		}
+	}
+}
+
 // NewOpenAIChat builds an adapter from a supplier config. baseURL is trimmed of
 // any trailing slash before the /chat/completions path is appended.
 func NewOpenAIChat(cfg config.LLMConfig, opts ...OpenAIOption) *OpenAIChatAdapter {
@@ -72,6 +88,7 @@ func NewOpenAIChat(cfg config.LLMConfig, opts ...OpenAIOption) *OpenAIChatAdapte
 			Transport: http.DefaultTransport,
 			Timeout:   defaultHTTPTimeout,
 		},
+		log: discardLogger("runtime/model/openai"),
 	}
 	for _, o := range opts {
 		o(a)

internal/runtime/model/openai_encode.go

@@ -15,6 +15,10 @@ type openAIChatRequest struct {
 	Stream        bool              `json:"stream,omitempty"`
 	StreamOptions *openAIStreamOpts `json:"stream_options,omitempty"`
 	Tools         []openAITool      `json:"tools,omitempty"`
+	// ReasoningEffort is the OpenAI-compatible reasoning strength knob. It is set
+	// only after validation against the detected vendor's whitelist (design/04
+	// §3.2); an unsupported value is downgraded or dropped, never forwarded as-is.
+	ReasoningEffort string `json:"reasoning_effort,omitempty"`
 }
 
 // openAIStreamOpts asks the provider to include usage in the final stream chunk.
@@ -66,13 +70,19 @@ func (a *OpenAIChatAdapter) buildRequest(req Request, stream bool) ([]byte, erro
 	if err != nil {
 		return nil, err
 	}
+	// The vendor behind an OpenAI-compatible endpoint decides which
+	// reasoning_effort tiers are legal; classify it from the resolved model (and
+	// the base URL as a fallback) before touching the request (design/04 §3.2).
+	vendor := reasoningVendorFor(req.Model, a.baseURL)
+	reportUnmappedThinking(a.log, vendor, req.Model, req.Thinking)
 	wire := openAIChatRequest{
-		Model:       req.Model,
-		Messages:    msgs,
-		Temperature: req.Temperature,
-		MaxTokens:   req.MaxTokens,
-		Stream:      stream,
-		Tools:       buildTools(req.Tools),
+		Model:           req.Model,
+		Messages:        msgs,
+		Temperature:     req.Temperature,
+		MaxTokens:       req.MaxTokens,
+		Stream:          stream,
+		Tools:           buildTools(req.Tools),
+		ReasoningEffort: resolveReasoningEffort(a.log, vendor, req.ReasoningEffort, req.Model),
 	}
 	if stream {
 		wire.StreamOptions = &openAIStreamOpts{IncludeUsage: true}

internal/runtime/model/reasoning.go

@@ -0,0 +1,216 @@
+package model
+
+import (
+	"io"
+	"log/slog"
+	"strings"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+)
+
+// discardLogger returns a logger that drops every record but still carries the
+// adapter's module source, so an adapter built without an injected logger can
+// never emit an unsourced record.
+func discardLogger(source string) *slog.Logger {
+	return logger.WithSource(slog.New(slog.NewTextHandler(io.Discard, nil)), source)
+}
+
+// Anthropic extended-thinking protocol bounds (design/04 §3.2).
+const (
+	// anthropicMinThinkingBudget is the smallest budget_tokens the Messages API
+	// accepts for thinking.type=enabled; anything below it is rejected with a
+	// 400, so a lower non-zero budget is raised and reported rather than sent.
+	anthropicMinThinkingBudget = 1024
+	// anthropicDefaultThinkingBudget is used when thinking is switched on without
+	// an explicit budget.
+	anthropicDefaultThinkingBudget = 4096
+	// anthropicThinkingBodyReserve is the body room kept on top of the thinking
+	// budget: max_tokens is shared by thinking and the visible answer, so the
+	// budget must never be allowed to consume it all (design/04 §3.2 red line:
+	// "预算与正文不得互相吃光").
+	anthropicThinkingBodyReserve = 2048
+)
+
+// reasoningVendor identifies the vendor behind an OpenAI-compatible endpoint.
+// The wire protocol is the same for all of them, but the accepted
+// reasoning_effort values are not, so a value must be checked against the right
+// whitelist instead of being forwarded blindly.
+type reasoningVendor string
+
+const (
+	vendorOpenAI   reasoningVendor = "openai"
+	vendorDeepSeek reasoningVendor = "deepseek"
+	vendorQwen     reasoningVendor = "qwen"
+	vendorUnknown  reasoningVendor = "unknown"
+)
+
+// reasoningEffortLadder is the canonical ascending order of reasoning_effort
+// tiers. It is used to round an unsupported value down to the nearest tier a
+// vendor accepts.
+var reasoningEffortLadder = []string{"none", "minimal", "low", "medium", "high", "xhigh", "max"}
+
+// reasoningEffortAllowed is the per-vendor whitelist. A vendor absent from this
+// table has no reasoning_effort support at all, which is reported rather than
+// guessed.
+var reasoningEffortAllowed = map[reasoningVendor]map[string]bool{
+	vendorOpenAI:   tierSet("none", "minimal", "low", "medium", "high", "xhigh", "max"),
+	vendorDeepSeek: tierSet("low", "high", "max"),
+}
+
+// tierSet builds a membership set from the given tiers.
+func tierSet(tiers ...string) map[string]bool {
+	set := make(map[string]bool, len(tiers))
+	for _, t := range tiers {
+		set[t] = true
+	}
+	return set
+}
+
+// reasoningVendorFor classifies the vendor of an OpenAI-compatible request from
+// its model name, falling back to the base URL when the name does not identify
+// one. An unrecognized pair yields vendorUnknown so the caller reports "not
+// supported" instead of assuming OpenAI semantics.
+func reasoningVendorFor(model, baseURL string) reasoningVendor {
+	m := strings.ToLower(strings.TrimSpace(model))
+	switch {
+	case strings.Contains(m, "deepseek"):
+		return vendorDeepSeek
+	case strings.Contains(m, "qwen"):
+		return vendorQwen
+	case strings.Contains(m, "gpt-"), strings.Contains(m, "chatgpt"),
+		strings.HasPrefix(m, "o1"), strings.HasPrefix(m, "o3"), strings.HasPrefix(m, "o4"):
+		return vendorOpenAI
+	}
+	u := strings.ToLower(strings.TrimSpace(baseURL))
+	switch {
+	case strings.Contains(u, "deepseek"):
+		return vendorDeepSeek
+	case strings.Contains(u, "dashscope"), strings.Contains(u, "aliyuncs"):
+		return vendorQwen
+	case strings.Contains(u, "openai"):
+		return vendorOpenAI
+	}
+	return vendorUnknown
+}
+
+// resolveReasoningEffort validates effort against the vendor's whitelist and
+// returns the value to send. An unsupported tier is rounded down to the nearest
+// tier the vendor accepts; a value the vendor does not accept at all — or a
+// vendor with no whitelist — yields "", meaning the field is dropped. Every
+// decision is logged (provider, field, value), never silently applied.
+func resolveReasoningEffort(log *slog.Logger, vendor reasoningVendor, effort, model string) string {
+	effort = strings.TrimSpace(effort)
+	if effort == "" {
+		return ""
+	}
+	allowed, ok := reasoningEffortAllowed[vendor]
+	if !ok {
+		log.Warn("reasoning_effort ignored: provider does not support it",
+			"provider", string(vendor), "field", "reasoning_effort", "value", effort, "model", model)
+		return ""
+	}
+	if allowed[effort] {
+		return effort
+	}
+	downgraded, ok := downgradeReasoningEffort(allowed, effort)
+	if !ok {
+		log.Warn("reasoning_effort dropped: unrecognized value",
+			"provider", string(vendor), "field", "reasoning_effort", "value", effort, "model", model)
+		return ""
+	}
+	log.Warn("reasoning_effort downgraded: value not accepted by provider",
+		"provider", string(vendor), "field", "reasoning_effort",
+		"value", effort, "sent", downgraded, "model", model)
+	return downgraded
+}
+
+// downgradeReasoningEffort rounds an unsupported tier down to the nearest tier
+// the vendor accepts using the canonical ladder order; a tier below the vendor's
+// minimum maps to that minimum. It reports false when effort is not on the
+// ladder at all, so the caller drops the field instead of inventing a value.
+func downgradeReasoningEffort(allowed map[string]bool, effort string) (string, bool) {
+	start := -1
+	for i, tier := range reasoningEffortLadder {
+		if tier == effort {
+			start = i
+			break
+		}
+	}
+	if start < 0 {
+		return "", false
+	}
+	for i := start; i >= 0; i-- {
+		if allowed[reasoningEffortLadder[i]] {
+			return reasoningEffortLadder[i], true
+		}
+	}
+	for _, tier := range reasoningEffortLadder {
+		if allowed[tier] {
+			return tier, true
+		}
+	}
+	return "", false
+}
+
+// anthropicThinkingFor resolves the extended-thinking directive together with the
+// max_tokens it requires. It returns the (possibly raised) max_tokens and the
+// wire block; a nil block means "do not send thinking" (no directive, or an
+// explicit off). Because max_tokens is shared by thinking and the visible answer,
+// the returned budget always leaves anthropicThinkingBodyReserve for the body,
+// and a request whose budget would eat the answer raises max_tokens instead — the
+// adjustment is logged so it is never a silent rewrite.
+func anthropicThinkingFor(th *Thinking, maxTokens int, log *slog.Logger) (int, *anthropicThinking) {
+	if th == nil || (th.Enable != nil && !*th.Enable) {
+		return maxTokens, nil
+	}
+	budget := th.BudgetTokens
+	if budget == 0 {
+		budget = anthropicDefaultThinkingBudget
+	}
+	if budget < anthropicMinThinkingBudget {
+		log.Warn("thinking budget raised to the protocol minimum",
+			"provider", "anthropic", "field", "thinking.budget_tokens",
+			"budget_tokens", th.BudgetTokens, "sent", anthropicMinThinkingBudget)
+		budget = anthropicMinThinkingBudget
+	}
+	if need := budget + anthropicThinkingBodyReserve; maxTokens < need {
+		log.Warn("max_tokens raised to leave room for thinking plus the answer",
+			"provider", "anthropic", "budget_tokens", budget,
+			"max_tokens_requested", maxTokens, "max_tokens_sent", need,
+			"body_reserve", anthropicThinkingBodyReserve)
+		maxTokens = need
+	}
+	return maxTokens, &anthropicThinking{Type: anthropicThinkingTypeEnabled, BudgetTokens: budget}
+}
+
+// reportUnmappedThinking logs why a Thinking directive cannot be carried by an
+// OpenAI-compatible request, naming the provider and the field that was ignored.
+// Qwen3 does have enable_thinking, but the protocol has no portable field for
+// it (vLLM wants chat_template_kwargs.enable_thinking, DashScope's compatible
+// mode wants a top-level enable_thinking), and sending the wrong shape can 400
+// the request — so this version reports it instead of guessing.
+func reportUnmappedThinking(log *slog.Logger, vendor reasoningVendor, model string, th *Thinking) {
+	if th == nil {
+		return
+	}
+	if th.Enable != nil {
+		switch vendor {
+		case vendorQwen:
+			log.Warn("enable_thinking not forwarded: the OpenAI-compatible protocol has no portable field for it",
+				"provider", "qwen", "field", "extra_body.chat_template_kwargs.enable_thinking",
+				"enable", *th.Enable, "model", model)
+		case vendorDeepSeek:
+			log.Warn("deepseek thinking switch not mapped in this version; only reasoning_effort is forwarded",
+				"provider", "deepseek", "field", "thinking.type", "enable", *th.Enable, "model", model)
+		default:
+			log.Warn("thinking switch ignored: provider has no boolean thinking switch",
+				"provider", string(vendor), "field", "thinking.enable", "enable", *th.Enable, "model", model)
+		}
+		return
+	}
+	if th.BudgetTokens > 0 {
+		log.Warn("thinking budget ignored: OpenAI-compatible providers take reasoning_effort, not a token budget",
+			"provider", string(vendor), "field", "thinking.budget_tokens",
+			"budget_tokens", th.BudgetTokens, "model", model)
+	}
+}

internal/runtime/model/reasoning_test.go

@@ -0,0 +1,364 @@
+package model
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"net/http"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+)
+
+// captureLog returns a logger writing text records into a buffer, plus the
+// buffer, so a test can assert the WARN an adapter emits.
+func captureLog() (*slog.Logger, *bytes.Buffer) {
+	buf := &bytes.Buffer{}
+	return slog.New(slog.NewTextHandler(buf, &slog.HandlerOptions{Level: slog.LevelDebug})), buf
+}
+
+// boolPtr is a convenience for the tri-state Thinking.Enable.
+func boolPtr(v bool) *bool { return &v }
+
+// TestAnthropicChat_ThinkingBudgetLeavesRoomForTheAnswer is the design/04 §3.2
+// red line: a budget large enough to eat max_tokens must not be sent as-is —
+// the adapter raises max_tokens so thinking and the visible answer both fit, and
+// it logs the adjustment (never a silent rewrite).
+func TestAnthropicChat_ThinkingBudgetLeavesRoomForTheAnswer(t *testing.T) {
+	t.Parallel()
+	ch := make(chan anthropicCaptured, 1)
+	srv := newAnthropicServer(t, http.StatusOK, "application/json", anthropicTextResponse, ch)
+	log, buf := captureLog()
+	ad := NewAnthropicChat(
+		config.LLMConfig{AnthropicBaseURL: srv.URL, AnthropicModel: "claude-test"},
+		WithAnthropicLogger(log))
+
+	const budget = 4096
+	// max_tokens equals the budget: without the guard the whole budget would be
+	// consumed by thinking and the answer would come back empty.
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:     "claude-test",
+		Messages:  []Message{TextMessage(RoleUser, "hi")},
+		MaxTokens: budget,
+		Thinking:  &Thinking{BudgetTokens: budget},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	body := (<-ch).body
+	think, ok := body["thinking"].(map[string]any)
+	if !ok {
+		t.Fatalf("body.thinking = %v, want an enabled directive", body["thinking"])
+	}
+	if think["type"] != anthropicThinkingTypeEnabled {
+		t.Errorf("thinking.type = %v, want %q", think["type"], anthropicThinkingTypeEnabled)
+	}
+	gotBudget, _ := think["budget_tokens"].(float64)
+	maxTokens, _ := body["max_tokens"].(float64)
+	if int(gotBudget) != budget {
+		t.Errorf("thinking.budget_tokens = %v, want %d", gotBudget, budget)
+	}
+	if maxTokens <= gotBudget {
+		t.Fatalf("max_tokens = %v, want > budget_tokens %v (thinking would eat the answer)", maxTokens, gotBudget)
+	}
+	if maxTokens < gotBudget+anthropicThinkingBodyReserve {
+		t.Errorf("max_tokens = %v, want >= budget %v + body reserve %d", maxTokens, gotBudget, anthropicThinkingBodyReserve)
+	}
+	if !strings.Contains(buf.String(), "max_tokens raised") {
+		t.Errorf("log = %q, want a WARN explaining the max_tokens raise", buf.String())
+	}
+}
+
+// TestAnthropicChat_ThinkingBudgetBelowMaxTokensUnchanged pins the non-saturated
+// case: when the caller's max_tokens already leaves room, it is sent untouched
+// and the budget stays strictly below it.
+func TestAnthropicChat_ThinkingBudgetBelowMaxTokensUnchanged(t *testing.T) {
+	t.Parallel()
+	ch := make(chan anthropicCaptured, 1)
+	srv := newAnthropicServer(t, http.StatusOK, "application/json", anthropicTextResponse, ch)
+	log, buf := captureLog()
+	ad := NewAnthropicChat(
+		config.LLMConfig{AnthropicBaseURL: srv.URL, AnthropicModel: "claude-test"},
+		WithAnthropicLogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:     "claude-test",
+		Messages:  []Message{TextMessage(RoleUser, "hi")},
+		MaxTokens: anthropicDefaultMaxTokens,
+		Thinking:  &Thinking{BudgetTokens: 4096},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	body := (<-ch).body
+	think := body["thinking"].(map[string]any)
+	gotBudget, _ := think["budget_tokens"].(float64)
+	maxTokens, _ := body["max_tokens"].(float64)
+	if maxTokens != float64(anthropicDefaultMaxTokens) {
+		t.Errorf("max_tokens = %v, want the requested %d (unchanged)", maxTokens, anthropicDefaultMaxTokens)
+	}
+	if gotBudget >= maxTokens {
+		t.Errorf("budget_tokens %v >= max_tokens %v", gotBudget, maxTokens)
+	}
+	if strings.Contains(buf.String(), "max_tokens raised") {
+		t.Errorf("unexpected adjustment log: %q", buf.String())
+	}
+}
+
+// TestAnthropicChat_ThinkingDisabledOmitsField asserts the explicit off switch
+// sends no thinking directive at all (Anthropic treats a missing field as off).
+func TestAnthropicChat_ThinkingDisabledOmitsField(t *testing.T) {
+	t.Parallel()
+	ch := make(chan anthropicCaptured, 1)
+	srv := newAnthropicServer(t, http.StatusOK, "application/json", anthropicTextResponse, ch)
+	ad := NewAnthropicChat(config.LLMConfig{AnthropicBaseURL: srv.URL, AnthropicModel: "claude-test"})
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:    "claude-test",
+		Messages: []Message{TextMessage(RoleUser, "hi")},
+		Thinking: &Thinking{BudgetTokens: 4096, Enable: boolPtr(false)},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	if body := (<-ch).body; body["thinking"] != nil {
+		t.Fatalf("body.thinking = %v, want the field omitted", body["thinking"])
+	}
+}
+
+// TestAnthropicChat_ThinkingBudgetRaisedToProtocolMinimum asserts a budget below
+// the API minimum is raised (sending it as-is would 400) and reported.
+func TestAnthropicChat_ThinkingBudgetRaisedToProtocolMinimum(t *testing.T) {
+	t.Parallel()
+	ch := make(chan anthropicCaptured, 1)
+	srv := newAnthropicServer(t, http.StatusOK, "application/json", anthropicTextResponse, ch)
+	log, buf := captureLog()
+	ad := NewAnthropicChat(
+		config.LLMConfig{AnthropicBaseURL: srv.URL, AnthropicModel: "claude-test"},
+		WithAnthropicLogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:    "claude-test",
+		Messages: []Message{TextMessage(RoleUser, "hi")},
+		Thinking: &Thinking{BudgetTokens: 512},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	think := (<-ch).body["thinking"].(map[string]any)
+	if got, _ := think["budget_tokens"].(float64); int(got) != anthropicMinThinkingBudget {
+		t.Errorf("thinking.budget_tokens = %v, want the minimum %d", got, anthropicMinThinkingBudget)
+	}
+	if !strings.Contains(buf.String(), "protocol minimum") {
+		t.Errorf("log = %q, want a WARN about the minimum budget", buf.String())
+	}
+}
+
+// TestOpenAIChat_ReasoningEffortPassthrough asserts a supported tier on a known
+// provider is forwarded verbatim, with no warning.
+func TestOpenAIChat_ReasoningEffortPassthrough(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	log, buf := captureLog()
+	ad := NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "gpt-test"}, WithOpenAILogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:           "gpt-4o",
+		Messages:        []Message{TextMessage(RoleUser, "hi")},
+		ReasoningEffort: "high",
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	if got := (<-ch).body["reasoning_effort"]; got != "high" {
+		t.Fatalf("body.reasoning_effort = %v, want high", got)
+	}
+	if buf.Len() != 0 {
+		t.Errorf("unexpected log for a supported value: %q", buf.String())
+	}
+}
+
+// TestOpenAIChat_ReasoningEffortDowngradedForDeepSeek asserts a tier the vendor
+// does not accept (DeepSeek allows only low/high/max) is rounded down to the
+// nearest allowed tier and reported, never forwarded as-is.
+func TestOpenAIChat_ReasoningEffortDowngradedForDeepSeek(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	log, buf := captureLog()
+	ad := NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "deepseek-chat"}, WithOpenAILogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:           "deepseek-chat",
+		Messages:        []Message{TextMessage(RoleUser, "hi")},
+		ReasoningEffort: "medium",
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	if got := (<-ch).body["reasoning_effort"]; got != "low" {
+		t.Fatalf("body.reasoning_effort = %v, want the downgraded low", got)
+	}
+	rec := buf.String()
+	for _, want := range []string{"level=WARN", "reasoning_effort", "deepseek", "medium", "low"} {
+		if !strings.Contains(rec, want) {
+			t.Errorf("log %q missing %q", rec, want)
+		}
+	}
+}
+
+// TestOpenAIChat_ReasoningEffortDroppedForUnknownProvider asserts an
+// unrecognized provider/model leaves the request untouched and reports the
+// ignored field (design/04 §3.2: never silently ineffective).
+func TestOpenAIChat_ReasoningEffortDroppedForUnknownProvider(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	log, buf := captureLog()
+	ad := NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "mystery-1"}, WithOpenAILogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:           "mystery-1",
+		Messages:        []Message{TextMessage(RoleUser, "hi")},
+		ReasoningEffort: "high",
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	body := (<-ch).body
+	if _, present := body["reasoning_effort"]; present {
+		t.Fatalf("body.reasoning_effort = %v, want the field dropped", body["reasoning_effort"])
+	}
+	rec := buf.String()
+	for _, want := range []string{"level=WARN", "reasoning_effort", "unknown", "high"} {
+		if !strings.Contains(rec, want) {
+			t.Errorf("log %q missing %q", rec, want)
+		}
+	}
+}
+
+// TestOpenAIChat_QwenEnableThinkingReportedNotForwarded documents the deliberate
+// choice for the Qwen3 hard switch: the OpenAI-compatible protocol has no
+// portable wire shape for enable_thinking, so this version reports it and leaves
+// the request byte-identical instead of guessing a shape that could 400.
+func TestOpenAIChat_QwenEnableThinkingReportedNotForwarded(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	log, buf := captureLog()
+	ad := NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "qwen3-max"}, WithOpenAILogger(log))
+
+	plain := make(chan capturedRequest, 1)
+	plainSrv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, plain)
+	plainAd := NewOpenAIChat(config.LLMConfig{BaseURL: plainSrv.URL, Model: "qwen3-max"})
+	if _, err := plainAd.Chat(context.Background(), Request{
+		Model:    "qwen3-max",
+		Messages: []Message{TextMessage(RoleUser, "hi")},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:    "qwen3-max",
+		Messages: []Message{TextMessage(RoleUser, "hi")},
+		Thinking: &Thinking{Enable: boolPtr(false)},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	body := (<-ch).body
+	for _, key := range []string{"enable_thinking", "chat_template_kwargs", "extra_body", "thinking"} {
+		if _, present := body[key]; present {
+			t.Errorf("body.%s = %v, want the request unchanged", key, body[key])
+		}
+	}
+	if len(body) != len((<-plain).body) {
+		t.Errorf("request shape changed with a thinking directive: %v", body)
+	}
+	rec := buf.String()
+	for _, want := range []string{"level=WARN", "enable_thinking", "qwen"} {
+		if !strings.Contains(rec, want) {
+			t.Errorf("log %q missing %q", rec, want)
+		}
+	}
+}
+
+// TestOpenAIChat_ThinkingBudgetReportedIgnored asserts a token budget (an
+// Anthropic-style directive) is reported as unmappable on an OpenAI-compatible
+// endpoint rather than silently dropped.
+func TestOpenAIChat_ThinkingBudgetReportedIgnored(t *testing.T) {
+	t.Parallel()
+	ch := make(chan capturedRequest, 1)
+	srv := newCompletionServer(t, http.StatusOK, "application/json", okCompletion, ch)
+	log, buf := captureLog()
+	ad := NewOpenAIChat(config.LLMConfig{BaseURL: srv.URL, Model: "gpt-4o"}, WithOpenAILogger(log))
+
+	if _, err := ad.Chat(context.Background(), Request{
+		Model:    "gpt-4o",
+		Messages: []Message{TextMessage(RoleUser, "hi")},
+		Thinking: &Thinking{BudgetTokens: 8192},
+	}, Options{}); err != nil {
+		t.Fatalf("Chat error: %v", err)
+	}
+	if _, present := (<-ch).body["thinking"]; present {
+		t.Fatal("body.thinking was sent to an OpenAI-compatible endpoint")
+	}
+	rec := buf.String()
+	for _, want := range []string{"level=WARN", "thinking.budget_tokens", "gpt"} {
+		if !strings.Contains(rec, want) {
+			t.Errorf("log %q missing %q", rec, want)
+		}
+	}
+}
+
+// TestAnthropicChatStream_ThinkingBudgetLeavesRoomForTheAnswer runs the same
+// red-line check on the streaming path, which builds its own request body.
+func TestAnthropicChatStream_ThinkingBudgetLeavesRoomForTheAnswer(t *testing.T) {
+	t.Parallel()
+	ch := make(chan anthropicCaptured, 1)
+	const sse = "event: message_start\ndata: {\"type\":\"message_start\"}\n\n" +
+		"event: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n" +
+		"event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"hi\"}}\n\n" +
+		"event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+	srv := newAnthropicServer(t, http.StatusOK, "text/event-stream", sse, ch)
+	ad := NewAnthropicChat(config.LLMConfig{AnthropicBaseURL: srv.URL, AnthropicModel: "claude-test"})
+
+	if _, err := ad.ChatStream(context.Background(), Request{
+		Model:     "claude-test",
+		Messages:  []Message{TextMessage(RoleUser, "hi")},
+		MaxTokens: 2048,
+		Thinking:  &Thinking{BudgetTokens: 2048},
+	}, func(StreamEvent) {}); err != nil {
+		t.Fatalf("ChatStream error: %v", err)
+	}
+	body := (<-ch).body
+	think, ok := body["thinking"].(map[string]any)
+	if !ok {
+		t.Fatalf("stream body.thinking = %v, want an enabled directive", body["thinking"])
+	}
+	gotBudget, _ := think["budget_tokens"].(float64)
+	maxTokens, _ := body["max_tokens"].(float64)
+	if gotBudget >= maxTokens {
+		t.Fatalf("stream max_tokens = %v, want > budget_tokens %v", maxTokens, gotBudget)
+	}
+}
+
+// TestReasoningVendorFor_Classification locks the vendor detection the whitelist
+// depends on, including the fallback to the base URL.
+func TestReasoningVendorFor_Classification(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		model   string
+		baseURL string
+		want    reasoningVendor
+	}{
+		{model: "deepseek-reasoner", want: vendorDeepSeek},
+		{model: "Qwen3-Max", want: vendorQwen},
+		{model: "gpt-4o", want: vendorOpenAI},
+		{model: "o3-mini", want: vendorOpenAI},
+		{model: "chatgpt-4o-latest", want: vendorOpenAI},
+		{model: "claude-sonnet-4", baseURL: "https://api.openai.com/v1", want: vendorOpenAI},
+		{model: "qwen-plus", baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1", want: vendorQwen},
+		{model: "some-model", baseURL: "https://api.deepseek.com/v1", want: vendorDeepSeek},
+		{model: "some-model", baseURL: "http://localhost:8000/v1", want: vendorUnknown},
+	}
+	for _, tt := range cases {
+		if got := reasoningVendorFor(tt.model, tt.baseURL); got != tt.want {
+			t.Errorf("reasoningVendorFor(%q, %q) = %q, want %q", tt.model, tt.baseURL, got, tt.want)
+		}
+	}
+}

internal/runtime/model/runtime.go

@@ -141,7 +141,7 @@ func (m *RuntimeLLM) swap(groups []runtimeconfig.Group) error {
 	if len(groups) == 0 {
 		groups = runtimeconfig.GroupFromEnv(m.env)
 	}
-	snap, err := buildSnapshot(groups, m.env)
+	snap, err := buildSnapshot(groups, m.env, m.log)
 	if err != nil {
 		return err
 	}
@@ -162,10 +162,10 @@ func (m *RuntimeLLM) load() *runtimeChainSnapshot {
 // without a base URL/model yields a nil chain (no model configured), surfaced as
 // ErrNoModel by the adapter methods. The Router keeps the env vision model so a
 // dedicated vision model survives a reload that only changes the vendor group.
-func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig) (*runtimeChainSnapshot, error) {
+func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig, log *slog.Logger) (*runtimeChainSnapshot, error) {
 	active := groups[0]
 	cfg := active.ToLLMConfig()
-	chain, err := NewChatChain(cfg)
+	chain, err := NewChatChainWithLog(cfg, log)
 	if err != nil && !errors.Is(err, ErrNoModel) {
 		return nil, err
 	}

internal/services/gateway/admin_write_persona_thinking_test.go

@@ -0,0 +1,102 @@
+package gateway
+
+import (
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/persona/loader"
+)
+
+// TestPersonaUpsertRequest_ThinkingRoundTripsThroughYAML pins the admin persona
+// write path for the optional `thinking` block: the hand-written DTO maps into
+// the loader struct, yaml.Marshal emits the documented keys, and the reload of
+// that YAML yields the same values — i.e. the field really round-trips instead of
+// being dropped by an un-whitelisted DTO.
+func TestPersonaUpsertRequest_ThinkingRoundTripsThroughYAML(t *testing.T) {
+	t.Parallel()
+
+	show := false
+	req := personaUpsertRequest{
+		ID: "xilian", Name: "昔涟", Role: "r", SystemPrompt: "s",
+		Thinking: &personaThinkingRequest{BudgetTokens: 4096, Effort: " medium ", ShowToUser: &show, Mode: " on "},
+	}
+	p := personaFromRequest(req)
+	if err := p.ValidateThinking(); err != nil {
+		t.Fatalf("ValidateThinking() error: %v", err)
+	}
+	data, err := yaml.Marshal(p)
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	back := &loader.Persona{}
+	if err := yaml.Unmarshal(data, back); err != nil {
+		t.Fatalf("Unmarshal: %v", err)
+	}
+	if back.Thinking.BudgetTokens != 4096 || back.Thinking.Mode != loader.ThinkingModeOn || back.Thinking.Effort != "medium" {
+		t.Fatalf("thinking = %+v, want 4096/on/medium", back.Thinking)
+	}
+	if back.Thinking.ShowToUser == nil || *back.Thinking.ShowToUser {
+		t.Fatalf("showToUser = %v, want an explicit false", back.Thinking.ShowToUser)
+	}
+}
+
+// TestPersonaUpsertRequest_ThinkingInvalidRejected asserts an invalid thinking
+// block is rejected through the same validation the loader uses, so the admin API
+// cannot persist a mode the runtime would refuse to load.
+func TestPersonaUpsertRequest_ThinkingInvalidRejected(t *testing.T) {
+	t.Parallel()
+
+	p := personaFromRequest(personaUpsertRequest{
+		ID: "x", Name: "x", Role: "r", Thinking: &personaThinkingRequest{Mode: "always"},
+	})
+	err := p.ValidateThinking()
+	if err == nil {
+		t.Fatal("ValidateThinking() = nil, want an error")
+	}
+	if !strings.Contains(err.Error(), "always") {
+		t.Fatalf("error %q does not name the offending mode", err)
+	}
+}
+
+// TestPersonaUpsertRequest_NoThinkingBlockOmitsTheKey asserts a request without a
+// thinking block produces none in the YAML, so no existing persona file gains a
+// noise section.
+func TestPersonaUpsertRequest_NoThinkingBlockOmitsTheKey(t *testing.T) {
+	t.Parallel()
+
+	data, err := yaml.Marshal(personaFromRequest(personaUpsertRequest{ID: "x", Name: "x", Role: "r", SystemPrompt: "s"}))
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	if strings.Contains(string(data), "thinking") {
+		t.Fatalf("marshaled persona carries a thinking block:\n%s", data)
+	}
+}
+
+// TestApplyThinkingEdit_PreservesOnOmission is the non-destructive update rule: a
+// client that omits `thinking` keeps the stored block, an explicit block replaces
+// it, and an all-default block clears it.
+func TestApplyThinkingEdit_PreservesOnOmission(t *testing.T) {
+	t.Parallel()
+
+	show := false
+	stored := &loader.Persona{Thinking: loader.ThinkingParams{BudgetTokens: 8192, Mode: loader.ThinkingModeOn, ShowToUser: &show}}
+
+	kept := applyThinkingEdit(nil, stored)
+	if kept.BudgetTokens != 8192 || kept.Mode != loader.ThinkingModeOn || kept.ShowToUser == nil {
+		t.Fatalf("applyThinkingEdit(nil, stored) = %+v, want the stored block", kept)
+	}
+	replaced := applyThinkingEdit(&personaThinkingRequest{BudgetTokens: 1024, Mode: "off"}, stored)
+	if replaced.BudgetTokens != 1024 || replaced.Mode != loader.ThinkingModeOff || replaced.ShowToUser != nil {
+		t.Fatalf("applyThinkingEdit(explicit, stored) = %+v, want the request block", replaced)
+	}
+	cleared := applyThinkingEdit(&personaThinkingRequest{}, stored)
+	if cleared.BudgetTokens != 0 || cleared.Mode != "" || cleared.ShowToUser != nil {
+		t.Fatalf("applyThinkingEdit(empty object, stored) = %+v, want the zero block", cleared)
+	}
+	if created := applyThinkingEdit(nil, nil); created.BudgetTokens != 0 || created.ShowToUser != nil {
+		t.Fatalf("applyThinkingEdit(nil, nil) = %+v, want the zero block (create path)", created)
+	}
+}

internal/services/gateway/admin_write_personas_users.go

@@ -38,6 +38,19 @@ type personaUpsertRequest struct {
 	Modes        []string `json:"modes"`
 	Mode         string   `json:"mode"`
 	MemoryNS     string   `json:"memoryNamespace"`
+	// Thinking is the optional reasoning/presentation block (design/01 §2.1). It
+	// is persisted into the persona YAML as-is; omitting it on an update keeps the
+	// stored block (see adminUpdatePersona).
+	Thinking *personaThinkingRequest `json:"thinking,omitempty"`
+}
+
+// personaThinkingRequest is the wire form of the persona `thinking` section. The
+// pointers/naming mirror the YAML so a panel can round-trip it verbatim.
+type personaThinkingRequest struct {
+	BudgetTokens int    `json:"budgetTokens,omitempty"`
+	Effort       string `json:"effort,omitempty"`
+	ShowToUser   *bool  `json:"showToUser,omitempty"`
+	Mode         string `json:"mode,omitempty"`
 }
 
 // adminCreatePersona registers a new persona in the registry (real runtime
@@ -65,6 +78,11 @@ func (s *Server) adminCreatePersona(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	p := personaFromRequest(req)
+	if err := p.ValidateThinking(); err != nil {
+		s.auditClaims(r, "persona.create", "error")
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid thinking config: %v", err))
+		return
+	}
 	if err := savePersonaYAML(p); err != nil {
 		s.auditClaims(r, "persona.create", "error")
 		s.log.Error("persona persist", "id", req.ID, "err", err)
@@ -112,6 +130,16 @@ func (s *Server) adminUpdatePersona(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	p := personaFromRequest(req)
+	if err := p.ValidateThinking(); err != nil {
+		s.auditClaims(r, "persona.update", "error")
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid thinking config: %v", err))
+		return
+	}
+	// A client that does not know the optional `thinking` block (an older panel, a
+	// script) omits it; keep the stored one instead of silently wiping a
+	// hand-edited config. Sending the object replaces it, and sending it with all
+	// fields default clears it.
+	p.Thinking = applyThinkingEdit(req.Thinking, existingPersona(reg, id))
 	if err := savePersonaYAML(p); err != nil {
 		s.auditClaims(r, "persona.update", "error")
 		s.log.Error("persona persist", "id", id, "err", err)
@@ -223,9 +251,46 @@ func personaFromRequest(req personaUpsertRequest) *loader.Persona {
 		Background:   req.Background,
 		Values:       req.Values,
 		Emotion:      loader.EmotionParams{MemoryNamespace: strings.TrimSpace(req.MemoryNS)},
+		Thinking:     thinkingFromRequest(req.Thinking),
 	}
 }
 
+// thinkingFromRequest maps the wire `thinking` block onto the persona field; a
+// missing block yields the zero value, which yaml.Marshal omits entirely.
+func thinkingFromRequest(req *personaThinkingRequest) loader.ThinkingParams {
+	if req == nil {
+		return loader.ThinkingParams{}
+	}
+	return loader.ThinkingParams{
+		BudgetTokens: req.BudgetTokens,
+		Effort:       strings.TrimSpace(req.Effort),
+		ShowToUser:   req.ShowToUser,
+		Mode:         strings.TrimSpace(req.Mode),
+	}
+}
+
+// existingPersona returns the stored persona for id, or nil when it is absent.
+func existingPersona(reg *personareg.Registry, id string) *loader.Persona {
+	if p, ok := reg.Persona(id); ok {
+		return p
+	}
+	return nil
+}
+
+// applyThinkingEdit returns the `thinking` block an update should persist: the
+// request's own block when it carries one, otherwise the stored persona's block —
+// so a client that does not know the optional field can never wipe it. An update
+// that sends the object replaces the block outright (all-default fields clear it).
+func applyThinkingEdit(req *personaThinkingRequest, existing *loader.Persona) loader.ThinkingParams {
+	if req != nil {
+		return thinkingFromRequest(req)
+	}
+	if existing != nil {
+		return existing.Thinking
+	}
+	return loader.ThinkingParams{}
+}
+
 // characterFromRequest builds the registry.Character bound to the persona.
 func characterFromRequest(req personaUpsertRequest) *personareg.Character {
 	modes := append([]string(nil), req.Modes...)