fix(core): preserve prompt cache across deferred tool discovery

docs/design/2026-07-06-session-start-profiler.md

@@ -12,7 +12,7 @@ The profiler is enabled only when `QWEN_CODE_PROFILE_SESSION_START=1`.
 
 When enabled, core writes JSONL records under `Storage.getRuntimeBaseDir()/session-start-perf/`. Daily JSONL filenames use the UTC date from the record timestamp. Each record includes a timestamp, `SessionStartSource`, success flag, total duration, bounded stage durations, and small aggregate counts such as history length and rendered snapshot count. The #4748 daemon profiling follow-up adds an optional opaque Session ID when the caller supplies one so this detail record can be joined to the cross-process trace.
 
-The measured stages follow the existing `startChat()` sequence: tool registry warm, resumed deferred-tool reveal scan, deferred reminder setup, initial chat history build, skill reminder dedup seeding, agent reminder dedup seeding, system instruction build, `GeminiChat` construction, orphan tool-use repair, SessionStart hook, optional SessionStart context apply, and `setTools()`.
+The measured stages follow the existing `startChat()` sequence: tool registry warm, resumed deferred-tool reveal scan, deferred-tool preload decision, deferred-tool catalog setup, initial chat history build, skill reminder dedup seeding, agent reminder dedup seeding, system instruction build, `GeminiChat` construction, orphan tool-use repair, SessionStart hook, optional SessionStart context apply, and `setTools()`.
 
 ## Safety Boundaries
 

docs/design/fork-resume-live-capabilities.md

@@ -15,8 +15,8 @@ resume, rebuild its executable surface from the current parent session:
 - use the current parent's rendered system instruction;
 - take the current parent's advertised tool names and resolve their schemas
   through the resumed agent's current registry;
-- include current MCP, deferred-tool, and Skill reminders on the continuation
-  turn, while declaring earlier capability listings obsolete;
+- include current MCP and Skill reminders on the continuation turn, while
+  declaring earlier capability listings obsolete;
 - leave the task paused when the current parent prompt or tool surface cannot
   be reconstructed.
 

docs/design/prompt-cache/deferred-tool-call-stable-schema.md

