From 1f3bc8b22bfcd2c439ae342efa57712515581ac3 Mon Sep 17 00:00:00 2001
From: Yixiang Tu <tuyixiang@deepseek.com>
Date: Fri, 23 Oct 2026 13:55:06 +0800
Subject: [PATCH] fix(llm): rebuild tool history for additions to an empty set

---
 .../2026-09-20-dynamic-tool-updates.i18n.yaml |  8 ++--
 .../2026-09-20-dynamic-tool-updates.md        |  4 +-
 .../2026-09-20-dynamic-tool-updates.zh.md     |  4 +-
 packages/llm/llm-deepseek/README.i18n.yaml    |  4 +-
 packages/llm/llm-deepseek/README.md           |  2 +-
 packages/llm/llm-deepseek/README.zh.md        |  2 +-
 .../llm/llm-deepseek/tests/adapter.e2e.ts     | 10 ++--
 .../tests/fixtures/deferred-tools.ts          | 22 +++++++--
 packages/llm/llm/README.i18n.yaml             |  4 +-
 packages/llm/llm/README.md                    |  2 +-
 packages/llm/llm/README.zh.md                 |  2 +-
 packages/llm/llm/src/content.ts               |  9 ++--
 packages/llm/llm/tests/content.spec.ts        | 40 +++++++++++++++-
 packages/llm/llm/tests/service.spec.ts        |  9 +++-
 .../session-snapshot/README.i18n.yaml         |  4 +-
 .../test-support/session-snapshot/README.md   |  2 +-
 .../session-snapshot/README.zh.md             |  2 +-
 .../session-snapshot/src/suite.ts             | 10 ++--
 .../session-snapshot/tests/suite.spec.ts      |  9 +++-
 .../deepseek-deferred-tools/session.v4.jsonl  | 48 +++++++++++--------
 .../deepseek-deferred-tools/snapshot.yml      |  2 +-
 .../tool-schemas.expected.json                | 21 ++++----
 22 files changed, 146 insertions(+), 74 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.i18n.yaml
index c899f1ca29..9e822eb717 100644
--- a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.i18n.yaml
@@ -9,11 +9,11 @@
   en: 97fe58a13135b4a1
   zh: 7490373a8d941da5
 /agent-note-active-tool-headers-and-stateful-request-projection/decision:
-  en: c1ca2f0657dc02c0
-  zh: db63130f49594d44
+  en: 51773686866c95d1
+  zh: 489ea0e1144720e1
 /agent-note-active-tool-headers-and-stateful-request-projection/alternatives-considered:
   en: 311db1f781e386e7
   zh: 7e3312544154a158
 /agent-note-active-tool-headers-and-stateful-request-projection/consequences:
-  en: aa3e68c78ac3f666
-  zh: 5ec40c83183fc7e0
+  en: 94b1037f25176c7d
+  zh: 141c25306a57e5ea
diff --git a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.md b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.md
index b255ef500c..23a21d7636 100644
--- a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.md
+++ b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.md
@@ -14,7 +14,7 @@ Plugin and MCP tools change during conversations. Providers differ in whether th
 
 `Session.toolHistory()` caches a capability-independent fold of committed headers and developer messages. First access restores inherited events; later reads consume only unseen events. Immutable snapshots carry initial declarations and ordered update identities with additions resolved through their historical headers. Explicit series starts and changed retained definitions rebuild declarations. Restoring a retained name with an unchanged definition continues the series: the projection keeps the declaration unchanged and lets the recorded addition re-offer the tool after its earlier removal, so a removal never disables a declared tool and a loading mode never rewrites an earlier declaration.
 
-Loop and compaction requests carry this snapshot as `GenerateOptions.toolHistory`. At adapter dispatch, `projectToolUpdates` uses the prepared route's `toolUpdate`. Unsupported routes receive active definitions without `deferLoading` or developer messages. Supported routes defer historical additions; `in-history` retains removed definitions and removal blocks, while `addition-only` omits both. On addition-only routes, removing any tool rebuilds the route's baseline after that update: the request declarations change even when the removed tool was activated later, so retaining superseded activation blocks cannot preserve the full conversation prefix. Previously activated tools become immediate; explicitly deferred declarations with no activation remain deferred. Subsequent additions remain deferred until their recorded activation. Superseded tool blocks are omitted without discarding other content in those messages. The Session fold and durable events remain capability-independent. Missing history or a request prefix omitting recorded updates uses current declarations without developer updates.
+Loop and compaction requests carry this snapshot as `GenerateOptions.toolHistory`. At adapter dispatch, `projectToolUpdates` uses the prepared route's `toolUpdate`. Unsupported routes receive active definitions without `deferLoading` or developer messages. Supported routes defer historical additions; `in-history` retains removed definitions and removal blocks, while `addition-only` omits both. On addition-only routes, removing any tool rebuilds the route's baseline after that update: the request declarations change even when the removed tool was activated later, so retaining superseded activation blocks cannot preserve the full conversation prefix. Adding tools when no declarations exist also rebuilds the baseline. Deferred declarations count as existing tools. The first tools would otherwise require a non-deferred placeholder in DeepSeek, which changes the prefix anyway; declaring them immediately avoids an unnecessary activation message and placeholder. Previously activated tools become immediate; explicitly deferred declarations with no activation remain deferred. Subsequent additions remain deferred until their recorded activation. Superseded tool blocks are omitted without discarding other content in those messages. The Session fold and durable events remain capability-independent. Missing history or a request prefix omitting recorded updates uses current declarations without developer updates.
 
 DeepSeek translates projected updates into system-role `tool_addition` and `tool_removal` blocks and `defer_loading` declarations, sending the tool-changes beta header when update blocks occur. The default `deepseek-flash` entry declares `addition-only`; pi-ai selects `in-history` for compatible Anthropic routes and `addition-only` for compatible Chat Completions and Responses routes. Chat and Trajectory display developer messages as context nodes, using localized tool-change notices: single changes show the tool name; multiple changes show counts and expandable name lists.
 
@@ -36,6 +36,6 @@ Tool lists and logical update events are capability-independent; only outgoing d
 
 The authored [headless prompt/tool scenario](../../../../snapshots/session/dynamic-tool-prompt-updates/snapshot.yml) pins an appended prompt beside a deferred tool addition and verifies that the first request's messages stay unchanged. It shares the stable-prompt scenario's tool lifecycle and schema expectations.
 
-The [DeepSeek replacement scenario](../../../../snapshots/session/deepseek-deferred-tools/snapshot.yml) checks a rebuilt baseline, a subsequent deferred addition, and removal of that later-activated tool through Messages serialization. An adapter-local placeholder covers nonempty all-deferred requests that remain, including explicit deferred declarations and direct calls. It does not activate real tools. These checks establish request construction, not measured cache savings from rebuilding.
+The [DeepSeek replacement scenario](../../../../snapshots/session/deepseek-deferred-tools/snapshot.yml) checks the first additions to an empty set, a rebuilt baseline, a subsequent deferred addition, and removal of that later-activated tool through Messages serialization. An adapter-local placeholder covers nonempty all-deferred requests that remain, including explicit deferred declarations and direct calls. It does not activate real tools. These checks establish request construction, not measured cache savings from rebuilding.
 
 The [real DeepSeek SDK test](../../../../apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts) measures the first request after a native tool addition with both unchanged and simultaneously updated instructions. Unique user history prevents a shared system-prompt cache hit from satisfying the preceding-input assertion. Removal checks tool availability without requiring cache retention; each case disables retries.
