From 3a8d64e8ce1aaee0dda820c5de764d3d0b13c1e3 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 10:00:01 +0800
Subject: [PATCH 1/7] fix(providers): omit tool_choice on openai-completions
 requests without tools

Strict OpenAI-compatible endpoints (xAI-style gateways/relays) reject
requests that set tool_choice without a tools array ("A tool_choice was
set on the request but no tools were specified"). Text-only calls such
as compaction summaries and title generation carry no tools but always
sent tool_choice: "none", so compaction on gpt-5.6 via chat-completions
relays failed with 400.

Gate tool_choice at the openai-completions dispatch point: only forward
it when the request actually carries tools, matching the existing guard
in agentRunner. tool_choice is meaningless without tools, so behavior
is unchanged on lenient endpoints.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/lib/providers/runtime/streamByApi.ts  |   8 +-
 .../test/providers/request-options.test.mjs   |   7 +-
 .../stream-by-api-tool-choice.test.mjs        | 126 ++++++++++++++++++
 3 files changed, 139 insertions(+), 2 deletions(-)
 create mode 100644 crates/agent-gui/test/providers/stream-by-api-tool-choice.test.mjs

diff --git a/crates/agent-gui/src/lib/providers/runtime/streamByApi.ts b/crates/agent-gui/src/lib/providers/runtime/streamByApi.ts
index 96afb9d67..6b5c2fc6c 100644
--- a/crates/agent-gui/src/lib/providers/runtime/streamByApi.ts
+++ b/crates/agent-gui/src/lib/providers/runtime/streamByApi.ts
@@ -148,10 +148,16 @@ export function streamSimpleByApi(model: Model<any>, context: Context, options:
       const openAICompletionsContext = openAICompletionsOptions.deepSeekProviderAdapter
         ? normalizeStructuredToolCallHistoryForDeepSeek(context)
         : context;
+      // 严格校验的 OpenAI 兼容端点（xAI/各类中转网关）对「带 tool_choice 但没带
+      // tools」的请求直接 400（"A tool_choice was set on the request but no tools
+      // were specified"）——compaction 摘要、标题生成等 text-only 请求没有工具，
+      // 会踩中。tool_choice 在无工具时本就无意义，只在请求真正携带 tools 时下发。
       const openAIOptions: OpenAICompletionsOptions = {
         ...buildOpenAIBaseOptions(model, openAICompletionsOptions),
         reasoningEffort: clampOpenAIReasoningEffort(model, openAICompletionsOptions.reasoning),
-        toolChoice: mapToolChoiceToOpenAI(openAICompletionsOptions.toolChoice),
+        toolChoice: openAICompletionsContext.tools?.length
+          ? mapToolChoiceToOpenAI(openAICompletionsOptions.toolChoice)
+          : undefined,
       };
       return withStreamRetry(
         () => streamOpenAICompletions(model as any, openAICompletionsContext, openAIOptions),
diff --git a/crates/agent-gui/test/providers/request-options.test.mjs b/crates/agent-gui/test/providers/request-options.test.mjs
index 48c1ec81d..972536806 100644
--- a/crates/agent-gui/test/providers/request-options.test.mjs
+++ b/crates/agent-gui/test/providers/request-options.test.mjs
@@ -355,7 +355,12 @@ test("Codex Chat Completions streams forward reasoning effort", async () => {
 
   const result = localProviders.streamSimpleByApi(
     model,
-    { messages: [] },
+    {
+      // toolChoice 只在请求真正携带 tools 时下发（无工具下发会被严格
+      // OpenAI 兼容端点 400），透传断言需要一个非空 tools。
+      tools: [{ name: "echo", description: "Echo tool", parameters: { type: "object" } }],
+      messages: [],
+    },
     { reasoning: "high", toolChoice: "auto" },
   );
 
diff --git a/crates/agent-gui/test/providers/stream-by-api-tool-choice.test.mjs b/crates/agent-gui/test/providers/stream-by-api-tool-choice.test.mjs
new file mode 100644
index 000000000..9d632473f
--- /dev/null
+++ b/crates/agent-gui/test/providers/stream-by-api-tool-choice.test.mjs
@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTsModuleLoader } from "../helpers/load-ts-module.mjs";
+
+function createUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+function createSourceStream() {
+  const assistant = {
+    role: "assistant",
+    content: [{ type: "text", text: "ok" }],
+    api: "openai-completions",
+    provider: "openai",
+    model: "gpt-5.6",
+    usage: createUsage(),
+    stopReason: "stop",
+    timestamp: Date.now(),
+  };
+  const events = [
+    { type: "start", partial: { ...assistant, content: [] } },
+    { type: "done", reason: "stop", message: assistant },
+  ];
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const event of events) {
+        yield event;
+      }
+    },
+    async result() {
+      return assistant;
+    },
+  };
+}
+
+function createOpenAICompletionsModel() {
+  return {
+    id: "gpt-5.6",
+    name: "gpt-5.6",
+    api: "openai-completions",
+    provider: "openai",
+    baseUrl: "https://relay.example.com/v1",
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 272000,
+    maxTokens: 128000,
+  };
+}
+
+function createLoaderCapturingOptions(capturedOptions) {
+  return createTsModuleLoader({
+    mocks: {
+      "@earendil-works/pi-ai/api/openai-completions": {
+        stream(_model, _context, options) {
+          capturedOptions.push(options);
+          return createSourceStream();
+        },
+      },
+    },
+  });
+}
+
+async function streamOnce(context, toolChoice) {
+  const capturedOptions = [];
+  const loader = createLoaderCapturingOptions(capturedOptions);
+  const { streamSimpleByApi } = loader.loadModule("src/lib/providers/runtime/streamByApi.ts");
+  const stream = streamSimpleByApi(createOpenAICompletionsModel(), context, {
+    apiKey: "test-key",
+    toolChoice,
+  });
+  await stream.result();
+  assert.equal(capturedOptions.length, 1);
+  return capturedOptions[0];
+}
+
+const echoTool = {
+  name: "echo",
+  description: "Echo tool",
+  parameters: { type: "object", properties: {} },
+};
+
+test("openai-completions: 无工具请求不下发 tool_choice（压缩摘要等 text-only 路径）", async () => {
+  const options = await streamOnce(
+    { messages: [{ role: "user", content: "compaction payload", timestamp: 1 }] },
+    "none",
+  );
+  assert.equal(options.toolChoice, undefined);
+});
+
+test("openai-completions: 无工具请求即使 toolChoice=auto 也不下发", async () => {
+  const options = await streamOnce(
+    { messages: [{ role: "user", content: "hi", timestamp: 1 }] },
+    "auto",
+  );
+  assert.equal(options.toolChoice, undefined);
+});
+
+test("openai-completions: 带工具请求保留 tool_choice=none", async () => {
+  const options = await streamOnce(
+    {
+      tools: [echoTool],
+      messages: [{ role: "user", content: "hi", timestamp: 1 }],
+    },
+    "none",
+  );
+  assert.equal(options.toolChoice, "none");
+});
+
+test("openai-completions: 带工具请求 any 映射为 required", async () => {
+  const options = await streamOnce(
+    {
+      tools: [echoTool],
+      messages: [{ role: "user", content: "hi", timestamp: 1 }],
+    },
+    "any",
+  );
+  assert.equal(options.toolChoice, "required");
+});

From 53e3507f19941cac03325dae2aff990ab5b74338 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 10:50:04 +0800
Subject: [PATCH 2/7] fix(providers): restore adaptive thinking for decorated
 anthropic model ids
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since ee8dba1 anthropic adaptive-thinking dispatch relies solely on the
catalog's compat.forceAdaptiveThinking, so any model id that misses the
exact catalog match (date suffixes, case variants, relay renames like
claude-4.6-sonnet) degraded to budget mode: requests carried the removed
budget_tokens field with no output_config.effort, which 4.7+/Fable-class
endpoints reject with 400 and relays silently strip — the user's thinking
level selection had no effect ("always Medium" reports).

Fix in modelFactory with two fallbacks, both written onto the model object
because pi-ai's raw stream() dispatches adaptive-vs-budget from
model.compat as well:

- Normalized catalog lookup (lowercase, strip @version, strip -YYYYMMDD)
  inherits full catalog metadata while keeping the user-configured id in
  the request body.
- For ids the catalog still misses, restore the pre-refactor family
  heuristics (plus reversed naming like claude-4.6-sonnet/claude-5-sonnet,
  with a lookbehind so claude-3-5-sonnet stays budget) to set
  compat.forceAdaptiveThinking and the xhigh/max thinkingLevelMap tiers.

Mirror the same resolution into the web settings module so the WebUI level
dropdown matches what the desktop actually sends. Add wire-level regression
tests capturing the real pi-ai anthropic payload per level.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../test/webui/web-settings.test.mjs          |  41 +++++
 .../web/src/lib/settings/index.ts             |  94 ++++++++++-
 .../src/lib/providers/runtime/modelFactory.ts |  94 ++++++++++-
 .../model-factory-anthropic.test.mjs          | 146 ++++++++++++++++++
 4 files changed, 368 insertions(+), 7 deletions(-)
 create mode 100644 crates/agent-gui/test/providers/model-factory-anthropic.test.mjs

diff --git a/crates/agent-gateway/test/webui/web-settings.test.mjs b/crates/agent-gateway/test/webui/web-settings.test.mjs
index 0dac60d4e..7b8531713 100644
--- a/crates/agent-gateway/test/webui/web-settings.test.mjs
+++ b/crates/agent-gateway/test/webui/web-settings.test.mjs
@@ -205,6 +205,47 @@ test("web chat runtime controls default and follow model-aware reasoning support
   assert.equal(settings.isThinkingAlwaysOnForModel("claude_code", "claude-opus-4-8"), false);
   assert.equal(settings.isThinkingAlwaysOnForModel("claude_code", undefined), false);
 
+  // 中转装饰过的 Anthropic id（日期后缀/大小写/@版本）按规范化后的目录条目解析，
+  // xhigh/max 档位与"思考不可关"语义不丢失；与桌面端 modelFactory 同步。
+  assert.deepEqual(
+    settings.getChatRuntimeReasoningLevelsForProvider({
+      providerId: "claude_code",
+      modelId: "claude-opus-4-8-20260213",
+    }),
+    ["minimal", "low", "medium", "high", "xhigh", "max"],
+  );
+  assert.deepEqual(
+    settings.getChatRuntimeReasoningLevelsForProvider({
+      providerId: "claude_code",
+      modelId: "claude-sonnet-4-6-20251114",
+    }),
+    ["minimal", "low", "medium", "high", "max"],
+  );
+  assert.equal(settings.isThinkingAlwaysOnForModel("claude_code", "Claude-Fable-5"), true);
+  // 目录彻底未命中的三方改名 id 走 id 启发式补 xhigh/max。
+  assert.deepEqual(
+    settings.getChatRuntimeReasoningLevelsForProvider({
+      providerId: "claude_code",
+      modelId: "claude-4.6-sonnet",
+    }),
+    ["minimal", "low", "medium", "high", "max"],
+  );
+  assert.deepEqual(
+    settings.getChatRuntimeReasoningLevelsForProvider({
+      providerId: "claude_code",
+      modelId: "claude-5-sonnet",
+    }),
+    ["minimal", "low", "medium", "high", "xhigh", "max"],
+  );
+  // 旧世代 id 不误判。
+  assert.deepEqual(
+    settings.getChatRuntimeReasoningLevelsForProvider({
+      providerId: "claude_code",
+      modelId: "claude-3-5-sonnet-20241022",
+    }),
+    ["minimal", "low", "medium", "high"],
+  );
+
   assert.deepEqual(
     settings.normalizeChatRuntimeControlsForProvider(
       {
diff --git a/crates/agent-gateway/web/src/lib/settings/index.ts b/crates/agent-gateway/web/src/lib/settings/index.ts
index 953c8b20d..532f84876 100644
--- a/crates/agent-gateway/web/src/lib/settings/index.ts
+++ b/crates/agent-gateway/web/src/lib/settings/index.ts
@@ -927,6 +927,81 @@ function findKnownModel(providerId: ProviderId, modelId: string | undefined) {
   return getBuiltinModels(toKnownProvider(providerId)).find((model) => model.id === trimmedId);
 }
 
+// —— 以下 Anthropic id 规范化与启发式与桌面端 modelFactory.ts 手动保持同步 ——
+// 中转/网关常给官方 Anthropic 模型 id 加装饰（日期后缀、@版本、大小写变化），
+// 逐字匹配漏检后档位列表会塌缩、丢掉 xhigh/max，与桌面端实际发送的档位脱节。
+function normalizeAnthropicModelIdCandidates(modelId: string): string[] {
+  const candidates: string[] = [];
+  const push = (value: string) => {
+    if (value && !candidates.includes(value)) candidates.push(value);
+  };
+  push(modelId);
+  const lower = modelId.toLowerCase();
+  push(lower);
+  const withoutAtVersion = lower.split("@")[0];
+  push(withoutAtVersion);
+  push(withoutAtVersion.replace(/-20\d{6}$/, ""));
+  return candidates;
+}
+
+function findKnownAnthropicModel(modelId: string) {
+  const models = getBuiltinModels("anthropic");
+  for (const candidate of normalizeAnthropicModelIdCandidates(modelId)) {
+    const known = models.find((model) => model.id === candidate);
+    if (known) return known;
+  }
+  return undefined;
+}
+
+function findKnownModelForThinking(providerId: ProviderId, modelId: string) {
+  return toKnownProvider(providerId) === "anthropic"
+    ? findKnownAnthropicModel(modelId)
+    : findKnownModel(providerId, modelId);
+}
+
+function isClaudeFamilyVersionAtLeast(
+  normalizedModelId: string,
+  family: "opus" | "sonnet",
+  minimumMinor: number,
+) {
+  // minor 限定 1-2 位数字，避免把日期后缀（如 claude-sonnet-4-20250514）误读成小版本号；
+  // 同时接受三方中转的倒序命名（claude-4.6-sonnet）。
+  const match = normalizedModelId.match(
+    new RegExp(`(?:${family}[-.]4[-.](\\d{1,2})(?!\\d)|4[-.](\\d{1,2})(?!\\d)[-.]${family})`),
+  );
+  if (!match) return false;
+  const minor = Number(match[1] ?? match[2]);
+  return Number.isFinite(minor) && minor >= minimumMinor;
+}
+
+// Claude 5 起（sonnet-5 / fable-5 / mythos-5 等）整个家族都是 adaptive thinking 且支持 xhigh。
+// 倒序写法（claude-5-sonnet）用负向后行断言排除 3-5-sonnet 这类旧世代小版本号。
+function isClaudeFamilyMajorVersionAtLeast(normalizedModelId: string, minimumMajor: number) {
+  const match = normalizedModelId.match(
+    /(?:(?:opus|sonnet|haiku|fable|mythos)[-.](\d{1,2})(?!\d)|(?<!\d[-.])(\d{1,2})[-.](?:opus|sonnet|haiku|fable|mythos))/,
+  );
+  if (!match) return false;
+  const major = Number(match[1] ?? match[2]);
+  return Number.isFinite(major) && major >= minimumMajor;
+}
+
+// 目录彻底未命中的三方改名 id（如 claude-4.6-sonnet）退回 id 启发式，推断
+// xhigh/max 档位声明；与桌面端 deriveAnthropicThinkingOverridesForCustomModel 同步。
+function deriveAnthropicThinkingLevelMapForCustomModel(
+  modelId: string,
+): Record<string, string> | undefined {
+  const id = modelId.trim().toLowerCase();
+  const adaptive =
+    id.includes("mythos-preview") ||
+    isClaudeFamilyVersionAtLeast(id, "opus", 6) ||
+    isClaudeFamilyVersionAtLeast(id, "sonnet", 6) ||
+    isClaudeFamilyMajorVersionAtLeast(id, 5);
+  if (!adaptive) return undefined;
+  const supportsXHigh =
+    isClaudeFamilyVersionAtLeast(id, "opus", 7) || isClaudeFamilyMajorVersionAtLeast(id, 5);
+  return supportsXHigh ? { xhigh: "xhigh", max: "max" } : { max: "max" };
+}
+
 function getKnownModelLimits(
   providerId: ProviderId,
   modelId: string | undefined,
@@ -942,17 +1017,22 @@ export function getKnownModelThinkingLevels(
 ): ReasoningLevel[] {
   const trimmedId = modelId?.trim();
   if (!trimmedId) return [];
-  const known = findKnownModel(providerId, trimmedId);
+  const known = findKnownModelForThinking(providerId, trimmedId);
   // 目录之外的自定义模型（deepseek/glm 等三方聚合）无法从 id 判断推理能力，
   // 与桌面端 modelFactory 自定义分支一致按可推理处理：标准档位，xhigh/max
-  // 仍需目录 opt-in；deepseek 走 codex 时镜像桌面端 DeepSeek 适配层的 xhigh 档。
+  // 仍需目录 opt-in；deepseek 走 codex 时镜像桌面端 DeepSeek 适配层的 xhigh 档，
+  // claude_code 走桌面端同款 id 启发式补 xhigh/max。
+  const customThinkingLevelMap =
+    providerId === "codex" && trimmedId.toLowerCase().includes("deepseek")
+      ? { xhigh: "max" }
+      : toKnownProvider(providerId) === "anthropic"
+        ? deriveAnthropicThinkingLevelMapForCustomModel(trimmedId)
+        : undefined;
   const model =
     known ??
     ({
       reasoning: true,
-      ...(providerId === "codex" && trimmedId.toLowerCase().includes("deepseek")
-        ? { thinkingLevelMap: { xhigh: "max" } }
-        : {}),
+      ...(customThinkingLevelMap ? { thinkingLevelMap: customThinkingLevelMap } : {}),
     } as Parameters<typeof getSupportedThinkingLevels>[0]);
   return getSupportedThinkingLevels(model).filter((level) => level !== "off");
 }
@@ -961,7 +1041,9 @@ export function isThinkingAlwaysOnForModel(
   providerId: ProviderId,
   modelId: string | undefined,
 ): boolean {
-  const known = findKnownModel(providerId, modelId);
+  const trimmedId = modelId?.trim();
+  if (!trimmedId) return false;
+  const known = findKnownModelForThinking(providerId, trimmedId);
   return known ? !getSupportedThinkingLevels(known).includes("off") : false;
 }
 
diff --git a/crates/agent-gui/src/lib/providers/runtime/modelFactory.ts b/crates/agent-gui/src/lib/providers/runtime/modelFactory.ts
index bb0850113..b9ec0241d 100644
--- a/crates/agent-gui/src/lib/providers/runtime/modelFactory.ts
+++ b/crates/agent-gui/src/lib/providers/runtime/modelFactory.ts
@@ -28,6 +28,93 @@ function resolveKnownModel(
   return known?.api ? ({ ...known, baseUrl } as Model<any>) : undefined;
 }
 
+// ---------------------------------------------------------------------------
+// Anthropic 目录回查与自定义模型思考能力推断
+// ---------------------------------------------------------------------------
+
+// 中转/网关常给官方 Anthropic 模型 id 加装饰（日期后缀、@版本、大小写变化），逐字
+// 匹配会漏检；漏检后模型丢失 compat.forceAdaptiveThinking，思考配置退化成 4.7+/
+// Fable 世代已删除的 budget_tokens（官方端点 400、中转剥字段后档位彻底失效）。
+// 先精确查，再按规范化候选回查目录；命中则继承完整目录元数据，但保留用户配置的
+// 原始 id——请求体里的 model 字段必须是端点认识的字符串。
+function normalizeAnthropicModelIdCandidates(modelId: string): string[] {
+  const candidates: string[] = [];
+  const push = (value: string) => {
+    if (value && !candidates.includes(value)) candidates.push(value);
+  };
+  push(modelId);
+  const lower = modelId.toLowerCase();
+  push(lower);
+  const withoutAtVersion = lower.split("@")[0];
+  push(withoutAtVersion);
+  push(withoutAtVersion.replace(/-20\d{6}$/, ""));
+  return candidates;
+}
+
+function resolveKnownAnthropicModel(modelId: string, baseUrl: string): Model<any> | undefined {
+  for (const candidate of normalizeAnthropicModelIdCandidates(modelId)) {
+    const known = resolveKnownModel("anthropic", candidate, baseUrl);
+    if (known) {
+      return { ...known, id: modelId, name: modelId } as Model<any>;
+    }
+  }
+  return undefined;
+}
+
+function isAnthropicMythosPreview(normalizedModelId: string) {
+  return normalizedModelId.includes("mythos-preview");
+}
+
+function isClaudeFamilyVersionAtLeast(
+  normalizedModelId: string,
+  family: "opus" | "sonnet",
+  minimumMinor: number,
+) {
+  // minor 限定 1-2 位数字，避免把日期后缀（如 claude-sonnet-4-20250514）误读成小版本号；
+  // 同时接受三方中转的倒序命名（claude-4.6-sonnet）。
+  const match = normalizedModelId.match(
+    new RegExp(`(?:${family}[-.]4[-.](\\d{1,2})(?!\\d)|4[-.](\\d{1,2})(?!\\d)[-.]${family})`),
+  );
+  if (!match) return false;
+  const minor = Number(match[1] ?? match[2]);
+  return Number.isFinite(minor) && minor >= minimumMinor;
+}
+
+// Claude 5 起（sonnet-5 / fable-5 / mythos-5 等）整个家族都是 adaptive thinking 且支持 xhigh。
+// 倒序写法（claude-5-sonnet）用负向后行断言排除 3-5-sonnet 这类旧世代小版本号。
+function isClaudeFamilyMajorVersionAtLeast(normalizedModelId: string, minimumMajor: number) {
+  const match = normalizedModelId.match(
+    /(?:(?:opus|sonnet|haiku|fable|mythos)[-.](\d{1,2})(?!\d)|(?<!\d[-.])(\d{1,2})[-.](?:opus|sonnet|haiku|fable|mythos))/,
+  );
+  if (!match) return false;
+  const major = Number(match[1] ?? match[2]);
+  return Number.isFinite(major) && major >= minimumMajor;
+}
+
+// 目录彻底未命中的三方改名 id（如 claude-4.6-sonnet）退回 ee8dba1 之前的 id 启发式：
+// 能识别为 adaptive 家族的补上 compat.forceAdaptiveThinking 与 xhigh/max 档位声明，
+// pi-ai stream() 与本地 thinkingLevels.ts 都以模型对象上的这两个字段为准。
+export function deriveAnthropicThinkingOverridesForCustomModel(modelId: string): {
+  compat?: Model<"anthropic-messages">["compat"];
+  thinkingLevelMap?: Model<"anthropic-messages">["thinkingLevelMap"];
+} {
+  const id = modelId.trim().toLowerCase();
+  const adaptive =
+    isAnthropicMythosPreview(id) ||
+    isClaudeFamilyVersionAtLeast(id, "opus", 6) ||
+    isClaudeFamilyVersionAtLeast(id, "sonnet", 6) ||
+    isClaudeFamilyMajorVersionAtLeast(id, 5);
+  if (!adaptive) return {};
+
+  // xhigh：Opus 4.7+ 与 Claude 5 家族；Mythos Preview / Opus 4.6 / Sonnet 4.6 只到 max。
+  const supportsXHigh =
+    isClaudeFamilyVersionAtLeast(id, "opus", 7) || isClaudeFamilyMajorVersionAtLeast(id, 5);
+  return {
+    compat: { forceAdaptiveThinking: true },
+    thinkingLevelMap: supportsXHigh ? { xhigh: "xhigh", max: "max" } : { max: "max" },
+  };
+}
+
 function maybeAppendGeminiApiVersion(baseUrl: string) {
   try {
     const url = new URL(baseUrl);
@@ -325,7 +412,7 @@ export function createModelFromConfig(
     return custom;
   }
 
-  const known = resolveKnownModel("anthropic", modelId, baseUrl);
+  const known = resolveKnownAnthropicModel(modelId, baseUrl);
   if (known) {
     return applyDeepSeekModelDefaults(
       {
@@ -342,6 +429,7 @@ export function createModelFromConfig(
     );
   }
 
+  const thinkingOverrides = deriveAnthropicThinkingOverridesForCustomModel(modelId);
   const custom: Model<"anthropic-messages"> = {
     id: modelId,
     name: modelId,
@@ -353,6 +441,10 @@ export function createModelFromConfig(
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow,
     maxTokens,
+    ...(thinkingOverrides.compat ? { compat: thinkingOverrides.compat } : {}),
+    ...(thinkingOverrides.thinkingLevelMap
+      ? { thinkingLevelMap: thinkingOverrides.thinkingLevelMap }
+      : {}),
   };
   return applyDeepSeekModelDefaults(custom, {
     providerId,
diff --git a/crates/agent-gui/test/providers/model-factory-anthropic.test.mjs b/crates/agent-gui/test/providers/model-factory-anthropic.test.mjs
new file mode 100644
index 000000000..c8181212d
--- /dev/null
+++ b/crates/agent-gui/test/providers/model-factory-anthropic.test.mjs
@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createTsModuleLoader } from "../helpers/load-ts-module.mjs";
+
+// 走真实 pi-ai anthropic stream()，用 onPayload 截获请求体后中断，
+// 断言的是最终线格式（thinking/output_config），不是中间结构。
+const realAnthropic = await import(
+  new URL(
+    "../../node_modules/@earendil-works/pi-ai/dist/api/anthropic-messages.js",
+    import.meta.url,
+  ).href
+);
+
+const loader = createTsModuleLoader({
+  mocks: {
+    "@earendil-works/pi-ai/api/anthropic-messages": { stream: realAnthropic.stream },
+  },
+});
+
+const { createModelFromConfig, getAvailableThinkingLevelsForModel } = loader.loadModule(
+  "src/lib/providers/runtime/modelFactory.ts",
+);
+const { streamSimpleByApi } = loader.loadModule("src/lib/providers/runtime/streamByApi.ts");
+
+const RELAY_BASE_URL = "https://relay.example.com/v1";
+
+function levelsFor(modelId) {
+  return getAvailableThinkingLevelsForModel("claude_code", modelId, RELAY_BASE_URL);
+}
+
+async function captureWirePayload(modelId, reasoning) {
+  const model = createModelFromConfig("claude_code", modelId, RELAY_BASE_URL);
+  let captured;
+  const stream = streamSimpleByApi(
+    model,
+    { messages: [{ role: "user", content: "hi", timestamp: 1 }] },
+    {
+      apiKey: "sk-test",
+      reasoning,
+      onPayload: (payload) => {
+        captured = payload;
+        throw new Error("__capture_stop__");
+      },
+    },
+  );
+  try {
+    await stream.result();
+  } catch {
+    // onPayload 抛错中断请求属预期。
+  }
+  assert.ok(captured, `expected payload capture for ${modelId}`);
+  return captured;
+}
+
+test("anthropic: 装饰过的目录模型 id（日期后缀/大小写/@版本）继承目录 adaptive 元数据", () => {
+  for (const [modelId, baseId] of [
+    ["claude-opus-4-8-20260213", "claude-opus-4-8"],
+    ["Claude-Fable-5", "claude-fable-5"],
+    ["claude-sonnet-4-6-20251114", "claude-sonnet-4-6"],
+    ["claude-opus-4-5@20251101", "claude-opus-4-5"],
+  ]) {
+    const model = createModelFromConfig("claude_code", modelId, RELAY_BASE_URL);
+    const base = createModelFromConfig("claude_code", baseId, "https://api.anthropic.com");
+    // 请求体 model 字段必须保留用户配置的原始 id。
+    assert.equal(model.id, modelId);
+    assert.equal(model.baseUrl, RELAY_BASE_URL);
+    assert.equal(
+      model.compat?.forceAdaptiveThinking,
+      base.compat?.forceAdaptiveThinking,
+      `${modelId} should inherit adaptive flag from ${baseId}`,
+    );
+    assert.deepEqual(model.thinkingLevelMap, base.thinkingLevelMap);
+  }
+});
+
+test("anthropic: 装饰 id 的可选档位与目录基础模型一致（xhigh/max 不丢失）", () => {
+  assert.deepEqual(levelsFor("claude-opus-4-8-20260213"), [
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+  ]);
+  assert.deepEqual(levelsFor("claude-sonnet-4-6-20251114"), [
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "max",
+  ]);
+});
+
+test("anthropic: 目录未命中的三方改名 id 走启发式识别 adaptive 家族", () => {
+  // Opus 4.7+/Claude 5 家族：xhigh 直通。
+  for (const modelId of ["claude-4.7-opus", "claude-5-sonnet", "custom-fable-5-relay"]) {
+    const model = createModelFromConfig("claude_code", modelId, RELAY_BASE_URL);
+    assert.equal(model.compat?.forceAdaptiveThinking, true, `${modelId} should be adaptive`);
+    assert.deepEqual(model.thinkingLevelMap, { xhigh: "xhigh", max: "max" });
+  }
+  // Opus 4.6/Sonnet 4.6/Mythos Preview：只到 max。
+  for (const modelId of ["claude-4.6-sonnet", "claude-mythos-preview"]) {
+    const model = createModelFromConfig("claude_code", modelId, RELAY_BASE_URL);
+    assert.equal(model.compat?.forceAdaptiveThinking, true, `${modelId} should be adaptive`);
+    assert.deepEqual(model.thinkingLevelMap, { max: "max" });
+  }
+});
+
+test("anthropic: 旧世代/歧义 id 不误判为 adaptive，保持 budget 语义", () => {
+  for (const modelId of [
+    "claude-3-5-sonnet-20241022",
+    "claude-3-7-sonnet-20250219",
+    "claude-4-5-sonnet",
+    "claude-sonnet-4-5-x",
+    "claude-3-haiku-20240307",
+  ]) {
+    const model = createModelFromConfig("claude_code", modelId, RELAY_BASE_URL);
+    assert.notEqual(
+      model.compat?.forceAdaptiveThinking,
+      true,
+      `${modelId} must stay budget-mode`,
+    );
+  }
+});
+
+test("anthropic wire: 装饰 id 发送 adaptive + output_config.effort，档位随选择变化", async () => {
+  const high = await captureWirePayload("claude-opus-4-8-20260213", "high");
+  assert.equal(high.thinking?.type, "adaptive");
+  assert.equal(high.output_config?.effort, "high");
+  assert.equal(high.model, "claude-opus-4-8-20260213");
+
+  const max = await captureWirePayload("claude-opus-4-8-20260213", "max");
+  assert.equal(max.output_config?.effort, "max");
+
+  const low = await captureWirePayload("claude-4.7-opus", "low");
+  assert.equal(low.thinking?.type, "adaptive");
+  assert.equal(low.output_config?.effort, "low");
+});
+
+test("anthropic wire: 旧世代 id 仍发送 budget_tokens 且不带 output_config", async () => {
+  const payload = await captureWirePayload("claude-3-7-sonnet-20250219", "high");
+  assert.equal(payload.thinking?.type, "enabled");
+  assert.equal(payload.thinking?.budget_tokens, 16_384);
+  assert.equal(payload.output_config, undefined);
+});

From 666503c02c9f1fd176355630bbd2cb5a0e987be3 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 11:26:55 +0800
Subject: [PATCH 3/7] fix(skills): make ClawHub installs reliable

Resolve publisher-scoped ClawHub downloads and preserve source identity metadata.

Normalize compatible legacy skill names and show install preparation progress immediately in GUI and WebUI.
---
 .../web/src/lib/skills/clawHub.ts             | 117 ++++++++-
 .../agent-gateway/web/src/lib/skills/index.ts |   5 +
 .../src/pages/skills-hub/SkillsHubPage.tsx    | 242 +++++++++++++-----
 .../src-tauri/src/services/skills/clawhub.rs  |  38 +--
 .../src-tauri/src/services/skills/install.rs  | 153 ++++++++++-
 .../src-tauri/src/services/skills/jobs.rs     |   6 +
 .../src-tauri/src/services/skills/library.rs  |  12 +
 .../src-tauri/src/services/skills/tests.rs    | 132 ++++++++--
 .../src-tauri/src/services/skills/types.rs    |   5 +
 crates/agent-gui/src/lib/skills/clawHub.ts    | 117 ++++++++-
 crates/agent-gui/src/lib/skills/index.ts      |   5 +
 .../src/pages/skills-hub/SkillsHubPage.tsx    | 242 +++++++++++++-----
 .../test/skills/clawhub-contract.test.mjs     |  74 ++++++
 .../skills-store-install-feedback.test.mjs    |  59 +++++
 docs/features/skills-and-mcp.md               |  12 +-
 15 files changed, 1012 insertions(+), 207 deletions(-)
 create mode 100644 crates/agent-gui/test/skills/clawhub-contract.test.mjs
 create mode 100644 crates/agent-gui/test/skills/skills-store-install-feedback.test.mjs

diff --git a/crates/agent-gateway/web/src/lib/skills/clawHub.ts b/crates/agent-gateway/web/src/lib/skills/clawHub.ts
index 4d11599b9..592e7deef 100644
--- a/crates/agent-gateway/web/src/lib/skills/clawHub.ts
+++ b/crates/agent-gateway/web/src/lib/skills/clawHub.ts
@@ -43,10 +43,6 @@ function asString(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function asNumber(value: unknown): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-
 function asNullableNumber(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
@@ -62,7 +58,13 @@ function buildClawHubWebUrl(ownerHandle: string | null, slug: string) {
   return `${CLAWHUB_API_BASE}/${encodeURIComponent(ownerHandle)}/${encodeURIComponent(slug)}`;
 }
 
-function normalizeSkillCard(raw: unknown): ClawHubSkillCard | null {
+export function buildClawHubSkillKey(skill: Pick<ClawHubSkillCard, "slug" | "ownerHandle">) {
+  const slug = skill.slug.trim().toLowerCase();
+  const ownerHandle = skill.ownerHandle?.trim().replace(/^@+/, "").toLowerCase();
+  return `clawhub:${ownerHandle || "?"}/${slug}`;
+}
+
+export function normalizeClawHubSkillCard(raw: unknown): ClawHubSkillCard | null {
   const item = asRecord(raw);
   const slug = asString(item.slug);
   if (!slug) return null;
@@ -78,9 +80,14 @@ function normalizeSkillCard(raw: unknown): ClawHubSkillCard | null {
     summary: asString(item.summary) ?? "",
     latestVersion:
       asString(latestVersion.version) ?? asString(tags.latest) ?? asString(item.version),
-    downloads: asNumber(stats.downloads),
-    stars: asNumber(stats.stars),
-    installsCurrent: asNumber(stats.installsCurrent),
+    downloads: asNullableNumber(item.downloads) ?? asNullableNumber(stats.downloads) ?? 0,
+    stars: asNullableNumber(item.stars) ?? asNullableNumber(stats.stars) ?? 0,
+    installsCurrent:
+      asNullableNumber(item.installsCurrent) ??
+      asNullableNumber(item.installs) ??
+      asNullableNumber(stats.installsCurrent) ??
+      asNullableNumber(stats.installs) ??
+      0,
     updatedAt: asNullableNumber(item.updatedAt),
     ownerHandle,
     webUrl: asString(item.webUrl) ?? buildClawHubWebUrl(ownerHandle, slug),
@@ -96,7 +103,7 @@ function normalizeSkillDetail(raw: unknown): ClawHubSkillDetail | null {
   const owner = asRecord(payload.owner ?? item.owner);
   const metadata = asRecord(payload.metadata ?? item.metadata);
   const moderation = asRecord(payload.moderation ?? item.moderation);
-  const card = normalizeSkillCard({
+  const card = normalizeClawHubSkillCard({
     ...item,
     latestVersion,
     owner,
@@ -118,14 +125,28 @@ function normalizeSkillDetail(raw: unknown): ClawHubSkillDetail | null {
   };
 }
 
+export class ClawHubHttpError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(status: number, body: string) {
+    const detail = body.trim();
+    super(`ClawHub request failed with HTTP ${status}${detail ? `: ${detail}` : ""}`);
+    this.name = "ClawHubHttpError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
 async function fetchClawHubJson(url: URL): Promise<unknown> {
   const response = await fetch(url.toString(), {
     headers: { Accept: "application/json" },
   });
+  const body = await response.text();
   if (!response.ok) {
-    throw new Error(`ClawHub request failed with HTTP ${response.status}`);
+    throw new ClawHubHttpError(response.status, body);
   }
-  return response.json();
+  return JSON.parse(body) as unknown;
 }
 
 export async function listClawHubSkills(params: {
@@ -143,7 +164,9 @@ export async function listClawHubSkills(params: {
 
   const json = asRecord(await fetchClawHubJson(url));
   const items = Array.isArray(json.items)
-    ? json.items.map(normalizeSkillCard).filter((item): item is ClawHubSkillCard => Boolean(item))
+    ? json.items
+        .map(normalizeClawHubSkillCard)
+        .filter((item): item is ClawHubSkillCard => Boolean(item))
     : [];
   return {
     items,
@@ -162,10 +185,78 @@ export async function searchClawHubSkills(params: {
 
   const json = asRecord(await fetchClawHubJson(url));
   return Array.isArray(json.results)
-    ? json.results.map(normalizeSkillCard).filter((item): item is ClawHubSkillCard => Boolean(item))
+    ? json.results
+        .map(normalizeClawHubSkillCard)
+        .filter((item): item is ClawHubSkillCard => Boolean(item))
     : [];
 }
 
+function narrowOwnerCandidates(
+  candidates: ClawHubSkillCard[],
+  predicate: (candidate: ClawHubSkillCard) => boolean,
+) {
+  const narrowed = candidates.filter(predicate);
+  return narrowed.length > 0 ? narrowed : candidates;
+}
+
+export function selectClawHubOwnerCandidate(
+  skill: ClawHubSkillCard,
+  candidates: ClawHubSkillCard[],
+): ClawHubSkillCard | null {
+  let exact = candidates.filter(
+    (candidate) =>
+      candidate.slug.toLowerCase() === skill.slug.toLowerCase() && Boolean(candidate.ownerHandle),
+  );
+  if (exact.length === 1) return exact[0];
+  if (exact.length === 0) return null;
+
+  if (skill.updatedAt !== null) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.updatedAt === skill.updatedAt);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.latestVersion) {
+    exact = narrowOwnerCandidates(
+      exact,
+      (candidate) => candidate.latestVersion === skill.latestVersion,
+    );
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.downloads > 0) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.downloads === skill.downloads);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.summary) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.summary === skill.summary);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.displayName) {
+    exact = narrowOwnerCandidates(
+      exact,
+      (candidate) => candidate.displayName === skill.displayName,
+    );
+  }
+  return exact.length === 1 ? exact[0] : null;
+}
+
+export async function resolveClawHubSkillOwner(skill: ClawHubSkillCard): Promise<ClawHubSkillCard> {
+  if (skill.ownerHandle) return skill;
+
+  const candidates = await searchClawHubSkills({ query: skill.slug, limit: 50 });
+  const resolved = selectClawHubOwnerCandidate(skill, candidates);
+  if (!resolved?.ownerHandle) {
+    throw new Error(
+      `ClawHub skill "${skill.slug}" has multiple publishers, but the catalog item does not identify one`,
+    );
+  }
+
+  return {
+    ...skill,
+    ownerHandle: resolved.ownerHandle,
+    webUrl: resolved.webUrl ?? buildClawHubWebUrl(resolved.ownerHandle, skill.slug),
+    downloadUrl: buildClawHubDownloadUrl(skill.slug, resolved.ownerHandle),
+  };
+}
+
 export async function getClawHubSkillDetail(
   slug: string,
   ownerHandle?: string | null,
diff --git a/crates/agent-gateway/web/src/lib/skills/index.ts b/crates/agent-gateway/web/src/lib/skills/index.ts
index fa6ff5c86..78651a6e3 100644
--- a/crates/agent-gateway/web/src/lib/skills/index.ts
+++ b/crates/agent-gateway/web/src/lib/skills/index.ts
@@ -33,8 +33,12 @@ export type SkillSummary = {
 export type SkillSourceMetadata = {
   registry: string;
   slug: string;
+  ownerHandle?: string | null;
   version?: string | null;
   publishedAt?: number | null;
+  originalName?: string | null;
+  normalizedName?: string | null;
+  compatibilityTransform?: string | null;
 };
 
 export type SkillDiscovery = {
@@ -93,6 +97,7 @@ export type SkillInstallJobSnapshot = {
   source: string;
   label?: string | null;
   slug?: string | null;
+  ownerHandle?: string | null;
   version?: string | null;
   downloadedBytes: number;
   totalBytes?: number | null;
diff --git a/crates/agent-gateway/web/src/pages/skills-hub/SkillsHubPage.tsx b/crates/agent-gateway/web/src/pages/skills-hub/SkillsHubPage.tsx
index 16193bd8e..00ece7e94 100644
--- a/crates/agent-gateway/web/src/pages/skills-hub/SkillsHubPage.tsx
+++ b/crates/agent-gateway/web/src/pages/skills-hub/SkillsHubPage.tsx
@@ -46,11 +46,13 @@ import {
 } from "../../lib/skills";
 import {
   buildClawHubDownloadUrl,
+  buildClawHubSkillKey,
   type ClawHubSkillCard,
   type ClawHubSkillDetail,
   type ClawHubSort,
   getClawHubSkillDetail,
   listClawHubSkills,
+  resolveClawHubSkillOwner,
   searchClawHubSkills,
 } from "../../lib/skills/clawHub";
 
@@ -76,6 +78,7 @@ const STORE_SORT_OPTIONS: Array<{ value: ClawHubSort; labelKey: string }> = [
 type StoreSkillInstallState = {
   done: boolean;
   installing: boolean;
+  pending: boolean;
   terminalJob: boolean;
   job: SkillInstallJobSnapshot | undefined;
   progress: number | null;
@@ -330,7 +333,11 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
   const [storeLoadingMore, setStoreLoadingMore] = useState(false);
   const [storeError, setStoreError] = useState<string | null>(null);
   const [installJobs, setInstallJobs] = useState<Record<string, SkillInstallJobSnapshot>>({});
-  const [installingBySlug, setInstallingBySlug] = useState<Record<string, string>>({});
+  const [installingByStoreKey, setInstallingByStoreKey] = useState<Record<string, string>>({});
+  const [pendingInstallKeys, setPendingInstallKeys] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+  const pendingInstallTokensRef = useRef(new Map<string, symbol>());
   const [deletingSkillName, setDeletingSkillName] = useState<string | null>(null);
   const [externalScans, setExternalScans] = useState<ExternalToolScan[] | null>(null);
   const [externalLoading, setExternalLoading] = useState(false);
@@ -548,37 +555,58 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
     };
   }, [previewInstalledSkill, t]);
 
-  const installedBySlug = useMemo(() => {
+  const installedStoreState = useMemo(() => {
     const installed = new Map<string, SkillSummary>();
+    const slugs = new Set<string>();
     for (const skill of skills) {
       if (skill.source?.registry !== "clawhub") continue;
       const slug = skill.source.slug?.trim();
-      if (slug) installed.set(slug, skill);
+      if (!slug) continue;
+      slugs.add(slug);
+      installed.set(
+        buildClawHubSkillKey({ slug, ownerHandle: skill.source.ownerHandle ?? null }),
+        skill,
+      );
     }
-    return installed;
+    return { installed, slugs };
   }, [skills]);
-  const completedInstallSlugs = useMemo(() => {
+  const completedInstallState = useMemo(() => {
+    const keys = new Set<string>();
     const slugs = new Set<string>();
-    for (const [slug, jobId] of Object.entries(installingBySlug)) {
+    for (const [storeKey, jobId] of Object.entries(installingByStoreKey)) {
       const job = installJobs[jobId];
-      if (job?.phase === "done" && slug.trim()) {
-        slugs.add(slug.trim());
+      if (job?.phase === "done") {
+        keys.add(storeKey);
+        if (job.slug?.trim()) slugs.add(job.slug.trim());
       }
     }
     for (const job of Object.values(installJobs)) {
       if (job.phase === "done" && job.slug?.trim()) {
         slugs.add(job.slug.trim());
+        keys.add(
+          buildClawHubSkillKey({
+            slug: job.slug.trim(),
+            ownerHandle: job.ownerHandle ?? null,
+          }),
+        );
       }
     }
-    return slugs;
-  }, [installJobs, installingBySlug]);
+    return { keys, slugs };
+  }, [installJobs, installingByStoreKey]);
+  const installedStoreKeys = useMemo(() => {
+    const keys = new Set(installedStoreState.installed.keys());
+    for (const key of completedInstallState.keys) {
+      keys.add(key);
+    }
+    return keys;
+  }, [completedInstallState.keys, installedStoreState.installed]);
   const installedStoreSlugs = useMemo(() => {
-    const slugs = new Set(installedBySlug.keys());
-    for (const slug of completedInstallSlugs) {
+    const slugs = new Set(installedStoreState.slugs);
+    for (const slug of completedInstallState.slugs) {
       slugs.add(slug);
     }
     return slugs;
-  }, [completedInstallSlugs, installedBySlug]);
+  }, [completedInstallState.slugs, installedStoreState.slugs]);
 
   useEffect(() => {
     if (view !== "store" || lockedByChatMode) return;
@@ -732,30 +760,76 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
   }
 
   async function installStoreSkill(skill: ClawHubSkillCard) {
-    const existingJobId = installingBySlug[skill.slug];
-    const existingJob = existingJobId ? installJobs[existingJobId] : undefined;
+    const initialStoreKey = buildClawHubSkillKey(skill);
+    const initialJobId = installingByStoreKey[initialStoreKey];
+    const initialJob = initialJobId ? installJobs[initialJobId] : undefined;
     if (
       lockedByChatMode ||
-      installedStoreSlugs.has(skill.slug) ||
-      (existingJob && !TERMINAL_INSTALL_PHASES.has(existingJob.phase))
+      pendingInstallTokensRef.current.has(initialStoreKey) ||
+      installedStoreKeys.has(initialStoreKey) ||
+      (!skill.ownerHandle && installedStoreSlugs.has(skill.slug)) ||
+      (initialJob && !TERMINAL_INSTALL_PHASES.has(initialJob.phase))
     ) {
       return;
     }
+
+    const pendingToken = Symbol(initialStoreKey);
+    pendingInstallTokensRef.current.set(initialStoreKey, pendingToken);
+    setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
     setStoreError(null);
     try {
+      const resolvedSkill = await resolveClawHubSkillOwner(skill);
+      const storeKey = buildClawHubSkillKey(resolvedSkill);
+      const activePendingToken = pendingInstallTokensRef.current.get(storeKey);
+      if (activePendingToken && activePendingToken !== pendingToken) return;
+      if (storeKey !== initialStoreKey) {
+        pendingInstallTokensRef.current.set(storeKey, pendingToken);
+        setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
+      }
+      setStoreItems((prev) =>
+        prev.map((item) =>
+          item.slug === resolvedSkill.slug &&
+          item.updatedAt === resolvedSkill.updatedAt &&
+          (!item.ownerHandle || item.ownerHandle === resolvedSkill.ownerHandle)
+            ? resolvedSkill
+            : item,
+        ),
+      );
+      const existingJobId = installingByStoreKey[storeKey];
+      const existingJob = existingJobId ? installJobs[existingJobId] : undefined;
+      if (
+        installedStoreKeys.has(storeKey) ||
+        (existingJob && !TERMINAL_INSTALL_PHASES.has(existingJob.phase))
+      ) {
+        return;
+      }
       const job = await startSkillInstallJob({
-        source: buildClawHubDownloadUrl(skill.slug, skill.ownerHandle),
-        label: skill.displayName,
-        slug: skill.slug,
-        ownerHandle: skill.ownerHandle,
-        version: skill.latestVersion,
+        source: buildClawHubDownloadUrl(resolvedSkill.slug, resolvedSkill.ownerHandle),
+        label: resolvedSkill.displayName,
+        slug: resolvedSkill.slug,
+        ownerHandle: resolvedSkill.ownerHandle,
+        version: resolvedSkill.latestVersion,
         conflict: "backup",
       });
       setInstallJobs((prev) => ({ ...prev, [job.jobId]: job }));
-      setInstallingBySlug((prev) => ({ ...prev, [skill.slug]: job.jobId }));
+      setInstallingByStoreKey((prev) => ({
+        ...prev,
+        [initialStoreKey]: job.jobId,
+        [storeKey]: job.jobId,
+      }));
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       setStoreError(msg || t("settings.skillsHubInstallFailed"));
+    } finally {
+      let changed = false;
+      for (const [storeKey, token] of pendingInstallTokensRef.current) {
+        if (token !== pendingToken) continue;
+        pendingInstallTokensRef.current.delete(storeKey);
+        changed = true;
+      }
+      if (changed) {
+        setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
+      }
     }
   }
 
@@ -763,6 +837,8 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
     if (lockedByChatMode || isAlwaysEnabledSkillName(skill.name) || deletingSkillName) return;
     const skillName = skill.name;
     const sourceSlug = skill.source?.registry === "clawhub" ? skill.source.slug?.trim() || "" : "";
+    const sourceOwnerHandle =
+      skill.source?.registry === "clawhub" ? skill.source.ownerHandle?.trim() || null : null;
     setLoadError(null);
     setDeletingSkillName(skillName);
     try {
@@ -775,17 +851,24 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
       setSkills((prev) => prev.filter((item) => item.name !== skillName));
       setPreviewInstalledSkill((current) => (current?.name === skillName ? null : current));
       if (sourceSlug) {
-        setInstallingBySlug((prev) => {
-          if (!(sourceSlug in prev)) return prev;
+        const sourceKey = buildClawHubSkillKey({
+          slug: sourceSlug,
+          ownerHandle: sourceOwnerHandle,
+        });
+        setInstallingByStoreKey((prev) => {
+          if (!(sourceKey in prev)) return prev;
           const next = { ...prev };
-          delete next[sourceSlug];
+          delete next[sourceKey];
           return next;
         });
         setInstallJobs((prev) => {
           let changed = false;
           const next = { ...prev };
           for (const [jobId, job] of Object.entries(prev)) {
-            if (job.slug?.trim() === sourceSlug) {
+            if (
+              job.slug?.trim() === sourceSlug &&
+              (!sourceOwnerHandle || job.ownerHandle?.trim() === sourceOwnerHandle)
+            ) {
               delete next[jobId];
               changed = true;
             }
@@ -1339,8 +1422,10 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
                       loadingMore={storeLoadingMore}
                       error={storeError}
                       cursor={storeCursor}
+                      installedKeys={installedStoreKeys}
                       installedSlugs={installedStoreSlugs}
-                      installingBySlug={installingBySlug}
+                      pendingInstallKeys={pendingInstallKeys}
+                      installingByStoreKey={installingByStoreKey}
                       installJobs={installJobs}
                       onSortChange={setStoreSort}
                       onLoadMore={() => void loadMoreStore()}
@@ -1925,8 +2010,10 @@ function SkillsStoreView(props: {
   loadingMore: boolean;
   error: string | null;
   cursor: string | null;
+  installedKeys: Set<string>;
   installedSlugs: Set<string>;
-  installingBySlug: Record<string, string>;
+  pendingInstallKeys: ReadonlySet<string>;
+  installingByStoreKey: Record<string, string>;
   installJobs: Record<string, SkillInstallJobSnapshot>;
   onSortChange: (value: ClawHubSort) => void;
   onLoadMore: () => void;
@@ -1940,8 +2027,10 @@ function SkillsStoreView(props: {
     loadingMore,
     error,
     cursor,
+    installedKeys,
     installedSlugs,
-    installingBySlug,
+    pendingInstallKeys,
+    installingByStoreKey,
     installJobs,
     onSortChange,
     onLoadMore,
@@ -1968,7 +2057,16 @@ function SkillsStoreView(props: {
     setPreviewError(null);
     setPreviewLoading(true);
 
-    void getClawHubSkillDetail(previewSkill.slug, previewSkill.ownerHandle)
+    void resolveClawHubSkillOwner(previewSkill)
+      .then((resolvedSkill) => {
+        if (
+          !cancelled &&
+          buildClawHubSkillKey(resolvedSkill) !== buildClawHubSkillKey(previewSkill)
+        ) {
+          setPreviewSkill(resolvedSkill);
+        }
+        return getClawHubSkillDetail(resolvedSkill.slug, resolvedSkill.ownerHandle);
+      })
       .then((detail) => {
         if (!cancelled) {
           setPreviewDetail(detail);
@@ -1992,16 +2090,22 @@ function SkillsStoreView(props: {
   }, [previewSkill, t]);
 
   function getInstallState(skill: ClawHubSkillCard): StoreSkillInstallState {
-    const jobId = installingBySlug[skill.slug];
+    const storeKey = buildClawHubSkillKey(skill);
+    const pending = pendingInstallKeys.has(storeKey);
+    const jobId = installingByStoreKey[storeKey];
     const job = jobId ? installJobs[jobId] : undefined;
     const terminalJob = Boolean(job && TERMINAL_INSTALL_PHASES.has(job.phase));
-    const done = installedSlugs.has(skill.slug) || job?.phase === "done";
+    const done =
+      installedKeys.has(storeKey) ||
+      (!skill.ownerHandle && installedSlugs.has(skill.slug)) ||
+      job?.phase === "done";
     return {
       done,
-      installing: Boolean(job && !terminalJob),
+      installing: pending || Boolean(job && !terminalJob),
+      pending,
       terminalJob,
       job,
-      progress: job ? getInstallProgressPercent(job) : null,
+      progress: pending ? null : job ? getInstallProgressPercent(job) : null,
     };
   }
 
@@ -2114,13 +2218,13 @@ function SkillsStoreView(props: {
               )}
             >
               {items.map((skill) => {
-                const { done, installing, terminalJob, job, progress } = getInstallState(skill);
+                const { done, installing, pending, job, progress } = getInstallState(skill);
                 const link = buildClawHubSkillUrl(skill);
 
                 return (
                   // biome-ignore lint/a11y/useSemanticElements: The card contains nested controls and cannot be a native button.
                   <div
-                    key={skill.slug}
+                    key={buildClawHubSkillKey(skill)}
                     role="button"
                     tabIndex={0}
                     aria-label={skill.displayName}
@@ -2210,25 +2314,27 @@ function SkillsStoreView(props: {
                         ) : null}
                       </div>
 
-                      {job && !done && !terminalJob ? (
+                      {installing && !done ? (
                         <div className="space-y-1.5">
                           <div className="flex items-center justify-between gap-3 text-[10.5px] text-muted-foreground">
-                            <span>{installPhaseLabel(job, t)}</span>
-                            <span className="flex items-center gap-1.5">
-                              {formatInstallProgress(job)}
-                              <button
-                                type="button"
-                                title={t("settings.cancel")}
-                                onClick={(event) => {
-                                  event.stopPropagation();
-                                  void cancelSkillInstallJob(job.jobId).catch(() => undefined);
-                                }}
-                                onKeyDown={(event) => event.stopPropagation()}
-                                className="text-muted-foreground/70 transition-colors hover:text-foreground"
-                              >
-                                <X className="h-3 w-3" />
-                              </button>
-                            </span>
+                            <span>{installPhaseLabel(pending ? undefined : job, t)}</span>
+                            {job && !pending ? (
+                              <span className="flex items-center gap-1.5">
+                                {formatInstallProgress(job)}
+                                <button
+                                  type="button"
+                                  title={t("settings.cancel")}
+                                  onClick={(event) => {
+                                    event.stopPropagation();
+                                    void cancelSkillInstallJob(job.jobId).catch(() => undefined);
+                                  }}
+                                  onKeyDown={(event) => event.stopPropagation()}
+                                  className="text-muted-foreground/70 transition-colors hover:text-foreground"
+                                >
+                                  <X className="h-3 w-3" />
+                                </button>
+                              </span>
+                            ) : null}
                           </div>
                           <div className="h-1.5 overflow-hidden rounded-full bg-foreground/[0.08]">
                             {progress === null ? (
@@ -2243,7 +2349,7 @@ function SkillsStoreView(props: {
                         </div>
                       ) : null}
 
-                      {job?.phase === "error" && job.error && !done ? (
+                      {job?.phase === "error" && job.error && !done && !pending ? (
                         <div className="rounded-xl border border-destructive/25 bg-destructive/5 px-3 py-2 text-[11px] text-destructive">
                           {job.error}
                         </div>
@@ -2259,6 +2365,7 @@ function SkillsStoreView(props: {
                             "border-border/55 bg-background/75 text-foreground/85 backdrop-blur-md",
                         )}
                         disabled={done || installing}
+                        aria-busy={installing}
                         onClick={(event) => {
                           event.stopPropagation();
                           onInstall(skill);
@@ -2273,7 +2380,7 @@ function SkillsStoreView(props: {
                           <Cloud className="h-3.5 w-3.5" />
                         )}
                         {installing
-                          ? installPhaseLabel(job, t)
+                          ? installPhaseLabel(pending ? undefined : job, t)
                           : done
                             ? t("settings.skillsStoreInstalled")
                             : t("settings.skillsStoreInstall")}
@@ -2337,7 +2444,7 @@ function SkillsStorePreviewDrawer(props: {
   const supportedOs = detail?.supportedOs ?? [];
   const supportedSystems = detail?.supportedSystems ?? [];
   const actionLabel = installState.installing
-    ? installPhaseLabel(installState.job, t)
+    ? installPhaseLabel(installState.pending ? undefined : installState.job, t)
     : installState.done
       ? t("settings.skillsStoreInstalled")
       : t("settings.skillsStoreInstall");
@@ -2439,11 +2546,15 @@ function SkillsStorePreviewDrawer(props: {
               />
             </div>
 
-            {installState.job && installState.installing ? (
+            {installState.installing && !installState.done ? (
               <div className="rounded-2xl border border-border/50 bg-background/75 p-3 backdrop-blur-md">
                 <div className="flex items-center justify-between gap-3 text-[11px] text-foreground/85">
-                  <span>{installPhaseLabel(installState.job, t)}</span>
-                  <span>{formatInstallProgress(installState.job)}</span>
+                  <span>
+                    {installPhaseLabel(installState.pending ? undefined : installState.job, t)}
+                  </span>
+                  {installState.job && !installState.pending ? (
+                    <span>{formatInstallProgress(installState.job)}</span>
+                  ) : null}
                 </div>
                 <div className="mt-2 h-1.5 overflow-hidden rounded-full bg-foreground/[0.08]">
                   {installState.progress === null ? (
@@ -2458,7 +2569,10 @@ function SkillsStorePreviewDrawer(props: {
               </div>
             ) : null}
 
-            {installState.job?.phase === "error" && installState.job.error && !installState.done ? (
+            {installState.job?.phase === "error" &&
+            installState.job.error &&
+            !installState.done &&
+            !installState.pending ? (
               <div className="rounded-2xl border border-destructive/25 bg-destructive/5 p-3 text-[12px] text-destructive">
                 {installState.job.error}
               </div>
@@ -2569,6 +2683,7 @@ function SkillsStorePreviewDrawer(props: {
                 "border-border/55 bg-background/75 text-foreground/85 backdrop-blur-md",
             )}
             disabled={installState.done || installState.installing}
+            aria-busy={installState.installing}
             onClick={onInstall}
           >
             {installState.installing ? (
@@ -2644,8 +2759,9 @@ function StorePreviewField(props: { label: string; value?: string | null }) {
 function dedupeStoreItems(items: ClawHubSkillCard[]) {
   const seen = new Set<string>();
   return items.filter((item) => {
-    if (seen.has(item.slug)) return false;
-    seen.add(item.slug);
+    const storeKey = buildClawHubSkillKey(item);
+    if (seen.has(storeKey)) return false;
+    seen.add(storeKey);
     return true;
   });
 }
diff --git a/crates/agent-gui/src-tauri/src/services/skills/clawhub.rs b/crates/agent-gui/src-tauri/src/services/skills/clawhub.rs
index 08d297709..f55bb99cb 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/clawhub.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/clawhub.rs
@@ -40,25 +40,6 @@ pub(crate) fn json_string(item: &serde_json::Map<String, Value>, key: &str) -> O
         .map(ToOwned::to_owned)
 }
 
-pub(crate) fn json_u64(item: &serde_json::Map<String, Value>, key: &str) -> u64 {
-    match item.get(key) {
-        Some(Value::Number(number)) => number
-            .as_u64()
-            .or_else(|| number.as_i64().and_then(|value| u64::try_from(value).ok()))
-            .or_else(|| {
-                number.as_f64().and_then(|value| {
-                    if value.is_finite() && value >= 0.0 {
-                        Some(value as u64)
-                    } else {
-                        None
-                    }
-                })
-            })
-            .unwrap_or(0),
-        _ => 0,
-    }
-}
-
 pub(crate) fn json_optional_u64(item: &serde_json::Map<String, Value>, key: &str) -> Option<u64> {
     item.get(key).and_then(|value| match value {
         Value::Number(number) => number
@@ -88,7 +69,10 @@ pub(crate) fn clawhub_download_url_for_slug(
         .append_pair("slug", slug)
         .append_pair("tag", tag);
     // ClawHub 对重名 slug 返回 409，必须带 ownerHandle 消歧。
-    if let Some(owner) = owner_handle.map(str::trim).filter(|value| !value.is_empty()) {
+    if let Some(owner) = owner_handle
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
         url.query_pairs_mut().append_pair("ownerHandle", owner);
     }
     Ok(url.into())
@@ -123,10 +107,16 @@ pub(crate) fn normalize_clawhub_skill_card(raw: &Value) -> Option<SystemClawHubS
         display_name: json_string(item, "displayName").unwrap_or(slug),
         summary: json_string(item, "summary").unwrap_or_default(),
         latest_version,
-        downloads: stats.map(|value| json_u64(value, "downloads")).unwrap_or(0),
-        stars: stats.map(|value| json_u64(value, "stars")).unwrap_or(0),
-        installs_current: stats
-            .map(|value| json_u64(value, "installsCurrent"))
+        downloads: json_optional_u64(item, "downloads")
+            .or_else(|| stats.and_then(|value| json_optional_u64(value, "downloads")))
+            .unwrap_or(0),
+        stars: json_optional_u64(item, "stars")
+            .or_else(|| stats.and_then(|value| json_optional_u64(value, "stars")))
+            .unwrap_or(0),
+        installs_current: json_optional_u64(item, "installsCurrent")
+            .or_else(|| json_optional_u64(item, "installs"))
+            .or_else(|| stats.and_then(|value| json_optional_u64(value, "installsCurrent")))
+            .or_else(|| stats.and_then(|value| json_optional_u64(value, "installs")))
             .unwrap_or(0),
         updated_at: json_optional_u64(item, "updatedAt"),
         owner_handle,
diff --git a/crates/agent-gui/src-tauri/src/services/skills/install.rs b/crates/agent-gui/src-tauri/src/services/skills/install.rs
index 8f8e9d548..e2c6aa197 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/install.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/install.rs
@@ -28,7 +28,10 @@ fn unique_suffix() -> String {
         .duration_since(std::time::UNIX_EPOCH)
         .unwrap_or_default()
         .as_nanos();
-    format!("{nanos}-{}", UNIQUE_SUFFIX_SEQ.fetch_add(1, Ordering::Relaxed))
+    format!(
+        "{nanos}-{}",
+        UNIQUE_SUFFIX_SEQ.fetch_add(1, Ordering::Relaxed)
+    )
 }
 
 fn staging_root(dest_root: &Path) -> PathBuf {
@@ -268,7 +271,10 @@ pub(crate) fn install_skill_dir(
     })
 }
 
-pub(crate) fn normalize_conflict(value: Option<&str>, default_value: &str) -> Result<String, String> {
+pub(crate) fn normalize_conflict(
+    value: Option<&str>,
+    default_value: &str,
+) -> Result<String, String> {
     let raw = value.unwrap_or(default_value).trim();
     match raw {
         "backup" | "fail" | "overwrite" => Ok(raw.to_string()),
@@ -284,8 +290,123 @@ pub(crate) fn normalize_method(value: Option<&str>) -> Result<String, String> {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct SkillNameCompatibilityTransform {
+    pub(crate) original_name: String,
+    pub(crate) normalized_name: String,
+}
+
+fn is_clawhub_download_source(source: &str) -> bool {
+    reqwest::Url::parse(source)
+        .ok()
+        .map(|url| url.host_str() == Some("clawhub.ai") && url.path() == "/api/v1/download")
+        .unwrap_or(false)
+}
+
+fn registry_skill_slug(value: &str) -> &str {
+    value
+        .trim()
+        .trim_start_matches('@')
+        .rsplit('/')
+        .next()
+        .unwrap_or("")
+}
+
+fn rewrite_skill_metadata_name(metadata_file: &Path, normalized_name: &str) -> Result<(), String> {
+    if is_skill_json(metadata_file) {
+        let content = fs::read_to_string(metadata_file)
+            .map_err(|e| format!("Failed to read {}: {e}", metadata_file.display()))?;
+        let mut value = serde_json::from_str::<Value>(&content)
+            .map_err(|e| format!("Failed to parse {}: {e}", metadata_file.display()))?;
+        let object = value.as_object_mut().ok_or_else(|| {
+            format!(
+                "Skill metadata must be an object: {}",
+                metadata_file.display()
+            )
+        })?;
+        object.insert(
+            "name".to_string(),
+            Value::String(normalized_name.to_string()),
+        );
+        let next = serde_json::to_vec_pretty(&value)
+            .map_err(|e| format!("Failed to serialize {}: {e}", metadata_file.display()))?;
+        return fs::write(metadata_file, next)
+            .map_err(|e| format!("Failed to update {}: {e}", metadata_file.display()));
+    }
+
+    let content = fs::read_to_string(metadata_file)
+        .map_err(|e| format!("Failed to read {}: {e}", metadata_file.display()))?;
+    let (yaml, body) = split_frontmatter(&content)?;
+    if yaml.lines().count() == 1 && frontmatter_keys(&yaml).len() > 1 {
+        return Err("Cannot safely normalize an inline Skill frontmatter name".to_string());
+    }
+
+    let mut replaced = false;
+    let mut lines = Vec::new();
+    for line in yaml.lines() {
+        let is_top_level = !line
+            .chars()
+            .next()
+            .map(char::is_whitespace)
+            .unwrap_or(false);
+        let is_name = is_top_level
+            && line
+                .split_once(':')
+                .map(|(key, _)| key.trim() == "name")
+                .unwrap_or(false);
+        if is_name {
+            lines.push(format!("name: {normalized_name}"));
+            replaced = true;
+        } else {
+            lines.push(line.to_string());
+        }
+    }
+    if !replaced {
+        return Err(format!(
+            "Missing top-level Skill name in {}",
+            metadata_file.display()
+        ));
+    }
+
+    let next = format!("---\n{}\n---\n{}", lines.join("\n"), body);
+    fs::write(metadata_file, next)
+        .map_err(|e| format!("Failed to update {}: {e}", metadata_file.display()))
+}
+
+pub(crate) fn normalize_clawhub_candidate_name(
+    candidate: &Path,
+    slug: &str,
+) -> Result<Option<SkillNameCompatibilityTransform>, String> {
+    let metadata_file = metadata_file_for(candidate).ok_or_else(|| {
+        format!(
+            "No SKILL.md, skill.md, skill.json, or README.md found in {}",
+            candidate.display()
+        )
+    })?;
+    let metadata = read_skill_metadata_file(&metadata_file)?;
+    let Some(original_name) = metadata.name else {
+        return Ok(None);
+    };
+    if sanitize_skill_name(&original_name).is_ok() {
+        return Ok(None);
+    }
+
+    let normalized_name = normalize_skill_name(&original_name);
+    let expected_name = registry_skill_slug(slug);
+    if normalized_name != expected_name || sanitize_skill_name(expected_name).is_err() {
+        return Ok(None);
+    }
+
+    rewrite_skill_metadata_name(&metadata_file, expected_name)?;
+    Ok(Some(SkillNameCompatibilityTransform {
+        original_name,
+        normalized_name,
+    }))
+}
+
 fn build_skill_source_metadata(
     payload: &serde_json::Map<String, Value>,
+    compatibility: Option<&SkillNameCompatibilityTransform>,
 ) -> Result<Option<Vec<u8>>, String> {
     let Some(slug) = object_string(payload, "slug") else {
         return Ok(None);
@@ -297,6 +418,9 @@ fn build_skill_source_metadata(
             .or_else(|| object_string(payload, "owner")),
         "version": object_string(payload, "version"),
         "publishedAt": payload.get("publishedAt").and_then(Value::as_u64),
+        "originalName": compatibility.map(|value| value.original_name.as_str()),
+        "normalizedName": compatibility.map(|value| value.normalized_name.as_str()),
+        "compatibilityTransform": compatibility.map(|_| "normalize-agent-skill-name"),
     });
     serde_json::to_vec_pretty(&metadata)
         .map(Some)
@@ -327,8 +451,6 @@ where
     let name_override = object_string(payload, "name")
         .map(sanitize_skill_name)
         .transpose()?;
-    let source_meta = build_skill_source_metadata(payload)?;
-
     if should_cancel() {
         return Err(INSTALL_CANCELLED_ERROR.to_string());
     }
@@ -375,14 +497,37 @@ where
     if name_override.is_some() && candidates.len() != 1 {
         return Err("name can only be used when exactly one skill is installed".to_string());
     }
+    let normalize_clawhub_name = candidates.len() == 1 && is_clawhub_download_source(source);
+    let registry_slug = object_string(payload, "slug").map(ToOwned::to_owned);
 
     let mut results = Vec::new();
     for candidate in candidates {
         if should_cancel() {
             return Err(INSTALL_CANCELLED_ERROR.to_string());
         }
+        let compatibility = if normalize_clawhub_name {
+            registry_slug
+                .as_deref()
+                .map(|slug| normalize_clawhub_candidate_name(&candidate, slug))
+                .transpose()?
+                .flatten()
+        } else {
+            None
+        };
+        if let Some(transform) = compatibility.as_ref() {
+            on_progress(SkillInstallProgressUpdate {
+                phase: "validating",
+                downloaded_bytes: None,
+                total_bytes: None,
+                message: Some(format!(
+                    "Normalizing Skill name '{}' to '{}' for Agent Skills compatibility",
+                    transform.original_name, transform.normalized_name
+                )),
+            });
+        }
         let metadata = read_skill_metadata_from_dir(&candidate)?;
         let skill_name = name_override.as_deref().unwrap_or(&metadata.name);
+        let source_meta = build_skill_source_metadata(payload, compatibility.as_ref())?;
         ensure_not_builtin_skill_management_target(root, skill_name, "install")?;
         on_progress(SkillInstallProgressUpdate {
             phase: "installing",
diff --git a/crates/agent-gui/src-tauri/src/services/skills/jobs.rs b/crates/agent-gui/src-tauri/src/services/skills/jobs.rs
index 93b776868..b4deb90ca 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/jobs.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/jobs.rs
@@ -17,6 +17,7 @@ pub(crate) struct SkillInstallJobState {
     pub(crate) source: String,
     pub(crate) label: Option<String>,
     pub(crate) slug: Option<String>,
+    pub(crate) owner_handle: Option<String>,
     pub(crate) version: Option<String>,
     pub(crate) downloaded_bytes: u64,
     pub(crate) total_bytes: Option<u64>,
@@ -52,6 +53,7 @@ pub(crate) fn install_job_snapshot(job: &SkillInstallJobState) -> SystemSkillIns
         source: job.source.clone(),
         label: job.label.clone(),
         slug: job.slug.clone(),
+        owner_handle: job.owner_handle.clone(),
         version: job.version.clone(),
         downloaded_bytes: job.downloaded_bytes,
         total_bytes: job.total_bytes,
@@ -141,6 +143,9 @@ pub(crate) fn start_install_job_from_payload(
         .to_string();
     let label = object_string(payload, "label").map(ToOwned::to_owned);
     let slug = object_string(payload, "slug").map(ToOwned::to_owned);
+    let owner_handle = object_string(payload, "ownerHandle")
+        .or_else(|| object_string(payload, "owner"))
+        .map(ToOwned::to_owned);
     let version = object_string(payload, "version").map(ToOwned::to_owned);
     normalize_conflict(object_string(payload, "conflict"), "backup")?;
     normalize_method(object_string(payload, "method"))?;
@@ -154,6 +159,7 @@ pub(crate) fn start_install_job_from_payload(
         source,
         label,
         slug,
+        owner_handle,
         version,
         downloaded_bytes: 0,
         total_bytes: None,
diff --git a/crates/agent-gui/src-tauri/src/services/skills/library.rs b/crates/agent-gui/src-tauri/src/services/skills/library.rs
index e23e6160e..71b70444e 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/library.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/library.rs
@@ -254,13 +254,25 @@ pub(crate) fn read_skill_source_metadata(skill_dir: &Path) -> Option<SystemSkill
         .map(str::trim)
         .filter(|value| !value.is_empty())
         .map(ToOwned::to_owned);
+    let optional_string = |key: &str| {
+        value
+            .get(key)
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(ToOwned::to_owned)
+    };
     let published_at = value.get("publishedAt").and_then(Value::as_u64);
 
     Some(SystemSkillSourceMetadata {
         registry: "clawhub".to_string(),
         slug,
+        owner_handle: optional_string("ownerHandle"),
         version,
         published_at,
+        original_name: optional_string("originalName"),
+        normalized_name: optional_string("normalizedName"),
+        compatibility_transform: optional_string("compatibilityTransform"),
     })
 }
 
diff --git a/crates/agent-gui/src-tauri/src/services/skills/tests.rs b/crates/agent-gui/src-tauri/src/services/skills/tests.rs
index 4395f0092..52a2b0721 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/tests.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/tests.rs
@@ -113,8 +113,7 @@ fn readme_without_frontmatter_derives_metadata_for_management() {
     )
     .expect("write readme");
 
-    let raw_metadata =
-        read_skill_metadata_file(&dir.join("README.md")).expect("read raw metadata");
+    let raw_metadata = read_skill_metadata_file(&dir.join("README.md")).expect("read raw metadata");
     assert!(raw_metadata.name.is_none());
     assert!(raw_metadata.description.is_none());
 
@@ -372,8 +371,7 @@ fn builtin_seed_removes_retired_builtin_files() {
     ensure_builtin_agent_skills_in_root(&root).expect("seed builtins");
     let creator_dir = root.join("skills-creator");
     let retired_script = creator_dir.join("scripts").join("old_helper.py");
-    fs::create_dir_all(retired_script.parent().expect("script parent"))
-        .expect("create scripts");
+    fs::create_dir_all(retired_script.parent().expect("script parent")).expect("create scripts");
     fs::write(&retired_script, "#!/usr/bin/env python3\nprint('old')\n")
         .expect("write retired script");
 
@@ -462,8 +460,8 @@ fn clawhub_download_url_preserves_slug_and_tag_params() {
 
 #[test]
 fn clawhub_download_url_appends_owner_handle_for_disambiguation() {
-    let url = clawhub_download_url_for_slug("example-skill", Some("acme"), None)
-        .expect("download url");
+    let url =
+        clawhub_download_url_for_slug("example-skill", Some("acme"), None).expect("download url");
     let parsed = reqwest::Url::parse(&url).expect("parse url");
     let pairs = parsed
         .query_pairs()
@@ -474,35 +472,56 @@ fn clawhub_download_url_appends_owner_handle_for_disambiguation() {
     assert_eq!(pairs.get("tag").map(String::as_str), Some("latest"));
     assert_eq!(pairs.get("ownerHandle").map(String::as_str), Some("acme"));
 
-    let blank_owner = clawhub_download_url_for_slug("example-skill", Some("  "), None)
-        .expect("download url");
+    let blank_owner =
+        clawhub_download_url_for_slug("example-skill", Some("  "), None).expect("download url");
     assert!(!blank_owner.contains("ownerHandle"));
 }
 
 #[test]
-fn normalize_clawhub_skill_card_supports_search_shape() {
+fn normalize_clawhub_skill_card_supports_live_list_shape_without_owner() {
     let raw = json!({
-        "slug": "owner/example-skill",
+        "slug": "example-skill",
         "displayName": "Example Skill",
         "summary": "Example summary",
         "latestVersion": { "version": "1.0.0" },
         "stats": {
             "downloads": 11,
             "stars": 7,
-            "installsCurrent": 3
+            "installs": 3
         },
-        "updatedAt": 12345,
-        "owner": { "handle": "owner" }
+        "updatedAt": 12345
     });
 
     let card = normalize_clawhub_skill_card(&raw).expect("normalize card");
 
-    assert_eq!(card.slug, "owner/example-skill");
+    assert_eq!(card.slug, "example-skill");
     assert_eq!(card.display_name, "Example Skill");
     assert_eq!(card.latest_version.as_deref(), Some("1.0.0"));
     assert_eq!(card.downloads, 11);
     assert_eq!(card.stars, 7);
     assert_eq!(card.installs_current, 3);
+    assert_eq!(card.owner_handle, None);
+    assert!(!card.download_url.contains("ownerHandle"));
+}
+
+#[test]
+fn normalize_clawhub_skill_card_supports_live_search_shape_with_owner() {
+    let raw = json!({
+        "slug": "example-skill",
+        "displayName": "Example Skill",
+        "summary": "Example summary",
+        "version": "1.0.0",
+        "downloads": 11,
+        "updatedAt": 12345,
+        "ownerHandle": "owner",
+        "owner": { "handle": "owner" }
+    });
+
+    let card = normalize_clawhub_skill_card(&raw).expect("normalize card");
+
+    assert_eq!(card.slug, "example-skill");
+    assert_eq!(card.latest_version.as_deref(), Some("1.0.0"));
+    assert_eq!(card.downloads, 11);
     assert_eq!(card.owner_handle.as_deref(), Some("owner"));
     assert!(card.download_url.contains("/api/v1/download"));
     assert!(card.download_url.contains("ownerHandle=owner"));
@@ -517,7 +536,8 @@ fn install_source_persists_clawhub_metadata_when_slug_is_present() {
     let payload = json!({
         "source": source.to_string_lossy(),
         "conflict": "fail",
-        "slug": "owner/clawhub-skill",
+        "slug": "clawhub-skill",
+        "ownerHandle": "owner",
         "version": "1.0.0",
         "publishedAt": 12345
     });
@@ -528,11 +548,54 @@ fn install_source_persists_clawhub_metadata_when_slug_is_present() {
         read_skill_source_metadata(&root.join(&installed[0].name)).expect("read source meta");
 
     assert_eq!(source_metadata.registry, "clawhub");
-    assert_eq!(source_metadata.slug, "owner/clawhub-skill");
+    assert_eq!(source_metadata.slug, "clawhub-skill");
+    assert_eq!(source_metadata.owner_handle.as_deref(), Some("owner"));
     assert_eq!(source_metadata.version.as_deref(), Some("1.0.0"));
     assert_eq!(source_metadata.published_at, Some(12345));
 }
 
+#[test]
+fn clawhub_candidate_normalizes_nonportable_name_when_it_matches_slug() {
+    let tmp = TempDir::new("liveagent-clawhub-name-normalize-test").expect("temp dir");
+    let candidate = tmp.path().join("candidate");
+    fs::create_dir_all(&candidate).expect("create candidate");
+    fs::write(
+        candidate.join("SKILL.md"),
+        "---\nname: SkillScan\nmetadata:\n  version: 1.1.6\ndescription: Security gate\n---\n\n# SkillScan\n",
+    )
+    .expect("write skill");
+
+    let transform = normalize_clawhub_candidate_name(&candidate, "skillscan")
+        .expect("normalize candidate")
+        .expect("compatibility transform");
+    let metadata = read_skill_metadata_from_dir(&candidate).expect("read normalized metadata");
+    let content = fs::read_to_string(candidate.join("SKILL.md")).expect("read normalized skill");
+
+    assert_eq!(transform.original_name, "SkillScan");
+    assert_eq!(transform.normalized_name, "skillscan");
+    assert_eq!(metadata.name, "skillscan");
+    assert!(content.contains("name: skillscan"));
+    assert!(content.contains("metadata:\n  version: 1.1.6"));
+}
+
+#[test]
+fn clawhub_candidate_does_not_normalize_name_that_does_not_match_slug() {
+    let tmp = TempDir::new("liveagent-clawhub-name-mismatch-test").expect("temp dir");
+    let candidate = tmp.path().join("candidate");
+    fs::create_dir_all(&candidate).expect("create candidate");
+    fs::write(
+        candidate.join("SKILL.md"),
+        "---\nname: DifferentName\ndescription: Mismatch\n---\n",
+    )
+    .expect("write skill");
+
+    let transform =
+        normalize_clawhub_candidate_name(&candidate, "skillscan").expect("inspect candidate");
+
+    assert_eq!(transform, None);
+    assert!(read_skill_metadata_from_dir(&candidate).is_err());
+}
+
 #[test]
 fn validate_and_package_round_trip() {
     let tmp = TempDir::new("liveagent-skill-package-test").expect("temp dir");
@@ -566,8 +629,7 @@ fn delete_installed_skill_rejects_builtin_skill() {
     let root = tmp.path().join("skills");
     write_skill(&root, "skills-installer", "Built-in replacement");
 
-    let error =
-        delete_installed_skill(&root, "skills-installer").expect_err("delete should fail");
+    let error = delete_installed_skill(&root, "skills-installer").expect_err("delete should fail");
 
     assert!(
         error.contains("cannot modify built-in Skill"),
@@ -659,8 +721,7 @@ fn validate_accepts_non_english_markdown_documentation() {
     )
     .expect("write skill");
 
-    let validation =
-        validate_installed_skill(&root, "multilingual-skill").expect("validate skill");
+    let validation = validate_installed_skill(&root, "multilingual-skill").expect("validate skill");
 
     assert!(validation.ok, "{:?}", validation.errors);
 }
@@ -800,7 +861,10 @@ fn install_skill_dir_failure_leaves_existing_target_untouched() {
     let bad_dir = write_skill(&bad_source, "different-name", "Bad");
     let error = install_skill_dir(&root, &bad_dir, "stable-skill", "overwrite", None)
         .expect_err("name mismatch should fail");
-    assert!(error.contains("does not match"), "unexpected error: {error}");
+    assert!(
+        error.contains("does not match"),
+        "unexpected error: {error}"
+    );
 
     let content = fs::read_to_string(root.join("stable-skill").join("SKILL.md"))
         .expect("target survives failed overwrite");
@@ -827,7 +891,10 @@ fn concurrent_same_name_installs_serialize_into_one_target_and_complete_backups(
         })
         .collect();
     for handle in handles {
-        handle.join().expect("join writer").expect("install succeeds");
+        handle
+            .join()
+            .expect("join writer")
+            .expect("install succeeds");
     }
 
     // Exactly one complete live target...
@@ -867,14 +934,22 @@ fn concurrent_distinct_installs_all_succeed_and_staging_is_drained() {
         })
         .collect();
     for handle in handles {
-        handle.join().expect("join writer").expect("install succeeds");
+        handle
+            .join()
+            .expect("join writer")
+            .expect("install succeeds");
     }
 
     let (skills, invalid) = list_installed_skills(&root).expect("list skills");
     assert_eq!(skills.len(), WRITERS);
-    assert!(invalid.is_empty(), "unexpected invalid entries: {invalid:?}");
+    assert!(
+        invalid.is_empty(),
+        "unexpected invalid entries: {invalid:?}"
+    );
     assert_eq!(
-        fs::read_dir(root.join(".staging")).expect("staging").count(),
+        fs::read_dir(root.join(".staging"))
+            .expect("staging")
+            .count(),
         0
     );
 }
@@ -907,7 +982,8 @@ fn cancel_install_job_flags_running_jobs_and_rejects_finished_ones() {
         phase: "downloading".to_string(),
         source: "https://example.test/skill.zip".to_string(),
         label: None,
-        slug: None,
+        slug: Some("github".to_string()),
+        owner_handle: Some("acme".to_string()),
         version: None,
         downloaded_bytes: 0,
         total_bytes: None,
@@ -921,6 +997,10 @@ fn cancel_install_job_flags_running_jobs_and_rejects_finished_ones() {
     })
     .expect("insert job");
 
+    let snapshot = get_install_job_snapshot(&job_id).expect("read job snapshot");
+    assert_eq!(snapshot.slug.as_deref(), Some("github"));
+    assert_eq!(snapshot.owner_handle.as_deref(), Some("acme"));
+
     cancel_install_job(&job_id).expect("cancel running job");
     let flagged = skill_install_jobs()
         .lock()
diff --git a/crates/agent-gui/src-tauri/src/services/skills/types.rs b/crates/agent-gui/src-tauri/src/services/skills/types.rs
index 798c921c4..8ea4371dd 100644
--- a/crates/agent-gui/src-tauri/src/services/skills/types.rs
+++ b/crates/agent-gui/src-tauri/src/services/skills/types.rs
@@ -29,8 +29,12 @@ pub struct SystemReadSkillMetadataResponse {
 pub struct SystemSkillSourceMetadata {
     pub registry: String,
     pub slug: String,
+    pub owner_handle: Option<String>,
     pub version: Option<String>,
     pub published_at: Option<u64>,
+    pub original_name: Option<String>,
+    pub normalized_name: Option<String>,
+    pub compatibility_transform: Option<String>,
 }
 
 #[derive(Debug, Serialize, Clone)]
@@ -138,6 +142,7 @@ pub struct SystemSkillInstallJobSnapshot {
     pub source: String,
     pub label: Option<String>,
     pub slug: Option<String>,
+    pub owner_handle: Option<String>,
     pub version: Option<String>,
     pub downloaded_bytes: u64,
     pub total_bytes: Option<u64>,
diff --git a/crates/agent-gui/src/lib/skills/clawHub.ts b/crates/agent-gui/src/lib/skills/clawHub.ts
index 4d11599b9..592e7deef 100644
--- a/crates/agent-gui/src/lib/skills/clawHub.ts
+++ b/crates/agent-gui/src/lib/skills/clawHub.ts
@@ -43,10 +43,6 @@ function asString(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function asNumber(value: unknown): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-
 function asNullableNumber(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
@@ -62,7 +58,13 @@ function buildClawHubWebUrl(ownerHandle: string | null, slug: string) {
   return `${CLAWHUB_API_BASE}/${encodeURIComponent(ownerHandle)}/${encodeURIComponent(slug)}`;
 }
 
-function normalizeSkillCard(raw: unknown): ClawHubSkillCard | null {
+export function buildClawHubSkillKey(skill: Pick<ClawHubSkillCard, "slug" | "ownerHandle">) {
+  const slug = skill.slug.trim().toLowerCase();
+  const ownerHandle = skill.ownerHandle?.trim().replace(/^@+/, "").toLowerCase();
+  return `clawhub:${ownerHandle || "?"}/${slug}`;
+}
+
+export function normalizeClawHubSkillCard(raw: unknown): ClawHubSkillCard | null {
   const item = asRecord(raw);
   const slug = asString(item.slug);
   if (!slug) return null;
@@ -78,9 +80,14 @@ function normalizeSkillCard(raw: unknown): ClawHubSkillCard | null {
     summary: asString(item.summary) ?? "",
     latestVersion:
       asString(latestVersion.version) ?? asString(tags.latest) ?? asString(item.version),
-    downloads: asNumber(stats.downloads),
-    stars: asNumber(stats.stars),
-    installsCurrent: asNumber(stats.installsCurrent),
+    downloads: asNullableNumber(item.downloads) ?? asNullableNumber(stats.downloads) ?? 0,
+    stars: asNullableNumber(item.stars) ?? asNullableNumber(stats.stars) ?? 0,
+    installsCurrent:
+      asNullableNumber(item.installsCurrent) ??
+      asNullableNumber(item.installs) ??
+      asNullableNumber(stats.installsCurrent) ??
+      asNullableNumber(stats.installs) ??
+      0,
     updatedAt: asNullableNumber(item.updatedAt),
     ownerHandle,
     webUrl: asString(item.webUrl) ?? buildClawHubWebUrl(ownerHandle, slug),
@@ -96,7 +103,7 @@ function normalizeSkillDetail(raw: unknown): ClawHubSkillDetail | null {
   const owner = asRecord(payload.owner ?? item.owner);
   const metadata = asRecord(payload.metadata ?? item.metadata);
   const moderation = asRecord(payload.moderation ?? item.moderation);
-  const card = normalizeSkillCard({
+  const card = normalizeClawHubSkillCard({
     ...item,
     latestVersion,
     owner,
@@ -118,14 +125,28 @@ function normalizeSkillDetail(raw: unknown): ClawHubSkillDetail | null {
   };
 }
 
+export class ClawHubHttpError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(status: number, body: string) {
+    const detail = body.trim();
+    super(`ClawHub request failed with HTTP ${status}${detail ? `: ${detail}` : ""}`);
+    this.name = "ClawHubHttpError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
 async function fetchClawHubJson(url: URL): Promise<unknown> {
   const response = await fetch(url.toString(), {
     headers: { Accept: "application/json" },
   });
+  const body = await response.text();
   if (!response.ok) {
-    throw new Error(`ClawHub request failed with HTTP ${response.status}`);
+    throw new ClawHubHttpError(response.status, body);
   }
-  return response.json();
+  return JSON.parse(body) as unknown;
 }
 
 export async function listClawHubSkills(params: {
@@ -143,7 +164,9 @@ export async function listClawHubSkills(params: {
 
   const json = asRecord(await fetchClawHubJson(url));
   const items = Array.isArray(json.items)
-    ? json.items.map(normalizeSkillCard).filter((item): item is ClawHubSkillCard => Boolean(item))
+    ? json.items
+        .map(normalizeClawHubSkillCard)
+        .filter((item): item is ClawHubSkillCard => Boolean(item))
     : [];
   return {
     items,
@@ -162,10 +185,78 @@ export async function searchClawHubSkills(params: {
 
   const json = asRecord(await fetchClawHubJson(url));
   return Array.isArray(json.results)
-    ? json.results.map(normalizeSkillCard).filter((item): item is ClawHubSkillCard => Boolean(item))
+    ? json.results
+        .map(normalizeClawHubSkillCard)
+        .filter((item): item is ClawHubSkillCard => Boolean(item))
     : [];
 }
 
+function narrowOwnerCandidates(
+  candidates: ClawHubSkillCard[],
+  predicate: (candidate: ClawHubSkillCard) => boolean,
+) {
+  const narrowed = candidates.filter(predicate);
+  return narrowed.length > 0 ? narrowed : candidates;
+}
+
+export function selectClawHubOwnerCandidate(
+  skill: ClawHubSkillCard,
+  candidates: ClawHubSkillCard[],
+): ClawHubSkillCard | null {
+  let exact = candidates.filter(
+    (candidate) =>
+      candidate.slug.toLowerCase() === skill.slug.toLowerCase() && Boolean(candidate.ownerHandle),
+  );
+  if (exact.length === 1) return exact[0];
+  if (exact.length === 0) return null;
+
+  if (skill.updatedAt !== null) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.updatedAt === skill.updatedAt);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.latestVersion) {
+    exact = narrowOwnerCandidates(
+      exact,
+      (candidate) => candidate.latestVersion === skill.latestVersion,
+    );
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.downloads > 0) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.downloads === skill.downloads);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.summary) {
+    exact = narrowOwnerCandidates(exact, (candidate) => candidate.summary === skill.summary);
+    if (exact.length === 1) return exact[0];
+  }
+  if (skill.displayName) {
+    exact = narrowOwnerCandidates(
+      exact,
+      (candidate) => candidate.displayName === skill.displayName,
+    );
+  }
+  return exact.length === 1 ? exact[0] : null;
+}
+
+export async function resolveClawHubSkillOwner(skill: ClawHubSkillCard): Promise<ClawHubSkillCard> {
+  if (skill.ownerHandle) return skill;
+
+  const candidates = await searchClawHubSkills({ query: skill.slug, limit: 50 });
+  const resolved = selectClawHubOwnerCandidate(skill, candidates);
+  if (!resolved?.ownerHandle) {
+    throw new Error(
+      `ClawHub skill "${skill.slug}" has multiple publishers, but the catalog item does not identify one`,
+    );
+  }
+
+  return {
+    ...skill,
+    ownerHandle: resolved.ownerHandle,
+    webUrl: resolved.webUrl ?? buildClawHubWebUrl(resolved.ownerHandle, skill.slug),
+    downloadUrl: buildClawHubDownloadUrl(skill.slug, resolved.ownerHandle),
+  };
+}
+
 export async function getClawHubSkillDetail(
   slug: string,
   ownerHandle?: string | null,
diff --git a/crates/agent-gui/src/lib/skills/index.ts b/crates/agent-gui/src/lib/skills/index.ts
index a13757a75..637aafeee 100644
--- a/crates/agent-gui/src/lib/skills/index.ts
+++ b/crates/agent-gui/src/lib/skills/index.ts
@@ -33,8 +33,12 @@ export type SkillSummary = {
 export type SkillSourceMetadata = {
   registry: string;
   slug: string;
+  ownerHandle?: string | null;
   version?: string | null;
   publishedAt?: number | null;
+  originalName?: string | null;
+  normalizedName?: string | null;
+  compatibilityTransform?: string | null;
 };
 
 export type SkillDiscovery = {
@@ -93,6 +97,7 @@ export type SkillInstallJobSnapshot = {
   source: string;
   label?: string | null;
   slug?: string | null;
+  ownerHandle?: string | null;
   version?: string | null;
   downloadedBytes: number;
   totalBytes?: number | null;
diff --git a/crates/agent-gui/src/pages/skills-hub/SkillsHubPage.tsx b/crates/agent-gui/src/pages/skills-hub/SkillsHubPage.tsx
index 0025a2ce1..9674df5b6 100644
--- a/crates/agent-gui/src/pages/skills-hub/SkillsHubPage.tsx
+++ b/crates/agent-gui/src/pages/skills-hub/SkillsHubPage.tsx
@@ -46,11 +46,13 @@ import {
 } from "../../lib/skills";
 import {
   buildClawHubDownloadUrl,
+  buildClawHubSkillKey,
   type ClawHubSkillCard,
   type ClawHubSkillDetail,
   type ClawHubSort,
   getClawHubSkillDetail,
   listClawHubSkills,
+  resolveClawHubSkillOwner,
   searchClawHubSkills,
 } from "../../lib/skills/clawHub";
 
@@ -76,6 +78,7 @@ const STORE_SORT_OPTIONS: Array<{ value: ClawHubSort; labelKey: string }> = [
 type StoreSkillInstallState = {
   done: boolean;
   installing: boolean;
+  pending: boolean;
   terminalJob: boolean;
   job: SkillInstallJobSnapshot | undefined;
   progress: number | null;
@@ -330,7 +333,11 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
   const [storeLoadingMore, setStoreLoadingMore] = useState(false);
   const [storeError, setStoreError] = useState<string | null>(null);
   const [installJobs, setInstallJobs] = useState<Record<string, SkillInstallJobSnapshot>>({});
-  const [installingBySlug, setInstallingBySlug] = useState<Record<string, string>>({});
+  const [installingByStoreKey, setInstallingByStoreKey] = useState<Record<string, string>>({});
+  const [pendingInstallKeys, setPendingInstallKeys] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+  const pendingInstallTokensRef = useRef(new Map<string, symbol>());
   const [deletingSkillName, setDeletingSkillName] = useState<string | null>(null);
   const [externalScans, setExternalScans] = useState<ExternalToolScan[] | null>(null);
   const [externalLoading, setExternalLoading] = useState(false);
@@ -548,37 +555,58 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
     };
   }, [previewInstalledSkill, t]);
 
-  const installedBySlug = useMemo(() => {
+  const installedStoreState = useMemo(() => {
     const installed = new Map<string, SkillSummary>();
+    const slugs = new Set<string>();
     for (const skill of skills) {
       if (skill.source?.registry !== "clawhub") continue;
       const slug = skill.source.slug?.trim();
-      if (slug) installed.set(slug, skill);
+      if (!slug) continue;
+      slugs.add(slug);
+      installed.set(
+        buildClawHubSkillKey({ slug, ownerHandle: skill.source.ownerHandle ?? null }),
+        skill,
+      );
     }
-    return installed;
+    return { installed, slugs };
   }, [skills]);
-  const completedInstallSlugs = useMemo(() => {
+  const completedInstallState = useMemo(() => {
+    const keys = new Set<string>();
     const slugs = new Set<string>();
-    for (const [slug, jobId] of Object.entries(installingBySlug)) {
+    for (const [storeKey, jobId] of Object.entries(installingByStoreKey)) {
       const job = installJobs[jobId];
-      if (job?.phase === "done" && slug.trim()) {
-        slugs.add(slug.trim());
+      if (job?.phase === "done") {
+        keys.add(storeKey);
+        if (job.slug?.trim()) slugs.add(job.slug.trim());
       }
     }
     for (const job of Object.values(installJobs)) {
       if (job.phase === "done" && job.slug?.trim()) {
         slugs.add(job.slug.trim());
+        keys.add(
+          buildClawHubSkillKey({
+            slug: job.slug.trim(),
+            ownerHandle: job.ownerHandle ?? null,
+          }),
+        );
       }
     }
-    return slugs;
-  }, [installJobs, installingBySlug]);
+    return { keys, slugs };
+  }, [installJobs, installingByStoreKey]);
+  const installedStoreKeys = useMemo(() => {
+    const keys = new Set(installedStoreState.installed.keys());
+    for (const key of completedInstallState.keys) {
+      keys.add(key);
+    }
+    return keys;
+  }, [completedInstallState.keys, installedStoreState.installed]);
   const installedStoreSlugs = useMemo(() => {
-    const slugs = new Set(installedBySlug.keys());
-    for (const slug of completedInstallSlugs) {
+    const slugs = new Set(installedStoreState.slugs);
+    for (const slug of completedInstallState.slugs) {
       slugs.add(slug);
     }
     return slugs;
-  }, [completedInstallSlugs, installedBySlug]);
+  }, [completedInstallState.slugs, installedStoreState.slugs]);
 
   useEffect(() => {
     if (view !== "store" || lockedByChatMode) return;
@@ -732,30 +760,76 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
   }
 
   async function installStoreSkill(skill: ClawHubSkillCard) {
-    const existingJobId = installingBySlug[skill.slug];
-    const existingJob = existingJobId ? installJobs[existingJobId] : undefined;
+    const initialStoreKey = buildClawHubSkillKey(skill);
+    const initialJobId = installingByStoreKey[initialStoreKey];
+    const initialJob = initialJobId ? installJobs[initialJobId] : undefined;
     if (
       lockedByChatMode ||
-      installedStoreSlugs.has(skill.slug) ||
-      (existingJob && !TERMINAL_INSTALL_PHASES.has(existingJob.phase))
+      pendingInstallTokensRef.current.has(initialStoreKey) ||
+      installedStoreKeys.has(initialStoreKey) ||
+      (!skill.ownerHandle && installedStoreSlugs.has(skill.slug)) ||
+      (initialJob && !TERMINAL_INSTALL_PHASES.has(initialJob.phase))
     ) {
       return;
     }
+
+    const pendingToken = Symbol(initialStoreKey);
+    pendingInstallTokensRef.current.set(initialStoreKey, pendingToken);
+    setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
     setStoreError(null);
     try {
+      const resolvedSkill = await resolveClawHubSkillOwner(skill);
+      const storeKey = buildClawHubSkillKey(resolvedSkill);
+      const activePendingToken = pendingInstallTokensRef.current.get(storeKey);
+      if (activePendingToken && activePendingToken !== pendingToken) return;
+      if (storeKey !== initialStoreKey) {
+        pendingInstallTokensRef.current.set(storeKey, pendingToken);
+        setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
+      }
+      setStoreItems((prev) =>
+        prev.map((item) =>
+          item.slug === resolvedSkill.slug &&
+          item.updatedAt === resolvedSkill.updatedAt &&
+          (!item.ownerHandle || item.ownerHandle === resolvedSkill.ownerHandle)
+            ? resolvedSkill
+            : item,
+        ),
+      );
+      const existingJobId = installingByStoreKey[storeKey];
+      const existingJob = existingJobId ? installJobs[existingJobId] : undefined;
+      if (
+        installedStoreKeys.has(storeKey) ||
+        (existingJob && !TERMINAL_INSTALL_PHASES.has(existingJob.phase))
+      ) {
+        return;
+      }
       const job = await startSkillInstallJob({
-        source: buildClawHubDownloadUrl(skill.slug, skill.ownerHandle),
-        label: skill.displayName,
-        slug: skill.slug,
-        ownerHandle: skill.ownerHandle,
-        version: skill.latestVersion,
+        source: buildClawHubDownloadUrl(resolvedSkill.slug, resolvedSkill.ownerHandle),
+        label: resolvedSkill.displayName,
+        slug: resolvedSkill.slug,
+        ownerHandle: resolvedSkill.ownerHandle,
+        version: resolvedSkill.latestVersion,
         conflict: "backup",
       });
       setInstallJobs((prev) => ({ ...prev, [job.jobId]: job }));
-      setInstallingBySlug((prev) => ({ ...prev, [skill.slug]: job.jobId }));
+      setInstallingByStoreKey((prev) => ({
+        ...prev,
+        [initialStoreKey]: job.jobId,
+        [storeKey]: job.jobId,
+      }));
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       setStoreError(msg || t("settings.skillsHubInstallFailed"));
+    } finally {
+      let changed = false;
+      for (const [storeKey, token] of pendingInstallTokensRef.current) {
+        if (token !== pendingToken) continue;
+        pendingInstallTokensRef.current.delete(storeKey);
+        changed = true;
+      }
+      if (changed) {
+        setPendingInstallKeys(new Set(pendingInstallTokensRef.current.keys()));
+      }
     }
   }
 
@@ -763,6 +837,8 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
     if (lockedByChatMode || isAlwaysEnabledSkillName(skill.name) || deletingSkillName) return;
     const skillName = skill.name;
     const sourceSlug = skill.source?.registry === "clawhub" ? skill.source.slug?.trim() || "" : "";
+    const sourceOwnerHandle =
+      skill.source?.registry === "clawhub" ? skill.source.ownerHandle?.trim() || null : null;
     setLoadError(null);
     setDeletingSkillName(skillName);
     try {
@@ -775,17 +851,24 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
       setSkills((prev) => prev.filter((item) => item.name !== skillName));
       setPreviewInstalledSkill((current) => (current?.name === skillName ? null : current));
       if (sourceSlug) {
-        setInstallingBySlug((prev) => {
-          if (!(sourceSlug in prev)) return prev;
+        const sourceKey = buildClawHubSkillKey({
+          slug: sourceSlug,
+          ownerHandle: sourceOwnerHandle,
+        });
+        setInstallingByStoreKey((prev) => {
+          if (!(sourceKey in prev)) return prev;
           const next = { ...prev };
-          delete next[sourceSlug];
+          delete next[sourceKey];
           return next;
         });
         setInstallJobs((prev) => {
           let changed = false;
           const next = { ...prev };
           for (const [jobId, job] of Object.entries(prev)) {
-            if (job.slug?.trim() === sourceSlug) {
+            if (
+              job.slug?.trim() === sourceSlug &&
+              (!sourceOwnerHandle || job.ownerHandle?.trim() === sourceOwnerHandle)
+            ) {
               delete next[jobId];
               changed = true;
             }
@@ -1339,8 +1422,10 @@ export function SkillsHubPage(props: SkillsHubPageProps) {
                       loadingMore={storeLoadingMore}
                       error={storeError}
                       cursor={storeCursor}
+                      installedKeys={installedStoreKeys}
                       installedSlugs={installedStoreSlugs}
-                      installingBySlug={installingBySlug}
+                      pendingInstallKeys={pendingInstallKeys}
+                      installingByStoreKey={installingByStoreKey}
                       installJobs={installJobs}
                       onSortChange={setStoreSort}
                       onLoadMore={() => void loadMoreStore()}
@@ -1924,8 +2009,10 @@ function SkillsStoreView(props: {
   loadingMore: boolean;
   error: string | null;
   cursor: string | null;
+  installedKeys: Set<string>;
   installedSlugs: Set<string>;
-  installingBySlug: Record<string, string>;
+  pendingInstallKeys: ReadonlySet<string>;
+  installingByStoreKey: Record<string, string>;
   installJobs: Record<string, SkillInstallJobSnapshot>;
   onSortChange: (value: ClawHubSort) => void;
   onLoadMore: () => void;
@@ -1939,8 +2026,10 @@ function SkillsStoreView(props: {
     loadingMore,
     error,
     cursor,
+    installedKeys,
     installedSlugs,
-    installingBySlug,
+    pendingInstallKeys,
+    installingByStoreKey,
     installJobs,
     onSortChange,
     onLoadMore,
@@ -1967,7 +2056,16 @@ function SkillsStoreView(props: {
     setPreviewError(null);
     setPreviewLoading(true);
 
-    void getClawHubSkillDetail(previewSkill.slug, previewSkill.ownerHandle)
+    void resolveClawHubSkillOwner(previewSkill)
+      .then((resolvedSkill) => {
+        if (
+          !cancelled &&
+          buildClawHubSkillKey(resolvedSkill) !== buildClawHubSkillKey(previewSkill)
+        ) {
+          setPreviewSkill(resolvedSkill);
+        }
+        return getClawHubSkillDetail(resolvedSkill.slug, resolvedSkill.ownerHandle);
+      })
       .then((detail) => {
         if (!cancelled) {
           setPreviewDetail(detail);
@@ -1991,16 +2089,22 @@ function SkillsStoreView(props: {
   }, [previewSkill, t]);
 
   function getInstallState(skill: ClawHubSkillCard): StoreSkillInstallState {
-    const jobId = installingBySlug[skill.slug];
+    const storeKey = buildClawHubSkillKey(skill);
+    const pending = pendingInstallKeys.has(storeKey);
+    const jobId = installingByStoreKey[storeKey];
     const job = jobId ? installJobs[jobId] : undefined;
     const terminalJob = Boolean(job && TERMINAL_INSTALL_PHASES.has(job.phase));
-    const done = installedSlugs.has(skill.slug) || job?.phase === "done";
+    const done =
+      installedKeys.has(storeKey) ||
+      (!skill.ownerHandle && installedSlugs.has(skill.slug)) ||
+      job?.phase === "done";
     return {
       done,
-      installing: Boolean(job && !terminalJob),
+      installing: pending || Boolean(job && !terminalJob),
+      pending,
       terminalJob,
       job,
-      progress: job ? getInstallProgressPercent(job) : null,
+      progress: pending ? null : job ? getInstallProgressPercent(job) : null,
     };
   }
 
@@ -2113,13 +2217,13 @@ function SkillsStoreView(props: {
               )}
             >
               {items.map((skill) => {
-                const { done, installing, terminalJob, job, progress } = getInstallState(skill);
+                const { done, installing, pending, job, progress } = getInstallState(skill);
                 const link = buildClawHubSkillUrl(skill);
 
                 return (
                   // biome-ignore lint/a11y/useSemanticElements: The card contains nested controls and cannot be a native button.
                   <div
-                    key={skill.slug}
+                    key={buildClawHubSkillKey(skill)}
                     role="button"
                     tabIndex={0}
                     aria-label={skill.displayName}
@@ -2209,25 +2313,27 @@ function SkillsStoreView(props: {
                         ) : null}
                       </div>
 
-                      {job && !done && !terminalJob ? (
+                      {installing && !done ? (
                         <div className="space-y-1.5">
                           <div className="flex items-center justify-between gap-3 text-[10.5px] text-muted-foreground">
-                            <span>{installPhaseLabel(job, t)}</span>
-                            <span className="flex items-center gap-1.5">
-                              {formatInstallProgress(job)}
-                              <button
-                                type="button"
-                                title={t("settings.cancel")}
-                                onClick={(event) => {
-                                  event.stopPropagation();
-                                  void cancelSkillInstallJob(job.jobId).catch(() => undefined);
-                                }}
-                                onKeyDown={(event) => event.stopPropagation()}
-                                className="text-muted-foreground/70 transition-colors hover:text-foreground"
-                              >
-                                <X className="h-3 w-3" />
-                              </button>
-                            </span>
+                            <span>{installPhaseLabel(pending ? undefined : job, t)}</span>
+                            {job && !pending ? (
+                              <span className="flex items-center gap-1.5">
+                                {formatInstallProgress(job)}
+                                <button
+                                  type="button"
+                                  title={t("settings.cancel")}
+                                  onClick={(event) => {
+                                    event.stopPropagation();
+                                    void cancelSkillInstallJob(job.jobId).catch(() => undefined);
+                                  }}
+                                  onKeyDown={(event) => event.stopPropagation()}
+                                  className="text-muted-foreground/70 transition-colors hover:text-foreground"
+                                >
+                                  <X className="h-3 w-3" />
+                                </button>
+                              </span>
+                            ) : null}
                           </div>
                           <div className="h-1.5 overflow-hidden rounded-full bg-foreground/[0.08]">
                             {progress === null ? (
@@ -2242,7 +2348,7 @@ function SkillsStoreView(props: {
                         </div>
                       ) : null}
 
-                      {job?.phase === "error" && job.error && !done ? (
+                      {job?.phase === "error" && job.error && !done && !pending ? (
                         <div className="rounded-xl border border-destructive/25 bg-destructive/5 px-3 py-2 text-[11px] text-destructive">
                           {job.error}
                         </div>
@@ -2258,6 +2364,7 @@ function SkillsStoreView(props: {
                             "border-border/55 bg-background/75 text-foreground/85 backdrop-blur-md",
                         )}
                         disabled={done || installing}
+                        aria-busy={installing}
                         onClick={(event) => {
                           event.stopPropagation();
                           onInstall(skill);
@@ -2272,7 +2379,7 @@ function SkillsStoreView(props: {
                           <Cloud className="h-3.5 w-3.5" />
                         )}
                         {installing
-                          ? installPhaseLabel(job, t)
+                          ? installPhaseLabel(pending ? undefined : job, t)
                           : done
                             ? t("settings.skillsStoreInstalled")
                             : t("settings.skillsStoreInstall")}
@@ -2336,7 +2443,7 @@ function SkillsStorePreviewDrawer(props: {
   const supportedOs = detail?.supportedOs ?? [];
   const supportedSystems = detail?.supportedSystems ?? [];
   const actionLabel = installState.installing
-    ? installPhaseLabel(installState.job, t)
+    ? installPhaseLabel(installState.pending ? undefined : installState.job, t)
     : installState.done
       ? t("settings.skillsStoreInstalled")
       : t("settings.skillsStoreInstall");
@@ -2438,11 +2545,15 @@ function SkillsStorePreviewDrawer(props: {
               />
             </div>
 
-            {installState.job && installState.installing ? (
+            {installState.installing && !installState.done ? (
               <div className="rounded-2xl border border-border/50 bg-background/75 p-3 backdrop-blur-md">
                 <div className="flex items-center justify-between gap-3 text-[11px] text-foreground/85">
-                  <span>{installPhaseLabel(installState.job, t)}</span>
-                  <span>{formatInstallProgress(installState.job)}</span>
+                  <span>
+                    {installPhaseLabel(installState.pending ? undefined : installState.job, t)}
+                  </span>
+                  {installState.job && !installState.pending ? (
+                    <span>{formatInstallProgress(installState.job)}</span>
+                  ) : null}
                 </div>
                 <div className="mt-2 h-1.5 overflow-hidden rounded-full bg-foreground/[0.08]">
                   {installState.progress === null ? (
@@ -2457,7 +2568,10 @@ function SkillsStorePreviewDrawer(props: {
               </div>
             ) : null}
 
-            {installState.job?.phase === "error" && installState.job.error && !installState.done ? (
+            {installState.job?.phase === "error" &&
+            installState.job.error &&
+            !installState.done &&
+            !installState.pending ? (
               <div className="rounded-2xl border border-destructive/25 bg-destructive/5 p-3 text-[12px] text-destructive">
                 {installState.job.error}
               </div>
@@ -2570,6 +2684,7 @@ function SkillsStorePreviewDrawer(props: {
                 "border-border/55 bg-background/75 text-foreground/85 backdrop-blur-md",
             )}
             disabled={installState.done || installState.installing}
+            aria-busy={installState.installing}
             onClick={onInstall}
           >
             {installState.installing ? (
@@ -2645,8 +2760,9 @@ function StorePreviewField(props: { label: string; value?: string | null }) {
 function dedupeStoreItems(items: ClawHubSkillCard[]) {
   const seen = new Set<string>();
   return items.filter((item) => {
-    if (seen.has(item.slug)) return false;
-    seen.add(item.slug);
+    const storeKey = buildClawHubSkillKey(item);
+    if (seen.has(storeKey)) return false;
+    seen.add(storeKey);
     return true;
   });
 }
diff --git a/crates/agent-gui/test/skills/clawhub-contract.test.mjs b/crates/agent-gui/test/skills/clawhub-contract.test.mjs
new file mode 100644
index 000000000..80025df76
--- /dev/null
+++ b/crates/agent-gui/test/skills/clawhub-contract.test.mjs
@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTsModuleLoader } from "../helpers/load-ts-module.mjs";
+
+const loader = createTsModuleLoader();
+const clawHub = loader.loadModule("src/lib/skills/clawHub.ts");
+
+test("normalizes current ClawHub list and search response shapes", () => {
+  const listCard = clawHub.normalizeClawHubSkillCard({
+    slug: "github",
+    displayName: "Github",
+    summary: "GitHub CLI workflows",
+    latestVersion: { version: "1.0.0" },
+    stats: { downloads: 193172, stars: 652, installs: 7621 },
+    updatedAt: 1781268517834,
+  });
+  const searchCard = clawHub.normalizeClawHubSkillCard({
+    slug: "github",
+    displayName: "Github",
+    summary: "GitHub CLI workflows",
+    version: "1.0.0",
+    downloads: 193172,
+    updatedAt: 1781268517834,
+    ownerHandle: "steipete",
+    owner: { handle: "steipete", displayName: "Peter Steinberger" },
+  });
+
+  assert.equal(listCard.ownerHandle, null);
+  assert.equal(listCard.downloads, 193172);
+  assert.equal(listCard.installsCurrent, 7621);
+  assert.equal(searchCard.ownerHandle, "steipete");
+  assert.equal(searchCard.latestVersion, "1.0.0");
+  assert.equal(searchCard.downloads, 193172);
+  assert.match(searchCard.downloadUrl, /ownerHandle=steipete/);
+});
+
+test("selects the publisher matching the unscoped catalog card", () => {
+  const catalogCard = clawHub.normalizeClawHubSkillCard({
+    slug: "github",
+    displayName: "Github",
+    summary: "GitHub CLI workflows",
+    latestVersion: { version: "1.0.0" },
+    stats: { downloads: 193172 },
+    updatedAt: 1781268517834,
+  });
+  const candidates = [
+    {
+      ...catalogCard,
+      ownerHandle: "steipete",
+      updatedAt: 1781268517834,
+    },
+    {
+      ...catalogCard,
+      ownerHandle: "eohmig",
+      downloads: 8,
+      updatedAt: 1782439133368,
+    },
+  ];
+
+  const selected = clawHub.selectClawHubOwnerCandidate(catalogCard, candidates);
+
+  assert.equal(selected.ownerHandle, "steipete");
+});
+
+test("uses publisher and slug as the store identity", () => {
+  assert.notEqual(
+    clawHub.buildClawHubSkillKey({ slug: "github", ownerHandle: "steipete" }),
+    clawHub.buildClawHubSkillKey({ slug: "github", ownerHandle: "eohmig" }),
+  );
+  assert.equal(
+    clawHub.buildClawHubSkillKey({ slug: "GitHub", ownerHandle: "@STEIPETE" }),
+    "clawhub:steipete/github",
+  );
+});
diff --git a/crates/agent-gui/test/skills/skills-store-install-feedback.test.mjs b/crates/agent-gui/test/skills/skills-store-install-feedback.test.mjs
new file mode 100644
index 000000000..6361beaac
--- /dev/null
+++ b/crates/agent-gui/test/skills/skills-store-install-feedback.test.mjs
@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+const pageSources = [
+  {
+    label: "GUI",
+    source: readFileSync(
+      new URL("../../src/pages/skills-hub/SkillsHubPage.tsx", import.meta.url),
+      "utf8",
+    ),
+  },
+  {
+    label: "WebUI",
+    source: readFileSync(
+      new URL(
+        "../../../agent-gateway/web/src/pages/skills-hub/SkillsHubPage.tsx",
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  },
+];
+
+function installFunctionSource(source) {
+  const start = source.indexOf("  async function installStoreSkill(");
+  const end = source.indexOf("\n  async function deleteSkill(", start);
+  assert.notEqual(start, -1, "installStoreSkill must exist");
+  assert.notEqual(end, -1, "installStoreSkill must end before deleteSkill");
+  return source.slice(start, end);
+}
+
+for (const { label, source } of pageSources) {
+  test(`${label} shows pending install feedback before owner resolution`, () => {
+    const installSource = installFunctionSource(source);
+    const pendingClaim = installSource.indexOf(
+      "pendingInstallTokensRef.current.set(initialStoreKey, pendingToken);",
+    );
+    const ownerResolution = installSource.indexOf("await resolveClawHubSkillOwner(skill);");
+
+    assert.notEqual(pendingClaim, -1);
+    assert.notEqual(ownerResolution, -1);
+    assert.ok(pendingClaim < ownerResolution, "pending state must be claimed before the first await");
+    assert.match(
+      installSource,
+      /pendingInstallTokensRef\.current\.has\(initialStoreKey\)/,
+    );
+    assert.match(installSource, /finally \{[\s\S]*token !== pendingToken[\s\S]*delete\(storeKey\)/);
+  });
+
+  test(`${label} renders pending progress in cards and the preview drawer`, () => {
+    assert.match(source, /pendingInstallKeys=\{pendingInstallKeys\}/);
+    assert.match(source, /installing: pending \|\| Boolean\(job && !terminalJob\)/);
+    assert.match(source, /\{installing && !done \? \(/);
+    assert.match(source, /installState\.installing && !installState\.done/);
+    assert.match(source, /aria-busy=\{installing\}/);
+    assert.match(source, /aria-busy=\{installState\.installing\}/);
+  });
+}
diff --git a/docs/features/skills-and-mcp.md b/docs/features/skills-and-mcp.md
index 47ab1a026..f81975aae 100644
--- a/docs/features/skills-and-mcp.md
+++ b/docs/features/skills-and-mcp.md
@@ -35,6 +35,16 @@
 
 另有 UI 专用的后台安装 job 动作（不在 agent 工具 schema 内）：`install_start` 启动带进度的后台安装线程、`install_status` 轮询快照、`install_cancel` 协作式取消（下载与逐 skill 安装循环检查取消标记，终态为 `phase: "cancelled"`）。
 
+## ClawHub 兼容边界
+
+| 场景 | 处理规则 |
+|---|---|
+| Store identity | ClawHub Skill 以 `ownerHandle + slug` 作为唯一身份；React key、安装任务、已安装状态和 `_meta.json` 回读不得只按 slug 合并。 |
+| list 缺 owner | `/api/v1/skills` 条目缺少发布者时，详情/安装前通过精确搜索按 `updatedAt`、version、downloads 等字段懒解析 owner；无法唯一匹配时明确失败，不盲选发布者。 |
+| 下载/详情 | 所有已解析的详情和 `/api/v1/download` 请求都携带 `ownerHandle`，避免重名 slug 返回 HTTP 409。 |
+| 非便携名称 | 仍严格执行 Agent Skills 小写名称规范；只有 ClawHub 单 Skill 包的非法名称归一化后与 registry slug 完全一致时，才改写临时副本并把原名、规范名和转换类型写入 `_meta.json`。 |
+| 原始内容 | 名称兼容转换只发生在下载临时目录，不修改注册表下载包；其他名称不匹配继续按严格校验拒绝。 |
+
 ## Skills 选择与 Prompt 注入
 
 | 阶段 | 说明 |
@@ -82,7 +92,7 @@ Registry card 会被归一化为统一的 `McpRegistryCard`，其中 `installDra
 
 | 区域 | 注意事项 |
 |---|---|
-| Skills Hub | GUI/WebUI 都有 installed/store、preview drawer、install job 状态和 installedBySlug 推导。 |
+| Skills Hub | GUI/WebUI 都有 installed/store、preview drawer、install job 状态，并以 `ownerHandle + slug` 推导 ClawHub 安装身份。 |
 | MCP Hub | GUI/WebUI 都有 server form、registry browser、preview drawer、install draft。 |
 | i18n | 双端有各自 `i18n/config.ts`，新增文案要同步。 |
 | settings sync | Skills/MCP settings 从 GUI 经 Gateway 同步到 WebUI，WebUI 修改再回写 GUI。 |

From 023272d3aee2f7da40db9b3336169e3e15f92d91 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 12:42:31 +0800
Subject: [PATCH 4/7] feat(file-tree): add hidden file visibility toggle

---
 .../internal/proto/v1/gateway.pb.go           |  54 +++-
 .../internal/server/websocket_fs_handlers.go  |   2 +
 .../internal/server/websocket_payload_test.go |   5 +-
 .../server/websocket_skills_handlers.go       |   7 +-
 crates/agent-gateway/proto/v1/gateway.proto   |   4 +
 .../project-tools/file-tree/ContextMenu.tsx   |  22 ++
 .../project-tools/file-tree/Row.tsx           |  12 +-
 .../project-tools/file-tree/index.tsx         |  10 +-
 .../project-tools/file-tree/model.ts          |  15 +-
 .../file-tree/useFileTreeData.ts              |  12 +
 crates/agent-gateway/web/src/i18n/config.ts   |   4 +
 .../web/src/lib/gatewaySocket.ts              |  10 +-
 .../web/src/lib/settings/index.ts             |   5 +
 .../agent-gateway/web/src/shims/tauriCore.ts  |   2 +
 .../src-tauri/src/commands/workspace/fs.rs    | 285 ++++++++++++++++--
 .../src-tauri/src/services/gateway_bridge.rs  |  18 +-
 .../project-tools/file-tree/ContextMenu.tsx   |  22 ++
 .../project-tools/file-tree/Row.tsx           |  12 +-
 .../project-tools/file-tree/index.tsx         |  10 +-
 .../project-tools/file-tree/model.ts          |  15 +-
 .../file-tree/useFileTreeData.ts              |  12 +
 crates/agent-gui/src/i18n/config.ts           |   4 +
 crates/agent-gui/src/lib/settings/index.ts    |   5 +
 23 files changed, 496 insertions(+), 51 deletions(-)

diff --git a/crates/agent-gateway/internal/proto/v1/gateway.pb.go b/crates/agent-gateway/internal/proto/v1/gateway.pb.go
index e348a30be..a2f4a1305 100644
--- a/crates/agent-gateway/internal/proto/v1/gateway.pb.go
+++ b/crates/agent-gateway/internal/proto/v1/gateway.pb.go
@@ -8974,6 +8974,7 @@ type FileMentionListRequest struct {
 	Workdir       string                 `protobuf:"bytes,1,opt,name=workdir,proto3" json:"workdir,omitempty"`
 	MaxResults    uint32                 `protobuf:"varint,2,opt,name=max_results,json=maxResults,proto3" json:"max_results,omitempty"`
 	Query         string                 `protobuf:"bytes,3,opt,name=query,proto3" json:"query,omitempty"`
+	ShowHidden    *bool                  `protobuf:"varint,4,opt,name=show_hidden,json=showHidden,proto3,oneof" json:"show_hidden,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
 }
@@ -9029,10 +9030,18 @@ func (x *FileMentionListRequest) GetQuery() string {
 	return ""
 }
 
+func (x *FileMentionListRequest) GetShowHidden() bool {
+	if x != nil && x.ShowHidden != nil {
+		return *x.ShowHidden
+	}
+	return false
+}
+
 type FileMentionEntry struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	Path          string                 `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
 	Kind          string                 `protobuf:"bytes,2,opt,name=kind,proto3" json:"kind,omitempty"`
+	Hidden        bool                   `protobuf:"varint,3,opt,name=hidden,proto3" json:"hidden,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
 }
@@ -9081,6 +9090,13 @@ func (x *FileMentionEntry) GetKind() string {
 	return ""
 }
 
+func (x *FileMentionEntry) GetHidden() bool {
+	if x != nil {
+		return x.Hidden
+	}
+	return false
+}
+
 type FileMentionListResponse struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	Entries       []*FileMentionEntry    `protobuf:"bytes,1,rep,name=entries,proto3" json:"entries,omitempty"`
@@ -9548,6 +9564,7 @@ type FsListRequest struct {
 	Depth         uint32                 `protobuf:"varint,3,opt,name=depth,proto3" json:"depth,omitempty"`
 	Offset        uint32                 `protobuf:"varint,4,opt,name=offset,proto3" json:"offset,omitempty"`
 	MaxResults    uint32                 `protobuf:"varint,5,opt,name=max_results,json=maxResults,proto3" json:"max_results,omitempty"`
+	ShowHidden    *bool                  `protobuf:"varint,6,opt,name=show_hidden,json=showHidden,proto3,oneof" json:"show_hidden,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
 }
@@ -9617,10 +9634,18 @@ func (x *FsListRequest) GetMaxResults() uint32 {
 	return 0
 }
 
+func (x *FsListRequest) GetShowHidden() bool {
+	if x != nil && x.ShowHidden != nil {
+		return *x.ShowHidden
+	}
+	return false
+}
+
 type FsListEntry struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	Path          string                 `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
 	Kind          string                 `protobuf:"bytes,2,opt,name=kind,proto3" json:"kind,omitempty"`
+	Hidden        bool                   `protobuf:"varint,3,opt,name=hidden,proto3" json:"hidden,omitempty"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
 }
@@ -9669,6 +9694,13 @@ func (x *FsListEntry) GetKind() string {
 	return ""
 }
 
+func (x *FsListEntry) GetHidden() bool {
+	if x != nil {
+		return x.Hidden
+	}
+	return false
+}
+
 type FsListResponse struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	Path          string                 `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
@@ -11447,15 +11479,19 @@ const file_proto_v1_gateway_proto_rawDesc = "" +
 	"\fpayload_json\x18\x01 \x01(\tR\vpayloadJson\"6\n" +
 	"\x13SkillManageResponse\x12\x1f\n" +
 	"\vresult_json\x18\x01 \x01(\tR\n" +
-	"resultJson\"i\n" +
+	"resultJson\"\x9f\x01\n" +
 	"\x16FileMentionListRequest\x12\x18\n" +
 	"\aworkdir\x18\x01 \x01(\tR\aworkdir\x12\x1f\n" +
 	"\vmax_results\x18\x02 \x01(\rR\n" +
 	"maxResults\x12\x14\n" +
-	"\x05query\x18\x03 \x01(\tR\x05query\":\n" +
+	"\x05query\x18\x03 \x01(\tR\x05query\x12$\n" +
+	"\vshow_hidden\x18\x04 \x01(\bH\x00R\n" +
+	"showHidden\x88\x01\x01B\x0e\n" +
+	"\f_show_hidden\"R\n" +
 	"\x10FileMentionEntry\x12\x12\n" +
 	"\x04path\x18\x01 \x01(\tR\x04path\x12\x12\n" +
-	"\x04kind\x18\x02 \x01(\tR\x04kind\"y\n" +
+	"\x04kind\x18\x02 \x01(\tR\x04kind\x12\x16\n" +
+	"\x06hidden\x18\x03 \x01(\bR\x06hidden\"y\n" +
 	"\x17FileMentionListResponse\x12@\n" +
 	"\aentries\x18\x01 \x03(\v2&.liveagent.gateway.v1.FileMentionEntryR\aentries\x12\x1c\n" +
 	"\ttruncated\x18\x02 \x01(\bR\ttruncated\"V\n" +
@@ -11483,17 +11519,21 @@ const file_proto_v1_gateway_proto_rawDesc = "" +
 	"\x06parent\x18\x01 \x01(\tR\x06parent\x12\x12\n" +
 	"\x04name\x18\x02 \x01(\tR\x04name\"3\n" +
 	"\x1dFsCreateProjectFolderResponse\x12\x12\n" +
-	"\x04path\x18\x01 \x01(\tR\x04path\"\x8c\x01\n" +
+	"\x04path\x18\x01 \x01(\tR\x04path\"\xc2\x01\n" +
 	"\rFsListRequest\x12\x18\n" +
 	"\aworkdir\x18\x01 \x01(\tR\aworkdir\x12\x12\n" +
 	"\x04path\x18\x02 \x01(\tR\x04path\x12\x14\n" +
 	"\x05depth\x18\x03 \x01(\rR\x05depth\x12\x16\n" +
 	"\x06offset\x18\x04 \x01(\rR\x06offset\x12\x1f\n" +
 	"\vmax_results\x18\x05 \x01(\rR\n" +
-	"maxResults\"5\n" +
+	"maxResults\x12$\n" +
+	"\vshow_hidden\x18\x06 \x01(\bH\x00R\n" +
+	"showHidden\x88\x01\x01B\x0e\n" +
+	"\f_show_hidden\"M\n" +
 	"\vFsListEntry\x12\x12\n" +
 	"\x04path\x18\x01 \x01(\tR\x04path\x12\x12\n" +
-	"\x04kind\x18\x02 \x01(\tR\x04kind\"\xfc\x01\n" +
+	"\x04kind\x18\x02 \x01(\tR\x04kind\x12\x16\n" +
+	"\x06hidden\x18\x03 \x01(\bR\x06hidden\"\xfc\x01\n" +
 	"\x0eFsListResponse\x12\x12\n" +
 	"\x04path\x18\x01 \x01(\tR\x04path\x12\x19\n" +
 	"\bhas_path\x18\x02 \x01(\bR\ahasPath\x12\x14\n" +
@@ -12025,6 +12065,8 @@ func file_proto_v1_gateway_proto_init() {
 	file_proto_v1_gateway_proto_msgTypes[17].OneofWrappers = []any{}
 	file_proto_v1_gateway_proto_msgTypes[25].OneofWrappers = []any{}
 	file_proto_v1_gateway_proto_msgTypes[76].OneofWrappers = []any{}
+	file_proto_v1_gateway_proto_msgTypes[103].OneofWrappers = []any{}
+	file_proto_v1_gateway_proto_msgTypes[114].OneofWrappers = []any{}
 	type x struct{}
 	out := protoimpl.TypeBuilder{
 		File: protoimpl.DescBuilder{
diff --git a/crates/agent-gateway/internal/server/websocket_fs_handlers.go b/crates/agent-gateway/internal/server/websocket_fs_handlers.go
index cb5ea909f..9c8c7b3f5 100644
--- a/crates/agent-gateway/internal/server/websocket_fs_handlers.go
+++ b/crates/agent-gateway/internal/server/websocket_fs_handlers.go
@@ -176,6 +176,7 @@ func (c *websocketConnection) handleFsList(req websocketRequest) {
 		Depth      *int   `json:"depth"`
 		Offset     *int   `json:"offset"`
 		MaxResults *int   `json:"max_results"`
+		ShowHidden *bool  `json:"show_hidden"`
 	}
 
 	var body payload
@@ -216,6 +217,7 @@ func (c *websocketConnection) handleFsList(req websocketRequest) {
 				Depth:      depth,
 				Offset:     offset,
 				MaxResults: maxResults,
+				ShowHidden: body.ShowHidden,
 			},
 		},
 	})
diff --git a/crates/agent-gateway/internal/server/websocket_payload_test.go b/crates/agent-gateway/internal/server/websocket_payload_test.go
index 8a7efdcef..fb7b96997 100644
--- a/crates/agent-gateway/internal/server/websocket_payload_test.go
+++ b/crates/agent-gateway/internal/server/websocket_payload_test.go
@@ -198,7 +198,7 @@ func TestWebsocketFsPayloadsUseFrontendFieldNames(t *testing.T) {
 		Total:      3,
 		HasMore:    true,
 		Entries: []*gatewayv1.FsListEntry{
-			{Path: "src/components", Kind: "dir"},
+			{Path: "src/components", Kind: "dir", Hidden: true},
 			{Path: "src/app.tsx", Kind: "file"},
 		},
 	})
@@ -218,6 +218,9 @@ func TestWebsocketFsPayloadsUseFrontendFieldNames(t *testing.T) {
 	if entries[0]["path"] != "src/components" || entries[0]["kind"] != "dir" {
 		t.Fatalf("fs.list first entry = %#v", entries[0])
 	}
+	if entries[0]["hidden"] != true || entries[1]["hidden"] != false {
+		t.Fatalf("fs.list hidden flags = %#v", entries)
+	}
 
 	readEditable := websocketFsReadEditableTextResponsePayload(&gatewayv1.FsReadEditableTextResponse{
 		Path:        "src/main.ts",
diff --git a/crates/agent-gateway/internal/server/websocket_skills_handlers.go b/crates/agent-gateway/internal/server/websocket_skills_handlers.go
index c140cfcf6..920729287 100644
--- a/crates/agent-gateway/internal/server/websocket_skills_handlers.go
+++ b/crates/agent-gateway/internal/server/websocket_skills_handlers.go
@@ -43,6 +43,7 @@ func (c *websocketConnection) handleFileMentionList(req websocketRequest) {
 		Workdir    string `json:"workdir"`
 		MaxResults *int   `json:"max_results"`
 		Query      string `json:"query"`
+		ShowHidden *bool  `json:"show_hidden"`
 	}
 
 	var body payload
@@ -72,6 +73,7 @@ func (c *websocketConnection) handleFileMentionList(req websocketRequest) {
 				Workdir:    workdir,
 				MaxResults: maxResults,
 				Query:      query,
+				ShowHidden: body.ShowHidden,
 			},
 		},
 	})
@@ -93,8 +95,9 @@ func (c *websocketConnection) handleFileMentionList(req websocketRequest) {
 	entries := make([]map[string]any, 0, len(resp.GetEntries()))
 	for _, entry := range resp.GetEntries() {
 		entries = append(entries, map[string]any{
-			"path": entry.GetPath(),
-			"kind": entry.GetKind(),
+			"path":   entry.GetPath(),
+			"kind":   entry.GetKind(),
+			"hidden": entry.GetHidden(),
 		})
 	}
 
diff --git a/crates/agent-gateway/proto/v1/gateway.proto b/crates/agent-gateway/proto/v1/gateway.proto
index d4b70b0a8..c35bd1821 100644
--- a/crates/agent-gateway/proto/v1/gateway.proto
+++ b/crates/agent-gateway/proto/v1/gateway.proto
@@ -915,11 +915,13 @@ message FileMentionListRequest {
   string workdir = 1;
   uint32 max_results = 2;
   string query = 3;
+  optional bool show_hidden = 4;
 }
 
 message FileMentionEntry {
   string path = 1;
   string kind = 2;
+  bool hidden = 3;
 }
 
 message FileMentionListResponse {
@@ -969,11 +971,13 @@ message FsListRequest {
   uint32 depth = 3;
   uint32 offset = 4;
   uint32 max_results = 5;
+  optional bool show_hidden = 6;
 }
 
 message FsListEntry {
   string path = 1;
   string kind = 2;
+  bool hidden = 3;
 }
 
 message FsListResponse {
diff --git a/crates/agent-gateway/web/src/components/project-tools/file-tree/ContextMenu.tsx b/crates/agent-gateway/web/src/components/project-tools/file-tree/ContextMenu.tsx
index d8005b67a..2fc22c268 100644
--- a/crates/agent-gateway/web/src/components/project-tools/file-tree/ContextMenu.tsx
+++ b/crates/agent-gateway/web/src/components/project-tools/file-tree/ContextMenu.tsx
@@ -21,6 +21,7 @@ import {
   Edit3,
   ExternalLink,
   Eye,
+  EyeOff,
   FilePenLine,
   Folder,
   FolderOpen,
@@ -70,6 +71,7 @@ export type FileTreeContextMenuProps = {
   canMutate: boolean;
   canOpenFile: boolean;
   canInsertMention: boolean;
+  showHidden: boolean;
   onClose: () => void;
   onOpenFile: (path: string) => void;
   onOpenExternal: (path: string) => void;
@@ -78,6 +80,7 @@ export type FileTreeContextMenuProps = {
   onDelete: (path: string) => void;
   onInsertMention: (path: string) => void;
   onRefresh: (path: string, kind: FileTreeKind) => void;
+  onToggleHidden: () => void;
   onActionError: (message: string) => void;
 };
 
@@ -90,6 +93,7 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
     canMutate,
     canOpenFile,
     canInsertMention,
+    showHidden,
     onClose,
     onOpenFile,
     onOpenExternal,
@@ -98,6 +102,7 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
     onDelete,
     onInsertMention,
     onRefresh,
+    onToggleHidden,
     onActionError,
   } = props;
   const { t } = useLocale();
@@ -277,6 +282,23 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
         {t("projectTools.fileTree.delete")}
       </button>
       <div className="mx-1 my-1 h-px bg-border/60" />
+      <button
+        type="button"
+        role="menuitemcheckbox"
+        aria-checked={showHidden}
+        className={MENU_ITEM_CLASS}
+        onClick={() => {
+          onToggleHidden();
+          onClose();
+        }}
+      >
+        {showHidden ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+        {t(
+          showHidden
+            ? "projectTools.fileTree.hideHiddenFiles"
+            : "projectTools.fileTree.showHiddenFiles",
+        )}
+      </button>
       <button
         type="button"
         role="menuitem"
diff --git a/crates/agent-gateway/web/src/components/project-tools/file-tree/Row.tsx b/crates/agent-gateway/web/src/components/project-tools/file-tree/Row.tsx
index 7c9ece0c4..fe99b5ba6 100644
--- a/crates/agent-gateway/web/src/components/project-tools/file-tree/Row.tsx
+++ b/crates/agent-gateway/web/src/components/project-tools/file-tree/Row.tsx
@@ -16,6 +16,7 @@ export type FileTreeRowProps = {
   path: string;
   name: string;
   kind: FileTreeKind;
+  hidden: boolean;
   depth: number;
   expanded: boolean;
   selected: boolean;
@@ -34,6 +35,7 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
     path,
     name,
     kind,
+    hidden,
     depth,
     expanded,
     selected,
@@ -62,7 +64,10 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
       {kind === "dir" ? (
         <button
           type="button"
-          className="flex h-5 w-5 shrink-0 items-center justify-center rounded hover:bg-background"
+          className={cn(
+            "flex h-5 w-5 shrink-0 items-center justify-center rounded hover:bg-background",
+            hidden && "opacity-60 group-hover:opacity-80",
+          )}
           onClick={() => onToggle(path, expanded)}
           title={expanded ? t("projectTools.fileTree.collapse") : t("projectTools.fileTree.expand")}
         >
@@ -79,7 +84,10 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
       )}
       <button
         type="button"
-        className="flex min-w-0 flex-1 items-center gap-1.5 bg-transparent p-0 text-left text-inherit leading-5"
+        className={cn(
+          "flex min-w-0 flex-1 items-center gap-1.5 bg-transparent p-0 text-left text-inherit leading-5",
+          hidden && "opacity-60 group-hover:opacity-80",
+        )}
         title={title}
         onClick={() => onSelect(path)}
         onDoubleClick={() => {
diff --git a/crates/agent-gateway/web/src/components/project-tools/file-tree/index.tsx b/crates/agent-gateway/web/src/components/project-tools/file-tree/index.tsx
index 3ebe6fc39..0dfafd546 100644
--- a/crates/agent-gateway/web/src/components/project-tools/file-tree/index.tsx
+++ b/crates/agent-gateway/web/src/components/project-tools/file-tree/index.tsx
@@ -17,6 +17,7 @@ import {
 } from "react";
 import { useLocale } from "../../../i18n";
 import type { RightDockFileTreeStatePatch } from "../../../lib/settings";
+import { cn } from "../../../lib/shared/utils";
 import { getFileTypeIcon } from "../../chat/fileTypeIcons";
 import { Check, FolderOpen, Loader2, RefreshCw, Search, Trash2, X } from "../../icons";
 import { Button } from "../../ui/button";
@@ -89,6 +90,7 @@ export function FileTreePanel(props: { active: boolean }) {
     workspaceActivityClient: context.clients.workspaceActivity ?? null,
     expandedPaths: syncState.expandedPaths,
     query,
+    showHidden: syncState.showHidden,
   });
 
   const nodesRef = useRef(nodes);
@@ -546,7 +548,10 @@ export function FileTreePanel(props: { active: boolean }) {
                 <button
                   key={`${entry.kind}:${entry.path}`}
                   type="button"
-                  className="flex w-full select-none items-center gap-1.5 rounded-md px-2 text-left text-xs leading-5 text-muted-foreground hover:bg-muted hover:text-foreground"
+                  className={cn(
+                    "flex w-full select-none items-center gap-1.5 rounded-md px-2 text-left text-xs leading-5 text-muted-foreground hover:bg-muted hover:text-foreground",
+                    entry.hidden && "opacity-60 hover:opacity-80",
+                  )}
                   style={{ minHeight: FILE_TREE_ROW_HEIGHT }}
                   title={entry.path}
                   onClick={() => void revealPath(entry.path, entry.kind)}
@@ -602,6 +607,7 @@ export function FileTreePanel(props: { active: boolean }) {
                   path={node.path}
                   name={node.name}
                   kind={node.kind}
+                  hidden={node.hidden}
                   depth={row.depth}
                   expanded={expandedSet.has(row.path)}
                   selected={selectedPath === row.path}
@@ -628,6 +634,7 @@ export function FileTreePanel(props: { active: boolean }) {
           canMutate={canMutate}
           canOpenFile={Boolean(fileTree.onOpenFile)}
           canInsertMention={Boolean(fileTree.onInsertFileMention)}
+          showHidden={syncState.showHidden}
           onClose={() => setContextMenu(null)}
           onOpenFile={handleOpenFile}
           onOpenExternal={handleOpenExternal}
@@ -636,6 +643,7 @@ export function FileTreePanel(props: { active: boolean }) {
           onDelete={(path) => void deletePath(path)}
           onInsertMention={handleInsertMention}
           onRefresh={handleMenuRefresh}
+          onToggleHidden={() => emitState({ showHidden: !syncState.showHidden })}
           onActionError={setActionError}
         />
       ) : null}
diff --git a/crates/agent-gateway/web/src/components/project-tools/file-tree/model.ts b/crates/agent-gateway/web/src/components/project-tools/file-tree/model.ts
index bbb7921b9..79565771c 100644
--- a/crates/agent-gateway/web/src/components/project-tools/file-tree/model.ts
+++ b/crates/agent-gateway/web/src/components/project-tools/file-tree/model.ts
@@ -10,12 +10,13 @@ import type { WorkspaceActivityEventPayload } from "../../../lib/workspace-activ
 
 export type FileTreeKind = "file" | "dir";
 
-export type FileTreeEntry = { path: string; kind: FileTreeKind };
+export type FileTreeEntry = { path: string; kind: FileTreeKind; hidden: boolean };
 
 export type FileTreeNode = {
   path: string;
   name: string;
   kind: FileTreeKind;
+  hidden: boolean;
   children: string[];
   loaded: boolean;
   loading: boolean;
@@ -91,6 +92,7 @@ export function createRootNode(cwd: string): FileTreeNode {
     path: ROOT_PATH,
     name: rootName(cwd),
     kind: "dir",
+    hidden: false,
     children: [],
     loaded: false,
     loading: false,
@@ -167,13 +169,22 @@ export function applyFileTreeListResponse(
     if (!entry.path) continue;
     childPaths.push(entry.path);
     const name = basename(entry.path) || entry.path;
+    const hidden = parent.hidden || entry.hidden;
     const existing = nodes[entry.path];
-    if (existing && existing.kind === entry.kind && existing.name === name) continue;
+    if (
+      existing &&
+      existing.kind === entry.kind &&
+      existing.name === name &&
+      existing.hidden === hidden
+    ) {
+      continue;
+    }
     const sameKind = existing !== undefined && existing.kind === entry.kind;
     next[entry.path] = {
       path: entry.path,
       name,
       kind: entry.kind,
+      hidden,
       children: sameKind ? existing.children : [],
       loaded: sameKind ? existing.loaded : false,
       loading: false,
diff --git a/crates/agent-gateway/web/src/components/project-tools/file-tree/useFileTreeData.ts b/crates/agent-gateway/web/src/components/project-tools/file-tree/useFileTreeData.ts
index 1e90135bc..791d91d27 100644
--- a/crates/agent-gateway/web/src/components/project-tools/file-tree/useFileTreeData.ts
+++ b/crates/agent-gateway/web/src/components/project-tools/file-tree/useFileTreeData.ts
@@ -81,6 +81,7 @@ export type UseFileTreeDataOptions = {
   expandedPaths: string[];
   // Live search input (the panel debounces persistence separately).
   query: string;
+  showHidden: boolean;
 };
 
 export type UseFileTreeDataResult = {
@@ -104,6 +105,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     workspaceActivityClient,
     expandedPaths,
     query,
+    showHidden,
   } = options;
   const { t } = useLocale();
 
@@ -132,6 +134,8 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     queryRef.current = query;
   }, [query]);
 
+  const showHiddenRef = useRef(showHidden);
+
   const activeRef = useRef(active);
 
   // All bucket mutations go through here: pure computation first, then a
@@ -201,6 +205,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
           depth: 1,
           offset: 0,
           max_results: FILE_TREE_LIST_MAX_RESULTS,
+          show_hidden: showHiddenRef.current,
         });
         // Out-of-order protection: a response only lands if it belongs to the
         // newest request issued for this path.
@@ -273,6 +278,12 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     [bumpSearchRefresh, cwd, loadChildren, projectPathKey],
   );
 
+  useEffect(() => {
+    if (showHiddenRef.current === showHidden) return;
+    showHiddenRef.current = showHidden;
+    refreshVisible();
+  }, [refreshVisible, showHidden]);
+
   // ---------------------------------------------------------------------
   // Workspace-activity invalidation (replaces the old 3s full polling)
   // ---------------------------------------------------------------------
@@ -352,6 +363,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
         workdir: cwd,
         query,
         max_results: FILE_TREE_SEARCH_MAX_RESULTS,
+        show_hidden: showHiddenRef.current,
       })
         .then((response) => {
           if (cancelled) return;
diff --git a/crates/agent-gateway/web/src/i18n/config.ts b/crates/agent-gateway/web/src/i18n/config.ts
index d97faaae8..c83d0d5e1 100644
--- a/crates/agent-gateway/web/src/i18n/config.ts
+++ b/crates/agent-gateway/web/src/i18n/config.ts
@@ -637,6 +637,8 @@ export const translations: Record<Locale, Record<string, string>> = {
     "projectTools.fileTree.renamePlaceholder": "新名称",
     "projectTools.fileTree.searchPlaceholder": "搜索文件",
     "projectTools.fileTree.refresh": "刷新",
+    "projectTools.fileTree.showHiddenFiles": "显示隐藏文件",
+    "projectTools.fileTree.hideHiddenFiles": "隐藏隐藏文件",
     "projectTools.fileTree.searching": "搜索中...",
     "projectTools.fileTree.noMatches": "无匹配结果",
     "projectTools.fileTree.resultsTruncated": "结果已截断",
@@ -2360,6 +2362,8 @@ export const translations: Record<Locale, Record<string, string>> = {
     "projectTools.fileTree.renamePlaceholder": "New name",
     "projectTools.fileTree.searchPlaceholder": "Search files",
     "projectTools.fileTree.refresh": "Refresh",
+    "projectTools.fileTree.showHiddenFiles": "Show Hidden Files",
+    "projectTools.fileTree.hideHiddenFiles": "Hide Hidden Files",
     "projectTools.fileTree.searching": "Searching...",
     "projectTools.fileTree.noMatches": "No matches",
     "projectTools.fileTree.resultsTruncated": "Results truncated",
diff --git a/crates/agent-gateway/web/src/lib/gatewaySocket.ts b/crates/agent-gateway/web/src/lib/gatewaySocket.ts
index 75b0ee95b..eea4bdc33 100644
--- a/crates/agent-gateway/web/src/lib/gatewaySocket.ts
+++ b/crates/agent-gateway/web/src/lib/gatewaySocket.ts
@@ -130,7 +130,7 @@ export type SshKnownHostResetResult = {
 };
 
 type MentionListResponse = {
-  entries: Array<{ path: string; kind: "file" | "dir" }>;
+  entries: Array<{ path: string; kind: "file" | "dir"; hidden: boolean }>;
   truncated: boolean;
 };
 
@@ -158,7 +158,7 @@ type FsListResponse = {
   maxResults: number;
   total: number;
   hasMore: boolean;
-  entries: Array<{ path: string; kind: "file" | "dir" }>;
+  entries: Array<{ path: string; kind: "file" | "dir"; hidden: boolean }>;
 };
 
 type FsWriteTextResponse = {
@@ -2245,11 +2245,13 @@ export class GatewayWebSocketClient {
     workdir: string,
     maxResults?: number,
     query?: string,
+    showHidden?: boolean,
   ): Promise<MentionListResponse> {
     return this.requestWithRecovery<MentionListResponse>("mentions.list", {
       workdir,
       max_results: maxResults,
       query,
+      show_hidden: showHidden,
     });
   }
 
@@ -2277,6 +2279,7 @@ export class GatewayWebSocketClient {
     depth?: number,
     offset?: number,
     maxResults?: number,
+    showHidden?: boolean,
   ): Promise<FsListResponse> {
     return this.requestWithRecovery<FsListResponse>("fs.list", {
       workdir,
@@ -2284,6 +2287,7 @@ export class GatewayWebSocketClient {
       depth,
       offset,
       max_results: maxResults,
+      show_hidden: showHidden,
     });
   }
 
@@ -3361,6 +3365,7 @@ export type GatewayWebSocketClientLike = {
     workdir: string,
     maxResults?: number,
     query?: string,
+    showHidden?: boolean,
   ): Promise<MentionListResponse>;
   listFsRoots(): Promise<FsRootsResponse>;
   listDirs(path: string, maxResults?: number): Promise<FsListDirsResponse>;
@@ -3371,6 +3376,7 @@ export type GatewayWebSocketClientLike = {
     depth?: number,
     offset?: number,
     maxResults?: number,
+    showHidden?: boolean,
   ): Promise<FsListResponse>;
   writeTextFile(params: {
     workdir: string;
diff --git a/crates/agent-gateway/web/src/lib/settings/index.ts b/crates/agent-gateway/web/src/lib/settings/index.ts
index 532f84876..f78ea7b56 100644
--- a/crates/agent-gateway/web/src/lib/settings/index.ts
+++ b/crates/agent-gateway/web/src/lib/settings/index.ts
@@ -103,6 +103,7 @@ export type RightDockFileTreeState = {
   query: string;
   selectedPath: string;
   expandedPaths: string[];
+  showHidden: boolean;
   // Reveal nonce: bumped (via bumpRevision) when another surface asks the
   // file tree to reveal selectedPath (expand ancestors + scroll into view).
   // Content refreshes are driven by workspace-activity invalidation, and
@@ -1642,6 +1643,7 @@ export const DEFAULT_RIGHT_DOCK_FILE_TREE_STATE: RightDockFileTreeState = {
   query: "",
   selectedPath: "",
   expandedPaths: [""],
+  showHidden: false,
   revision: 0,
 };
 
@@ -1667,6 +1669,7 @@ export function normalizeRightDockFileTreeState(input: unknown): RightDockFileTr
     query: normalizeRightDockFileTreeSearchQuery(obj.query),
     selectedPath: normalizeRightDockFileTreePath(obj.selectedPath),
     expandedPaths: normalizeRightDockFileTreeExpandedPaths(obj.expandedPaths),
+    showHidden: obj.showHidden === true,
     revision: normalizeIntegerInRange(obj.revision, 0, Number.MAX_SAFE_INTEGER, 0),
   };
 }
@@ -2117,6 +2120,7 @@ function rightDockFileTreeStateEqual(
   return (
     left.query === right.query &&
     left.selectedPath === right.selectedPath &&
+    left.showHidden === right.showHidden &&
     left.revision === right.revision &&
     left.expandedPaths.length === right.expandedPaths.length &&
     left.expandedPaths.every((path, index) => path === right.expandedPaths[index])
@@ -2300,6 +2304,7 @@ export function updateRightDockFileTreeState(
       patch.expandedPaths !== undefined
         ? normalizeRightDockFileTreeExpandedPaths(patch.expandedPaths)
         : current.expandedPaths,
+    showHidden: patch.showHidden ?? current.showHidden,
     revision: patch.bumpRevision
       ? current.revision + 1
       : patch.revision !== undefined
diff --git a/crates/agent-gateway/web/src/shims/tauriCore.ts b/crates/agent-gateway/web/src/shims/tauriCore.ts
index 00ef1f895..18af5032d 100644
--- a/crates/agent-gateway/web/src/shims/tauriCore.ts
+++ b/crates/agent-gateway/web/src/shims/tauriCore.ts
@@ -229,6 +229,7 @@ export async function invoke<T>(command: string, args?: Record<string, unknown>)
         typeof args?.depth === "number" ? args.depth : undefined,
         typeof args?.offset === "number" ? args.offset : undefined,
         typeof args?.max_results === "number" ? args.max_results : undefined,
+        typeof args?.show_hidden === "boolean" ? args.show_hidden : undefined,
       )) as T;
     case "fs_write_text":
       return (await getGatewayWebSocketClient(loadToken().trim()).writeTextFile({
@@ -272,6 +273,7 @@ export async function invoke<T>(command: string, args?: Record<string, unknown>)
         String(args?.workdir ?? ""),
         typeof args?.max_results === "number" ? args.max_results : undefined,
         typeof args?.query === "string" ? args.query : undefined,
+        typeof args?.show_hidden === "boolean" ? args.show_hidden : undefined,
       )) as T;
     case "system_list_skill_files":
       return (await getGatewayWebSocketClient(loadToken().trim()).listSkillFiles()) as T;
diff --git a/crates/agent-gui/src-tauri/src/commands/workspace/fs.rs b/crates/agent-gui/src-tauri/src/commands/workspace/fs.rs
index 2615f537d..8209663d8 100644
--- a/crates/agent-gui/src-tauri/src/commands/workspace/fs.rs
+++ b/crates/agent-gui/src-tauri/src/commands/workspace/fs.rs
@@ -6,7 +6,7 @@ use reqwest::header::{CONTENT_LENGTH, CONTENT_TYPE};
 use reqwest::Url;
 use serde::Serialize;
 use serde_json::Value;
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, HashSet};
 use std::fs;
 use std::io::{self, Cursor, Read, Seek};
 use std::path::{Component, Path, PathBuf};
@@ -3452,6 +3452,7 @@ pub async fn fs_rename(
 pub struct ListEntry {
     pub path: String,
     pub kind: String,
+    pub hidden: bool,
 }
 
 #[derive(Debug, Serialize)]
@@ -3629,31 +3630,100 @@ pub async fn fs_list_dirs(
     run_blocking("fs_list_dirs", move || fs_list_dirs_sync(path, max_results)).await
 }
 
-fn build_ignore_walker(base: &Path, max_depth: Option<usize>) -> ignore::Walk {
+#[derive(Clone, Copy)]
+struct WalkerVisibility {
+    include_system_hidden: bool,
+    include_ignored: bool,
+}
+
+fn requested_visibility(
+    show_hidden: Option<bool>,
+    default_include_system_hidden: bool,
+) -> WalkerVisibility {
+    WalkerVisibility {
+        include_system_hidden: show_hidden.unwrap_or(default_include_system_hidden),
+        include_ignored: show_hidden == Some(true),
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn has_macos_hidden_flag(entry: &ignore::DirEntry) -> bool {
+    use std::os::macos::fs::MetadataExt;
+
+    const UF_HIDDEN: u32 = 0x0000_8000;
+    entry
+        .metadata()
+        .is_ok_and(|metadata| metadata.st_flags() & UF_HIDDEN != 0)
+}
+
+#[cfg(not(target_os = "macos"))]
+fn has_macos_hidden_flag(_entry: &ignore::DirEntry) -> bool {
+    false
+}
+
+fn build_workspace_walker(
+    base: &Path,
+    max_depth: Option<usize>,
+    visibility: WalkerVisibility,
+    skip_common_dirs: bool,
+) -> ignore::Walk {
     let mut builder = WalkBuilder::new(base);
     builder
-        .hidden(false)
-        .ignore(true)
-        .git_ignore(true)
-        .git_global(true)
-        .git_exclude(true)
+        .hidden(!visibility.include_system_hidden)
+        .ignore(!visibility.include_ignored)
+        .git_ignore(!visibility.include_ignored)
+        .git_global(!visibility.include_ignored)
+        .git_exclude(!visibility.include_ignored)
         .require_git(false)
         .follow_links(false);
+    let filter_macos_hidden = cfg!(target_os = "macos") && !visibility.include_system_hidden;
+    if filter_macos_hidden || skip_common_dirs {
+        builder.filter_entry(move |entry| {
+            (!filter_macos_hidden || !has_macos_hidden_flag(entry))
+                && (!skip_common_dirs || should_visit_mention_entry(entry))
+        });
+    }
     if let Some(depth) = max_depth {
         builder.max_depth(Some(depth));
     }
     builder.build()
 }
 
+fn build_ignore_walker(base: &Path, max_depth: Option<usize>) -> ignore::Walk {
+    build_workspace_walker(
+        base,
+        max_depth,
+        requested_visibility(None, true),
+        false,
+    )
+}
+
+fn visible_paths_for_hidden_marking(
+    base: &Path,
+    max_depth: Option<usize>,
+    skip_common_dirs: bool,
+) -> HashSet<PathBuf> {
+    build_workspace_walker(
+        base,
+        max_depth,
+        requested_visibility(Some(false), false),
+        skip_common_dirs,
+    )
+    .filter_map(Result::ok)
+    .map(|entry| entry.into_path())
+    .collect()
+}
+
 pub(crate) fn fs_list_sync(
     workdir: String,
     path: Option<String>,
     depth: Option<usize>,
     offset: Option<usize>,
     max_results: Option<usize>,
+    show_hidden: Option<bool>,
 ) -> Result<ListResponse, FsCommandError> {
     let wd = canonicalize_workdir(&workdir)?;
-    fs_list_impl(&wd, path, depth, offset, max_results)
+    fs_list_impl(&wd, path, depth, offset, max_results, show_hidden)
         .map_err(|e| FsCommandError::from(e).with_workdir(&wd))
 }
 
@@ -3663,6 +3733,7 @@ fn fs_list_impl(
     depth: Option<usize>,
     offset: Option<usize>,
     max_results: Option<usize>,
+    show_hidden: Option<bool>,
 ) -> Result<ListResponse, FsError> {
     let rel_opt = sanitize_optional_rel_path(path)?;
     let path_display = rel_opt.as_ref().map(|rel| logical_rel_path(rel));
@@ -3692,9 +3763,14 @@ fn fs_list_impl(
         entries.push(ListEntry {
             path: rel_to_workdir_str(wd, &base),
             kind: "file".to_string(),
+            hidden: false,
         });
     } else {
-        for result in build_ignore_walker(&base, Some(depth)) {
+        let visibility = requested_visibility(show_hidden, true);
+        let normally_visible = visibility
+            .include_ignored
+            .then(|| visible_paths_for_hidden_marking(&base, Some(depth), false));
+        for result in build_workspace_walker(&base, Some(depth), visibility, false) {
             let entry = match result {
                 Ok(v) => v,
                 Err(_) => continue,
@@ -3713,6 +3789,9 @@ fn fs_list_impl(
             entries.push(ListEntry {
                 path: rel_to_workdir_str(wd, entry.path()),
                 kind: kind.to_string(),
+                hidden: normally_visible
+                    .as_ref()
+                    .is_some_and(|paths| !paths.contains(entry.path())),
             });
         }
     }
@@ -3745,9 +3824,10 @@ pub async fn fs_list(
     depth: Option<usize>,
     offset: Option<usize>,
     max_results: Option<usize>,
+    show_hidden: Option<bool>,
 ) -> Result<ListResponse, FsCommandError> {
     run_blocking_fs("fs_list", move || {
-        fs_list_sync(workdir, path, depth, offset, max_results)
+        fs_list_sync(workdir, path, depth, offset, max_results, show_hidden)
     })
     .await
 }
@@ -4273,6 +4353,7 @@ const MENTION_IGNORED_DIR_NAMES: &[&str] = &[
 pub struct MentionFileEntry {
     pub path: String,
     pub kind: String,
+    pub hidden: bool,
 }
 
 #[derive(Debug, Serialize)]
@@ -4348,6 +4429,7 @@ pub fn fs_mention_list_sync(
     workdir: String,
     max_results: Option<usize>,
     query: Option<String>,
+    show_hidden: Option<bool>,
 ) -> Result<MentionListResponse, String> {
     let wd = canonicalize_workdir(&workdir).map_err(|e| e.to_string())?;
     let max_results = max_results.unwrap_or(DEFAULT_MENTION_MAX_RESULTS).max(1);
@@ -4358,15 +4440,11 @@ pub fn fs_mention_list_sync(
         QUERY_MENTION_CANDIDATE_LIMIT.max(max_results)
     };
 
-    let walker = WalkBuilder::new(&wd)
-        .hidden(true)
-        .git_ignore(true)
-        .git_global(true)
-        .git_exclude(true)
-        .require_git(false)
-        .follow_links(false)
-        .filter_entry(should_visit_mention_entry)
-        .build();
+    let visibility = requested_visibility(show_hidden, false);
+    let normally_visible = visibility
+        .include_ignored
+        .then(|| visible_paths_for_hidden_marking(&wd, None, true));
+    let walker = build_workspace_walker(&wd, None, visibility, !visibility.include_ignored);
 
     let mut entries: Vec<MentionFileEntry> = Vec::new();
     let mut truncated = false;
@@ -4402,6 +4480,9 @@ pub fn fs_mention_list_sync(
         entries.push(MentionFileEntry {
             path,
             kind: kind.to_string(),
+            hidden: normally_visible
+                .as_ref()
+                .is_some_and(|paths| !paths.contains(entry.path())),
         });
     }
 
@@ -4421,9 +4502,10 @@ pub async fn fs_mention_list(
     workdir: String,
     max_results: Option<usize>,
     query: Option<String>,
+    show_hidden: Option<bool>,
 ) -> Result<MentionListResponse, String> {
     run_blocking("fs_mention_list", move || {
-        fs_mention_list_sync(workdir, max_results, query)
+        fs_mention_list_sync(workdir, max_results, query, show_hidden)
     })
     .await
 }
@@ -4443,6 +4525,30 @@ mod tests {
         std::env::temp_dir().join(format!("liveagent-{name}-{suffix}"))
     }
 
+    fn list_test_entries(workdir: &Path, show_hidden: Option<bool>) -> Vec<ListEntry> {
+        fs_list_sync(
+            workdir.display().to_string(),
+            None,
+            Some(3),
+            None,
+            Some(100),
+            show_hidden,
+        )
+        .expect("list should succeed")
+        .entries
+    }
+
+    fn mention_test_entries(workdir: &Path, show_hidden: Option<bool>) -> Vec<MentionFileEntry> {
+        fs_mention_list_sync(
+            workdir.display().to_string(),
+            Some(100),
+            None,
+            show_hidden,
+        )
+        .expect("mention list should succeed")
+        .entries
+    }
+
     fn png_like_bytes() -> Vec<u8> {
         b"\x89PNG\r\n\x1a\nliveagent-test".to_vec()
     }
@@ -5225,6 +5331,7 @@ mod tests {
             Some(3),
             None,
             Some(100),
+            None,
         )
         .expect("list should succeed");
         let paths = response
@@ -5249,6 +5356,7 @@ mod tests {
             Some(1),
             None,
             Some(10),
+            None,
         )
         .expect_err("outside path should fail");
         assert!(
@@ -5260,6 +5368,103 @@ mod tests {
         let _ = fs::remove_dir_all(workdir);
     }
 
+    #[test]
+    fn list_hidden_toggle_includes_and_marks_ignored_and_dot_entries() {
+        let workdir = unique_test_workdir("list-hidden-toggle");
+        fs::create_dir_all(workdir.join(".hidden_dir")).expect("create hidden dir");
+        fs::create_dir_all(workdir.join("ignored_dir")).expect("create ignored dir");
+        fs::write(workdir.join(".gitignore"), "ignored_dir/\nignored.txt\n")
+            .expect("write gitignore");
+        fs::write(workdir.join("visible.txt"), "visible").expect("write visible file");
+        fs::write(workdir.join(".hidden.txt"), "hidden").expect("write hidden file");
+        fs::write(workdir.join(".hidden_dir/child.txt"), "hidden").expect("write hidden child");
+        fs::write(workdir.join("ignored.txt"), "ignored").expect("write ignored file");
+        fs::write(workdir.join("ignored_dir/child.txt"), "ignored").expect("write ignored child");
+
+        let legacy_entries = list_test_entries(&workdir, None);
+        assert!(legacy_entries.iter().any(|entry| entry.path == ".hidden.txt"));
+        assert!(!legacy_entries.iter().any(|entry| entry.path == "ignored.txt"));
+
+        let hidden_entries = list_test_entries(&workdir, Some(false));
+        let hidden_paths = hidden_entries
+            .iter()
+            .map(|entry| entry.path.as_str())
+            .collect::<Vec<_>>();
+        assert!(hidden_paths.contains(&"visible.txt"));
+        assert!(!hidden_paths.iter().any(|path| path.starts_with('.')));
+        assert!(!hidden_paths.iter().any(|path| path.starts_with("ignored")));
+
+        let shown_entries = list_test_entries(&workdir, Some(true));
+        let entry = |path: &str| {
+            shown_entries
+                .iter()
+                .find(|entry| entry.path == path)
+                .unwrap_or_else(|| panic!("missing entry: {path}"))
+        };
+        assert!(!entry("visible.txt").hidden);
+        assert!(entry(".hidden.txt").hidden);
+        assert!(entry(".hidden_dir/child.txt").hidden);
+        assert!(entry("ignored.txt").hidden);
+        assert!(entry("ignored_dir/child.txt").hidden);
+
+        let _ = fs::remove_dir_all(workdir);
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn list_hidden_toggle_respects_macos_finder_hidden_flag() {
+        let workdir = unique_test_workdir("list-macos-hidden");
+        fs::create_dir_all(&workdir).expect("create workdir");
+        let hidden_path = workdir.join("finder-hidden.txt");
+        fs::write(&hidden_path, "hidden").expect("write hidden file");
+        let status = Command::new("chflags")
+            .arg("hidden")
+            .arg(&hidden_path)
+            .status()
+            .expect("run chflags");
+        assert!(status.success(), "chflags hidden failed");
+
+        let hidden_entries = list_test_entries(&workdir, Some(false));
+        assert!(!hidden_entries.iter().any(|entry| entry.path == "finder-hidden.txt"));
+
+        let shown_entries = list_test_entries(&workdir, Some(true));
+        assert!(
+            shown_entries
+                .iter()
+                .any(|entry| entry.path == "finder-hidden.txt" && entry.hidden)
+        );
+
+        let _ = fs::remove_dir_all(workdir);
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn list_hidden_toggle_respects_windows_hidden_attribute() {
+        use std::os::windows::fs::OpenOptionsExt;
+
+        const FILE_ATTRIBUTE_HIDDEN: u32 = 0x2;
+        let workdir = unique_test_workdir("list-windows-hidden");
+        fs::create_dir_all(&workdir).expect("create workdir");
+        fs::OpenOptions::new()
+            .write(true)
+            .create(true)
+            .attributes(FILE_ATTRIBUTE_HIDDEN)
+            .open(workdir.join("windows-hidden.txt"))
+            .expect("create hidden file");
+
+        let hidden_entries = list_test_entries(&workdir, Some(false));
+        assert!(!hidden_entries.iter().any(|entry| entry.path == "windows-hidden.txt"));
+
+        let shown_entries = list_test_entries(&workdir, Some(true));
+        assert!(
+            shown_entries
+                .iter()
+                .any(|entry| entry.path == "windows-hidden.txt" && entry.hidden)
+        );
+
+        let _ = fs::remove_dir_all(workdir);
+    }
+
     #[cfg(unix)]
     #[test]
     fn create_dir_and_rename_reject_out_of_bounds_symlink_parents() {
@@ -5305,10 +5510,8 @@ mod tests {
         fs::write(workdir.join("src/app.ts"), "export {}").expect("write app");
         fs::write(workdir.join("node_modules/pkg/ignored.ts"), "export {}").expect("write ignored");
 
-        let response = fs_mention_list_sync(workdir.display().to_string(), Some(100), None)
-            .expect("mention list should succeed");
-        let paths = response
-            .entries
+        let entries = mention_test_entries(&workdir, None);
+        let paths = entries
             .iter()
             .map(|entry| entry.path.as_str())
             .collect::<Vec<_>>();
@@ -5337,10 +5540,8 @@ mod tests {
         fs::write(workdir.join("ignored_dir/hidden.ts"), "export {}").expect("write hidden");
         fs::write(workdir.join("ignored_file.txt"), "hidden").expect("write ignored file");
 
-        let response = fs_mention_list_sync(workdir.display().to_string(), Some(100), None)
-            .expect("mention list should succeed");
-        let paths = response
-            .entries
+        let entries = mention_test_entries(&workdir, None);
+        let paths = entries
             .iter()
             .map(|entry| entry.path.as_str())
             .collect::<Vec<_>>();
@@ -5358,6 +5559,32 @@ mod tests {
         let _ = fs::remove_dir_all(workdir);
     }
 
+    #[test]
+    fn mention_list_hidden_toggle_includes_and_marks_filtered_entries() {
+        let workdir = unique_test_workdir("mention-hidden-toggle");
+        fs::create_dir_all(workdir.join("node_modules/pkg")).expect("create node_modules");
+        fs::create_dir_all(workdir.join("ignored_dir")).expect("create ignored dir");
+        fs::write(workdir.join(".gitignore"), "ignored_dir/\n").expect("write gitignore");
+        fs::write(workdir.join("visible.txt"), "visible").expect("write visible file");
+        fs::write(workdir.join(".hidden.txt"), "hidden").expect("write hidden file");
+        fs::write(workdir.join("ignored_dir/child.txt"), "ignored")
+            .expect("write ignored file");
+
+        let shown_entries = mention_test_entries(&workdir, Some(true));
+        let entry = |path: &str| {
+            shown_entries
+                .iter()
+                .find(|entry| entry.path == path)
+                .unwrap_or_else(|| panic!("missing entry: {path}"))
+        };
+        assert!(!entry("visible.txt").hidden);
+        assert!(entry(".hidden.txt").hidden);
+        assert!(entry("node_modules").hidden);
+        assert!(entry("ignored_dir/child.txt").hidden);
+
+        let _ = fs::remove_dir_all(workdir);
+    }
+
     #[test]
     fn mention_list_query_filters_and_ranks_filename_matches() {
         let workdir = unique_test_workdir("mention-query");
@@ -5370,6 +5597,7 @@ mod tests {
             workdir.display().to_string(),
             Some(10),
             Some("needle".to_string()),
+            None,
         )
         .expect("mention list should succeed");
         let paths = response
@@ -5454,6 +5682,7 @@ mod tests {
             None,
             None,
             None,
+            None,
         )
         .expect("list should accept a file target");
         assert_eq!(list.target_kind.as_deref(), Some("file"));
diff --git a/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs b/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
index 67c9e7b55..8a36e02b7 100644
--- a/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
+++ b/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
@@ -341,7 +341,12 @@ pub async fn handle_file_mention_list(
         .filter(|value| *value > 0);
 
     tauri::async_runtime::spawn_blocking(move || {
-        fs_mention_list_sync(request.workdir, max_results, Some(request.query))
+        fs_mention_list_sync(
+            request.workdir,
+            max_results,
+            Some(request.query),
+            request.show_hidden,
+        )
     })
     .await
     .map_err(|e| format!("gateway file mention list join failed: {e}"))?
@@ -352,6 +357,7 @@ pub async fn handle_file_mention_list(
             .map(|entry| proto::FileMentionEntry {
                 path: entry.path,
                 kind: entry.kind,
+                hidden: entry.hidden,
             })
             .collect(),
         truncated: response.truncated,
@@ -431,7 +437,14 @@ pub async fn handle_fs_list(
         .filter(|value| *value > 0);
 
     tauri::async_runtime::spawn_blocking(move || {
-        fs_list_sync(request.workdir, path, depth, offset, max_results)
+        fs_list_sync(
+            request.workdir,
+            path,
+            depth,
+            offset,
+            max_results,
+            request.show_hidden,
+        )
     })
     .await
     .map_err(|e| format!("gateway fs list join failed: {e}"))?
@@ -452,6 +465,7 @@ pub async fn handle_fs_list(
                 .map(|entry| proto::FsListEntry {
                     path: entry.path,
                     kind: entry.kind,
+                    hidden: entry.hidden,
                 })
                 .collect(),
         }
diff --git a/crates/agent-gui/src/components/project-tools/file-tree/ContextMenu.tsx b/crates/agent-gui/src/components/project-tools/file-tree/ContextMenu.tsx
index d8005b67a..2fc22c268 100644
--- a/crates/agent-gui/src/components/project-tools/file-tree/ContextMenu.tsx
+++ b/crates/agent-gui/src/components/project-tools/file-tree/ContextMenu.tsx
@@ -21,6 +21,7 @@ import {
   Edit3,
   ExternalLink,
   Eye,
+  EyeOff,
   FilePenLine,
   Folder,
   FolderOpen,
@@ -70,6 +71,7 @@ export type FileTreeContextMenuProps = {
   canMutate: boolean;
   canOpenFile: boolean;
   canInsertMention: boolean;
+  showHidden: boolean;
   onClose: () => void;
   onOpenFile: (path: string) => void;
   onOpenExternal: (path: string) => void;
@@ -78,6 +80,7 @@ export type FileTreeContextMenuProps = {
   onDelete: (path: string) => void;
   onInsertMention: (path: string) => void;
   onRefresh: (path: string, kind: FileTreeKind) => void;
+  onToggleHidden: () => void;
   onActionError: (message: string) => void;
 };
 
@@ -90,6 +93,7 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
     canMutate,
     canOpenFile,
     canInsertMention,
+    showHidden,
     onClose,
     onOpenFile,
     onOpenExternal,
@@ -98,6 +102,7 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
     onDelete,
     onInsertMention,
     onRefresh,
+    onToggleHidden,
     onActionError,
   } = props;
   const { t } = useLocale();
@@ -277,6 +282,23 @@ export function FileTreeContextMenu(props: FileTreeContextMenuProps) {
         {t("projectTools.fileTree.delete")}
       </button>
       <div className="mx-1 my-1 h-px bg-border/60" />
+      <button
+        type="button"
+        role="menuitemcheckbox"
+        aria-checked={showHidden}
+        className={MENU_ITEM_CLASS}
+        onClick={() => {
+          onToggleHidden();
+          onClose();
+        }}
+      >
+        {showHidden ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+        {t(
+          showHidden
+            ? "projectTools.fileTree.hideHiddenFiles"
+            : "projectTools.fileTree.showHiddenFiles",
+        )}
+      </button>
       <button
         type="button"
         role="menuitem"
diff --git a/crates/agent-gui/src/components/project-tools/file-tree/Row.tsx b/crates/agent-gui/src/components/project-tools/file-tree/Row.tsx
index 7c9ece0c4..fe99b5ba6 100644
--- a/crates/agent-gui/src/components/project-tools/file-tree/Row.tsx
+++ b/crates/agent-gui/src/components/project-tools/file-tree/Row.tsx
@@ -16,6 +16,7 @@ export type FileTreeRowProps = {
   path: string;
   name: string;
   kind: FileTreeKind;
+  hidden: boolean;
   depth: number;
   expanded: boolean;
   selected: boolean;
@@ -34,6 +35,7 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
     path,
     name,
     kind,
+    hidden,
     depth,
     expanded,
     selected,
@@ -62,7 +64,10 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
       {kind === "dir" ? (
         <button
           type="button"
-          className="flex h-5 w-5 shrink-0 items-center justify-center rounded hover:bg-background"
+          className={cn(
+            "flex h-5 w-5 shrink-0 items-center justify-center rounded hover:bg-background",
+            hidden && "opacity-60 group-hover:opacity-80",
+          )}
           onClick={() => onToggle(path, expanded)}
           title={expanded ? t("projectTools.fileTree.collapse") : t("projectTools.fileTree.expand")}
         >
@@ -79,7 +84,10 @@ export const FileTreeRow = memo(function FileTreeRow(props: FileTreeRowProps) {
       )}
       <button
         type="button"
-        className="flex min-w-0 flex-1 items-center gap-1.5 bg-transparent p-0 text-left text-inherit leading-5"
+        className={cn(
+          "flex min-w-0 flex-1 items-center gap-1.5 bg-transparent p-0 text-left text-inherit leading-5",
+          hidden && "opacity-60 group-hover:opacity-80",
+        )}
         title={title}
         onClick={() => onSelect(path)}
         onDoubleClick={() => {
diff --git a/crates/agent-gui/src/components/project-tools/file-tree/index.tsx b/crates/agent-gui/src/components/project-tools/file-tree/index.tsx
index 3ebe6fc39..0dfafd546 100644
--- a/crates/agent-gui/src/components/project-tools/file-tree/index.tsx
+++ b/crates/agent-gui/src/components/project-tools/file-tree/index.tsx
@@ -17,6 +17,7 @@ import {
 } from "react";
 import { useLocale } from "../../../i18n";
 import type { RightDockFileTreeStatePatch } from "../../../lib/settings";
+import { cn } from "../../../lib/shared/utils";
 import { getFileTypeIcon } from "../../chat/fileTypeIcons";
 import { Check, FolderOpen, Loader2, RefreshCw, Search, Trash2, X } from "../../icons";
 import { Button } from "../../ui/button";
@@ -89,6 +90,7 @@ export function FileTreePanel(props: { active: boolean }) {
     workspaceActivityClient: context.clients.workspaceActivity ?? null,
     expandedPaths: syncState.expandedPaths,
     query,
+    showHidden: syncState.showHidden,
   });
 
   const nodesRef = useRef(nodes);
@@ -546,7 +548,10 @@ export function FileTreePanel(props: { active: boolean }) {
                 <button
                   key={`${entry.kind}:${entry.path}`}
                   type="button"
-                  className="flex w-full select-none items-center gap-1.5 rounded-md px-2 text-left text-xs leading-5 text-muted-foreground hover:bg-muted hover:text-foreground"
+                  className={cn(
+                    "flex w-full select-none items-center gap-1.5 rounded-md px-2 text-left text-xs leading-5 text-muted-foreground hover:bg-muted hover:text-foreground",
+                    entry.hidden && "opacity-60 hover:opacity-80",
+                  )}
                   style={{ minHeight: FILE_TREE_ROW_HEIGHT }}
                   title={entry.path}
                   onClick={() => void revealPath(entry.path, entry.kind)}
@@ -602,6 +607,7 @@ export function FileTreePanel(props: { active: boolean }) {
                   path={node.path}
                   name={node.name}
                   kind={node.kind}
+                  hidden={node.hidden}
                   depth={row.depth}
                   expanded={expandedSet.has(row.path)}
                   selected={selectedPath === row.path}
@@ -628,6 +634,7 @@ export function FileTreePanel(props: { active: boolean }) {
           canMutate={canMutate}
           canOpenFile={Boolean(fileTree.onOpenFile)}
           canInsertMention={Boolean(fileTree.onInsertFileMention)}
+          showHidden={syncState.showHidden}
           onClose={() => setContextMenu(null)}
           onOpenFile={handleOpenFile}
           onOpenExternal={handleOpenExternal}
@@ -636,6 +643,7 @@ export function FileTreePanel(props: { active: boolean }) {
           onDelete={(path) => void deletePath(path)}
           onInsertMention={handleInsertMention}
           onRefresh={handleMenuRefresh}
+          onToggleHidden={() => emitState({ showHidden: !syncState.showHidden })}
           onActionError={setActionError}
         />
       ) : null}
diff --git a/crates/agent-gui/src/components/project-tools/file-tree/model.ts b/crates/agent-gui/src/components/project-tools/file-tree/model.ts
index bbb7921b9..79565771c 100644
--- a/crates/agent-gui/src/components/project-tools/file-tree/model.ts
+++ b/crates/agent-gui/src/components/project-tools/file-tree/model.ts
@@ -10,12 +10,13 @@ import type { WorkspaceActivityEventPayload } from "../../../lib/workspace-activ
 
 export type FileTreeKind = "file" | "dir";
 
-export type FileTreeEntry = { path: string; kind: FileTreeKind };
+export type FileTreeEntry = { path: string; kind: FileTreeKind; hidden: boolean };
 
 export type FileTreeNode = {
   path: string;
   name: string;
   kind: FileTreeKind;
+  hidden: boolean;
   children: string[];
   loaded: boolean;
   loading: boolean;
@@ -91,6 +92,7 @@ export function createRootNode(cwd: string): FileTreeNode {
     path: ROOT_PATH,
     name: rootName(cwd),
     kind: "dir",
+    hidden: false,
     children: [],
     loaded: false,
     loading: false,
@@ -167,13 +169,22 @@ export function applyFileTreeListResponse(
     if (!entry.path) continue;
     childPaths.push(entry.path);
     const name = basename(entry.path) || entry.path;
+    const hidden = parent.hidden || entry.hidden;
     const existing = nodes[entry.path];
-    if (existing && existing.kind === entry.kind && existing.name === name) continue;
+    if (
+      existing &&
+      existing.kind === entry.kind &&
+      existing.name === name &&
+      existing.hidden === hidden
+    ) {
+      continue;
+    }
     const sameKind = existing !== undefined && existing.kind === entry.kind;
     next[entry.path] = {
       path: entry.path,
       name,
       kind: entry.kind,
+      hidden,
       children: sameKind ? existing.children : [],
       loaded: sameKind ? existing.loaded : false,
       loading: false,
diff --git a/crates/agent-gui/src/components/project-tools/file-tree/useFileTreeData.ts b/crates/agent-gui/src/components/project-tools/file-tree/useFileTreeData.ts
index 1e90135bc..791d91d27 100644
--- a/crates/agent-gui/src/components/project-tools/file-tree/useFileTreeData.ts
+++ b/crates/agent-gui/src/components/project-tools/file-tree/useFileTreeData.ts
@@ -81,6 +81,7 @@ export type UseFileTreeDataOptions = {
   expandedPaths: string[];
   // Live search input (the panel debounces persistence separately).
   query: string;
+  showHidden: boolean;
 };
 
 export type UseFileTreeDataResult = {
@@ -104,6 +105,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     workspaceActivityClient,
     expandedPaths,
     query,
+    showHidden,
   } = options;
   const { t } = useLocale();
 
@@ -132,6 +134,8 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     queryRef.current = query;
   }, [query]);
 
+  const showHiddenRef = useRef(showHidden);
+
   const activeRef = useRef(active);
 
   // All bucket mutations go through here: pure computation first, then a
@@ -201,6 +205,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
           depth: 1,
           offset: 0,
           max_results: FILE_TREE_LIST_MAX_RESULTS,
+          show_hidden: showHiddenRef.current,
         });
         // Out-of-order protection: a response only lands if it belongs to the
         // newest request issued for this path.
@@ -273,6 +278,12 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
     [bumpSearchRefresh, cwd, loadChildren, projectPathKey],
   );
 
+  useEffect(() => {
+    if (showHiddenRef.current === showHidden) return;
+    showHiddenRef.current = showHidden;
+    refreshVisible();
+  }, [refreshVisible, showHidden]);
+
   // ---------------------------------------------------------------------
   // Workspace-activity invalidation (replaces the old 3s full polling)
   // ---------------------------------------------------------------------
@@ -352,6 +363,7 @@ export function useFileTreeData(options: UseFileTreeDataOptions): UseFileTreeDat
         workdir: cwd,
         query,
         max_results: FILE_TREE_SEARCH_MAX_RESULTS,
+        show_hidden: showHiddenRef.current,
       })
         .then((response) => {
           if (cancelled) return;
diff --git a/crates/agent-gui/src/i18n/config.ts b/crates/agent-gui/src/i18n/config.ts
index 8f425057b..7b8f200c1 100644
--- a/crates/agent-gui/src/i18n/config.ts
+++ b/crates/agent-gui/src/i18n/config.ts
@@ -655,6 +655,8 @@ export const translations: Record<Locale, Record<string, string>> = {
     "projectTools.fileTree.renamePlaceholder": "新名称",
     "projectTools.fileTree.searchPlaceholder": "搜索文件",
     "projectTools.fileTree.refresh": "刷新",
+    "projectTools.fileTree.showHiddenFiles": "显示隐藏文件",
+    "projectTools.fileTree.hideHiddenFiles": "隐藏隐藏文件",
     "projectTools.fileTree.searching": "搜索中...",
     "projectTools.fileTree.noMatches": "无匹配结果",
     "projectTools.fileTree.resultsTruncated": "结果已截断",
@@ -2438,6 +2440,8 @@ export const translations: Record<Locale, Record<string, string>> = {
     "projectTools.fileTree.renamePlaceholder": "New name",
     "projectTools.fileTree.searchPlaceholder": "Search files",
     "projectTools.fileTree.refresh": "Refresh",
+    "projectTools.fileTree.showHiddenFiles": "Show Hidden Files",
+    "projectTools.fileTree.hideHiddenFiles": "Hide Hidden Files",
     "projectTools.fileTree.searching": "Searching...",
     "projectTools.fileTree.noMatches": "No matches",
     "projectTools.fileTree.resultsTruncated": "Results truncated",
diff --git a/crates/agent-gui/src/lib/settings/index.ts b/crates/agent-gui/src/lib/settings/index.ts
index f9883af79..af0060c94 100644
--- a/crates/agent-gui/src/lib/settings/index.ts
+++ b/crates/agent-gui/src/lib/settings/index.ts
@@ -103,6 +103,7 @@ export type RightDockFileTreeState = {
   query: string;
   selectedPath: string;
   expandedPaths: string[];
+  showHidden: boolean;
   // Reveal nonce: bumped (via bumpRevision) when another surface asks the
   // file tree to reveal selectedPath (expand ancestors + scroll into view).
   // Content refreshes are driven by workspace-activity invalidation, and
@@ -1545,6 +1546,7 @@ export const DEFAULT_RIGHT_DOCK_FILE_TREE_STATE: RightDockFileTreeState = {
   query: "",
   selectedPath: "",
   expandedPaths: [""],
+  showHidden: false,
   revision: 0,
 };
 
@@ -1570,6 +1572,7 @@ export function normalizeRightDockFileTreeState(input: unknown): RightDockFileTr
     query: normalizeRightDockFileTreeSearchQuery(obj.query),
     selectedPath: normalizeRightDockFileTreePath(obj.selectedPath),
     expandedPaths: normalizeRightDockFileTreeExpandedPaths(obj.expandedPaths),
+    showHidden: obj.showHidden === true,
     revision: normalizeIntegerInRange(obj.revision, 0, Number.MAX_SAFE_INTEGER, 0),
   };
 }
@@ -2029,6 +2032,7 @@ function rightDockFileTreeStateEqual(
   return (
     left.query === right.query &&
     left.selectedPath === right.selectedPath &&
+    left.showHidden === right.showHidden &&
     left.revision === right.revision &&
     left.expandedPaths.length === right.expandedPaths.length &&
     left.expandedPaths.every((path, index) => path === right.expandedPaths[index])
@@ -2212,6 +2216,7 @@ export function updateRightDockFileTreeState(
       patch.expandedPaths !== undefined
         ? normalizeRightDockFileTreeExpandedPaths(patch.expandedPaths)
         : current.expandedPaths,
+    showHidden: patch.showHidden ?? current.showHidden,
     revision: patch.bumpRevision
       ? current.revision + 1
       : patch.revision !== undefined

From b21ebbf0e08166dad90f2694979c8a4a4c3867a8 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 16:55:29 +0800
Subject: [PATCH 5/7] feat(chat): per-conversation model selection

Replace the global model choice with per-conversation state so parallel
tasks no longer clobber each other's model:

- chatHistory gains selected_model_json (schema v2; idempotent ensure
  re-run migrates existing DBs), with a targeted chat_history_set_model
  command mirroring set_pinned (no updated_at bump) and COALESCE-guarded
  upserts so null inputs never clobber a stored choice.
- ConversationSummary carries the selection (proto field 13) through
  history-sync, the mirrored sidebar layer, and the web wire types.
- Desktop resolves via a single derivation (gateway override >
  conversation selection > default); the visible entry's selection is
  React state so runtime-cache rebuilds can't drop it; records seed the
  entry on open/hydrate/bridge-ready, and sends pin the effective model.
- Web keeps unsent picks in a per-conversation override map, sends them
  with each chat command, and converges on the history-sync echo.
- settings.selectedModel narrows to "default for new conversations"
  (last picked anywhere); ChatHeader on both ends now takes
  onSelectModel instead of setSettings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../internal/proto/v1/gateway.pb.go           |  43 +++---
 crates/agent-gateway/proto/v1/gateway.proto   |   1 +
 .../agent-gateway/web/src/app/GatewayApp.tsx  | 138 ++++++++++++++----
 .../web/src/app/chatEventUtils.ts             |  26 +++-
 .../agent-gateway/web/src/lib/gatewayTypes.ts |   1 +
 .../web/src/lib/settings/index.ts             |  18 ++-
 .../web/src/lib/sidebar/reconcile.ts          |   2 +
 .../web/src/lib/sidebar/types.ts              |   1 +
 .../web/src/lib/sidebar/webSidebarBackend.ts  |   3 +
 .../web/src/pages/chat/ChatHeader.tsx         |   8 +-
 .../web/test/web-sidebar-backend.test.mjs     |  12 ++
 .../commands/history/chat_history/commands.rs |  27 ++++
 .../history/chat_history/repository.rs        |   6 +
 .../commands/history/chat_history/segments.rs |  53 ++++++-
 .../commands/history/chat_history/tests.rs    | 100 +++++++++++++
 .../commands/history/chat_history/types.rs    |   5 +
 .../src/commands/history/history_db.rs        |  32 +++-
 crates/agent-gui/src-tauri/src/lib.rs         |   1 +
 .../src/services/gateway/history_sync.rs      |   4 +
 .../src-tauri/src/services/gateway/types.rs   |   1 +
 .../src-tauri/src/services/gateway_bridge.rs  |   4 +
 .../src/lib/chat/history/chatHistory.ts       |  27 +++-
 crates/agent-gui/src/lib/settings/index.ts    |  18 ++-
 crates/agent-gui/src/lib/sidebar/reconcile.ts |   2 +
 crates/agent-gui/src/lib/sidebar/types.ts     |   1 +
 crates/agent-gui/src/pages/ChatPage.tsx       | 118 ++++++++++++---
 .../src/pages/chat/components/ChatHeader.tsx  |   8 +-
 .../history/useConversationHistoryActions.ts  |   8 +
 .../chat/hooks/useChatPageRuntimeStore.ts     |  11 ++
 crates/agent-gui/src/pages/chat/index.ts      |   1 +
 .../src/pages/chat/runtime/chatPageRuntime.ts |   6 +-
 .../src/pages/chat/runtime/modelSelection.ts  |  22 ++-
 .../test/chat/model-selection.test.mjs        | 138 +++++++++++++++---
 .../test/chat/sidebar-reconcile.test.mjs      |  34 +++++
 34 files changed, 775 insertions(+), 105 deletions(-)

diff --git a/crates/agent-gateway/internal/proto/v1/gateway.pb.go b/crates/agent-gateway/internal/proto/v1/gateway.pb.go
index a2f4a1305..467855934 100644
--- a/crates/agent-gateway/internal/proto/v1/gateway.pb.go
+++ b/crates/agent-gateway/internal/proto/v1/gateway.pb.go
@@ -6902,21 +6902,22 @@ func (x *HistoryListResponse) GetTotalCount() int32 {
 }
 
 type ConversationSummary struct {
-	state         protoimpl.MessageState `protogen:"open.v1"`
-	Id            string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
-	Title         string                 `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
-	CreatedAt     int64                  `protobuf:"varint,3,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
-	UpdatedAt     int64                  `protobuf:"varint,4,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
-	MessageCount  int32                  `protobuf:"varint,5,opt,name=message_count,json=messageCount,proto3" json:"message_count,omitempty"`
-	ProviderId    string                 `protobuf:"bytes,6,opt,name=provider_id,json=providerId,proto3" json:"provider_id,omitempty"`
-	Model         string                 `protobuf:"bytes,7,opt,name=model,proto3" json:"model,omitempty"`
-	SessionId     string                 `protobuf:"bytes,8,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
-	Cwd           string                 `protobuf:"bytes,9,opt,name=cwd,proto3" json:"cwd,omitempty"`
-	IsPinned      bool                   `protobuf:"varint,10,opt,name=is_pinned,json=isPinned,proto3" json:"is_pinned,omitempty"`
-	PinnedAt      int64                  `protobuf:"varint,11,opt,name=pinned_at,json=pinnedAt,proto3" json:"pinned_at,omitempty"`
-	IsShared      bool                   `protobuf:"varint,12,opt,name=is_shared,json=isShared,proto3" json:"is_shared,omitempty"`
-	unknownFields protoimpl.UnknownFields
-	sizeCache     protoimpl.SizeCache
+	state             protoimpl.MessageState `protogen:"open.v1"`
+	Id                string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	Title             string                 `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
+	CreatedAt         int64                  `protobuf:"varint,3,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+	UpdatedAt         int64                  `protobuf:"varint,4,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
+	MessageCount      int32                  `protobuf:"varint,5,opt,name=message_count,json=messageCount,proto3" json:"message_count,omitempty"`
+	ProviderId        string                 `protobuf:"bytes,6,opt,name=provider_id,json=providerId,proto3" json:"provider_id,omitempty"`
+	Model             string                 `protobuf:"bytes,7,opt,name=model,proto3" json:"model,omitempty"`
+	SessionId         string                 `protobuf:"bytes,8,opt,name=session_id,json=sessionId,proto3" json:"session_id,omitempty"`
+	Cwd               string                 `protobuf:"bytes,9,opt,name=cwd,proto3" json:"cwd,omitempty"`
+	IsPinned          bool                   `protobuf:"varint,10,opt,name=is_pinned,json=isPinned,proto3" json:"is_pinned,omitempty"`
+	PinnedAt          int64                  `protobuf:"varint,11,opt,name=pinned_at,json=pinnedAt,proto3" json:"pinned_at,omitempty"`
+	IsShared          bool                   `protobuf:"varint,12,opt,name=is_shared,json=isShared,proto3" json:"is_shared,omitempty"`
+	SelectedModelJson string                 `protobuf:"bytes,13,opt,name=selected_model_json,json=selectedModelJson,proto3" json:"selected_model_json,omitempty"`
+	unknownFields     protoimpl.UnknownFields
+	sizeCache         protoimpl.SizeCache
 }
 
 func (x *ConversationSummary) Reset() {
@@ -7033,6 +7034,13 @@ func (x *ConversationSummary) GetIsShared() bool {
 	return false
 }
 
+func (x *ConversationSummary) GetSelectedModelJson() string {
+	if x != nil {
+		return x.SelectedModelJson
+	}
+	return ""
+}
+
 type HistoryGetRequest struct {
 	state          protoimpl.MessageState `protogen:"open.v1"`
 	ConversationId string                 `protobuf:"bytes,1,opt,name=conversation_id,json=conversationId,proto3" json:"conversation_id,omitempty"`
@@ -11347,7 +11355,7 @@ const file_proto_v1_gateway_proto_rawDesc = "" +
 	"\x13HistoryListResponse\x12O\n" +
 	"\rconversations\x18\x01 \x03(\v2).liveagent.gateway.v1.ConversationSummaryR\rconversations\x12\x1f\n" +
 	"\vtotal_count\x18\x02 \x01(\x05R\n" +
-	"totalCount\"\xdd\x02\n" +
+	"totalCount\"\x8d\x03\n" +
 	"\x13ConversationSummary\x12\x0e\n" +
 	"\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n" +
 	"\x05title\x18\x02 \x01(\tR\x05title\x12\x1d\n" +
@@ -11365,7 +11373,8 @@ const file_proto_v1_gateway_proto_rawDesc = "" +
 	"\tis_pinned\x18\n" +
 	" \x01(\bR\bisPinned\x12\x1b\n" +
 	"\tpinned_at\x18\v \x01(\x03R\bpinnedAt\x12\x1b\n" +
-	"\tis_shared\x18\f \x01(\bR\bisShared\"_\n" +
+	"\tis_shared\x18\f \x01(\bR\bisShared\x12.\n" +
+	"\x13selected_model_json\x18\r \x01(\tR\x11selectedModelJson\"_\n" +
 	"\x11HistoryGetRequest\x12'\n" +
 	"\x0fconversation_id\x18\x01 \x01(\tR\x0econversationId\x12!\n" +
 	"\fmax_messages\x18\x02 \x01(\x05R\vmaxMessages\"\xb2\x02\n" +
diff --git a/crates/agent-gateway/proto/v1/gateway.proto b/crates/agent-gateway/proto/v1/gateway.proto
index c35bd1821..3d984de84 100644
--- a/crates/agent-gateway/proto/v1/gateway.proto
+++ b/crates/agent-gateway/proto/v1/gateway.proto
@@ -729,6 +729,7 @@ message ConversationSummary {
   bool is_pinned = 10;
   int64 pinned_at = 11;
   bool is_shared = 12;
+  string selected_model_json = 13;
 }
 
 message HistoryGetRequest {
diff --git a/crates/agent-gateway/web/src/app/GatewayApp.tsx b/crates/agent-gateway/web/src/app/GatewayApp.tsx
index 078faee40..4c8a02a02 100644
--- a/crates/agent-gateway/web/src/app/GatewayApp.tsx
+++ b/crates/agent-gateway/web/src/app/GatewayApp.tsx
@@ -77,11 +77,14 @@ import {
   isThinkingAlwaysOnForModel,
   normalizeChatRuntimeControlsForProvider,
   openRightDockSingletonTab,
+  parseSelectedModelJson,
   type RightDockFileTreeStatePatch,
   type RightDockProjectState,
   removeRightDockProjectState,
   resolveEffectiveTheme,
   resolveWorkspaceProjects,
+  type SelectedModel,
+  setSelectedModel,
   updateChatRuntimeControlsForProvider,
   updateCustomSettings,
   updateRightDockFileTreeState,
@@ -144,6 +147,7 @@ import {
   isChatEventTitleFinal,
   readChatEventTitle,
   readTunnelManagerToolChange,
+  resolveActiveModelSelection,
 } from "./chatEventUtils";
 import {
   CHAT_RUNTIME_FOREGROUND_PREPARE_TIMEOUT_MS,
@@ -223,6 +227,11 @@ export default function GatewayApp() {
   // currently authenticated browser-socket epoch.
   const [sidebarAgentStatusFresh, setSidebarAgentStatusFresh] = useState(false);
   const [conversationId, setConversationId] = useState("");
+  // 本地未持久化的会话模型切换（按会话 id 键）；发消息随 selected_model
+  // 落库后由 history-sync 回声在清理 effect 中收敛删除。
+  const [conversationModelOverrides, setConversationModelOverrides] = useState<
+    ReadonlyMap<string, SelectedModel>
+  >(new Map());
   const [chatError, setChatError] = useState<string | null>(null);
   // Sidebar errors raised outside the sidebar store (project removal flow).
   const [sidebarActionError, setSidebarActionError] = useState<string | null>(null);
@@ -812,9 +821,20 @@ export default function GatewayApp() {
           isPinned: existingNext?.isPinned ?? draftRow.isPinned,
           pinnedAt: existingNext ? existingNext.pinnedAt : draftRow.pinnedAt,
           isShared: existingNext?.isShared ?? draftRow.isShared,
+          selectedModelJson: existingNext?.selectedModelJson || draftRow.selectedModelJson,
           isPending: existingNext && existingNext.isPending !== true ? undefined : true,
         });
       }
+      // Re-key the local model override so the pick made on the draft keeps
+      // applying to the bound conversation.
+      setConversationModelOverrides((prev) => {
+        const override = prev.get(previousId);
+        if (!override) return prev;
+        const next = new Map(prev);
+        next.delete(previousId);
+        if (!next.has(nextId)) next.set(nextId, override);
+        return next;
+      });
     },
     [moveConversationUploads, sidebarStore, transcriptStoreRegistry],
   );
@@ -1436,6 +1456,47 @@ export default function GatewayApp() {
   // regardless of running state, which is what makes GUI queue auto-sends
   // race-free: the next run's events simply flow in).
   const displayedConversationId = resolveVisibleConversationId(selectedHistoryId, conversationId);
+
+  // 会话生效模型：本地 override > sidebar 行携带的持久化选择 > 全局默认。
+  const selectionForConversation = useCallback(
+    (targetConversationId: string) =>
+      resolveActiveModelSelection({
+        settings,
+        override: conversationModelOverrides.get(targetConversationId),
+        persistedSelectedModelJson: sidebarStore.peek(targetConversationId)?.selectedModelJson,
+      }),
+    [conversationModelOverrides, settings, sidebarStore],
+  );
+  const activeSelectedModel = useMemo(
+    () =>
+      resolveActiveModelSelection({
+        settings,
+        override: conversationModelOverrides.get(displayedConversationId),
+        persistedSelectedModelJson:
+          sidebarConversationsById.get(displayedConversationId)?.selectedModelJson,
+      }),
+    [conversationModelOverrides, displayedConversationId, settings, sidebarConversationsById],
+  );
+  // override 的持久化回声（本会话 selected_model 落库后随 history-sync 回流）
+  // 到达即清理，会话从此走服务器权威值。
+  useEffect(() => {
+    if (conversationModelOverrides.size === 0) return;
+    let changed = false;
+    const next = new Map(conversationModelOverrides);
+    for (const [id, override] of conversationModelOverrides) {
+      const persisted = parseSelectedModelJson(sidebarConversationsById.get(id)?.selectedModelJson);
+      if (
+        persisted &&
+        persisted.customProviderId === override.customProviderId &&
+        persisted.model === override.model
+      ) {
+        next.delete(id);
+        changed = true;
+      }
+    }
+    if (changed) setConversationModelOverrides(next);
+  }, [conversationModelOverrides, sidebarConversationsById]);
+
   const { transcript: displayedTranscript, busy: displayedConversationBusy } = useConversationChat({
     api,
     conversationId: displayedConversationId || null,
@@ -1765,6 +1826,7 @@ export default function GatewayApp() {
     if (isDisplayedConversation(activeConversationId)) {
       transcriptFollow.stickToBottom();
     }
+    const turnSelectedModel = selectionForConversation(activeConversationId);
     if (startedAsDraftConversation) {
       draftClientRequestsRef.current.set(clientRequestId, activeConversationId);
       // Optimistic pending sidebar row: survives authoritative reconciles
@@ -1772,8 +1834,8 @@ export default function GatewayApp() {
       sidebarStore.upsertLocal({
         id: activeConversationId,
         title: buildOptimisticConversationTitle(message),
-        providerId: settings.selectedModel?.customProviderId ?? "",
-        model: settings.selectedModel?.model ?? "",
+        providerId: turnSelectedModel?.customProviderId ?? "",
+        model: turnSelectedModel?.model ?? "",
         cwd: effectiveWorkdir || undefined,
         messageCount: 1,
         createdAt: startedAt,
@@ -1787,14 +1849,14 @@ export default function GatewayApp() {
       {
         providerId: currentChatProvider?.type,
         requestFormat: currentChatProvider?.requestFormat,
-        modelId: settings.selectedModel?.model,
+        modelId: turnSelectedModel?.model,
       },
     );
     const commandInput: GatewayChatCommandInput = {
       type: options?.editMessageRef ? "chat.edit_resend" : "chat.submit",
       message,
       conversationId: startedAsDraftConversation ? undefined : activeConversationId,
-      selectedModel: buildGatewaySelectedModel(settings.selectedModel, activeProviders),
+      selectedModel: buildGatewaySelectedModel(turnSelectedModel, activeProviders),
       systemSettings: buildGatewaySystemSettings(settings, effectiveWorkdir),
       uploadedFiles,
       clientRequestId,
@@ -1955,7 +2017,10 @@ export default function GatewayApp() {
           conversationId: isLocalDraftConversationId(conversationIdValue)
             ? undefined
             : conversationIdValue,
-          selectedModel: buildGatewaySelectedModel(settings.selectedModel, activeProviders),
+          selectedModel: buildGatewaySelectedModel(
+            selectionForConversation(conversationIdValue),
+            activeProviders,
+          ),
           systemSettings: buildGatewaySystemSettings(settings, workdirForTurn),
           uploadedFiles: materialized.uploadedFiles,
           clientRequestId: crypto.randomUUID(),
@@ -3055,65 +3120,63 @@ export default function GatewayApp() {
   );
 
   const currentModelLabel = useMemo(() => {
-    if (!settings.selectedModel) {
+    if (!activeSelectedModel) {
       return "选择模型";
     }
     const provider = activeProviders.find(
-      (item) => item.id === settings.selectedModel?.customProviderId,
+      (item) => item.id === activeSelectedModel.customProviderId,
     );
-    return provider
-      ? `${provider.name} / ${settings.selectedModel.model}`
-      : settings.selectedModel.model;
-  }, [activeProviders, settings.selectedModel]);
+    return provider ? `${provider.name} / ${activeSelectedModel.model}` : activeSelectedModel.model;
+  }, [activeProviders, activeSelectedModel]);
   const currentModelContextWindow = useMemo(() => {
-    if (!settings.selectedModel) {
+    if (!activeSelectedModel) {
       return undefined;
     }
     const provider = settings.customProviders.find(
-      (item) => item.id === settings.selectedModel?.customProviderId,
+      (item) => item.id === activeSelectedModel.customProviderId,
     );
     if (!provider) {
       return undefined;
     }
-    return findProviderModelConfig(provider, settings.selectedModel.model).contextWindow;
-  }, [settings.customProviders, settings.selectedModel]);
+    return findProviderModelConfig(provider, activeSelectedModel.model).contextWindow;
+  }, [settings.customProviders, activeSelectedModel]);
   const currentChatProvider = useMemo(() => {
-    if (!settings.selectedModel) {
+    if (!activeSelectedModel) {
       return undefined;
     }
     return settings.customProviders.find(
-      (item) => item.id === settings.selectedModel?.customProviderId,
+      (item) => item.id === activeSelectedModel.customProviderId,
     );
-  }, [settings.customProviders, settings.selectedModel]);
+  }, [settings.customProviders, activeSelectedModel]);
   const chatRuntimeReasoningOptions = useMemo(
     () =>
       getChatRuntimeReasoningLevelsForProvider({
         providerId: currentChatProvider?.type,
         requestFormat: currentChatProvider?.requestFormat,
-        modelId: settings.selectedModel?.model,
+        modelId: activeSelectedModel?.model,
       }),
-    [currentChatProvider?.requestFormat, currentChatProvider?.type, settings.selectedModel?.model],
+    [currentChatProvider?.requestFormat, currentChatProvider?.type, activeSelectedModel?.model],
   );
   const chatRuntimeThinkingAlwaysOn = useMemo(
     () =>
       isThinkingAlwaysOnForModel(
         currentChatProvider?.type ?? "claude_code",
-        settings.selectedModel?.model,
+        activeSelectedModel?.model,
       ),
-    [currentChatProvider?.type, settings.selectedModel?.model],
+    [currentChatProvider?.type, activeSelectedModel?.model],
   );
   const chatRuntimeControlsForCurrentProvider = useMemo(
     () =>
       normalizeChatRuntimeControlsForProvider(settings.chatRuntimeControls, {
         providerId: currentChatProvider?.type,
         requestFormat: currentChatProvider?.requestFormat,
-        modelId: settings.selectedModel?.model,
+        modelId: activeSelectedModel?.model,
       }),
     [
       currentChatProvider?.requestFormat,
       currentChatProvider?.type,
       settings.chatRuntimeControls,
-      settings.selectedModel?.model,
+      activeSelectedModel?.model,
     ],
   );
   const handleChatRuntimeControlsChange = useCallback(
@@ -3123,7 +3186,7 @@ export default function GatewayApp() {
         chatRuntimeControls: updateChatRuntimeControlsForProvider(prev.chatRuntimeControls, patch, {
           providerId: currentChatProvider?.type,
           requestFormat: currentChatProvider?.requestFormat,
-          modelId: settings.selectedModel?.model,
+          modelId: activeSelectedModel?.model,
         }),
       }));
     },
@@ -3131,7 +3194,7 @@ export default function GatewayApp() {
       currentChatProvider?.requestFormat,
       currentChatProvider?.type,
       setSettings,
-      settings.selectedModel?.model,
+      activeSelectedModel?.model,
     ],
   );
   const isAgentDevExecutionMode = isAgentDevMode(settings.system.executionMode);
@@ -3140,10 +3203,27 @@ export default function GatewayApp() {
     () => buildModelOptions(settings, { floatSelectedFirst: false }),
     [settings],
   );
-  const selectedValue = settings.selectedModel
-    ? toModelValue(settings.selectedModel.customProviderId, settings.selectedModel.model)
+  const selectedValue = activeSelectedModel
+    ? toModelValue(activeSelectedModel.customProviderId, activeSelectedModel.model)
     : undefined;
 
+  // 选择器切换：写当前会话的本地 override（下次发消息随 selected_model 落库），
+  // 并同步更新「新会话默认模型」（最近使用语义，走既有 settings 同步通道）。
+  const handleSelectModel = useCallback(
+    (selection: SelectedModel) => {
+      const targetConversationId = displayedConversationId.trim();
+      if (targetConversationId) {
+        setConversationModelOverrides((prev) => {
+          const next = new Map(prev);
+          next.set(targetConversationId, selection);
+          return next;
+        });
+      }
+      setSettings((prev) => setSelectedModel(prev, selection));
+    },
+    [displayedConversationId, setSettings],
+  );
+
   const skillsEnabled = settings.skills.enabled && isAgentMode;
   const selectedSkillNames = useMemo(
     () => (skillsEnabled ? mergeAlwaysEnabledSkillNames(settings.skills.selected) : []),
@@ -3812,7 +3892,7 @@ export default function GatewayApp() {
                     modelOptions={modelOptions}
                     selectedValue={selectedValue}
                     sidebarOpen={sidebarOpen}
-                    setSettings={setSettings}
+                    onSelectModel={handleSelectModel}
                     onOpenSettings={openSettings}
                     onToggleTheme={() =>
                       setSettings((prev) => ({
diff --git a/crates/agent-gateway/web/src/app/chatEventUtils.ts b/crates/agent-gateway/web/src/app/chatEventUtils.ts
index 9526050fb..ff084d438 100644
--- a/crates/agent-gateway/web/src/app/chatEventUtils.ts
+++ b/crates/agent-gateway/web/src/app/chatEventUtils.ts
@@ -1,5 +1,10 @@
 import type { ChatEvent, GatewaySelectedModel } from "@/lib/gatewayTypes";
-import type { AppSettings, SelectedModel } from "@/lib/settings";
+import {
+  type AppSettings,
+  normalizeSelectedModelForProviders,
+  parseSelectedModelJson,
+  type SelectedModel,
+} from "@/lib/settings";
 
 import type { ModelProviderSource, TunnelManagerToolChange } from "./types";
 
@@ -65,6 +70,25 @@ export function readTunnelManagerToolChange(event: ChatEvent): TunnelManagerTool
   return { action, projectPathKey };
 }
 
+// 会话生效模型的唯一派生点：本地未持久化的切换（override）>
+// history-sync 带回的会话持久化选择 > 全局默认（新会话语义）。
+// 前两级都按当前 providers 校验，失效则逐级回退。
+export function resolveActiveModelSelection(params: {
+  settings: AppSettings;
+  override?: SelectedModel;
+  persistedSelectedModelJson?: string;
+}): SelectedModel | undefined {
+  const { settings, override, persistedSelectedModelJson } = params;
+  return (
+    normalizeSelectedModelForProviders(override, settings.customProviders) ??
+    normalizeSelectedModelForProviders(
+      parseSelectedModelJson(persistedSelectedModelJson),
+      settings.customProviders,
+    ) ??
+    settings.selectedModel
+  );
+}
+
 export function buildGatewaySelectedModel(
   selectedModel: SelectedModel | undefined,
   providers: ModelProviderSource[],
diff --git a/crates/agent-gateway/web/src/lib/gatewayTypes.ts b/crates/agent-gateway/web/src/lib/gatewayTypes.ts
index c257ecbf8..f568dbec1 100644
--- a/crates/agent-gateway/web/src/lib/gatewayTypes.ts
+++ b/crates/agent-gateway/web/src/lib/gatewayTypes.ts
@@ -201,6 +201,7 @@ export type ConversationSummary = {
   model?: string;
   session_id?: string;
   cwd?: string;
+  selected_model_json?: string;
   is_pinned?: boolean;
   pinned_at?: number;
   is_shared?: boolean;
diff --git a/crates/agent-gateway/web/src/lib/settings/index.ts b/crates/agent-gateway/web/src/lib/settings/index.ts
index f78ea7b56..99a6b1a71 100644
--- a/crates/agent-gateway/web/src/lib/settings/index.ts
+++ b/crates/agent-gateway/web/src/lib/settings/index.ts
@@ -1422,6 +1422,22 @@ export function normalizeSelectedModel(input: unknown): SelectedModel | undefine
   return { customProviderId, model };
 }
 
+export function parseSelectedModelJson(json: string | null | undefined): SelectedModel | undefined {
+  if (!json?.trim()) return undefined;
+  try {
+    return normalizeSelectedModel(JSON.parse(json));
+  } catch {
+    return undefined;
+  }
+}
+
+export function serializeSelectedModelJson(
+  selectedModel: SelectedModel | undefined,
+): string | undefined {
+  const normalized = normalizeSelectedModel(selectedModel);
+  return normalized ? JSON.stringify(normalized) : undefined;
+}
+
 export function normalizeTheme(input: unknown): Theme {
   if (input === "dark") return "dark";
   if (input === "system" || input === "auto") return "system";
@@ -1569,7 +1585,7 @@ export function computeNextMemoryOrganizerRunAt(
   return candidate.getTime();
 }
 
-function normalizeSelectedModelForProviders(
+export function normalizeSelectedModelForProviders(
   selectedModel: SelectedModel | undefined,
   customProviders: CustomProvider[],
 ): SelectedModel | undefined {
diff --git a/crates/agent-gateway/web/src/lib/sidebar/reconcile.ts b/crates/agent-gateway/web/src/lib/sidebar/reconcile.ts
index 5e4b5d048..5c7ebe69f 100644
--- a/crates/agent-gateway/web/src/lib/sidebar/reconcile.ts
+++ b/crates/agent-gateway/web/src/lib/sidebar/reconcile.ts
@@ -92,6 +92,7 @@ function sameSidebarConversation(left: SidebarConversation, right: SidebarConver
     left.isPinned === right.isPinned &&
     left.pinnedAt === right.pinnedAt &&
     left.isShared === right.isShared &&
+    left.selectedModelJson === right.selectedModelJson &&
     left.isPending === right.isPending
   );
 }
@@ -121,6 +122,7 @@ export function mergeSidebarConversation(
     isPinned: next.isPinned ?? existing.isPinned,
     pinnedAt: "pinnedAt" in next ? next.pinnedAt : existing.pinnedAt,
     isShared: next.isShared ?? existing.isShared,
+    selectedModelJson: mergeOptionalText(next.selectedModelJson, existing.selectedModelJson),
     isPending: next.isPending === true ? true : undefined,
   };
 
diff --git a/crates/agent-gateway/web/src/lib/sidebar/types.ts b/crates/agent-gateway/web/src/lib/sidebar/types.ts
index 96d18f061..9da7d4f63 100644
--- a/crates/agent-gateway/web/src/lib/sidebar/types.ts
+++ b/crates/agent-gateway/web/src/lib/sidebar/types.ts
@@ -18,6 +18,7 @@ export type SidebarConversation = {
   isPinned?: boolean;
   pinnedAt?: number | null;
   isShared?: boolean;
+  selectedModelJson?: string;
   // Local-only draft/persisting row; survives authoritative reconciles until
   // the backend confirms (an upsert event clears it) or it is removed locally.
   isPending?: boolean;
diff --git a/crates/agent-gateway/web/src/lib/sidebar/webSidebarBackend.ts b/crates/agent-gateway/web/src/lib/sidebar/webSidebarBackend.ts
index 3518cbe02..d3c5340e8 100644
--- a/crates/agent-gateway/web/src/lib/sidebar/webSidebarBackend.ts
+++ b/crates/agent-gateway/web/src/lib/sidebar/webSidebarBackend.ts
@@ -52,6 +52,9 @@ export function normalizeGatewayConversationSummary(
     model: summary.model ?? "",
     sessionId: summary.session_id?.trim() ? summary.session_id : undefined,
     cwd: summary.cwd?.trim() ? summary.cwd : undefined,
+    selectedModelJson: summary.selected_model_json?.trim()
+      ? summary.selected_model_json
+      : undefined,
     messageCount: summary.message_count,
     createdAt: normalizeGatewayEpochMs(summary.created_at),
     updatedAt: normalizeGatewayEpochMs(summary.updated_at),
diff --git a/crates/agent-gateway/web/src/pages/chat/ChatHeader.tsx b/crates/agent-gateway/web/src/pages/chat/ChatHeader.tsx
index 05d9b03a5..20c60778d 100644
--- a/crates/agent-gateway/web/src/pages/chat/ChatHeader.tsx
+++ b/crates/agent-gateway/web/src/pages/chat/ChatHeader.tsx
@@ -26,7 +26,7 @@ import {
   type AppSettings,
   getNextTheme,
   type ProviderId,
-  setSelectedModel,
+  type SelectedModel,
   type Theme,
 } from "../../lib/settings";
 import { cn } from "../../lib/shared/utils";
@@ -52,7 +52,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
   modelOptions: ModelOption[];
   selectedValue?: string;
   sidebarOpen: boolean;
-  setSettings: (updater: (prev: AppSettings) => AppSettings) => void;
+  onSelectModel: (selection: SelectedModel) => void;
   onOpenSettings: (section?: SectionId) => void;
   onToggleTheme: () => void;
   onOpenSidebar: () => void;
@@ -66,7 +66,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
     modelOptions,
     selectedValue,
     sidebarOpen,
-    setSettings,
+    onSelectModel,
     onOpenSettings,
     onToggleTheme,
     onOpenSidebar,
@@ -208,7 +208,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
                                 onSelect={() => {
                                   const parsed = parseModelValue(option.value);
                                   if (!parsed) return;
-                                  setSettings((prev) => setSelectedModel(prev, parsed));
+                                  onSelectModel(parsed);
                                 }}
                                 className={cn(
                                   "model-selector-item h-[30px] max-w-full shrink-0 justify-between gap-3 overflow-hidden py-0 text-xs font-normal leading-5 text-foreground transition-none focus:bg-foreground/[0.05] dark:text-white",
diff --git a/crates/agent-gateway/web/test/web-sidebar-backend.test.mjs b/crates/agent-gateway/web/test/web-sidebar-backend.test.mjs
index 44d4868f6..c55345efb 100644
--- a/crates/agent-gateway/web/test/web-sidebar-backend.test.mjs
+++ b/crates/agent-gateway/web/test/web-sidebar-backend.test.mjs
@@ -32,6 +32,7 @@ function summary(id, overrides = {}) {
     is_pinned: overrides.is_pinned,
     pinned_at: overrides.pinned_at,
     is_shared: overrides.is_shared,
+    selected_model_json: overrides.selected_model_json,
   };
 }
 
@@ -118,6 +119,7 @@ test("normalize maps snake_case summaries with second→ms timestamps and empty
   assert.equal(normalized.model, "");
   assert.equal(normalized.sessionId, undefined);
   assert.equal(normalized.cwd, undefined);
+  assert.equal(normalized.selectedModelJson, undefined);
   assert.equal(normalized.createdAt, MILLIS);
   assert.equal(normalized.updatedAt, (SECONDS + 5) * 1000);
   assert.equal(normalized.isPinned, true);
@@ -134,6 +136,16 @@ test("normalize maps snake_case summaries with second→ms timestamps and empty
   // Blank titles fall back through formatConversationTitle.
   const untitled = normalizeGatewayConversationSummary(summary("c3", { title: "  " }));
   assert.notEqual(untitled.title.trim(), "");
+
+  // Non-empty selected_model_json passes through; blank normalizes to undefined.
+  const withSelection = normalizeGatewayConversationSummary(
+    summary("c4", { selected_model_json: '{"customProviderId":"p1","model":"m1"}' }),
+  );
+  assert.equal(withSelection.selectedModelJson, '{"customProviderId":"p1","model":"m1"}');
+  const blankSelection = normalizeGatewayConversationSummary(
+    summary("c5", { selected_model_json: "  " }),
+  );
+  assert.equal(blankSelection.selectedModelJson, undefined);
 });
 
 test("listConversations normalizes items/workdirs and hydrates the activity store", async () => {
diff --git a/crates/agent-gui/src-tauri/src/commands/history/chat_history/commands.rs b/crates/agent-gui/src-tauri/src/commands/history/chat_history/commands.rs
index c70af219c..bd11cde1a 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/chat_history/commands.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/chat_history/commands.rs
@@ -132,6 +132,7 @@ pub async fn chat_history_get_active_segment(
             model: record.model,
             session_id: record.session_id,
             cwd: record.cwd,
+            selected_model_json: record.selected_model_json,
             context_meta_json,
             active_segment_index,
             total_segment_count,
@@ -160,6 +161,7 @@ pub(crate) async fn chat_history_upsert_inner(
             model: input.model.clone(),
             session_id: input.session_id.clone(),
             cwd: input.cwd.clone(),
+            selected_model_json: input.selected_model_json.clone(),
             context_meta_json: input.context_meta_json.clone(),
             active_segment_index: input.active_segment_index,
             total_segment_count: input.total_segment_count,
@@ -324,6 +326,31 @@ pub async fn chat_history_set_pinned(
     Ok(summary)
 }
 
+pub(crate) async fn chat_history_set_model_inner(
+    id: String,
+    selected_model_json: String,
+) -> Result<ChatHistorySummary, String> {
+    tauri::async_runtime::spawn_blocking(move || {
+        let conn = open_db()?;
+        set_chat_history_model_sync(&conn, &id, &selected_model_json)
+    })
+    .await
+    .map_err(|e| format!("chat_history_set_model join 失败：{e}"))?
+}
+
+#[tauri::command]
+pub async fn chat_history_set_model(
+    id: String,
+    selected_model_json: String,
+    gateway_controller: tauri::State<'_, Arc<GatewayController>>,
+) -> Result<ChatHistorySummary, String> {
+    let summary = chat_history_set_model_inner(id, selected_model_json).await?;
+    gateway_controller
+        .publish_history_sync(build_history_sync_upsert(&summary))
+        .await;
+    Ok(summary)
+}
+
 pub(crate) async fn chat_history_share_get_inner(
     id: String,
 ) -> Result<ChatHistoryShareStatus, String> {
diff --git a/crates/agent-gui/src-tauri/src/commands/history/chat_history/repository.rs b/crates/agent-gui/src-tauri/src/commands/history/chat_history/repository.rs
index 81db44fb3..62f2be515 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/chat_history/repository.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/chat_history/repository.rs
@@ -6,6 +6,7 @@ fn row_to_summary(row: &rusqlite::Row<'_>) -> rusqlite::Result<ChatHistorySummar
         model: row.get("model")?,
         session_id: row.get("session_id")?,
         cwd: row.get("cwd")?,
+        selected_model_json: row.get("selected_model_json")?,
         message_count: row.get("total_message_count")?,
         created_at: row.get("created_at")?,
         updated_at: row.get("updated_at")?,
@@ -23,6 +24,7 @@ fn row_to_record(row: &rusqlite::Row<'_>) -> rusqlite::Result<ChatHistoryRecord>
         model: row.get("model")?,
         session_id: row.get("session_id")?,
         cwd: row.get("cwd")?,
+        selected_model_json: row.get("selected_model_json")?,
         context_meta_json: row.get("context_meta_json")?,
         active_segment_index: row.get("active_segment_index")?,
         total_segment_count: row.get("total_segment_count")?,
@@ -61,6 +63,7 @@ fn get_summary_by_id(conn: &Connection, id: &str) -> Result<ChatHistorySummary,
             h.model AS model,
             h.session_id AS session_id,
             h.cwd AS cwd,
+            h.selected_model_json AS selected_model_json,
             h.total_message_count AS total_message_count,
             h.created_at AS created_at,
             h.updated_at AS updated_at,
@@ -97,6 +100,7 @@ fn get_record_by_id(conn: &Connection, id: &str) -> Result<ChatHistoryRecord, St
             h.model AS model,
             h.session_id AS session_id,
             h.cwd AS cwd,
+            h.selected_model_json AS selected_model_json,
             h.context_meta_json AS context_meta_json,
             h.active_segment_index AS active_segment_index,
             h.total_segment_count AS total_segment_count,
@@ -201,6 +205,7 @@ pub(crate) fn list_chat_history_sync_with_filter(
                 h.model AS model,
                 h.session_id AS session_id,
                 h.cwd AS cwd,
+                h.selected_model_json AS selected_model_json,
                 h.total_message_count AS total_message_count,
                 h.created_at AS created_at,
                 h.updated_at AS updated_at,
@@ -309,6 +314,7 @@ pub(crate) fn list_shared_chat_history_sync(
                 h.model AS model,
                 h.session_id AS session_id,
                 h.cwd AS cwd,
+                h.selected_model_json AS selected_model_json,
                 h.total_message_count AS total_message_count,
                 h.created_at AS created_at,
                 h.updated_at AS updated_at,
diff --git a/crates/agent-gui/src-tauri/src/commands/history/chat_history/segments.rs b/crates/agent-gui/src-tauri/src/commands/history/chat_history/segments.rs
index a1af4c49e..1714b4e91 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/chat_history/segments.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/chat_history/segments.rs
@@ -36,6 +36,7 @@ fn validate_upsert_input(input: &ChatHistoryUpsertInput) -> Result<(), String> {
         model: input.model.clone(),
         session_id: input.session_id.clone(),
         cwd: input.cwd.clone(),
+        selected_model_json: input.selected_model_json.clone(),
         context_meta_json: input.context_meta_json.clone(),
         active_segment_index: input.active_segment_index,
         total_segment_count: input.total_segment_count,
@@ -315,6 +316,12 @@ fn upsert_chat_history_header(
         .map(str::trim)
         .filter(|value| !value.is_empty())
         .map(str::to_string);
+    let selected_model_json = input
+        .selected_model_json
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string);
 
     conn.execute(
         "
@@ -325,19 +332,21 @@ fn upsert_chat_history_header(
             model,
             session_id,
             cwd,
+            selected_model_json,
             context_meta_json,
             active_segment_index,
             total_segment_count,
             total_message_count,
             created_at,
             updated_at
-        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13)
         ON CONFLICT(id) DO UPDATE SET
             title = excluded.title,
             provider_id = excluded.provider_id,
             model = excluded.model,
             session_id = excluded.session_id,
             cwd = excluded.cwd,
+            selected_model_json = COALESCE(excluded.selected_model_json, chatHistory.selected_model_json),
             context_meta_json = excluded.context_meta_json,
             active_segment_index = excluded.active_segment_index,
             total_segment_count = excluded.total_segment_count,
@@ -351,6 +360,7 @@ fn upsert_chat_history_header(
             input.model.trim(),
             session_id,
             cwd,
+            selected_model_json,
             input.context_meta_json.trim(),
             input.active_segment_index,
             input.total_segment_count,
@@ -364,6 +374,47 @@ fn upsert_chat_history_header(
     Ok(())
 }
 
+fn set_chat_history_model_sync(
+    conn: &Connection,
+    id: &str,
+    selected_model_json: &str,
+) -> Result<ChatHistorySummary, String> {
+    let chat_id = id.trim();
+    if chat_id.is_empty() {
+        return Err("历史对话 id 不能为空".to_string());
+    }
+
+    let payload = selected_model_json.trim();
+    let parsed: serde_json::Value =
+        serde_json::from_str(payload).map_err(|_| "会话模型选择格式无效".to_string())?;
+    let has_non_empty = |key: &str| {
+        parsed
+            .get(key)
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|value| !value.trim().is_empty())
+    };
+    if !has_non_empty("customProviderId") || !has_non_empty("model") {
+        return Err("会话模型选择格式无效".to_string());
+    }
+
+    let affected = conn
+        .execute(
+            "
+            UPDATE chatHistory
+            SET selected_model_json = ?1
+            WHERE id = ?2
+            ",
+            params![payload, chat_id],
+        )
+        .map_err(|e| format!("更新历史对话模型选择失败：{e}"))?;
+
+    if affected == 0 {
+        return Err("未找到对应的历史对话".to_string());
+    }
+
+    get_summary_by_id(conn, chat_id)
+}
+
 fn set_chat_history_pinned_sync(
     conn: &Connection,
     id: &str,
diff --git a/crates/agent-gui/src-tauri/src/commands/history/chat_history/tests.rs b/crates/agent-gui/src-tauri/src/commands/history/chat_history/tests.rs
index a33d63057..89ab6b67b 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/chat_history/tests.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/chat_history/tests.rs
@@ -19,6 +19,7 @@ mod tests {
             model: "gpt-5".to_string(),
             session_id: Some("session-1".to_string()),
             cwd: Some("/tmp".to_string()),
+            selected_model_json: None,
             context_meta_json: "{}".to_string(),
             active_segment_index: 0,
             total_segment_count: 1,
@@ -524,6 +525,105 @@ mod tests {
         assert_eq!(summary.title, "Updated Conversation");
     }
 
+    #[test]
+    fn v1_database_gains_selected_model_column_via_v2_migration() {
+        // 复现存量库场景：完整的 v1 schema（无 selected_model_json）且
+        // user_version 已到 1——版本门禁必须由 v2 迁移补齐新列。
+        let v1 = Connection::open_in_memory().expect("open v1 in-memory chat history database");
+        v1.execute_batch(
+            "
+            CREATE TABLE chatHistory (
+                id TEXT PRIMARY KEY,
+                title TEXT NOT NULL,
+                provider_id TEXT NOT NULL,
+                model TEXT NOT NULL,
+                session_id TEXT,
+                cwd TEXT,
+                context_meta_json TEXT,
+                active_segment_index INTEGER,
+                total_segment_count INTEGER,
+                total_message_count INTEGER,
+                created_at INTEGER NOT NULL,
+                updated_at INTEGER NOT NULL,
+                is_pinned INTEGER NOT NULL DEFAULT 0,
+                pinned_at INTEGER
+            );
+            PRAGMA user_version = 1;
+            ",
+        )
+        .expect("create v1 chatHistory schema");
+
+        history_db::initialize_connection(&v1).expect("migrate v1 schema to v2");
+
+        assert!(
+            table_column_names(&v1, "chatHistory").contains(&"selected_model_json".to_string()),
+            "v2 migration should add selected_model_json to a v1 database"
+        );
+    }
+
+    #[test]
+    fn set_model_persists_without_bumping_updated_at() {
+        let conn = open_test_db().expect("open test db");
+        let conversation = sample_conversation();
+        upsert_chat_history_header(&conn, &conversation).expect("upsert header");
+        let before = get_summary_by_id(&conn, "conv-1").expect("load summary");
+
+        let payload = r#"{"customProviderId":"provider-a","model":"claude-fable-5"}"#;
+        let summary =
+            set_chat_history_model_sync(&conn, "conv-1", payload).expect("set conversation model");
+
+        assert_eq!(summary.selected_model_json.as_deref(), Some(payload));
+        assert_eq!(summary.updated_at, before.updated_at);
+        assert_eq!(summary.title, before.title);
+    }
+
+    #[test]
+    fn set_model_rejects_invalid_payloads() {
+        let conn = open_test_db().expect("open test db");
+        let conversation = sample_conversation();
+        upsert_chat_history_header(&conn, &conversation).expect("upsert header");
+
+        assert!(set_chat_history_model_sync(&conn, "conv-1", "not-json").is_err());
+        assert!(set_chat_history_model_sync(&conn, "conv-1", r#"{"model":"m"}"#).is_err());
+        assert!(set_chat_history_model_sync(
+            &conn,
+            "conv-1",
+            r#"{"customProviderId":" ","model":"m"}"#
+        )
+        .is_err());
+        assert!(set_chat_history_model_sync(
+            &conn,
+            "conv-missing",
+            r#"{"customProviderId":"provider-a","model":"m"}"#
+        )
+        .is_err());
+
+        let summary = get_summary_by_id(&conn, "conv-1").expect("load summary");
+        assert_eq!(summary.selected_model_json, None);
+    }
+
+    #[test]
+    fn upsert_header_preserves_selected_model_when_input_none() {
+        let conn = open_test_db().expect("open test db");
+        let mut conversation = sample_conversation();
+        upsert_chat_history_header(&conn, &conversation).expect("upsert header");
+
+        let payload = r#"{"customProviderId":"provider-a","model":"claude-fable-5"}"#;
+        set_chat_history_model_sync(&conn, "conv-1", payload).expect("set conversation model");
+
+        conversation.updated_at += 1_000;
+        upsert_chat_history_header(&conn, &conversation).expect("upsert without selection");
+        let preserved = get_summary_by_id(&conn, "conv-1").expect("load summary");
+        assert_eq!(preserved.selected_model_json.as_deref(), Some(payload));
+
+        let replacement = r#"{"customProviderId":"provider-b","model":"gpt-5"}"#;
+        conversation.selected_model_json = Some(replacement.to_string());
+        conversation.updated_at += 1_000;
+        upsert_chat_history_header(&conn, &conversation).expect("upsert with new selection");
+        let replaced = get_summary_by_id(&conn, "conv-1").expect("load summary");
+        assert_eq!(replaced.selected_model_json.as_deref(), Some(replacement));
+    }
+
     #[test]
     fn rename_preserves_existing_pin_state() {
         let conn = open_test_db().expect("open test db");
diff --git a/crates/agent-gui/src-tauri/src/commands/history/chat_history/types.rs b/crates/agent-gui/src-tauri/src/commands/history/chat_history/types.rs
index eee41bafc..9c3ec857a 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/chat_history/types.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/chat_history/types.rs
@@ -7,6 +7,7 @@ pub struct ChatHistorySummary {
     pub model: String,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub message_count: i64,
     pub created_at: i64,
     pub updated_at: i64,
@@ -65,6 +66,7 @@ pub struct ChatHistoryRecord {
     pub model: String,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub context_meta_json: String,
     pub active_segment_index: i64,
     pub total_segment_count: i64,
@@ -98,6 +100,7 @@ pub struct ChatHistoryActiveSegmentRecord {
     pub model: String,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub context_meta_json: String,
     pub active_segment_index: i64,
     pub total_segment_count: i64,
@@ -133,6 +136,7 @@ pub struct ChatHistoryUpsertInput {
     pub model: String,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub context_meta_json: String,
     pub active_segment_index: i64,
     pub total_segment_count: i64,
@@ -151,6 +155,7 @@ pub struct ChatHistoryConversationInput {
     pub model: String,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub context_meta_json: String,
     pub active_segment_index: i64,
     pub total_segment_count: i64,
diff --git a/crates/agent-gui/src-tauri/src/commands/history/history_db.rs b/crates/agent-gui/src-tauri/src/commands/history/history_db.rs
index 1771e4f7f..852ce9132 100644
--- a/crates/agent-gui/src-tauri/src/commands/history/history_db.rs
+++ b/crates/agent-gui/src-tauri/src/commands/history/history_db.rs
@@ -2,7 +2,7 @@ use rusqlite::{Connection, OptionalExtension};
 use std::{collections::HashSet, fs, path::PathBuf, sync::Mutex, time::Duration};
 
 const DB_FILENAME: &str = "chat-history.sqlite3";
-const HISTORY_DB_SCHEMA_VERSION: i64 = 1;
+const HISTORY_DB_SCHEMA_VERSION: i64 = 2;
 
 static HISTORY_DB_MIGRATION_LOCK: Mutex<()> = Mutex::new(());
 
@@ -83,6 +83,11 @@ fn migrate_history_db_inner(conn: &Connection) -> Result<(), String> {
         set_user_version(conn, 1)?;
     }
 
+    if current_version < 2 {
+        migrate_to_v2(conn)?;
+        set_user_version(conn, 2)?;
+    }
+
     // The subagent schema is versioned independently via subagentMeta and is
     // safe to (re)ensure on every startup.
     ensure_subagent_schema(conn)?;
@@ -95,6 +100,13 @@ fn migrate_to_v1(conn: &Connection) -> Result<(), String> {
     Ok(())
 }
 
+// v2: chatHistory 新增 selected_model_json（每会话模型选择）。schema ensure
+// 本身幂等，重跑即补齐缺失列。
+fn migrate_to_v2(conn: &Connection) -> Result<(), String> {
+    ensure_chat_history_schema(conn)?;
+    Ok(())
+}
+
 fn read_table_columns(
     conn: &Connection,
     table_name: &str,
@@ -163,7 +175,8 @@ fn ensure_chat_history_schema(conn: &Connection) -> Result<(), String> {
             created_at INTEGER NOT NULL,
             updated_at INTEGER NOT NULL,
             is_pinned INTEGER NOT NULL DEFAULT 0,
-            pinned_at INTEGER
+            pinned_at INTEGER,
+            selected_model_json TEXT
         );
 
         CREATE TABLE IF NOT EXISTS chatHistorySegment (
@@ -271,6 +284,10 @@ fn ensure_chat_history_columns(conn: &Connection) -> Result<(), String> {
                 "pinned_at",
                 "ALTER TABLE chatHistory ADD COLUMN pinned_at INTEGER;",
             ),
+            (
+                "selected_model_json",
+                "ALTER TABLE chatHistory ADD COLUMN selected_model_json TEXT;",
+            ),
         ],
     )?;
 
@@ -715,7 +732,10 @@ mod tests {
     #[test]
     fn initialize_connection_sets_schema_version() {
         let conn = open_test_db();
-        assert_eq!(read_user_version(&conn).expect("read version"), 1);
+        assert_eq!(
+            read_user_version(&conn).expect("read version"),
+            HISTORY_DB_SCHEMA_VERSION
+        );
     }
 
     #[test]
@@ -782,10 +802,14 @@ mod tests {
 
         initialize_connection(&conn).expect("migrate legacy history schema");
 
-        assert_eq!(read_user_version(&conn).expect("read version"), 1);
+        assert_eq!(
+            read_user_version(&conn).expect("read version"),
+            HISTORY_DB_SCHEMA_VERSION
+        );
         for (table_name, column_name) in [
             ("chatHistory", "context_meta_json"),
             ("chatHistory", "is_pinned"),
+            ("chatHistory", "selected_model_json"),
             ("subagentRun", "prompt"),
             ("subagentRun", "context_schema_version"),
         ] {
diff --git a/crates/agent-gui/src-tauri/src/lib.rs b/crates/agent-gui/src-tauri/src/lib.rs
index 77d31aef9..928acd48a 100644
--- a/crates/agent-gui/src-tauri/src/lib.rs
+++ b/crates/agent-gui/src-tauri/src/lib.rs
@@ -44,6 +44,7 @@ macro_rules! app_invoke_handler {
             commands::chat_history::chat_history_append_segment,
             commands::chat_history::chat_history_rename,
             commands::chat_history::chat_history_set_pinned,
+            commands::chat_history::chat_history_set_model,
             commands::chat_history::chat_history_share_get,
             commands::chat_history::chat_history_share_set,
             commands::chat_history::chat_history_delete,
diff --git a/crates/agent-gui/src-tauri/src/services/gateway/history_sync.rs b/crates/agent-gui/src-tauri/src/services/gateway/history_sync.rs
index 4ffb7b387..ea69f1446 100644
--- a/crates/agent-gui/src-tauri/src/services/gateway/history_sync.rs
+++ b/crates/agent-gui/src-tauri/src/services/gateway/history_sync.rs
@@ -15,6 +15,7 @@ pub fn build_history_sync_upsert(summary: &ChatHistorySummary) -> GatewayHistory
             model: Some(summary.model.clone()),
             session_id: summary.session_id.clone(),
             cwd: summary.cwd.clone(),
+            selected_model_json: summary.selected_model_json.clone(),
             created_at: summary.created_at,
             updated_at: summary.updated_at,
             message_count: summary.message_count,
@@ -48,6 +49,8 @@ pub(crate) fn build_history_sync_upsert_from_proto(
             model: (!summary.model.trim().is_empty()).then(|| summary.model.clone()),
             session_id: (!summary.session_id.trim().is_empty()).then(|| summary.session_id.clone()),
             cwd: (!summary.cwd.trim().is_empty()).then(|| summary.cwd.clone()),
+            selected_model_json: (!summary.selected_model_json.trim().is_empty())
+                .then(|| summary.selected_model_json.clone()),
             created_at: summary.created_at,
             updated_at: summary.updated_at,
             message_count: i64::from(summary.message_count),
@@ -88,6 +91,7 @@ pub(crate) fn build_history_sync_envelope(
             model: conversation.model.unwrap_or_default(),
             session_id: conversation.session_id.unwrap_or_default(),
             cwd: conversation.cwd.unwrap_or_default(),
+            selected_model_json: conversation.selected_model_json.unwrap_or_default(),
             is_pinned: conversation.is_pinned,
             pinned_at: conversation.pinned_at.unwrap_or_default(),
             is_shared: conversation.is_shared,
diff --git a/crates/agent-gui/src-tauri/src/services/gateway/types.rs b/crates/agent-gui/src-tauri/src/services/gateway/types.rs
index 7ea64c957..59e03400c 100644
--- a/crates/agent-gui/src-tauri/src/services/gateway/types.rs
+++ b/crates/agent-gui/src-tauri/src/services/gateway/types.rs
@@ -176,6 +176,7 @@ pub struct GatewayHistorySyncConversation {
     pub model: Option<String>,
     pub session_id: Option<String>,
     pub cwd: Option<String>,
+    pub selected_model_json: Option<String>,
     pub created_at: i64,
     pub updated_at: i64,
     pub message_count: i64,
diff --git a/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs b/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
index 8a36e02b7..45c636257 100644
--- a/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
+++ b/crates/agent-gui/src-tauri/src/services/gateway_bridge.rs
@@ -154,6 +154,7 @@ fn build_proto_history_list_response(
             model: item.model,
             session_id: item.session_id.unwrap_or_default(),
             cwd: item.cwd.unwrap_or_default(),
+            selected_model_json: item.selected_model_json.unwrap_or_default(),
             is_pinned: item.is_pinned,
             pinned_at: item.pinned_at.unwrap_or_default(),
             is_shared: item.is_shared,
@@ -1509,6 +1510,7 @@ fn build_proto_conversation_summary_from_record(
         model: record.model.clone(),
         session_id: record.session_id.clone().unwrap_or_default(),
         cwd: record.cwd.clone().unwrap_or_default(),
+        selected_model_json: record.selected_model_json.clone().unwrap_or_default(),
         is_pinned: record.is_pinned,
         pinned_at: record.pinned_at.unwrap_or_default(),
         is_shared: record.is_shared,
@@ -1528,6 +1530,7 @@ fn build_proto_conversation_summary(
         model: summary.model,
         session_id: summary.session_id.unwrap_or_default(),
         cwd: summary.cwd.unwrap_or_default(),
+        selected_model_json: summary.selected_model_json.unwrap_or_default(),
         is_pinned: summary.is_pinned,
         pinned_at: summary.pinned_at.unwrap_or_default(),
         is_shared: summary.is_shared,
@@ -1560,6 +1563,7 @@ fn history_list_json(page: chat_history::ChatHistoryListResponse) -> Value {
                 "model": item.model,
                 "session_id": item.session_id.unwrap_or_default(),
                 "cwd": item.cwd.unwrap_or_default(),
+                "selected_model_json": item.selected_model_json.unwrap_or_default(),
                 "is_pinned": item.is_pinned,
                 "pinned_at": item.pinned_at.unwrap_or_default(),
                 "is_shared": item.is_shared,
diff --git a/crates/agent-gui/src/lib/chat/history/chatHistory.ts b/crates/agent-gui/src/lib/chat/history/chatHistory.ts
index 532853596..29462179c 100644
--- a/crates/agent-gui/src/lib/chat/history/chatHistory.ts
+++ b/crates/agent-gui/src/lib/chat/history/chatHistory.ts
@@ -16,6 +16,7 @@ export type ChatHistorySummary = {
   model: string;
   sessionId?: string;
   cwd?: string;
+  selectedModelJson?: string;
   messageCount?: number;
   createdAt: number;
   updatedAt: number;
@@ -100,6 +101,7 @@ type ChatHistoryUpsertInput = {
   model: string;
   sessionId?: string;
   cwd?: string;
+  selectedModelJson?: string;
   contextMetaJson: string;
   activeSegmentIndex: number;
   totalSegmentCount: number;
@@ -194,6 +196,7 @@ function normalizeWireRecord(
     model: record.model,
     sessionId: record.sessionId,
     cwd: record.cwd,
+    selectedModelJson: record.selectedModelJson,
     createdAt: record.createdAt,
     updatedAt: record.updatedAt,
     isPinned: record.isPinned,
@@ -245,6 +248,7 @@ export async function getChatHistoryActiveSegment(id: string, fallbackSystemProm
     model: record.model,
     sessionId: record.sessionId,
     cwd: record.cwd,
+    selectedModelJson: record.selectedModelJson,
     createdAt: record.createdAt,
     updatedAt: record.updatedAt,
     isPinned: record.isPinned,
@@ -281,13 +285,24 @@ function buildChatHistoryConversationInput(params: {
   model: string;
   sessionId?: string;
   cwd?: string;
+  selectedModelJson?: string;
   title: string;
   createdAt?: number;
   updatedAt: number;
   state: ConversationViewState;
 }): ChatHistoryConversationInput {
-  const { conversationId, providerId, model, sessionId, cwd, title, createdAt, updatedAt, state } =
-    params;
+  const {
+    conversationId,
+    providerId,
+    model,
+    sessionId,
+    cwd,
+    selectedModelJson,
+    title,
+    createdAt,
+    updatedAt,
+    state,
+  } = params;
 
   return {
     id: conversationId,
@@ -296,6 +311,7 @@ function buildChatHistoryConversationInput(params: {
     model,
     sessionId,
     cwd,
+    selectedModelJson,
     contextMetaJson: JSON.stringify(state.meta),
     activeSegmentIndex: state.activeSegmentIndex,
     totalSegmentCount: state.meta.totalSegmentCount,
@@ -344,6 +360,12 @@ export async function setChatHistoryPinned(id: string, isPinned: boolean) {
   );
 }
 
+export async function setChatHistoryModel(id: string, selectedModelJson: string) {
+  return withConversationWriteLock(id, () =>
+    invoke<ChatHistorySummary>("chat_history_set_model", { id, selectedModelJson }),
+  );
+}
+
 export async function getChatHistoryShare(id: string) {
   return invoke<ChatHistoryShareStatus>("chat_history_share_get", { id });
 }
@@ -399,6 +421,7 @@ type PersistConversationStateParams = {
   model: string;
   sessionId?: string;
   cwd?: string;
+  selectedModelJson?: string;
   title: string;
   createdAt?: number;
   updatedAt: number;
diff --git a/crates/agent-gui/src/lib/settings/index.ts b/crates/agent-gui/src/lib/settings/index.ts
index af0060c94..f5f751105 100644
--- a/crates/agent-gui/src/lib/settings/index.ts
+++ b/crates/agent-gui/src/lib/settings/index.ts
@@ -1325,6 +1325,22 @@ export function normalizeSelectedModel(input: unknown): SelectedModel | undefine
   return { customProviderId, model };
 }
 
+export function parseSelectedModelJson(json: string | null | undefined): SelectedModel | undefined {
+  if (!json?.trim()) return undefined;
+  try {
+    return normalizeSelectedModel(JSON.parse(json));
+  } catch {
+    return undefined;
+  }
+}
+
+export function serializeSelectedModelJson(
+  selectedModel: SelectedModel | undefined,
+): string | undefined {
+  const normalized = normalizeSelectedModel(selectedModel);
+  return normalized ? JSON.stringify(normalized) : undefined;
+}
+
 export function normalizeTheme(input: unknown): Theme {
   if (input === "dark") return "dark";
   if (input === "system" || input === "auto") return "system";
@@ -1472,7 +1488,7 @@ export function computeNextMemoryOrganizerRunAt(
   return candidate.getTime();
 }
 
-function normalizeSelectedModelForProviders(
+export function normalizeSelectedModelForProviders(
   selectedModel: SelectedModel | undefined,
   customProviders: CustomProvider[],
 ): SelectedModel | undefined {
diff --git a/crates/agent-gui/src/lib/sidebar/reconcile.ts b/crates/agent-gui/src/lib/sidebar/reconcile.ts
index 5e4b5d048..5c7ebe69f 100644
--- a/crates/agent-gui/src/lib/sidebar/reconcile.ts
+++ b/crates/agent-gui/src/lib/sidebar/reconcile.ts
@@ -92,6 +92,7 @@ function sameSidebarConversation(left: SidebarConversation, right: SidebarConver
     left.isPinned === right.isPinned &&
     left.pinnedAt === right.pinnedAt &&
     left.isShared === right.isShared &&
+    left.selectedModelJson === right.selectedModelJson &&
     left.isPending === right.isPending
   );
 }
@@ -121,6 +122,7 @@ export function mergeSidebarConversation(
     isPinned: next.isPinned ?? existing.isPinned,
     pinnedAt: "pinnedAt" in next ? next.pinnedAt : existing.pinnedAt,
     isShared: next.isShared ?? existing.isShared,
+    selectedModelJson: mergeOptionalText(next.selectedModelJson, existing.selectedModelJson),
     isPending: next.isPending === true ? true : undefined,
   };
 
diff --git a/crates/agent-gui/src/lib/sidebar/types.ts b/crates/agent-gui/src/lib/sidebar/types.ts
index 96d18f061..9da7d4f63 100644
--- a/crates/agent-gui/src/lib/sidebar/types.ts
+++ b/crates/agent-gui/src/lib/sidebar/types.ts
@@ -18,6 +18,7 @@ export type SidebarConversation = {
   isPinned?: boolean;
   pinnedAt?: number | null;
   isShared?: boolean;
+  selectedModelJson?: string;
   // Local-only draft/persisting row; survives authoritative reconciles until
   // the backend confirms (an upsert event clears it) or it is removed locally.
   isPending?: boolean;
diff --git a/crates/agent-gui/src/pages/ChatPage.tsx b/crates/agent-gui/src/pages/ChatPage.tsx
index 0c325c939..9b81eb0d2 100644
--- a/crates/agent-gui/src/pages/ChatPage.tsx
+++ b/crates/agent-gui/src/pages/ChatPage.tsx
@@ -66,6 +66,7 @@ import {
   getChatHistoryShare,
   listChatHistory,
   listSharedChatHistory,
+  setChatHistoryModel,
   setChatHistoryShare,
 } from "../lib/chat/history/chatHistory";
 import { memoryExtraction } from "../lib/chat/memory/extractionController";
@@ -120,8 +121,10 @@ import {
   isRightDockSingletonTabOpen,
   normalizeChatRuntimeControls,
   normalizeChatRuntimeControlsForProvider,
+  normalizeSelectedModelForProviders,
   normalizeSystemToolSelection,
   openRightDockSingletonTab,
+  parseSelectedModelJson,
   type RightDockFileTreeStatePatch,
   type RightDockProjectState,
   removeRightDockProjectState,
@@ -129,6 +132,8 @@ import {
   resolveWorkspaceProjects,
   type SelectedModel,
   type SystemToolId,
+  serializeSelectedModelJson,
+  setSelectedModel,
   updateChatRuntimeControlsForProvider,
   updateCustomSettings,
   updateMemorySettings,
@@ -201,6 +206,7 @@ import {
   formatHookWarningMessage,
   MAX_UPLOAD_FILES,
   pruneIdleConversationRuntimeCaches,
+  resolveActiveModelSelection,
   resolveEffectiveChatModelSelection,
   type SendChatAction,
   scheduleIdleHydration,
@@ -634,6 +640,9 @@ export function ChatPage(props: ChatPageProps) {
   const [currentConversationCreatedAt, setCurrentConversationCreatedAt] = useState(
     () => initialConversationRef.current.createdAt,
   );
+  const [currentConversationSelectedModel, setCurrentConversationSelectedModel] = useState<
+    SelectedModel | undefined
+  >(undefined);
   const [projectRenamingId, setProjectRenamingId] = useState<string | null>(null);
   const [projectRenameDraft, setProjectRenameDraft] = useState("");
   const [runningConversationIds, setRunningConversationIds] = useState<ReadonlySet<string>>(
@@ -783,6 +792,7 @@ export function ChatPage(props: ChatPageProps) {
   // The only page-level subscription to the sidebar list: ChatPage's own
   // render needs (draft detection, pending-item effect, workspace root).
   const historyItems = useSidebarSelector(sidebarStore, selectConversations);
+  const sidebarConversationsById = useSidebarSelector(sidebarStore, (s) => s.byId);
   const [shareConversation, setShareConversation] = useState<ChatHistorySummary | null>(null);
   const [shareStatus, setShareStatus] = useState<ChatHistoryShareStatus | null>(null);
   const [shareLoading, setShareLoading] = useState(false);
@@ -1268,8 +1278,12 @@ export function ChatPage(props: ChatPageProps) {
     () => buildModelOptions(settings, { floatSelectedFirst: false }),
     [settings],
   );
-  const selectedValue = settings.selectedModel
-    ? toModelValue(settings.selectedModel.customProviderId, settings.selectedModel.model)
+  const activeSelectedModel = resolveActiveModelSelection(
+    settings,
+    currentConversationSelectedModel,
+  );
+  const selectedValue = activeSelectedModel
+    ? toModelValue(activeSelectedModel.customProviderId, activeSelectedModel.model)
     : undefined;
 
   const historyRenderItems = useMemo<RenderTimelineItem[]>(
@@ -1378,6 +1392,7 @@ export function ChatPage(props: ChatPageProps) {
     hookWarning,
     currentConversationSessionId,
     currentConversationCreatedAt,
+    currentConversationSelectedModel,
     setConversationState,
     setCompactionStatus,
     setIsSending,
@@ -1385,6 +1400,7 @@ export function ChatPage(props: ChatPageProps) {
     setHookWarning,
     setCurrentConversationSessionId,
     setCurrentConversationCreatedAt,
+    setCurrentConversationSelectedModel,
     setRunningConversationIds,
   });
 
@@ -2703,6 +2719,8 @@ export function ChatPage(props: ChatPageProps) {
     },
     getDefaultNewConversationWorkdir: () =>
       isAgentMode ? activeWorkspaceProjectPath || undefined : undefined,
+    resolveConversationSelectedModel: (json) =>
+      normalizeSelectedModelForProviders(parseSelectedModelJson(json), settings.customProviders),
     setCurrentConversationId,
     setErrorMessage,
     setHydratingConversationId,
@@ -3254,6 +3272,10 @@ export function ChatPage(props: ChatPageProps) {
       compactionStatus: cached?.compactionStatus,
       isSending: cached?.isSending,
       workdir: record.cwd,
+      selectedModel: normalizeSelectedModelForProviders(
+        parseSelectedModelJson(record.selectedModelJson),
+        settings.customProviders,
+      ),
     });
     const historySummary: ChatHistorySummary = {
       id: record.id,
@@ -3262,6 +3284,7 @@ export function ChatPage(props: ChatPageProps) {
       model: record.model,
       sessionId: record.sessionId,
       cwd: record.cwd,
+      selectedModelJson: record.selectedModelJson,
       messageCount: record.state.meta.totalMessageCount,
       createdAt: record.createdAt,
       updatedAt: record.updatedAt,
@@ -3311,11 +3334,11 @@ export function ChatPage(props: ChatPageProps) {
       getFirstUserMessageText(buildRequestContext(currentState)),
     );
     const providerId =
-      settings.selectedModel?.customProviderId ??
+      activeSelectedModel?.customProviderId ??
       sidebarStore.peek(currentConversationId)?.providerId ??
       "pending";
     const model =
-      settings.selectedModel?.model ?? sidebarStore.peek(currentConversationId)?.model ?? "pending";
+      activeSelectedModel?.model ?? sidebarStore.peek(currentConversationId)?.model ?? "pending";
 
     const pendingConversationTitle = t("chat.pendingTitle");
     const pendingItem = createPendingHistoryItem({
@@ -3345,7 +3368,7 @@ export function ChatPage(props: ChatPageProps) {
     currentConversationSessionId,
     historyItems,
     isSending,
-    settings.selectedModel,
+    activeSelectedModel,
     displayedConversationWorkdir,
     sidebarScope,
     sidebarStore,
@@ -3580,10 +3603,12 @@ export function ChatPage(props: ChatPageProps) {
 
     let effectiveSelectedModel: EffectiveChatModelSelection;
     try {
-      effectiveSelectedModel = resolveEffectiveChatModelSelection(
+      effectiveSelectedModel = resolveEffectiveChatModelSelection({
         settings,
-        gatewayBridgeRequest?.selectedModelOverride,
-      );
+        conversationSelectedModel:
+          conversationRuntimeCacheRef.current.get(conversationId)?.selectedModel,
+        gatewaySelectedModel: gatewayBridgeRequest?.selectedModelOverride,
+      });
     } catch (error) {
       const message = asErrorMessage(error, "当前模型配置不可用，请重新选择后重试。");
       setConversationErrorState(message);
@@ -3592,6 +3617,9 @@ export function ChatPage(props: ChatPageProps) {
     }
 
     const { selectedModel, provider, providerId, model } = effectiveSelectedModel;
+    updateConversationRuntimeEntry(conversationId, (prev) =>
+      selectedModelsMatch(prev.selectedModel, selectedModel) ? prev : { ...prev, selectedModel },
+    );
     const runtimeControls =
       gatewayBridgeRequest?.runtimeControlsOverride ??
       overrides?.runtimeControlsOverride ??
@@ -3935,6 +3963,7 @@ export function ChatPage(props: ChatPageProps) {
       sessionId,
       providerId,
       model,
+      selectedModel,
       cwd: conversationCwd,
       state: nextConversationState,
       fallbackTitle,
@@ -4083,6 +4112,7 @@ export function ChatPage(props: ChatPageProps) {
             sessionId,
             providerId,
             model,
+            selectedModel,
             cwd: conversationCwd,
             state,
             fallbackTitle,
@@ -4103,6 +4133,7 @@ export function ChatPage(props: ChatPageProps) {
             sessionId,
             providerId,
             model,
+            selectedModel,
             cwd: conversationCwd,
             state,
             fallbackTitle,
@@ -4223,6 +4254,7 @@ export function ChatPage(props: ChatPageProps) {
         sessionId,
         providerId,
         model,
+        selectedModel,
         cwd: conversationCwd,
         state: finalState,
         fallbackTitle,
@@ -4261,6 +4293,7 @@ export function ChatPage(props: ChatPageProps) {
         sessionId,
         providerId,
         model,
+        selectedModel,
         cwd: conversationCwd,
         state: finalState,
         fallbackTitle,
@@ -4858,24 +4891,75 @@ export function ChatPage(props: ChatPageProps) {
   const hasModels = modelOptions.length > 0;
 
   const currentModelLabel = (() => {
-    if (!settings.selectedModel) return t("chat.selectModel");
+    if (!activeSelectedModel) return t("chat.selectModel");
     const opt = modelOptions.find((o) => o.value === selectedValue);
     if (opt) return `${opt.providerName} / ${opt.model}`;
-    return settings.selectedModel.model;
+    return activeSelectedModel.model;
   })();
 
   const currentModelContextWindow = (() => {
-    if (!settings.selectedModel) return undefined;
+    if (!activeSelectedModel) return undefined;
     const provider = settings.customProviders.find(
-      (item) => item.id === settings.selectedModel?.customProviderId,
+      (item) => item.id === activeSelectedModel.customProviderId,
     );
     if (!provider) return undefined;
-    return findProviderModelConfig(provider, settings.selectedModel.model).contextWindow;
+    return findProviderModelConfig(provider, activeSelectedModel.model).contextWindow;
   })();
-  const currentChatProvider = settings.selectedModel
-    ? settings.customProviders.find((item) => item.id === settings.selectedModel?.customProviderId)
+  const currentChatProvider = activeSelectedModel
+    ? settings.customProviders.find((item) => item.id === activeSelectedModel.customProviderId)
     : undefined;
-  const currentChatModelId = settings.selectedModel?.model;
+  const currentChatModelId = activeSelectedModel?.model;
+
+  const handleSelectModel = useCallback(
+    (selection: SelectedModel) => {
+      const conversationId = currentConversationIdRef.current;
+      updateConversationRuntimeEntry(conversationId, (prev) =>
+        selectedModelsMatch(prev.selectedModel, selection)
+          ? prev
+          : { ...prev, selectedModel: selection },
+      );
+      const persistedRow = sidebarStore.peek(conversationId);
+      const selectedModelJson = serializeSelectedModelJson(selection);
+      if (persistedRow && !persistedRow.isPending && selectedModelJson) {
+        void setChatHistoryModel(conversationId, selectedModelJson)
+          .then((summary) => sidebarStore.upsertLocal({ ...summary, isPending: undefined }))
+          .catch((error) => {
+            updateConversationRuntimeEntry(conversationId, (prev) => ({
+              ...prev,
+              errorMessage: asErrorMessage(error, "保存会话模型选择失败。"),
+            }));
+          });
+      }
+      setSettings((prev) => setSelectedModel(prev, selection));
+    },
+    [currentConversationIdRef, setSettings, sidebarStore, updateConversationRuntimeEntry],
+  );
+
+  // 跨端收敛：history-sync 带回的会话模型选择（如 WebUI 发消息后落库）
+  // 写回当前会话的 runtime entry；值相等或发送中不动，无回环。
+  const displayedConversationPersistedModelJson =
+    sidebarConversationsById.get(currentConversationId)?.selectedModelJson;
+  useEffect(() => {
+    const parsed = normalizeSelectedModelForProviders(
+      parseSelectedModelJson(displayedConversationPersistedModelJson),
+      settings.customProviders,
+    );
+    if (!parsed) return;
+    const entry = conversationRuntimeCacheRef.current.get(currentConversationId);
+    if (!entry || entry.isSending) return;
+    if (selectedModelsMatch(entry.selectedModel, parsed)) return;
+    updateConversationRuntimeEntry(currentConversationId, (prev) => ({
+      ...prev,
+      selectedModel: parsed,
+    }));
+  }, [
+    conversationRuntimeCacheRef,
+    currentConversationId,
+    displayedConversationPersistedModelJson,
+    settings.customProviders,
+    updateConversationRuntimeEntry,
+  ]);
+
   const currentChatModelConfig = useMemo(
     () =>
       currentChatProvider && currentChatModelId
@@ -5182,7 +5266,7 @@ export function ChatPage(props: ChatPageProps) {
                   modelOptions={modelOptions}
                   selectedValue={selectedValue}
                   sidebarOpen={sidebarOpen}
-                  setSettings={setSettings}
+                  onSelectModel={handleSelectModel}
                   onOpenSettings={onOpenSettings}
                   onToggleTheme={onToggleTheme}
                   onOpenSidebar={handleOpenSidebar}
diff --git a/crates/agent-gui/src/pages/chat/components/ChatHeader.tsx b/crates/agent-gui/src/pages/chat/components/ChatHeader.tsx
index fd33a71b5..180cc9667 100644
--- a/crates/agent-gui/src/pages/chat/components/ChatHeader.tsx
+++ b/crates/agent-gui/src/pages/chat/components/ChatHeader.tsx
@@ -28,7 +28,7 @@ import {
   type AppSettings,
   getNextTheme,
   type ProviderId,
-  setSelectedModel,
+  type SelectedModel,
   type Theme,
 } from "../../../lib/settings";
 import { cn } from "../../../lib/shared/utils";
@@ -54,7 +54,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
   modelOptions: ModelOption[];
   selectedValue?: string;
   sidebarOpen: boolean;
-  setSettings: (updater: (prev: AppSettings) => AppSettings) => void;
+  onSelectModel: (selection: SelectedModel) => void;
   onOpenSettings: (section?: SectionId) => void;
   onToggleTheme: () => void;
   onOpenSidebar: () => void;
@@ -68,7 +68,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
     modelOptions,
     selectedValue,
     sidebarOpen,
-    setSettings,
+    onSelectModel,
     onOpenSettings,
     onToggleTheme,
     onOpenSidebar,
@@ -262,7 +262,7 @@ export const ChatHeader = memo(function ChatHeader(props: {
                                 onSelect={() => {
                                   const parsed = parseModelValue(option.value);
                                   if (!parsed) return;
-                                  setSettings((prev) => setSelectedModel(prev, parsed));
+                                  onSelectModel(parsed);
                                 }}
                                 className={cn(
                                   "model-selector-item h-[30px] max-w-full shrink-0 justify-between gap-3 overflow-hidden rounded-md py-0 text-xs font-normal leading-5 text-foreground transition-none data-[highlighted]:bg-foreground/[0.05] dark:text-white",
diff --git a/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts b/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
index 3dfb1e3cb..8532ae9a7 100644
--- a/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
+++ b/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
@@ -14,6 +14,7 @@ import {
   createConversationIdentity,
   waitForTitleLookahead,
 } from "../../../lib/chat/page/chatPageHelpers";
+import { type SelectedModel, serializeSelectedModelJson } from "../../../lib/settings";
 import type { SidebarStore } from "../../../lib/sidebar/store";
 import { disposeTodoToolState } from "../../../lib/tools/todoTools";
 import {
@@ -34,6 +35,7 @@ type PersistConversationParams = {
   providerId: string;
   model: string;
   cwd?: string;
+  selectedModel?: SelectedModel;
   state: ConversationViewState;
   fallbackTitle: string;
   createdAt: number;
@@ -73,6 +75,7 @@ type UseConversationHistoryActionsParams = {
   deleteConversationArtifacts: (conversationId: string) => void;
   disposeSubagentsForConversation?: (conversationId: string) => void;
   getDefaultNewConversationWorkdir?: () => string | undefined;
+  resolveConversationSelectedModel: (json: string | null | undefined) => SelectedModel | undefined;
   setCurrentConversationId: Dispatch<SetStateAction<string>>;
   setErrorMessage: Dispatch<SetStateAction<string | null>>;
   setHydratingConversationId: Dispatch<SetStateAction<string | null>>;
@@ -137,6 +140,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
     deleteConversationArtifacts,
     disposeSubagentsForConversation,
     getDefaultNewConversationWorkdir,
+    resolveConversationSelectedModel,
     setCurrentConversationId,
     setErrorMessage,
     setHydratingConversationId,
@@ -214,6 +218,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
       sessionId: record.sessionId ?? record.id,
       createdAt: record.createdAt,
       workdir: record.cwd,
+      selectedModel: resolveConversationSelectedModel(record.selectedModelJson),
     });
     activateConversation({
       conversationId: record.id,
@@ -280,6 +285,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
         sessionId: activeRecord.sessionId ?? activeRecord.id,
         createdAt: activeRecord.createdAt,
         workdir: activeRecord.cwd,
+        selectedModel: resolveConversationSelectedModel(activeRecord.selectedModelJson),
       });
       activateConversation({
         conversationId: activeRecord.id,
@@ -367,6 +373,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
       providerId,
       model,
       cwd,
+      selectedModel,
       state,
       fallbackTitle,
       createdAt,
@@ -397,6 +404,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
         model,
         sessionId,
         cwd,
+        selectedModelJson: serializeSelectedModelJson(selectedModel),
         title: titleToStore,
         createdAt,
         updatedAt,
diff --git a/crates/agent-gui/src/pages/chat/hooks/useChatPageRuntimeStore.ts b/crates/agent-gui/src/pages/chat/hooks/useChatPageRuntimeStore.ts
index 528b6fb58..ca91a3c99 100644
--- a/crates/agent-gui/src/pages/chat/hooks/useChatPageRuntimeStore.ts
+++ b/crates/agent-gui/src/pages/chat/hooks/useChatPageRuntimeStore.ts
@@ -4,6 +4,7 @@ import {
   type ConversationViewState,
   createConversationStateFromContext,
 } from "../../../lib/chat/conversation/conversationState";
+import type { SelectedModel } from "../../../lib/settings";
 import {
   type ConversationRuntimeEntry,
   createConversationRuntimeEntry,
@@ -30,6 +31,7 @@ type UseChatPageRuntimeStoreParams = {
   hookWarning: string | null;
   currentConversationSessionId: string;
   currentConversationCreatedAt: number;
+  currentConversationSelectedModel: SelectedModel | undefined;
   setConversationState: Dispatch<SetStateAction<ConversationViewState>>;
   setCompactionStatus: Dispatch<SetStateAction<CompactionStatus>>;
   setIsSending: Dispatch<SetStateAction<boolean>>;
@@ -37,6 +39,7 @@ type UseChatPageRuntimeStoreParams = {
   setHookWarning: Dispatch<SetStateAction<string | null>>;
   setCurrentConversationSessionId: Dispatch<SetStateAction<string>>;
   setCurrentConversationCreatedAt: Dispatch<SetStateAction<number>>;
+  setCurrentConversationSelectedModel: Dispatch<SetStateAction<SelectedModel | undefined>>;
   setRunningConversationIds: Dispatch<SetStateAction<ReadonlySet<string>>>;
 };
 
@@ -52,6 +55,7 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
     hookWarning,
     currentConversationSessionId,
     currentConversationCreatedAt,
+    currentConversationSelectedModel,
     setConversationState,
     setCompactionStatus,
     setIsSending,
@@ -59,6 +63,7 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
     setHookWarning,
     setCurrentConversationSessionId,
     setCurrentConversationCreatedAt,
+    setCurrentConversationSelectedModel,
     setRunningConversationIds,
   } = params;
 
@@ -90,12 +95,14 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
         sessionId: currentConversationSessionId,
         createdAt: currentConversationCreatedAt,
         workdir: conversationRuntimeCacheRef.current.get(currentConversationIdRef.current)?.workdir,
+        selectedModel: currentConversationSelectedModel,
       }),
     [
       compactionStatus,
       conversationState,
       currentConversationCreatedAt,
       currentConversationSessionId,
+      currentConversationSelectedModel,
       errorMessage,
       hookWarning,
       isSending,
@@ -112,11 +119,13 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
       setHookWarning(entry.hookWarning);
       setCurrentConversationSessionId(entry.sessionId);
       setCurrentConversationCreatedAt(entry.createdAt);
+      setCurrentConversationSelectedModel(entry.selectedModel);
     },
     [
       setCompactionStatus,
       setConversationState,
       setCurrentConversationCreatedAt,
+      setCurrentConversationSelectedModel,
       setCurrentConversationSessionId,
       setErrorMessage,
       setHookWarning,
@@ -228,6 +237,7 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
         sessionId: currentConversationSessionId,
         createdAt: currentConversationCreatedAt,
         workdir: conversationRuntimeCacheRef.current.get(currentConversationId)?.workdir,
+        selectedModel: currentConversationSelectedModel,
       }),
     );
   }, [
@@ -236,6 +246,7 @@ export function useChatPageRuntimeStore(params: UseChatPageRuntimeStoreParams) {
     currentConversationCreatedAt,
     currentConversationId,
     currentConversationSessionId,
+    currentConversationSelectedModel,
     errorMessage,
     hookWarning,
     isSending,
diff --git a/crates/agent-gui/src/pages/chat/index.ts b/crates/agent-gui/src/pages/chat/index.ts
index 92dba6ea6..46960db19 100644
--- a/crates/agent-gui/src/pages/chat/index.ts
+++ b/crates/agent-gui/src/pages/chat/index.ts
@@ -29,6 +29,7 @@ export { buildPreparedContext, buildResumeContext } from "./runtime/conversation
 export { startConversationTitleJob } from "./runtime/conversationTitleJob";
 export {
   type EffectiveChatModelSelection,
+  resolveActiveModelSelection,
   resolveEffectiveChatModelSelection,
 } from "./runtime/modelSelection";
 export { ChatTranscript } from "./transcript/ChatTranscript";
diff --git a/crates/agent-gui/src/pages/chat/runtime/chatPageRuntime.ts b/crates/agent-gui/src/pages/chat/runtime/chatPageRuntime.ts
index d2df5bc42..67f07dd6d 100644
--- a/crates/agent-gui/src/pages/chat/runtime/chatPageRuntime.ts
+++ b/crates/agent-gui/src/pages/chat/runtime/chatPageRuntime.ts
@@ -4,7 +4,7 @@ import type { HookRunWarning } from "../../../lib/automation/hookRunner";
 import type { CompactionStatus } from "../../../lib/chat/compaction/types";
 import type { ConversationViewState } from "../../../lib/chat/conversation/conversationState";
 import { normalizeErrorMessage } from "../../../lib/providers/llm";
-import type { AppSettings } from "../../../lib/settings";
+import type { AppSettings, SelectedModel } from "../../../lib/settings";
 
 export const MAX_IDLE_CONVERSATION_RUNTIME_CACHE_ENTRIES = 12;
 
@@ -17,6 +17,7 @@ export type ConversationRuntimeEntry = {
   sessionId: string;
   createdAt: number;
   workdir?: string;
+  selectedModel?: SelectedModel;
 };
 
 export function createConversationRuntimeEntry(params: {
@@ -28,6 +29,7 @@ export function createConversationRuntimeEntry(params: {
   errorMessage?: string | null;
   hookWarning?: string | null;
   workdir?: string;
+  selectedModel?: SelectedModel;
 }): ConversationRuntimeEntry {
   const {
     state,
@@ -38,6 +40,7 @@ export function createConversationRuntimeEntry(params: {
     errorMessage = null,
     hookWarning = null,
     workdir,
+    selectedModel,
   } = params;
   return {
     state,
@@ -48,6 +51,7 @@ export function createConversationRuntimeEntry(params: {
     sessionId,
     createdAt,
     workdir: workdir?.trim() || undefined,
+    selectedModel,
   };
 }
 
diff --git a/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts b/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
index f2447789d..9b4751523 100644
--- a/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
+++ b/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
@@ -11,16 +11,26 @@ export type EffectiveChatModelSelection = {
   model: string;
 };
 
-export function resolveEffectiveChatModelSelection(
+export function resolveActiveModelSelection(
   settings: AppSettings,
-  gatewaySelectedModel?: GatewaySelectedModelEvent,
-): EffectiveChatModelSelection {
+  conversationSelectedModel: SelectedModel | undefined,
+): SelectedModel | undefined {
+  return conversationSelectedModel ?? settings.selectedModel;
+}
+
+export function resolveEffectiveChatModelSelection(params: {
+  settings: AppSettings;
+  conversationSelectedModel?: SelectedModel;
+  gatewaySelectedModel?: GatewaySelectedModelEvent;
+}): EffectiveChatModelSelection {
+  const { settings, conversationSelectedModel, gatewaySelectedModel } = params;
   const resolveLocalSelection = (): EffectiveChatModelSelection => {
-    if (!settings.selectedModel) {
+    const activeSelectedModel = resolveActiveModelSelection(settings, conversationSelectedModel);
+    if (!activeSelectedModel) {
       throw new Error("请先在左上角选择一个模型（或先去设置添加模型）。");
     }
 
-    const { customProviderId, model } = settings.selectedModel;
+    const { customProviderId, model } = activeSelectedModel;
     const provider = settings.customProviders.find((item) => item.id === customProviderId);
     if (!provider) {
       throw new Error("所选供应商不存在，请重新选择模型。");
@@ -30,7 +40,7 @@ export function resolveEffectiveChatModelSelection(
     }
 
     return {
-      selectedModel: settings.selectedModel,
+      selectedModel: activeSelectedModel,
       provider,
       providerId: provider.type,
       model,
diff --git a/crates/agent-gui/test/chat/model-selection.test.mjs b/crates/agent-gui/test/chat/model-selection.test.mjs
index e5f28be6f..24c480ad6 100644
--- a/crates/agent-gui/test/chat/model-selection.test.mjs
+++ b/crates/agent-gui/test/chat/model-selection.test.mjs
@@ -36,7 +36,7 @@ test("local chat model selection resolves only an enabled selected model", () =>
     { customProviderId: "openai-main", model: "gpt-5" },
   );
 
-  const resolved = modelSelection.resolveEffectiveChatModelSelection(app);
+  const resolved = modelSelection.resolveEffectiveChatModelSelection({ settings: app });
 
   assert.equal(resolved.provider.id, "openai-main");
   assert.equal(resolved.providerId, "codex");
@@ -58,10 +58,13 @@ test("remote chat model selection does not fall back to another provider with th
 
   assert.throws(
     () =>
-      modelSelection.resolveEffectiveChatModelSelection(app, {
-        customProviderId: "missing-openai",
-        model: "gpt-5-mini",
-        providerType: "codex",
+      modelSelection.resolveEffectiveChatModelSelection({
+        settings: app,
+        gatewaySelectedModel: {
+          customProviderId: "missing-openai",
+          model: "gpt-5-mini",
+          providerType: "codex",
+        },
       }),
     /供应商不存在/,
   );
@@ -75,10 +78,13 @@ test("remote chat model selection rejects provider type drift", () => {
 
   assert.throws(
     () =>
-      modelSelection.resolveEffectiveChatModelSelection(app, {
-        customProviderId: "anthropic-main",
-        model: "claude-sonnet",
-        providerType: "codex",
+      modelSelection.resolveEffectiveChatModelSelection({
+        settings: app,
+        gatewaySelectedModel: {
+          customProviderId: "anthropic-main",
+          model: "claude-sonnet",
+          providerType: "codex",
+        },
       }),
     /供应商类型.*不一致/,
   );
@@ -98,10 +104,13 @@ test("remote chat model selection rejects models that are no longer enabled", ()
 
   assert.throws(
     () =>
-      modelSelection.resolveEffectiveChatModelSelection(app, {
-        customProviderId: "openai-main",
-        model: "gpt-5-mini",
-        providerType: "codex",
+      modelSelection.resolveEffectiveChatModelSelection({
+        settings: app,
+        gatewaySelectedModel: {
+          customProviderId: "openai-main",
+          model: "gpt-5-mini",
+          providerType: "codex",
+        },
       }),
     /未在桌面端启用/,
   );
@@ -113,10 +122,13 @@ test("remote chat model selection accepts an exact enabled provider model", () =
     { customProviderId: "gemini-main", model: "gemini-3.5-flash" },
   );
 
-  const resolved = modelSelection.resolveEffectiveChatModelSelection(app, {
-    customProviderId: "gemini-main",
-    model: "gemini-3.5-flash",
-    providerType: "gemini",
+  const resolved = modelSelection.resolveEffectiveChatModelSelection({
+    settings: app,
+    gatewaySelectedModel: {
+      customProviderId: "gemini-main",
+      model: "gemini-3.5-flash",
+      providerType: "gemini",
+    },
   });
 
   assert.equal(resolved.provider.id, "gemini-main");
@@ -126,3 +138,95 @@ test("remote chat model selection accepts an exact enabled provider model", () =
     model: "gemini-3.5-flash",
   });
 });
+
+test("conversation selection wins over the global default", () => {
+  const app = appSettings(
+    [
+      provider({ id: "openai-main", models: ["gpt-5"] }),
+      provider({ id: "anthropic-main", type: "claude_code", models: ["claude-fable-5"] }),
+    ],
+    { customProviderId: "openai-main", model: "gpt-5" },
+  );
+
+  const resolved = modelSelection.resolveEffectiveChatModelSelection({
+    settings: app,
+    conversationSelectedModel: { customProviderId: "anthropic-main", model: "claude-fable-5" },
+  });
+
+  assert.equal(resolved.provider.id, "anthropic-main");
+  assert.equal(resolved.providerId, "claude_code");
+  assert.deepEqual(resolved.selectedModel, {
+    customProviderId: "anthropic-main",
+    model: "claude-fable-5",
+  });
+});
+
+test("gateway override wins over the conversation selection", () => {
+  const app = appSettings(
+    [
+      provider({ id: "openai-main", models: ["gpt-5"] }),
+      provider({ id: "gemini-main", type: "gemini", models: ["gemini-3.5-flash"] }),
+    ],
+    { customProviderId: "openai-main", model: "gpt-5" },
+  );
+
+  const resolved = modelSelection.resolveEffectiveChatModelSelection({
+    settings: app,
+    conversationSelectedModel: { customProviderId: "openai-main", model: "gpt-5" },
+    gatewaySelectedModel: {
+      customProviderId: "gemini-main",
+      model: "gemini-3.5-flash",
+      providerType: "gemini",
+    },
+  });
+
+  assert.equal(resolved.provider.id, "gemini-main");
+});
+
+test("invalid conversation selection throws like an invalid default", () => {
+  const app = appSettings([provider({ id: "openai-main", models: ["gpt-5"] })], {
+    customProviderId: "openai-main",
+    model: "gpt-5",
+  });
+
+  assert.throws(
+    () =>
+      modelSelection.resolveEffectiveChatModelSelection({
+        settings: app,
+        conversationSelectedModel: { customProviderId: "missing", model: "gpt-5" },
+      }),
+    /供应商不存在/,
+  );
+});
+
+test("resolveActiveModelSelection prefers the conversation selection", () => {
+  const app = appSettings([provider({ id: "openai-main", models: ["gpt-5"] })], {
+    customProviderId: "openai-main",
+    model: "gpt-5",
+  });
+  const conversationSelection = { customProviderId: "other", model: "m" };
+
+  assert.equal(
+    modelSelection.resolveActiveModelSelection(app, conversationSelection),
+    conversationSelection,
+  );
+  assert.deepEqual(modelSelection.resolveActiveModelSelection(app, undefined), {
+    customProviderId: "openai-main",
+    model: "gpt-5",
+  });
+});
+
+test("selected model json round-trips and rejects malformed payloads", () => {
+  assert.equal(
+    settings.serializeSelectedModelJson({ customProviderId: "p1", model: "m1" }),
+    '{"customProviderId":"p1","model":"m1"}',
+  );
+  assert.deepEqual(settings.parseSelectedModelJson('{"customProviderId":"p1","model":"m1"}'), {
+    customProviderId: "p1",
+    model: "m1",
+  });
+  assert.equal(settings.parseSelectedModelJson(undefined), undefined);
+  assert.equal(settings.parseSelectedModelJson("not-json"), undefined);
+  assert.equal(settings.parseSelectedModelJson('{"model":"m1"}'), undefined);
+  assert.equal(settings.serializeSelectedModelJson(undefined), undefined);
+});
diff --git a/crates/agent-gui/test/chat/sidebar-reconcile.test.mjs b/crates/agent-gui/test/chat/sidebar-reconcile.test.mjs
index afb0e4b76..7e7d51731 100644
--- a/crates/agent-gui/test/chat/sidebar-reconcile.test.mjs
+++ b/crates/agent-gui/test/chat/sidebar-reconcile.test.mjs
@@ -19,6 +19,7 @@ function conversation(id, overrides = {}) {
     isPinned: overrides.isPinned,
     pinnedAt: overrides.pinnedAt,
     isShared: overrides.isShared,
+    selectedModelJson: overrides.selectedModelJson,
     isPending: overrides.isPending,
   };
 }
@@ -162,3 +163,36 @@ test("scope filter preserves identity when everything matches", () => {
   const items = [conversation("a", { cwd: "/p" }), conversation("b", { cwd: "/p" })];
   assert.equal(scope.filterConversationsForScope(items, { kind: "workdir", cwd: "/p" }), items);
 });
+
+test("merge keeps the existing selectedModelJson when the incoming row omits it", () => {
+  const existing = conversation("one", {
+    selectedModelJson: '{"customProviderId":"p1","model":"m1"}',
+  });
+  const merged = reconcile.mergeSidebarConversation(existing, conversation("one", { updatedAt: 2 }));
+  assert.equal(merged.selectedModelJson, '{"customProviderId":"p1","model":"m1"}');
+});
+
+test("merge replaces selectedModelJson with a non-empty incoming value", () => {
+  const existing = conversation("one", {
+    selectedModelJson: '{"customProviderId":"p1","model":"m1"}',
+  });
+  const merged = reconcile.mergeSidebarConversation(
+    existing,
+    conversation("one", {
+      updatedAt: 2,
+      selectedModelJson: '{"customProviderId":"p2","model":"m2"}',
+    }),
+  );
+  assert.equal(merged.selectedModelJson, '{"customProviderId":"p2","model":"m2"}');
+});
+
+test("merge keeps identity when selectedModelJson is unchanged", () => {
+  const existing = conversation("one", {
+    selectedModelJson: '{"customProviderId":"p1","model":"m1"}',
+  });
+  const merged = reconcile.mergeSidebarConversation(
+    existing,
+    conversation("one", { selectedModelJson: '{"customProviderId":"p1","model":"m1"}' }),
+  );
+  assert.equal(merged, existing);
+});

From d42cffcb6a2d6d46e4a0b05afcdc1957d014c394 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 17:20:27 +0800
Subject: [PATCH 6/7] fix(chat): preserve model changes during active runs

---
 .../history/useConversationHistoryActions.ts  |  7 ++++++-
 .../src/pages/chat/runtime/modelSelection.ts  |  7 +++++++
 .../test/chat/model-selection.test.mjs        | 20 +++++++++++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts b/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
index 8532ae9a7..c3ae35ddb 100644
--- a/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
+++ b/crates/agent-gui/src/pages/chat/history/useConversationHistoryActions.ts
@@ -23,6 +23,7 @@ import {
   pruneIdleConversationRuntimeCaches,
   setConversationRuntimeCacheEntry,
 } from "../runtime/chatPageRuntime";
+import { resolvePersistedConversationModelSelection } from "../runtime/modelSelection";
 
 type TitleJobRefValue = {
   conversationId: string;
@@ -396,6 +397,10 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
 
     const updatedAt = Date.now();
     markLocalHistorySnapshotSynced(conversationId, updatedAt);
+    const selectedModelToPersist = resolvePersistedConversationModelSelection({
+      runtimeSelectedModel: conversationRuntimeCacheRef.current.get(conversationId)?.selectedModel,
+      turnSelectedModel: selectedModel,
+    });
 
     try {
       const summary = await persistConversationState({
@@ -404,7 +409,7 @@ export function useConversationHistoryActions(params: UseConversationHistoryActi
         model,
         sessionId,
         cwd,
-        selectedModelJson: serializeSelectedModelJson(selectedModel),
+        selectedModelJson: serializeSelectedModelJson(selectedModelToPersist),
         title: titleToStore,
         createdAt,
         updatedAt,
diff --git a/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts b/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
index 9b4751523..4422ebb11 100644
--- a/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
+++ b/crates/agent-gui/src/pages/chat/runtime/modelSelection.ts
@@ -18,6 +18,13 @@ export function resolveActiveModelSelection(
   return conversationSelectedModel ?? settings.selectedModel;
 }
 
+export function resolvePersistedConversationModelSelection(params: {
+  runtimeSelectedModel?: SelectedModel;
+  turnSelectedModel?: SelectedModel;
+}): SelectedModel | undefined {
+  return params.runtimeSelectedModel ?? params.turnSelectedModel;
+}
+
 export function resolveEffectiveChatModelSelection(params: {
   settings: AppSettings;
   conversationSelectedModel?: SelectedModel;
diff --git a/crates/agent-gui/test/chat/model-selection.test.mjs b/crates/agent-gui/test/chat/model-selection.test.mjs
index 24c480ad6..5f90db61f 100644
--- a/crates/agent-gui/test/chat/model-selection.test.mjs
+++ b/crates/agent-gui/test/chat/model-selection.test.mjs
@@ -216,6 +216,26 @@ test("resolveActiveModelSelection prefers the conversation selection", () => {
   });
 });
 
+test("history persistence prefers the latest runtime selection over the turn-start model", () => {
+  const turnSelectedModel = { customProviderId: "openai-main", model: "gpt-5" };
+  const runtimeSelectedModel = {
+    customProviderId: "anthropic-main",
+    model: "claude-fable-5",
+  };
+
+  assert.equal(
+    modelSelection.resolvePersistedConversationModelSelection({
+      runtimeSelectedModel,
+      turnSelectedModel,
+    }),
+    runtimeSelectedModel,
+  );
+  assert.equal(
+    modelSelection.resolvePersistedConversationModelSelection({ turnSelectedModel }),
+    turnSelectedModel,
+  );
+});
+
 test("selected model json round-trips and rejects malformed payloads", () => {
   assert.equal(
     settings.serializeSelectedModelJson({ customProviderId: "p1", model: "m1" }),

From 2546149dc3e21784cd616cc4a939a8cb6baa5945 Mon Sep 17 00:00:00 2001
From: su-fen <715041@qq.com>
Date: Thu, 16 Jul 2026 17:34:01 +0800
Subject: [PATCH 7/7] test(settings): cover hidden file state

---
 crates/agent-gateway/test/webui/web-settings.test.mjs    | 4 ++++
 crates/agent-gui/test/settings/normalization.test.mjs    | 8 ++++++++
 crates/agent-gui/test/settings/right-dock-model.test.mjs | 4 ++++
 3 files changed, 16 insertions(+)

diff --git a/crates/agent-gateway/test/webui/web-settings.test.mjs b/crates/agent-gateway/test/webui/web-settings.test.mjs
index 7b8531713..1b66d742c 100644
--- a/crates/agent-gateway/test/webui/web-settings.test.mjs
+++ b/crates/agent-gateway/test/webui/web-settings.test.mjs
@@ -72,6 +72,7 @@ test("web settings normalization canonicalizes project keyed maps with Windows p
                   query: "legacy",
                   selectedPath: "src\\main.ts",
                   expandedPaths: ["", "src", "src\\components", "src"],
+                  showHidden: true,
                   revision: 2,
                 },
               },
@@ -108,6 +109,7 @@ test("web settings normalization canonicalizes project keyed maps with Windows p
           query: "legacy",
           selectedPath: "src/main.ts",
           expandedPaths: ["", "src", "src/components"],
+          showHidden: true,
           revision: 2,
         },
       },
@@ -1120,6 +1122,7 @@ test("gateway settings sync keeps right dock width local and syncs project state
                   query: "desktop",
                   selectedPath: "desktop.ts",
                   expandedPaths: ["", "src"],
+                  showHidden: true,
                   revision: 1,
                   stateVersion: 3,
                 },
@@ -1192,6 +1195,7 @@ test("gateway settings sync keeps right dock width local and syncs project state
       query: "desktop",
       selectedPath: "desktop.ts",
       expandedPaths: ["", "src"],
+      showHidden: true,
       revision: 1,
     },
   );
diff --git a/crates/agent-gui/test/settings/normalization.test.mjs b/crates/agent-gui/test/settings/normalization.test.mjs
index ea51cd9d2..a4422622d 100644
--- a/crates/agent-gui/test/settings/normalization.test.mjs
+++ b/crates/agent-gui/test/settings/normalization.test.mjs
@@ -154,6 +154,7 @@ test("settings normalization canonicalizes project keyed maps with Windows path
                   query: "legacy",
                   selectedPath: "src\\main.ts",
                   expandedPaths: ["", "src", "src\\components", "src"],
+                  showHidden: true,
                   revision: 2,
                 },
               },
@@ -190,6 +191,7 @@ test("settings normalization canonicalizes project keyed maps with Windows path
           query: "legacy",
           selectedPath: "src/main.ts",
           expandedPaths: ["", "src", "src/components"],
+          showHidden: true,
           revision: 2,
         },
       },
@@ -707,6 +709,7 @@ test("gateway settings sync payload redacts provider api keys", () => {
               query: "src",
               selectedPath: "src/main.ts",
               expandedPaths: ["", "src", "src/bad"],
+              showHidden: false,
               revision: 3,
             },
           },
@@ -1060,6 +1063,7 @@ test("normalizes right dock from current settings", () => {
           query: "src",
           selectedPath: "src/main.ts",
           expandedPaths: ["", "src", "src/components"],
+          showHidden: false,
           revision: 4,
         },
       },
@@ -1093,6 +1097,7 @@ test("opens right dock singleton tabs and updates file tree state per project",
     query: "x".repeat(250),
     selectedPath: "src/../main.ts",
     expandedPaths: ["", "src", "src/../bad", "src\\components", "src"],
+    showHidden: true,
     bumpRevision: true,
   });
   const updatedState = settings.getRightDockProjectState(
@@ -1109,6 +1114,7 @@ test("opens right dock singleton tabs and updates file tree state per project",
     query: "x".repeat(200),
     selectedPath: "src/main.ts",
     expandedPaths: ["", "src", "src/bad", "src/components"],
+    showHidden: true,
     revision: 1,
   });
   assert.equal(updatedState.openVersion, 1);
@@ -1269,6 +1275,7 @@ test("gateway settings sync keeps right dock width local and syncs project state
                   query: "desktop",
                   selectedPath: "desktop.ts",
                   expandedPaths: ["", "src"],
+                  showHidden: true,
                   revision: 1,
                   stateVersion: 3,
                 },
@@ -1341,6 +1348,7 @@ test("gateway settings sync keeps right dock width local and syncs project state
       query: "desktop",
       selectedPath: "desktop.ts",
       expandedPaths: ["", "src"],
+      showHidden: true,
       revision: 1,
     },
   );
diff --git a/crates/agent-gui/test/settings/right-dock-model.test.mjs b/crates/agent-gui/test/settings/right-dock-model.test.mjs
index e7473dd0c..4880658a5 100644
--- a/crates/agent-gui/test/settings/right-dock-model.test.mjs
+++ b/crates/agent-gui/test/settings/right-dock-model.test.mjs
@@ -69,6 +69,7 @@ test("normalizeRightDockProjectState migrates the full legacy tabs shape", () =>
           query: "abc",
           selectedPath: "src/x.ts",
           expandedPaths: ["", "src"],
+          showHidden: true,
           revision: 2,
           stateVersion: 3,
         },
@@ -93,6 +94,7 @@ test("normalizeRightDockProjectState migrates the full legacy tabs shape", () =>
         query: "abc",
         selectedPath: "src/x.ts",
         expandedPaths: ["", "src"],
+        showHidden: true,
         revision: 2,
       },
     },
@@ -486,6 +488,7 @@ test("right dock merge accepts legacy-shaped incoming project state", () => {
               query: "web",
               selectedPath: "web.ts",
               expandedPaths: ["", "src"],
+              showHidden: true,
               revision: 1,
               stateVersion: 2,
             },
@@ -508,6 +511,7 @@ test("right dock merge accepts legacy-shaped incoming project state", () => {
     query: "web",
     selectedPath: "web.ts",
     expandedPaths: ["", "src"],
+    showHidden: true,
     revision: 1,
   });
 });