@@ -0,0 +1,119 @@
+# Deferred Tool Catalog in `tool_search`
+
+## Problem
+
+Deferred tools were advertised through startup and lifecycle
+`<system-reminder>` messages. That makes the catalog ordinary conversation
+history: it can be diluted by a long context, removed by compression, or require
+special restoration during resume and compaction. Keeping the deferred set
+reachable therefore meant re-injecting catalog text into history whenever a
+lifecycle event evicted it.
+
+## Design
+
+The main session exposes two stable bridge tools:
+
+- `tool_search` advertises the current deferred-tool catalog in its dynamic
+  function description and returns full schemas for selected tools.
+- `tool_call` accepts a target tool name and target arguments, then hands the
+  request to the normal scheduler as that real target.
+
+The catalog is built from the live `ToolRegistry` whenever the provider-facing
+`tool_search` declaration is read. Bundled tools and MCP tools are grouped and
+sorted. Names and one-line descriptions are JSON quoted; MCP metadata is
+explicitly labelled as untrusted data rather than instructions.
+
+`tool_search` remains the schema lookup mechanism. Search results contain the
+matched declarations in the existing `<functions>` format, but discovering a
+normal deferred tool does not add that tool to the provider declaration list.
+An individually oversized schema may still use the existing direct-declaration
+fallback, and the search result tells the model to call that tool directly.
+
+```mermaid
+flowchart LR
+  A["tool_search description"] --> B["Live deferred-tool catalog"]
+  B --> C["tool_search returns selected full schema"]
+  C --> D["tool_call(name, arguments)"]
+  D --> E["Resolve live target in ToolRegistry"]
+  E --> F["Existing scheduler pipeline"]
+  F --> G["Permissions, validation, hooks, execution, telemetry"]
+```
+
+## Lifecycle
+
+The deferred catalog is no longer copied into startup, MCP-change, resume, or
+post-compression reminder messages. Compression can discard prior search
+results without making the catalog disappear because the current catalog is
+part of the `tool_search` declaration on every request. If the model needs a
+full schema again, it calls `tool_search` again.
+
+MCP connection changes update the registry. The next declaration read therefore
+contains the new catalog without appending synthetic user-history entries or
+rewriting the system instruction.
+
+The presentation ledger, unlike the catalog, does follow the active model
+context. A delivery surface commits a mark only after the carrying `tool_search`
+result enters active history, and rolls that commit back if the send fails
+before the push. Surfaces that execute a batch sequentially gate the whole batch
+against a snapshot taken before it starts, so a `tool_search` earlier in the
+same batch cannot self-authorize a sibling `tool_call`. Every history mutation
+that can evict a tool result — compression, `/clear`, resume reload,
+rewind/truncation, and stripping an orphaned turn that carried a tool result —
+clears the ledger, so an affected tool must be searched again before it can be
+routed. Revealed (directly declared) tools are unaffected: their schemas stay in
+the function-declaration list regardless of history.
+
+## Execution and safety
+
+`tool_call` is a transport bridge, not a separate executor. Before scheduling,
+Qwen Code:
+
+1. validates the bridge envelope;
+2. canonicalizes and loads the current target;
+3. rejects self-targeting, removed, replaced, directly visible, or otherwise
+   ineligible targets;
+4. retains the resolved target instance; and
+5. schedules the request under the real target identity.
+
+The real target continues to own argument validation, permission policy,
+confirmation, hooks, cancellation, result truncation, telemetry, and UI
+identity. The provider-facing response keeps the original `tool_call` name and
+call ID so request/response pairing remains valid.
+
+Reaching the catalog no longer depends on reminder text surviving in history, so
+nothing is re-injected after compression or resume. Execution still requires
+that the target schema was actually presented to the model: the registry keeps a
+session-scoped presentation ledger mapping each proxied tool to the schema
+fingerprint `tool_search` delivered, and `tool_call` rejects a target whose mark
+is missing or whose fingerprint no longer matches the live schema — issue
+#6721's fail-closed gate against routing guessed or stale arguments. This does
+not grant access to arbitrary tools: only live, hidden, proxy-eligible deferred
+tools with a current presented schema may be targeted.
+
+Subagents and teammates keep their existing direct declaration surface and do
+not receive `tool_call`, preserving their tool restrictions. If `tool_search`
+is unavailable in the main session, deferred tools continue to use the existing
+direct-declaration fallback.
+
+## Cache behavior
+
+Ordinary discovery no longer mutates the provider's function-declaration set:
+`tool_search` and `tool_call` remain stable bridge entries. The
+`tool_search.description` catalog changes only when the live deferred catalog
+changes, which is the intended capability change. Searching for or calling a
+tool does not itself rewrite the catalog into conversation history.
+
+## Verification
+
+Tests cover:
+
+- deterministic catalog rendering and live registry updates;
+- absence of deferred catalog reminders from startup and lifecycle paths;
+- repeated search after a prior schema result;
+- `tool_call` normalization, including the presentation-ledger gate, its
+  batch snapshot, delivery rollback, and ledger clearing across history
+  mutations;
+- rejection of malformed, missing, replaced, or ineligible targets;
+- preservation of real-target permissions, hooks, validation, telemetry, and
+  provider response identity; and
+- direct-declaration behavior for subagents and oversized schemas.

docs/design/toolsearch-preload-threshold.md

@@ -21,8 +21,8 @@ the equivalent gate.
 
 New setting `tools.toolSearch.threshold` (number, percent, default `10`).
 
-At session start (`GeminiClient.startChat`, before the deferred-tools reminder
-is resolved), when ToolSearch is registered and the threshold is > 0:
+At session start (`GeminiClient.startChat`, before the initial declarations are
+built), when ToolSearch is registered and the threshold is > 0:
 
 - Estimate the combined token footprint of every deferred tool schema —
   bundled built-ins and MCP alike