diff --git a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.zh.md b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.zh.md
index 4edcc7a061..9f4ee01afd 100644
--- a/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 `Session.toolHistory()` 缓存对已提交请求头和 developer 消息的归约，不依赖模型能力。首次访问恢复继承事件；后续读取仅处理新增事件。不可变快照携带初始声明和有序更新标识，添加定义通过历史请求头解析。显式新序列和保留定义变化会重建声明。以未变化的定义恢复保留名称时序列继续：投影保持声明不变，由记录的添加在先前移除之后重新提供该工具，因此移除不会禁用已声明的工具，加载模式也不会改写先前声明。
 
-循环和压缩请求通过 `GenerateOptions.toolHistory` 携带此快照。适配器分发时，`projectToolUpdates` 使用已准备路由的 `toolUpdate`。不支持的路由接收有效定义，不携带 `deferLoading` 或 developer 消息。支持的路由延迟历史添加；`in-history` 保留已移除定义和移除块，`addition-only` 则省略两者。在 addition-only 路由移除任何工具时，使用该次更新后的状态重建路由基线：即使被移除工具是后来激活的，请求声明也已发生变化，保留已被取代的激活块无法保留完整对话前缀。此前已激活工具变为立即加载；没有激活记录的显式延迟声明仍保持延迟。后续添加在记录的激活位置前保持延迟加载。已被取代的工具块会被省略，但不会丢弃这些消息中的其他内容。Session 归约和持久事件仍不依赖模型能力。缺少历史或请求前缀遗漏已记录更新时，使用当前声明且不发送 developer 更新。
+循环和压缩请求通过 `GenerateOptions.toolHistory` 携带此快照。适配器分发时，`projectToolUpdates` 使用已准备路由的 `toolUpdate`。不支持的路由接收有效定义，不携带 `deferLoading` 或 developer 消息。支持的路由延迟历史添加；`in-history` 保留已移除定义和移除块，`addition-only` 则省略两者。在 addition-only 路由移除任何工具时，使用该次更新后的状态重建路由基线：即使被移除工具是后来激活的，请求声明也已发生变化，保留已被取代的激活块无法保留完整对话前缀。不存在任何声明时添加工具，也会重建基线。延迟声明也计入已有工具。否则首批工具会使 DeepSeek 需要非延迟占位工具，同样改变前缀；直接声明这些工具可避免不必要的激活消息和占位工具。此前已激活工具变为立即加载；没有激活记录的显式延迟声明仍保持延迟。后续添加在记录的激活位置前保持延迟加载。已被取代的工具块会被省略，但不会丢弃这些消息中的其他内容。Session 归约和持久事件仍不依赖模型能力。缺少历史或请求前缀遗漏已记录更新时，使用当前声明且不发送 developer 更新。
 
 DeepSeek 把投影后的更新转换为 system 角色的 `tool_addition` 和 `tool_removal` 块以及 `defer_loading` 声明，在存在更新块时发送工具变更 beta 请求头。默认 `deepseek-flash` 条目声明 `addition-only`；pi-ai 为兼容的 Anthropic 路由选择 `in-history`，为兼容的 Chat Completions 和 Responses 路由选择 `addition-only`。Chat 和 Trajectory 将 developer 消息显示为上下文节点，工具变更使用本地化通知：单项变更显示工具名，多项变更显示数量及可展开的名称列表。
 