@@ -37,18 +37,16 @@ is resolved), when ToolSearch is registered and the threshold is > 0:
   restores the old behavior unconditionally.
 
 Preloaded tools therefore land in the initial declaration list, are filtered
-out of the startup deferred-tools reminder, and the declaration list stays
-stable for the whole session.
+out of the `tool_search` catalog (they are already directly callable), and the
+declaration list stays stable for the whole session.
 
 ## Decisions
 
-- **Session start only, never `setTools()`.** Revealing a tool the startup
-  reminder already announced would make `queueAddedMcpToolsReminder` flag it
-  as "removed", and a mid-session declaration change busts the very cache the
-  preload exists to protect. Tools from servers that connect later stay
-  deferred (announced via the added-tools reminder, reachable through
-  ToolSearch) until the next session start. `/clear` clears the revealed set
-  and re-runs the decision.
+- **Session start only, never `setTools()`.** A mid-session reveal changes the
+  declaration list and busts the very cache the preload exists to protect.
+  Tools from servers that connect later stay deferred (advertised in the
+  `tool_search` catalog, reachable through ToolSearch) until the next session
+  start. `/clear` clears the revealed set and re-runs the decision.
 - **One budget over the whole deferred set, bundled included.** Claude Code's
   auto threshold covers MCP/SDK tools only (its built-ins are managed
   separately), but it can afford that split: deferred tools are stripped from
@@ -72,4 +70,4 @@ stable for the whole session.
   starts (compression also passes through `startChat`) cannot ratchet the
   revealed set past the budget as servers come and go.
 - **No preload when ToolSearch is unavailable** — the existing eager-reveal
-  branch in `resolveDeferredToolsForReminder` already exposes everything.
+  branch in `resolveDeferredToolsForCatalog` already exposes everything.

integration-tests/sdk-typescript/sdk-mcp-server.test.ts

@@ -82,6 +82,7 @@ const MCP_CALCULATE_SUM = 'mcp__sdk-calculator__calculate_sum';
 const MCP_REVERSE_STRING = 'mcp__sdk-calculator__reverse_string';
 const MCP_MAYBE_FAIL = 'mcp__sdk-error-test__maybe_fail';
 const MCP_DELAYED_RESPONSE = 'mcp__sdk-async__delayed_response';
+const DEFERRED_TOOL_CALL = 'tool_call';
 
 describe('SDK MCP Server Integration (E2E)', () => {
   let helper: SDKTestHelper;
@@ -153,8 +154,14 @@ describe('SDK MCP Server Integration (E2E)', () => {
         if (requestIndex === 1) {
           return {
             toolCalls: [
-              fakeToolCall(MCP_CALCULATE_SUM, { a: 25, b: 17 }),
-              fakeToolCall(MCP_REVERSE_STRING, { text: 'hello world' }),
+              fakeToolCall(DEFERRED_TOOL_CALL, {
+                name: MCP_CALCULATE_SUM,
+                arguments: { a: 25, b: 17 },
+              }),
+              fakeToolCall(DEFERRED_TOOL_CALL, {
+                name: MCP_REVERSE_STRING,
+                arguments: { text: 'hello world' },
+              }),
             ],
           };
         }
@@ -186,17 +193,24 @@ describe('SDK MCP Server Integration (E2E)', () => {
         }
 
         expect(advertisedToolNames(fakeServer, 1)).toEqual(
-          expect.arrayContaining([MCP_CALCULATE_SUM, MCP_REVERSE_STRING]),
+          advertisedToolNames(fakeServer, 0),
+        );
+        expect(advertisedToolNames(fakeServer, 1)).toContain(
+          DEFERRED_TOOL_CALL,
+        );
+        expect(advertisedToolNames(fakeServer, 1)).not.toContain(
+          MCP_CALCULATE_SUM,
+        );
+        expect(advertisedToolNames(fakeServer, 1)).not.toContain(
+          MCP_REVERSE_STRING,
         );
 
-        const toolResults = findToolResults(messages, MCP_CALCULATE_SUM);
-        expect(toolResults).toHaveLength(1);
+        const toolResults = findToolResults(messages, DEFERRED_TOOL_CALL);
+        expect(toolResults).toHaveLength(2);
         expect(toolResults[0]?.isError).toBe(false);
         expect(toolResults[0]?.content).toContain('42');
-        const stringResults = findToolResults(messages, MCP_REVERSE_STRING);
-        expect(stringResults).toHaveLength(1);
-        expect(stringResults[0]?.isError).toBe(false);
-        expect(stringResults[0]?.content).toContain('dlrow olleh');
+        expect(toolResults[1]?.isError).toBe(false);
+        expect(toolResults[1]?.content).toContain('dlrow olleh');
         expect(
           systemMessage?.mcp_servers?.some(
             (server) => server.name === 'sdk-calculator',
@@ -353,7 +367,12 @@ describe('SDK MCP Server Integration (E2E)', () => {
             }
           : requestIndex === 1
             ? {
-                toolCalls: [fakeToolCall(MCP_MAYBE_FAIL, { shouldFail: true })],
+                toolCalls: [
+                  fakeToolCall(DEFERRED_TOOL_CALL, {
+                    name: MCP_MAYBE_FAIL,
+                    arguments: { shouldFail: true },
+                  }),
+                ],
               }
             : { content: 'Done.' };
       };
@@ -378,8 +397,16 @@ describe('SDK MCP Server Integration (E2E)', () => {
           messages.push(message);
         }
 
-        expect(advertisedToolNames(fakeServer, 1)).toContain(MCP_MAYBE_FAIL);
-        const toolResults = findToolResults(messages, MCP_MAYBE_FAIL);
+        expect(advertisedToolNames(fakeServer, 1)).toEqual(
+          advertisedToolNames(fakeServer, 0),
+        );
+        expect(advertisedToolNames(fakeServer, 1)).toContain(
+          DEFERRED_TOOL_CALL,
+        );
+        expect(advertisedToolNames(fakeServer, 1)).not.toContain(
+          MCP_MAYBE_FAIL,
+        );
+        const toolResults = findToolResults(messages, DEFERRED_TOOL_CALL);
         expect(toolResults).toHaveLength(1);
         expect(toolResults[0]?.isError).toBe(true);
         expect(toolResults[0]?.content).toContain('Tool intentionally failed');
@@ -432,9 +459,12 @@ describe('SDK MCP Server Integration (E2E)', () => {
           : requestIndex === 1
             ? {
                 toolCalls: [
-                  fakeToolCall(MCP_DELAYED_RESPONSE, {
-                    delay: 50,
-                    value: 'test_async',
+                  fakeToolCall(DEFERRED_TOOL_CALL, {
+                    name: MCP_DELAYED_RESPONSE,
+                    arguments: {
+                      delay: 50,
+                      value: 'test_async',
+                    },
                   }),
                 ],
               }
@@ -461,10 +491,16 @@ describe('SDK MCP Server Integration (E2E)', () => {
           messages.push(message);
         }
 
+        expect(advertisedToolNames(fakeServer, 1)).toEqual(
+          advertisedToolNames(fakeServer, 0),
+        );
         expect(advertisedToolNames(fakeServer, 1)).toContain(
+          DEFERRED_TOOL_CALL,
+        );
+        expect(advertisedToolNames(fakeServer, 1)).not.toContain(
           MCP_DELAYED_RESPONSE,
         );
-        const toolResults = findToolResults(messages, MCP_DELAYED_RESPONSE);
+        const toolResults = findToolResults(messages, DEFERRED_TOOL_CALL);
         expect(toolResults).toHaveLength(1);
         expect(toolResults[0]?.isError).toBe(false);
         expect(toolResults[0]?.content.toLowerCase()).toMatch(/test_async/i);