@@ -36,6 +36,6 @@ DeepSeek 把投影后的更新转换为 system 角色的 `tool_addition` 和 `to
 
 手写的[无界面提示词／工具场景](../../../../snapshots/session/dynamic-tool-prompt-updates/snapshot.yml)钉住追加提示词与延迟工具添加同时发生的行为，并验证首次请求的消息保持不变。它复用稳定提示词场景的工具生命周期和 schema 期望值。
 
-[DeepSeek 替换场景](../../../../snapshots/session/deepseek-deferred-tools/snapshot.yml)通过 Messages 序列化验证重建后的基线、后续延迟添加，以及移除该后来激活的工具。适配器内的占位工具覆盖仍然存在的非空全延迟请求，包括显式延迟声明和直接调用，不会激活真实工具。这些检查验证请求构造，不代表已经测量重建带来的缓存收益。
+[DeepSeek 替换场景](../../../../snapshots/session/deepseek-deferred-tools/snapshot.yml)通过 Messages 序列化验证向空工具集首次添加工具、重建后的基线、后续延迟添加，以及移除该后来激活的工具。适配器内的占位工具覆盖仍然存在的非空全延迟请求，包括显式延迟声明和直接调用，不会激活真实工具。这些检查验证请求构造，不代表已经测量重建带来的缓存收益。
 
 [真实 DeepSeek SDK 测试](../../../../apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts) 分别在指令不变和指令同时更新时测量原生工具新增后的首次请求。独有的用户历史确保仅命中共享系统提示词缓存无法满足前序输入断言。移除场景检查工具可用性，不要求保留缓存；每个用例均禁用重试。
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index d17e33ac4d..c3d2e1948c 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/README.i18n.yaml
@@ -63,8 +63,8 @@
   en: 1dc50052999253c6
   zh: 7abf968fc18bffcd
 /deepseek-ai-dsh-llm-deepseek/model-experience/deepseek-request/what-the-model-sees:
-  en: a5534fa423d207d8
-  zh: 52c524bc054076fb
+  en: 06f3cafb41d8d6bd
+  zh: 1b031d123a939685
 /deepseek-ai-dsh-llm-deepseek/model-experience/deepseek-request/token-effect:
   en: f8891795b5bfd744
   zh: b1235786b04a7558
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 99be446545..5bdea7637b 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -170,7 +170,7 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-The selected DeepSeek model receives the harness system prompt, message history, tool schemas, stop sequences, and call config (`maxTokens`, `reasoningEffort`, `temperature`). Provider-specific request-extension fields remain outside model input. The vision model normally receives retained user and tool-result images as Files API references beside attachment handles and request-preview dimensions. It also receives a normalized-object path when the current execution filesystem maps the attachment provider's host object; the descriptor marks this copy read-only and warns that normalization may have resized or re-encoded the upload. A Files resolution failure sends all retained images as inline base64 instead, and an over-budget older image keeps the access resolved for that request in its placeholder. Reasoning content from a prior assistant turn is passed back verbatim, whether or not that turn called a tool. Messages sends `{}` for historical tool arguments that are malformed JSON or are not objects. This argument fallback preserves call ids, tool names, and tool results; the original arguments stay in the Session log. Newly generated Messages tool arguments still require valid JSON objects. Messages omits `reasoning` and `tool-call` blocks inside user messages and tool results. This also permits replay of saved subagent notices containing assistant output; the original Session content remains intact. Empty user messages are skipped after conversion, while empty tool results retain their call ids and error flags. Other unsupported input blocks still fail with `UNSUPPORTED_CONTENT`. When every declared tool is deferred, the adapter prepends a non-deferred `DeferredToolPlaceholder` with the description `Reserved placeholder that keeps deferred tool loading active; never call this tool.` A numeric suffix avoids collisions with declared tools. The placeholder has no executor; calls receive the ordinary unavailable-tool result. The placeholder leaves real declarations unchanged. The shared [tool-update projection](../llm/README.md#known-limitations-and-deferred-work) rebuilds an addition-only baseline whenever a tool is removed, while keeping later additions deferred. Empty tool lists receive no placeholder.
+The selected DeepSeek model receives the harness system prompt, message history, tool schemas, stop sequences, and call config (`maxTokens`, `reasoningEffort`, `temperature`). Provider-specific request-extension fields remain outside model input. The vision model normally receives retained user and tool-result images as Files API references beside attachment handles and request-preview dimensions. It also receives a normalized-object path when the current execution filesystem maps the attachment provider's host object; the descriptor marks this copy read-only and warns that normalization may have resized or re-encoded the upload. A Files resolution failure sends all retained images as inline base64 instead, and an over-budget older image keeps the access resolved for that request in its placeholder. Reasoning content from a prior assistant turn is passed back verbatim, whether or not that turn called a tool. Messages sends `{}` for historical tool arguments that are malformed JSON or are not objects. This argument fallback preserves call ids, tool names, and tool results; the original arguments stay in the Session log. Newly generated Messages tool arguments still require valid JSON objects. Messages omits `reasoning` and `tool-call` blocks inside user messages and tool results. This also permits replay of saved subagent notices containing assistant output; the original Session content remains intact. Empty user messages are skipped after conversion, while empty tool results retain their call ids and error flags. Other unsupported input blocks still fail with `UNSUPPORTED_CONTENT`. When every declared tool is deferred, the adapter prepends a non-deferred `DeferredToolPlaceholder` with the description `Reserved placeholder that keeps deferred tool loading active; never call this tool.` A numeric suffix avoids collisions with declared tools. The placeholder has no executor; calls receive the ordinary unavailable-tool result. The placeholder leaves real declarations unchanged. The shared [tool-update projection](../llm/README.md#known-limitations-and-deferred-work) rebuilds an addition-only baseline when a tool is removed or tools are added to an empty set, while keeping later additions deferred. Empty tool lists receive no placeholder.
 
 #### Token effect
 
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index c6e74f18e2..009306fb5e 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -170,7 +170,7 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 
 #### 模型看到什么
 
-所选 DeepSeek 模型会收到 harness 系统提示词、消息历史、工具 schema、停止序列与调用配置（`maxTokens`、`reasoningEffort`、`temperature`）。提供方专用请求扩展字段留在模型输入之外。视觉模型通常接收 Files API 引用形式的用户与工具结果图片，其旁带附件句柄和请求预览尺寸。当前执行文件系统可以映射附件提供方的宿主对象时，它还会收到规范化对象路径；描述符会把该副本标记为只读，并警告规范化可能缩放或重新编码上传内容。Files 解析失败时，全部保留图片改用内联 base64；超出预算的较旧图片则在占位文本中保留当前请求已解析的访问方式。此前 assistant 轮次的推理内容会原样传回，无论该轮次是否调用了工具。 对于非法 JSON 或非对象的历史工具参数，Messages 发送 `{}`。此参数兜底保留调用 ID、工具名和工具结果；原始参数仍保留在 Session 日志中。新生成的 Messages 工具参数仍须是有效 JSON 对象。 Messages 会省略用户消息和工具结果中的 `reasoning` 与 `tool-call` 块。这也允许回放包含助手输出的已保存子 Agent 通知；原始 Session 内容保持完整。转换后的空用户消息会被跳过，空工具结果则保留调用 id 和错误标记。其他不支持的输入块仍会以 `UNSUPPORTED_CONTENT` 失败。 当所有已声明工具都为延迟加载时，适配器会在列表开头添加非延迟的 `DeferredToolPlaceholder`，描述为 `Reserved placeholder that keeps deferred tool loading active; never call this tool.`。如与已声明工具重名，则添加数字后缀。占位工具没有执行器；调用会收到常规的工具不可用结果。占位工具不会改变真实工具声明。共享的[工具更新投影](../llm/README.zh.md#known-limitations-and-deferred-work)在移除任何工具时重建 addition-only 基线，后续添加仍保持延迟加载。空工具列表不会添加占位工具。
+所选 DeepSeek 模型会收到 harness 系统提示词、消息历史、工具 schema、停止序列与调用配置（`maxTokens`、`reasoningEffort`、`temperature`）。提供方专用请求扩展字段留在模型输入之外。视觉模型通常接收 Files API 引用形式的用户与工具结果图片，其旁带附件句柄和请求预览尺寸。当前执行文件系统可以映射附件提供方的宿主对象时，它还会收到规范化对象路径；描述符会把该副本标记为只读，并警告规范化可能缩放或重新编码上传内容。Files 解析失败时，全部保留图片改用内联 base64；超出预算的较旧图片则在占位文本中保留当前请求已解析的访问方式。此前 assistant 轮次的推理内容会原样传回，无论该轮次是否调用了工具。 对于非法 JSON 或非对象的历史工具参数，Messages 发送 `{}`。此参数兜底保留调用 ID、工具名和工具结果；原始参数仍保留在 Session 日志中。新生成的 Messages 工具参数仍须是有效 JSON 对象。 Messages 会省略用户消息和工具结果中的 `reasoning` 与 `tool-call` 块。这也允许回放包含助手输出的已保存子 Agent 通知；原始 Session 内容保持完整。转换后的空用户消息会被跳过，空工具结果则保留调用 id 和错误标记。其他不支持的输入块仍会以 `UNSUPPORTED_CONTENT` 失败。 当所有已声明工具都为延迟加载时，适配器会在列表开头添加非延迟的 `DeferredToolPlaceholder`，描述为 `Reserved placeholder that keeps deferred tool loading active; never call this tool.`。如与已声明工具重名，则添加数字后缀。占位工具没有执行器；调用会收到常规的工具不可用结果。占位工具不会改变真实工具声明。共享的[工具更新投影](../llm/README.zh.md#known-limitations-and-deferred-work)在移除任何工具或向空工具集添加工具时重建 addition-only 基线，后续添加仍保持延迟加载。空工具列表不会添加占位工具。
 
 #### Token 影响
 
diff --git a/packages/llm/llm-deepseek/tests/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
index c437d810fd..03f2f5fec4 100644
--- a/packages/llm/llm-deepseek/tests/adapter.e2e.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
@@ -50,21 +50,21 @@ async function boot(models?: Messages.Options['models'], baseURL = Protocol.PUBL
 const tool = { name: 'lookup_value', description: 'Read the requested value. Always call this tool to obtain a value.', parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } }
 
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('DeepSeek Messages real API', () => {
-  it.each([false, true])('calls a replacement tool after every baseline tool has been removed, separate updates=%s', async (separate) => {
+  it.each(['together', 'separate', 'initially empty'])('calls a tool added to an empty set, updates=%s', async (mode) => {
     const model = 'deepseek-flash'
     const ctx = await boot([{ id: model, toolUpdate: 'addition-only' }], process.env.DEEPSEEK_BASE_URL ?? Protocol.PUBLIC_BASE_URL)
-    const updates = [createDeveloperMessage({ source: { kind: 'tool-registry' }, content: [
+    const updates = mode === 'initially empty' ? [] : [createDeveloperMessage({ source: { kind: 'tool-registry' }, content: [
       { type: 'tool-removal', toolName: 'old_lookup' },
-      ...separate ? [] : [{ type: 'tool-addition' as const, toolName: tool.name }],
+      ...mode !== 'together' ? [] : [{ type: 'tool-addition' as const, toolName: tool.name }],
     ] })]
-    if (separate) updates.push(createDeveloperMessage({ source: { kind: 'tool-registry' }, content: [
+    if (mode !== 'together') updates.push(createDeveloperMessage({ source: { kind: 'tool-registry' }, content: [
       { type: 'tool-addition', toolName: tool.name },
     ] }))
     const response = await assemble(ctx.llm.stream(options({
       model, reasoningEffort: ReasoningEffortId('high'),
       messages: [user('Call lookup_value with key "answer" to obtain the value. Do not guess.'), ...updates],
       tools: [tool],
-      toolHistory: { tools: [{ ...tool, name: 'old_lookup' }], updates: updates.map(update => ({
+      toolHistory: { tools: mode === 'initially empty' ? [] : [{ ...tool, name: 'old_lookup' }], updates: updates.map(update => ({
         messageId: update.id, additions: update.content.some(block => block.type === 'tool-addition') ? [tool] : [],
       })) },
     })), model)
diff --git a/packages/llm/llm-deepseek/tests/fixtures/deferred-tools.ts b/packages/llm/llm-deepseek/tests/fixtures/deferred-tools.ts
index ea3e240223..ec74a510e7 100644
--- a/packages/llm/llm-deepseek/tests/fixtures/deferred-tools.ts
+++ b/packages/llm/llm-deepseek/tests/fixtures/deferred-tools.ts
@@ -1,8 +1,8 @@
-/** Replay a complete replacement of the initially available tools through Messages serialization. */
+/** Replay first additions to an empty tool set and subsequent replacements through Messages serialization. */
 import assert from 'node:assert/strict'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-agent'
-import { projectToolUpdates } from '@deepseek-ai/dsh-llm'
+import { createUserMessage, projectToolUpdates } from '@deepseek-ai/dsh-llm'
 import { defineContentToolFixture } from '@deepseek-ai/dsh-tool-testkit'
 import { resolveAdapterOptions } from '../../src/config.ts'
 import { serialize } from '../../src/serialize.ts'
@@ -11,12 +11,18 @@ export const name = 'messages-deferred-tools-snapshot'
 export const inject = ['tools', 'llm']
 
 /**
- * Replace the baseline after its first call and check the serialized replay requests.
+ * Add and replace tools after an empty request, checking each serialized replay request.
  * @param ctx - Snapshot composition context.
  */
 export function apply(ctx: Context): void {
   ctx.on('agent/created', ({ agent }) => {
     agent.ctx.tools.restrict({ allow: [] })
+  })
+  let initialized = false
+  ctx.on('agent/turn-stopping', ({ agent }) => {
+    if (initialized) return
+    initialized = true
+    agent.send(createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: 'Call snapshot_initial, snapshot_ping, and snapshot_later, then reply DONE.' }] }), 'next-step', false)
     const removeInitial = agent.ctx.tools.register(defineContentToolFixture({
       name: 'snapshot_initial', description: 'Make snapshot_ping available.', parameters: {},
       async execute() {
@@ -43,14 +49,20 @@ export function apply(ctx: Context): void {
     }))
   })
   const connection = resolveAdapterOptions({})
-  let requests = 0
+  let requests = -1
   ctx.on('llm/stream', (options, next) => {
     const projected = projectToolUpdates(options.messages, options.tools, 'addition-only', options.toolHistory)
     assert.ok(projected.tools)
     const request = serialize({ ...options, tools: [...projected.tools] }, connection, projected.messages, new Map(), () => undefined)
     switch (++requests) {
+      case 0:
+        assert.deepEqual(request.tools, [])
+        break
       case 1:
-        assert.deepEqual(request.tools?.map(tool => tool.name), ['snapshot_initial'])
+        assert.deepEqual(request.tools, [
+          { name: 'snapshot_initial', description: 'Make snapshot_ping available.', input_schema: { type: 'object', properties: {} } },
+        ])
+        assert.deepEqual(request.messages.filter(message => message.role === 'system'), [])
         break
       case 2:
         assert.deepEqual(request.tools, [
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 78c5071896..16f199923c 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/README.i18n.yaml
@@ -54,8 +54,8 @@
   en: a81634136baef72f
   zh: b92dda883986b0e1
 /deepseek-ai-dsh-llm/known-limitations-and-deferred-work:
-  en: 9b2c811157cb5148
-  zh: 94577c68b22f0abb
+  en: ed57783be0df3110
+  zh: c0c433dd6a807b89
 /deepseek-ai-dsh-llm/known-limitations-and-deferred-work/dev-note:
   en: ecbc333b88e14d88
   zh: 77c725d92efd8646
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index a9caca0951..e635e4f53c 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -180,7 +180,7 @@ These limits define where this service stops and other packages or future work b
 - **Variants normally require a producer** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant have no producer ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
 - **`GenerateOptions.sessionId` is a locally-declared brand** — importing dsh-session's `SessionId` would create a dependency cycle.
-- **Tool updates require session history** — `GenerateOptions.tools` contains active definitions. `toolHistory` supplies the initial declarations and historically resolved additions from `Session.toolHistory()`. At adapter dispatch, `projectToolUpdates` constructs deferred declarations and retains removed definitions for `in-history`; `addition-only` omits removed definitions and removal messages. Removing any tool on an addition-only route rebuilds that route's baseline from the declarations available after that update. Superseded tool blocks are omitted while unrelated content survives; subsequent additions remain deferred. Unsupported routes receive active tools without developer messages or `deferLoading`. Missing history or a request prefix omitting recorded updates falls back to current declarations without developer messages. Explicitly deferred tools become immediate during a rebuild only if an addition has already activated them; unactivated declarations remain deferred.
+- **Tool updates require session history** — `GenerateOptions.tools` contains active definitions. `toolHistory` supplies the initial declarations and historically resolved additions from `Session.toolHistory()`. At adapter dispatch, `projectToolUpdates` constructs deferred declarations and retains removed definitions for `in-history`; `addition-only` omits removed definitions and removal messages. Removing any tool or adding tools to an empty set on an addition-only route rebuilds the baseline from the declarations available after that update. Deferred declarations count as existing tools. Superseded tool blocks are omitted while unrelated content survives; subsequent additions remain deferred. Unsupported routes receive active tools without developer messages or `deferLoading`. Missing history or a request prefix omitting recorded updates falls back to current declarations without developer messages. Explicitly deferred tools become immediate during a rebuild only if an addition has already activated them; unactivated declarations remain deferred.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 6b917948c1..4e07a748f0 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -180,7 +180,7 @@ const configure = (maxTokens: number): ConfigureCall =>
 - **变体通常要求实际产生方**——`prefill`、逐工具 `strict`、内容块 `cache` 提示和 `agent` 消息来源变体都没有产生方（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**——插件添加块类型的流若从未由 `block-end` 关闭，`blocks()` 会抛出异常。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**——导入 dsh-session 的 `SessionId` 会产生依赖循环。
-- **工具更新需要会话历史** — `GenerateOptions.tools` 包含当前有效定义。`toolHistory` 提供 `Session.toolHistory()` 派生的初始声明及已解析历史定义的添加记录。适配器分发时，`projectToolUpdates` 构造延迟声明，并在 `in-history` 模式保留已移除定义；`addition-only` 省略已移除定义和移除消息。在 addition-only 路由移除任何工具时，使用该次更新后的可用声明重建此路由的基线。已被取代的工具块会被省略，其他内容保留；后续添加仍保持延迟加载。不支持更新的路由接收有效工具，不携带 developer 消息或 `deferLoading`。缺少历史或请求前缀遗漏已记录更新时，回退为当前声明且不发送 developer 消息。显式延迟工具仅在已有添加记录将其激活时，才会在重建时变为立即加载；尚未激活的声明仍保持延迟加载。
+- **工具更新需要会话历史** — `GenerateOptions.tools` 包含当前有效定义。`toolHistory` 提供 `Session.toolHistory()` 派生的初始声明及已解析历史定义的添加记录。适配器分发时，`projectToolUpdates` 构造延迟声明，并在 `in-history` 模式保留已移除定义；`addition-only` 省略已移除定义和移除消息。在 addition-only 路由移除任何工具或向空工具集添加工具时，使用该次更新后的可用声明重建基线。延迟声明也计入已有工具。已被取代的工具块会被省略，其他内容保留；后续添加仍保持延迟加载。不支持更新的路由接收有效工具，不携带 developer 消息或 `deferLoading`。缺少历史或请求前缀遗漏已记录更新时，回退为当前声明且不发送 developer 消息。显式延迟工具仅在已有添加记录将其激活时，才会在重建时变为立即加载；尚未激活的声明仍保持延迟加载。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/llm/llm/src/content.ts b/packages/llm/llm/src/content.ts
index c2e2d33961..b862381118 100644
--- a/packages/llm/llm/src/content.ts
+++ b/packages/llm/llm/src/content.ts
@@ -393,7 +393,7 @@ function toolDeclarations(history: ToolHistory): Map<string, ToolSchema> {
   return declarations
 }
 
-/** Rebuild declarations after removals that addition-only routes cannot represent in history. */
+/** Rebuild declarations on removals or additions to an empty set, where the request prefix changes. */
 function rebaseAdditionOnlyHistory(
   history: ToolHistory,
   messages: ReadonlyMap<MessageId, readonly ContentBlock[]>,
@@ -403,7 +403,7 @@ function rebaseAdditionOnlyHistory(
   let retainedFrom = 0
   for (const [index, update] of history.updates.entries()) {
     const additions = new Map(update.additions.map(tool => [tool.name, tool]))
-    let reset = false
+    let reset = available.size === 0 && additions.size > 0
     // Completeness was checked before projection; Session resolves every addition's definition.
     for (const block of messages.get(update.messageId) as readonly ContentBlock[]) {
       if (block.type === 'tool-addition') {
@@ -427,8 +427,9 @@ function rebaseAdditionOnlyHistory(
  * Unsupported routes and incomplete history use current declarations without developer updates.
  * Explicitly deferred declarations require an addition to activate them.
  * A rebuild makes previously activated declarations immediate; unactivated declarations stay deferred.
- * Addition-only routes rebuild their baseline whenever a tool is removed;
- * later additions remain deferred and superseded tool blocks are omitted without dropping other content.
+ * Addition-only routes rebuild when a tool is removed or tools are added to an empty set;
+ * deferred declarations count as existing tools.
+ * Later additions remain deferred and superseded tool blocks are omitted without dropping other content.
  * @param messages - complete request inputs, or the prefix selected for an auxiliary call.
  * @param tools - currently active tool schemas.
  * @param toolUpdate - the resolved route's update mode.
diff --git a/packages/llm/llm/tests/content.spec.ts b/packages/llm/llm/tests/content.spec.ts
index c3376c1f70..14f6684f3b 100644
--- a/packages/llm/llm/tests/content.spec.ts
+++ b/packages/llm/llm/tests/content.spec.ts
@@ -445,10 +445,46 @@ describe('projectToolUpdates', () => {
 
     const projected = projectToolUpdates([prompt, added, duplicate, removed, restored], [deferred], mode, history)
 
-    expect(projected.tools).toEqual([deferred])
+    expect(projected.tools).toEqual(mode === 'in-history' ? [deferred] : [search])
     expect(projected.messages).toEqual(mode === 'in-history'
       ? [prompt, added, removed, restored]
-      : [prompt, restored])
+      : [prompt])
+  })
+
+  it.each([false, true])('rebuilds when adding the first tools to an empty set (removed=%s)', (removed) => {
+    const removal = developer([{ type: 'tool-removal', toolName: 'search' }])
+    const added = developer([{ type: 'tool-addition', toolName: 'fetch' }, { type: 'text', text: 'Keep this guidance.' }])
+    const later = developer([{ type: 'tool-addition', toolName: 'search' }])
+    const history: ToolHistory = {
+      tools: removed ? [search] : [],
+      updates: [
+        ...removed ? [{ messageId: removal.id, additions: [] }] : [],
+        { messageId: added.id, additions: [fetch] },
+        { messageId: later.id, additions: [search] },
+      ],
+    }
+    const messages = [prompt, ...removed ? [removal] : [], added, prompt, later]
+    const saved = JSON.stringify({ messages, history })
+    const projected = projectToolUpdates(messages, [fetch, search], 'addition-only', history)
+    expect(projected.tools).toEqual([fetch, { ...search, deferLoading: true }])
+    expect(roles(projected.messages)).toEqual([
+      [{ type: 'text', text: 'Keep this guidance.' }],
+      [{ type: 'tool-addition', toolName: 'search' }],
+    ])
+    expect(JSON.stringify({ messages, history })).toBe(saved)
+    const inHistory = projectToolUpdates(messages, [fetch, search], 'in-history', history)
+    expect(roles(inHistory.messages)).toContainEqual(added.content)
+  })
+
+  it('keeps additions deferred when an unactivated deferred declaration already exists', () => {
+    const deferred = { ...search, deferLoading: true as const }
+    const added = developer([{ type: 'tool-addition', toolName: 'fetch' }])
+    const messages = [prompt, added]
+    const projected = projectToolUpdates(messages, [deferred, fetch], 'addition-only', {
+      tools: [deferred], updates: [{ messageId: added.id, additions: [fetch] }],
+    })
+    expect(projected.tools).toEqual([deferred, { ...fetch, deferLoading: true }])
+    expect(projected.messages).toBe(messages)
   })
 
   it('uses current declarations without updates when history is missing or the prefix omits an update', () => {
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index a5d8be4413..f320f6fc3c 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -239,8 +239,13 @@ describe('LlmRuntime', () => {
         tools: [search],
         toolHistory: { tools: [], updates: [{ messageId: added.id, additions: [search] }] },
       }))
-      expect(adapter.lastOptions?.tools).toEqual([{ ...search, deferLoading: true }])
-      expect(adapter.lastOptions?.messages).toEqual([added])
+      if (mode === 'in-history') {
+        expect(adapter.lastOptions?.tools).toEqual([{ ...search, deferLoading: true }])
+        expect(adapter.lastOptions?.messages).toEqual([added])
+      } else {
+        expect(adapter.lastOptions?.tools).toEqual([search])
+        expect(adapter.lastOptions?.messages).toEqual([])
+      }
 
       const afterRemoval = await ctx.llm.prepareCall({ provider: 'test-provider', model: 'test-model' })
       await collect(afterRemoval.stream({
diff --git a/packages/test-support/session-snapshot/README.i18n.yaml b/packages/test-support/session-snapshot/README.i18n.yaml
index 10a22d3a98..1425edc812 100644
--- a/packages/test-support/session-snapshot/README.i18n.yaml
+++ b/packages/test-support/session-snapshot/README.i18n.yaml
@@ -24,8 +24,8 @@
   en: bd9dcb62ea4e77db
   zh: be9615f0ae662c9e
 /deepseek-ai-dsh-session-snapshot/use-this-package/pinning-request-headers-and-system-prompts:
-  en: 6b11d5111e1a3222
-  zh: de4d3889b1a5ebb4
+  en: fe59b0197fa5e34c
+  zh: dfa1844c2c965358
 /deepseek-ai-dsh-session-snapshot/use-this-package/platform-and-composition-variants:
   en: 64666ea2894acc4a
   zh: 0e78df32bcfd3633
diff --git a/packages/test-support/session-snapshot/README.md b/packages/test-support/session-snapshot/README.md
index e96bcf3b03..09aed7ac61 100644
--- a/packages/test-support/session-snapshot/README.md
+++ b/packages/test-support/session-snapshot/README.md
@@ -90,7 +90,7 @@ A nested `workspace.expected/<directory>/.empty` marker represents an empty dire
 
 ### Pinning request headers and system prompts
 
-A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The system prompt is surface node 0, logged as a `system/message` event before the step's first `request/header`; every fixture stores its text block as `"text":"{{system}}"` and the prompt sidecar keeps the full text. The pin's `request/header` events store `"tools":"{{tools}}"` while retaining config and reason, and the structured schema sidecar keeps the full catalogs. Logs containing developer messages retain ordered tool names in each header instead of the token so historical addition references remain verifiable. A child Session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`; a scenario whose prompt changes mid-run — replacing node 0, or appending after the cached history on an `in-history` route — declares `expectedPromptChanges`, and each change adds a `<!-- system/message change N -->` section to the prompt sidecar. The manifest spells these `header.changes` and `header.promptChanges`.
+A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The system prompt is surface node 0, logged as a `system/message` event before the step's first `request/header`; every fixture stores its text block as `"text":"{{system}}"` and the prompt sidecar keeps the full text. The pin's `request/header` events store `"tools":"{{tools}}"` while retaining config and reason, and the structured schema sidecar keeps the full catalogs. Logs containing developer messages retain ordered tool names in each header instead of the token so historical addition references remain verifiable. A child Session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`; a scenario whose prompt changes mid-run — replacing node 0, or appending after the cached history on an `in-history` route — declares `expectedPromptChanges`, and each change adds a `<!-- system/message change N -->` section to the prompt sidecar. The manifest spells these `header.changes` and `header.promptChanges`. Headers without tools retain an empty schema set in the sidecar, so the first later addition stays aligned with its header.
 
 ### Platform and composition variants
 
diff --git a/packages/test-support/session-snapshot/README.zh.md b/packages/test-support/session-snapshot/README.zh.md
index f4400c602d..01089dfd4f 100644
--- a/packages/test-support/session-snapshot/README.zh.md
+++ b/packages/test-support/session-snapshot/README.zh.md
@@ -90,7 +90,7 @@ Headless/ACP 与 SDK 适配器在规范化之前，将原始目录中的子创
 
 ### 固定请求 header 与系统提示
 
-每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` 伴随文件；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。系统提示是 surface 节点 0，作为 `system/message` 事件记录在该步骤第一个 `request/header` 之前；每个 fixture 把其文本块存储为 `"text":"{{system}}"`，提示词伴随文件保留完整文本。该 pin 的 `request/header` 事件存储 `"tools":"{{tools}}"`，同时保留配置与原因，结构化 schema 伴随文件保留完整目录。包含 developer 消息的日志会在各 header 中保留有序工具名，而不使用 token，以便继续校验历史工具添加引用。自身作用域组合出不同请求的 child Session 按 fixture 索引以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`；运行中提示词发生变化的场景——替换节点 0，或在 `in-history` 路由上追加到已缓存历史之后——声明 `expectedPromptChanges`，每次变化在提示词伴随文件中增加一个 `<!-- system/message change N -->` 小节。manifest 中对应字段为 `header.changes` 与 `header.promptChanges`。
+每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` 伴随文件；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。系统提示是 surface 节点 0，作为 `system/message` 事件记录在该步骤第一个 `request/header` 之前；每个 fixture 把其文本块存储为 `"text":"{{system}}"`，提示词伴随文件保留完整文本。该 pin 的 `request/header` 事件存储 `"tools":"{{tools}}"`，同时保留配置与原因，结构化 schema 伴随文件保留完整目录。包含 developer 消息的日志会在各 header 中保留有序工具名，而不使用 token，以便继续校验历史工具添加引用。自身作用域组合出不同请求的 child Session 按 fixture 索引以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`；运行中提示词发生变化的场景——替换节点 0，或在 `in-history` 路由上追加到已缓存历史之后——声明 `expectedPromptChanges`，每次变化在提示词伴随文件中增加一个 `<!-- system/message change N -->` 小节。manifest 中对应字段为 `header.changes` 与 `header.promptChanges`。没有工具的请求头在 sidecar 中保留空 schema 集，使后续首次添加仍与其请求头对齐。
 
 ### 平台与组合变体
 
diff --git a/packages/test-support/session-snapshot/src/suite.ts b/packages/test-support/session-snapshot/src/suite.ts
index d2a25af19c..ccaf94d7a8 100644
--- a/packages/test-support/session-snapshot/src/suite.ts
+++ b/packages/test-support/session-snapshot/src/suite.ts
@@ -419,6 +419,7 @@ function toolSchemasFrom(headers: readonly unknown[]): unknown[][] {
   return headers.flatMap((header) => {
     if (header === null || typeof header !== 'object') return []
     const tools = (header as { tools?: unknown }).tools
+    if (tools === undefined) return [[]]
     return Array.isArray(tools) ? [tools] : []
   })
 }
@@ -473,8 +474,8 @@ export function systemPromptPrecedesRequests(rawLog: string): boolean {
 
 /**
  * The normalized tool-schema arrays carried by request headers in a session
- * JSONL, in log order. Headers without an array-valued tools field are omitted
- * so callers can assert one schema set per header explicitly.
+ * JSONL, in log order. An absent tools field yields an empty schema set;
+ * invalid non-array fields are omitted.
  *
  * @param rawLog The session `.jsonl` content to inspect.
  * @param ctx The volatile values of the run that produced it.
@@ -524,15 +525,16 @@ export function parseToolSchemasSnapshot(snapshot: string): ToolSchemasSnapshot
 /**
  * Restore one sidecar schema set into a tokenized pinned header.
  *
- * @param header The parsed request header carrying a tools token or ordered tool names matching the sidecar.
+ * @param header The parsed header with a tools token, matching ordered names, or no tools for an empty sidecar.
  * @param schemas The complete schemas for this full header snapshot.
- * @returns A copy of the header with its complete schemas restored.
+ * @returns A copy with complete schemas restored, or the original header when tools are absent.
  */
 export function restorePinnedToolSchemas(header: unknown, schemas: readonly unknown[]): unknown {
   if (header === null || typeof header !== 'object' || Array.isArray(header)) {
     throw new Error('acp-snapshot: pinned request header must be an object')
   }
   const tools = (header as { tools?: unknown }).tools
+  if (tools === undefined && schemas.length === 0) return header
   const namesMatch = Array.isArray(tools) && tools.length === schemas.length
     && tools.every((name, index) => {
       const schema = schemas[index]
diff --git a/packages/test-support/session-snapshot/tests/suite.spec.ts b/packages/test-support/session-snapshot/tests/suite.spec.ts
index 6f07d10604..e7ae84442f 100644
--- a/packages/test-support/session-snapshot/tests/suite.spec.ts
+++ b/packages/test-support/session-snapshot/tests/suite.spec.ts
@@ -782,7 +782,7 @@ describe('systemPromptPrecedesRequests', () => {
 })
 
 describe('normalizedToolSchemas', () => {
-  it('extracts normalized schema arrays and omits absent or non-array fields', () => {
+  it('extracts normalized schema arrays, preserves empty headers, and omits invalid fields', () => {
     const log = [
       '{"type":"session","id":"a","createdAt":5,"cwd":"/w"}',
       '{"type":"request/header","seq":0,"time":9,"data":{"header":{"tools":[{"name":"read","description":"work in /w"}]}}}',
@@ -794,6 +794,7 @@ describe('normalizedToolSchemas', () => {
     ].join('\n')
     expect(normalizedToolSchemas(log, { sessionIds: [], cwd: '/w' })).toEqual([
       [{ name: 'read', description: 'work in {{cwd}}' }],
+      [],
     ])
   })
 })
@@ -893,6 +894,12 @@ describe('tool-schema snapshots', () => {
       .toEqual({ system: '{{system}}', tools: snapshot.initial })
   })
 
+  it('preserves absent tools only for an empty sidecar', () => {
+    const header = { config: { model: 'test' } }
+    expect(restorePinnedToolSchemas(header, [])).toBe(header)
+    expect(() => restorePinnedToolSchemas(header, snapshot.initial)).toThrow(/must equal/)
+  })
+
   it('restores ordered tool names only when they match the sidecar', () => {
     const schemas = [{ name: 'read' }, { name: 'write' }]
     expect(restorePinnedToolSchemas({ tools: ['read', 'write'] }, schemas)).toEqual({ tools: schemas })
diff --git a/snapshots/session/deepseek-deferred-tools/session.v4.jsonl b/snapshots/session/deepseek-deferred-tools/session.v4.jsonl
index ceb1cb5325..734954689b 100644
--- a/snapshots/session/deepseek-deferred-tools/session.v4.jsonl
+++ b/snapshots/session/deepseek-deferred-tools/session.v4.jsonl
@@ -2,37 +2,45 @@
 {"type":"permission/preset","data":{"preset":"danger-full-access"}}
 {"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
 {"type":"approval/policy","data":{"policy":"never"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call snapshot_initial, then snapshot_ping, then snapshot_later, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply READY."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
 {"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Call snapshot_initial, then snapshot_ping, then snapshot_later, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply READY."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent working directory: \"{{cwd}}\".\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"working-directory:current","text":"Current working directory: \"{{cwd}}\"."},{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
-{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_initial"]},"reason":"initial"}}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true}},"reason":"initial"}}
 {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
-{"type":"session/title","data":{"title":"Call snapshot_initial, then snapshot_pin","messageSeqs":[8],"source":{"kind":"fallback"}}}
-{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_initial","name":"snapshot_initial","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1792661643282,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792661643282,"index":0,"dt":[],"id":"call_initial","name":"snapshot_initial","args":["{}"]},{"type":"chunk","time":1792661643282,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_initial","name":"snapshot_initial","arguments":"{}"}}},{"type":"chunk","time":1792661643282,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1792661643282,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
-{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_initial","name":"snapshot_initial","arguments":"{}"}}
-{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_initial"},"toolCallId":"call_initial","content":[{"type":"text","text":"snapshot_ping is available."}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"session/title","data":{"title":"Reply READY.","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"READY"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"stream":[{"type":"chunk","time":1792734528886,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1792734528887,"index":0,"dt":[],"texts":["READY"]},{"type":"chunk","time":1792734528887,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"READY"}}},{"type":"chunk","time":1792734528887,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"source":{"kind":"user"},"content":[{"type":"text","text":"Call snapshot_initial, snapshot_ping, and snapshot_later, then reply DONE."}],"role":"user","id":"{{message:5}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":2}}
-{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_ping"]},"reason":"change"}}
-{"type":"developer/message","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_ping"},{"type":"tool-removal","toolName":"snapshot_initial"}],"role":"developer","id":"{{message:6}}"},"headerSeq":18},"surfaceOp":"append"}
-{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"stream":[{"type":"chunk","time":1792661643298,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792661643298,"index":0,"dt":[],"id":"call_dynamic_ping","name":"snapshot_ping","args":["{}"]},{"type":"chunk","time":1792661643298,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}}},{"type":"chunk","time":1792661643298,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
-{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}}
-{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_dynamic_ping"},"toolCallId":"call_dynamic_ping","content":[{"type":"text","text":"pong"}],"isError":false,"id":"{{message:8}}"}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"user/message","data":{"source":{"kind":"user"},"content":[{"type":"text","text":"Call snapshot_initial, snapshot_ping, and snapshot_later, then reply DONE."}],"role":"user","id":"{{message:5}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_initial"]},"reason":"change"}}
+{"type":"developer/message","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_initial"}],"role":"developer","id":"{{message:6}}"},"headerSeq":19},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_initial","name":"snapshot_initial","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1792734528899,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792734528899,"index":0,"dt":[],"id":"call_initial","name":"snapshot_initial","args":["{}"]},{"type":"chunk","time":1792734528899,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_initial","name":"snapshot_initial","arguments":"{}"}}},{"type":"chunk","time":1792734528899,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1792734528899,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_initial","name":"snapshot_initial","arguments":"{}"}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_initial"},"toolCallId":"call_initial","content":[{"type":"text","text":"snapshot_ping is available."}],"isError":false,"id":"{{message:8}}"}},"sourceEventSeqs":[22],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":2}}
 {"type":"step/start","data":{"turn":1,"step":3}}
-{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_later","snapshot_ping"]},"reason":"change"}}
-{"type":"developer/message","data":{"turn":1,"step":3,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_later"}],"role":"developer","id":"{{message:9}}"},"headerSeq":25},"surfaceOp":"append"}
-{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_later","name":"snapshot_later","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:10}}"},"stream":[{"type":"chunk","time":1792661643311,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792661643311,"index":0,"dt":[],"id":"call_later","name":"snapshot_later","args":["{}"]},{"type":"chunk","time":1792661643311,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_later","name":"snapshot_later","arguments":"{}"}}},{"type":"chunk","time":1792661643311,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
-{"type":"tool/call","data":{"turn":1,"step":3,"callId":"call_later","name":"snapshot_later","arguments":"{}"}}
-{"type":"tool/result","data":{"turn":1,"step":3,"message":{"role":"tool","source":{"kind":"tool","callId":"call_later"},"toolCallId":"call_later","content":[{"type":"text","text":"later"}],"isError":false,"id":"{{message:11}}"}},"sourceEventSeqs":[28],"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_ping"]},"reason":"change"}}
+{"type":"developer/message","data":{"turn":1,"step":3,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_ping"},{"type":"tool-removal","toolName":"snapshot_initial"}],"role":"developer","id":"{{message:9}}"},"headerSeq":26},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:10}}"},"stream":[{"type":"chunk","time":1792734528913,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792734528913,"index":0,"dt":[],"id":"call_dynamic_ping","name":"snapshot_ping","args":["{}"]},{"type":"chunk","time":1792734528913,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}}},{"type":"chunk","time":1792734528913,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":3,"callId":"call_dynamic_ping","name":"snapshot_ping","arguments":"{}"}}
+{"type":"tool/result","data":{"turn":1,"step":3,"message":{"role":"tool","source":{"kind":"tool","callId":"call_dynamic_ping"},"toolCallId":"call_dynamic_ping","content":[{"type":"text","text":"pong"}],"isError":false,"id":"{{message:11}}"}},"sourceEventSeqs":[29],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":3}}
 {"type":"step/start","data":{"turn":1,"step":4}}
-{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_final","snapshot_ping"]},"reason":"change"}}
-{"type":"developer/message","data":{"turn":1,"step":4,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_final"},{"type":"tool-removal","toolName":"snapshot_later"}],"role":"developer","id":"{{message:12}}"},"headerSeq":32},"surfaceOp":"append"}
-{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:13}}"},"usage":{"inputTokens":12,"outputTokens":2,"cacheReadTokens":10},"stream":[{"type":"chunk","time":1792661643324,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1792661643324,"index":0,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1792661643324,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1792661643324,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":2,"cacheReadTokens":10}}},{"type":"chunk","time":1792661643324,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_later","snapshot_ping"]},"reason":"change"}}
+{"type":"developer/message","data":{"turn":1,"step":4,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_later"}],"role":"developer","id":"{{message:12}}"},"headerSeq":33},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_later","name":"snapshot_later","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:13}}"},"stream":[{"type":"chunk","time":1792734528931,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1792734528931,"index":0,"dt":[],"id":"call_later","name":"snapshot_later","args":["{}"]},{"type":"chunk","time":1792734528931,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_later","name":"snapshot_later","arguments":"{}"}}},{"type":"chunk","time":1792734528931,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":4,"callId":"call_later","name":"snapshot_later","arguments":"{}"}}
+{"type":"tool/result","data":{"turn":1,"step":4,"message":{"role":"tool","source":{"kind":"tool","callId":"call_later"},"toolCallId":"call_later","content":[{"type":"text","text":"later"}],"isError":false,"id":"{{message:14}}"}},"sourceEventSeqs":[36],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":4}}
+{"type":"step/start","data":{"turn":1,"step":5}}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["snapshot_final","snapshot_ping"]},"reason":"change"}}
+{"type":"developer/message","data":{"turn":1,"step":5,"message":{"source":{"kind":"tool-registry"},"content":[{"type":"tool-addition","toolName":"snapshot_final"},{"type":"tool-removal","toolName":"snapshot_later"}],"role":"developer","id":"{{message:15}}"},"headerSeq":40},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:16}}"},"usage":{"inputTokens":12,"outputTokens":2,"cacheReadTokens":10},"stream":[{"type":"chunk","time":1792734528950,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1792734528950,"index":0,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1792734528950,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1792734528950,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":2,"cacheReadTokens":10}}},{"type":"chunk","time":1792734528950,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":5}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/deepseek-deferred-tools/snapshot.yml b/snapshots/session/deepseek-deferred-tools/snapshot.yml
index ceedc9db93..711ea1ae83 100644
--- a/snapshots/session/deepseek-deferred-tools/snapshot.yml
+++ b/snapshots/session/deepseek-deferred-tools/snapshot.yml
@@ -6,4 +6,4 @@ recording: authored
 header:
   class: deepseek-deferred-tools
   pin: true
-  changes: 3
+  changes: 4
diff --git a/snapshots/session/deepseek-deferred-tools/tool-schemas.expected.json b/snapshots/session/deepseek-deferred-tools/tool-schemas.expected.json
index 255e5a96d0..1f8ef7a8ec 100644
--- a/snapshots/session/deepseek-deferred-tools/tool-schemas.expected.json
+++ b/snapshots/session/deepseek-deferred-tools/tool-schemas.expected.json
@@ -1,15 +1,16 @@
 {
-  "initial": [
-    {
-      "name": "snapshot_initial",
-      "description": "Make snapshot_ping available.",
-      "parameters": {
-        "type": "object",
-        "properties": {}
-      }
-    }
-  ],
+  "initial": [],
   "changes": [
+    [
+      {
+        "name": "snapshot_initial",
+        "description": "Make snapshot_ping available.",
+        "parameters": {
+          "type": "object",
+          "properties": {}
+        }
+      }
+    ],
     [
       {
         "name": "snapshot_ping",