Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(mcp-host): make native tool discovery independent of MCP presentation
Alfredo Lopezf9546dad1d3c
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex f21aa261c..7b967cf39 100644--- a/docs/architecture/codex-subscription-transport-contract.md+++ b/docs/architecture/codex-subscription-transport-contract.md@@ -732,6 +732,32 @@ presentation counts change, including the first refresh. It reports the mode,strategy, native/MCP counts and presented/deferred counts without tool definitions.Direct mode reports `strategy: direct` and `deferredCount: 0`.+### Native tool presentation (#1003)++`CLERUM_NATIVE_TOOL_PRESENTATION=direct|auto` presents native tools and is+independent of `CODEX_TOOL_PRESENTATION` and `CLERUM_DYNAMIC_TOOLS_ENABLED`. It+applies to every provider and defaults to `direct`, which lists every native+exactly as before #1003: same `tools[]`, catalog, bridge behaviour, prompt text+and tool descriptions. `auto` lists the 3 bridge tools in every Codex mode, even+`direct` and even before MCP connects. It removes from `tools[]` each native whose+serialized definition exceeds `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES` (positive+integer, default 2048; `0` is rejected at startup). At the default that is the+pdf, xlsx, pptx, chart and dashboard generators. A removed native stays reachable:+`clerum__tool_search` lists natives under the `native` server,+`clerum__tool_describe` returns their schema, and `clerum__tool_call` runs them+by their real name, so validation and approval apply to that name. The bridge+never targets itself. When an MCP tool and a native share a name, the native wins.++The native decision runs after the MCP decision and only removes natives, so MCP+tools in `tools[]` are the same for both native modes. When `auto` hides a+native, all 3 bridge tools must be presented; otherwise mcp-host throws instead+of presenting an unreachable native. In Codex `direct` with native `auto`, the+`tool-presentation` diagnostic counts the 3 bridge tools: `nativeCount` and+`presentedCount` are 3 higher than with native `direct`, and every MCP field is+unchanged. The final list is reported by the separate `native-tool-presentation`+diagnostic (mode, budget, hidden names, presented count), emitted only in `auto`+when that result changes.+Search results contain bounded compact descriptions and no schemas. Follow`nextOffset` with the same query/filter to continue; explicit `enumerate`permits full traversal. Describe returns the exact selected schema, never adiff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.mdindex f1a863e22..c9269ef70 100644--- a/docs/architecture/grok-subscription-transport-contract.md+++ b/docs/architecture/grok-subscription-transport-contract.md@@ -273,7 +273,9 @@ constant to `true` only with recorded live-probe evidence.Tool payloads send `strict: false` so optional MCP fields stay optional on theResponses-shaped Grok wire (sibling of Codex #648). Agent tool presentationuses the same `CODEX_TOOL_PRESENTATION` knob as Codex and defaults to `direct`-when Grok is the primary or a fallback (sibling of Codex #644).+when Grok is the primary or a fallback (sibling of Codex #644). Native tools+follow the provider-independent `CLERUM_NATIVE_TOOL_PRESENTATION` (default+`direct`), described in the Codex contract under "Native tool presentation".## Terminal outcomesdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex e27c32cf6..660e6c099 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.479",+ "version": "0.1.480","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.479",+ "version": "0.1.480","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 566043608..8efd07c91 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.479",+ "version": "0.1.480","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {diff --git a/mcp-host/src/__tests__/integration/contextBreakdownEndToEnd.test.ts b/mcp-host/src/__tests__/integration/contextBreakdownEndToEnd.test.tsindex 335467d9b..697ef9194 100644--- a/mcp-host/src/__tests__/integration/contextBreakdownEndToEnd.test.ts+++ b/mcp-host/src/__tests__/integration/contextBreakdownEndToEnd.test.ts@@ -16,6 +16,7 @@ import { LlmPortAdapter } from '../../core/adapters/llmPortAdapter'import { ConversationManager } from '../../core/conversation/conversation'import type { SessionTokenUsage } from '../../core/conversation/conversationStore'import { DefaultReasoningFactory } from '../../core/reasoning/factory'+import { DefaultPromptBuilder } from '../../core/reasoning/promptBuilder'import type { SystemPromptParts } from '../../core/reasoning/systemPrompt'import { OpenAITokenCounter } from '../../core/tokenizer/openaiTokenCounter'import { FinishReason } from '../../core/types'@@ -71,7 +72,7 @@ describe('F1 — context breakdown end-to-end (factory → port → sink → pro// Wire the factory EXACTLY like taskExecutor:885 + F1.4.const factory = new DefaultReasoningFactory(llmPort,- undefined,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }),{},tokenCounter,raw => manager.recordContextBreakdown(conversation, raw),diff --git a/mcp-host/src/agent/__tests__/taskExecutor.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.test.tsindex 0a4097e2f..35c51e850 100644--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts@@ -1840,10 +1840,7 @@ describe('TaskExecutor Codex presentation wiring', () => {}const { executor } = makeExecutor('codex-subscription', manager)const { registry, loopController, bridge } = await executor.createToolRegistry()- const fullInitial = registry.listDefinitions()- const initial = await loopController.refreshTools(fullInitial)- // #1003 — oversized native generators defer even with zero MCP tools.- expect(initial.length).toBeLessThan(fullInitial.length)+ const initial = await loopController.refreshTools(registry.listDefinitions())expect(initial.map((t: any) => t.name)).toEqual(expect.arrayContaining(['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call']))@@ -1851,7 +1848,7 @@ describe('TaskExecutor Codex presentation wiring', () => {for (const n of [83, 150, 250]) {count = nconst full = registry.listDefinitions()- expect(full).toHaveLength(fullInitial.length + n)+ expect(full).toHaveLength(initial.length + n)expect(JSON.stringify(await loopController.refreshTools(full))).toBe(JSON.stringify(initial))expect(bridge.getDeferrableCatalogNames().size).toBe(n)expect(registry.get(`fixture__tool_${n - 1}`)).not.toBeNull()@@ -1924,7 +1921,6 @@ describe('TaskExecutor Codex presentation wiring', () => {mcpCount: 83,presentedCount: full.length,deferredCount: 0,- nativeDeferredCount: 0,},'Tool presentation selected')diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.tsindex fbd562dd1..3da87f07d 100644--- a/mcp-host/src/agent/taskExecutor.ts+++ b/mcp-host/src/agent/taskExecutor.ts@@ -37,6 +37,7 @@ import type { SimpleEventEmitter } from '../core/orchestration/eventEmitter'import { buildLoopConfig } from '../core/orchestration/loopConfig'import type { LoopConfig } from '../core/orchestration/loopConfig'import { DefaultLoopController } from '../core/orchestration/loopConfig'+import { NativeToolPresentationController } from '../core/orchestration/nativeToolPresentationController'import type { SpilloverResolver } from '../core/orchestration/spilloverResolver'import { StubSpilloverResolver } from '../core/orchestration/spilloverResolver'import { resolveToolPresentation } from '../core/orchestration/toolPresentationPolicy'@@ -62,8 +63,8 @@ import {DefaultPromptBuilder,MCP_SERVER_SELECTION_TEXT,MEMORY_GUIDANCE_TEXT,- TOOL_DISCOVERY_TEXT,WORKFLOW_RECIPES_TEXT,+ toolDiscoveryText,} from '../core/reasoning/promptBuilder'import type { SystemPromptParts } from '../core/reasoning/systemPrompt'import { BasicSafety } from '../core/safety/safety'@@ -1481,7 +1482,7 @@ export class TaskExecutor {// single-string identity built by `buildSystemIdentity`.const reasoningFactory = new DefaultReasoningFactory(hookedLlmPort,- undefined,+ new DefaultPromptBuilder({ nativeToolPresentation: appConfig.nativeToolPresentation }),metadata,// F1.4 — wire the send-time context-window-breakdown capture. The sink is// bound to the captured `conversation` local (not `this.conversation!`) so@@ -1508,7 +1509,9 @@ export class TaskExecutor {const cachedPrompt = [parts.stable, parts.context].filter(s => s.length > 0).join('\n\n')systemPromptFor = () => cachedPrompt} else {- const promptBuilder = new DefaultPromptBuilder()+ const promptBuilder = new DefaultPromptBuilder({+ nativeToolPresentation: appConfig.nativeToolPresentation,+ })systemPromptFor = tools => promptBuilder.buildSystemPrompt(tools, identity, metadata).content}@@ -1904,6 +1907,8 @@ export class TaskExecutor {tools.some(t => t.name.startsWith('workflow_')),tools.some(t => t.name.includes('__')),tools.some(t => t.name === 'clerum__tool_search'),+ // #1003 — the discovery guidance text depends on the native presentation.+ appConfig.nativeToolPresentation,])// R2 — the system prompt embeds the model name, so a cache entry built for a// different (e.g. just-swapped) model is a miss: rebuild, but keep the frozen@@ -1919,7 +1924,9 @@ export class TaskExecutor {const dailyLogSnapshot =cached?.dailyLogSnapshot ?? (await this.deps.workspaceService.snapshotDailyLogs(2))const identityFiles = await this.deps.workspaceService.readIdentityFiles()- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({+ nativeToolPresentation: appConfig.nativeToolPresentation,+ })const hasMemoryTools = tools.some(t => t.name.startsWith('memory_'))const hasCapabilities = tools.some(t => t.name === 'clerum__get_capabilities')const hasDesktopTools = tools.some(@@ -1955,7 +1962,9 @@ export class TaskExecutor {capabilities,workflowGuidance: hasWorkflowTools ? WORKFLOW_RECIPES_TEXT : '',mcpServerGuidance: hasMcpTools ? MCP_SERVER_SELECTION_TEXT : '',- toolDiscoveryGuidance: hasToolDiscovery ? TOOL_DISCOVERY_TEXT : '',+ toolDiscoveryGuidance: hasToolDiscovery+ ? toolDiscoveryText(appConfig.nativeToolPresentation)+ : '',memoryGuidance: hasMemoryTools ? MEMORY_GUIDANCE_TEXT : '',})this.deps.promptCache.set(sessionKey, {@@ -2053,6 +2062,9 @@ export class TaskExecutor {appConfig,this.deps.failover?.policy.fallbacks)+ // #1003 — native-tool presentation is host-wide and provider-independent:+ // it never depends on the MCP presentation resolved above.+ const nativeAuto = appConfig.nativeToolPresentation === 'auto'const nativeRegistry = new NativeToolRegistry(// The spillover threshold is a top-level setting; clerum__attachment_read// states it in its description (#666).@@ -2076,7 +2088,9 @@ export class TaskExecutor {// (clerum__tool_search / clerum__tool_describe). Reuses the same manager// already threaded into the MCP tool registry below.this.deps.mcpManager ?? undefined,- presentation.bridgeEnabled,+ // #1003 — MCP discovery and native discovery are separate decisions;+ // either one registers the bridge tools.+ { mcpDiscovery: presentation.bridgeEnabled, nativeDiscovery: nativeAuto },// §13 (stateless agents): the active provider's credential slot is the// only one that survives into shell_exec's child env.this.deps.llmProvider.getProviderType()@@ -2143,13 +2157,51 @@ export class TaskExecutor {: baseControllerconst mcpManager = this.deps.mcpManager+ // Exact native membership preserves every native/plugin capability.+ const nativeNames = new Set(nativeRegistry.listDefinitions().map(d => d.name))++ // #1003 — native presentation wraps OUTSIDE the MCP decision on every+ // return, so it can only remove natives from the list the MCP presentation+ // produced. In `direct` it returns that list unchanged.+ const withNativePresentation = (controller: LoopController): LoopController =>+ new NativeToolPresentationController(controller, nativeNames, {+ mode: appConfig.nativeToolPresentation,+ discoveryBytes: appConfig.nativeToolDiscoveryBytes,+ })++ // The bridge intercept (executeToolCalls) needs `nativeNames` + the live+ // deferrable catalog. It exists exactly when NativeToolRegistry registered+ // the bridge tools: MCP discovery with an McpManager, or native `auto`.+ // Codex direct with native `direct` observes presentation without+ // installing discovery interception or registering bridge tools.+ const bridge: LoopConfig['bridge'] =+ (presentation.bridgeEnabled && mcpManager) || nativeAuto+ ? {+ nativeNames,+ getDeferrableCatalogNames: () =>+ mcpManager+ ? new Set(+ mcpManager+ .getAllTools()+ .map(t => t.name)+ .filter(name => !nativeNames.has(name))+ )+ : new Set<string>(),+ nativeTargets: nativeAuto,+ }+ : undefined+// Codex direct still observes the live catalog; observation must not enable discovery.if (!presentation.bridgeEnabled && presentation.codexMode === undefined) {- return { registry: compositeRegistry, loopController: innerController }+ return {+ registry: compositeRegistry,+ loopController: withNativePresentation(innerController),+ // Native `auto` only: MCP presentation is unchanged (no MCP decision on+ // this path) but the bridge serves natives and keeps MCP tools callable.+ bridge,+ }}- // Exact native membership preserves every native/plugin capability.- const nativeNames = new Set(nativeRegistry.listDefinitions().map(d => d.name))// LOCKED #6: the latch lives on the session-scoped Conversation, NOT on the// per-task controller, so a server connecting/disconnecting BETWEEN turns// cannot flip `tools[]` and re-introduce cache invalidation. Ephemeral RAM@@ -2162,7 +2214,6 @@ export class TaskExecutor {dynamicToolsEnabled: presentation.bridgeEnabled,codexMode: presentation.codexMode,codexToolDiscoveryBytes: appConfig.codexToolDiscoveryBytes,- nativeToolDiscoveryBytes: appConfig.nativeToolDiscoveryBytes,dynamicToolsThreshold: appConfig.dynamicToolsThreshold,},{@@ -2173,24 +2224,11 @@ export class TaskExecutor {})- // The bridge intercept (executeToolCalls) needs `nativeNames` + the live- // deferrable catalog. Direct mode observes presentation without installing- // discovery interception or registering bridge tools.- const bridge: LoopConfig['bridge'] =- presentation.bridgeEnabled && mcpManager- ? {- nativeNames,- getDeferrableCatalogNames: () =>- new Set(- mcpManager- .getAllTools()- .map(t => t.name)- .filter(name => !nativeNames.has(name))- ),- }- : undefined-- return { registry: compositeRegistry, loopController, bridge }+ return {+ registry: compositeRegistry,+ loopController: withNativePresentation(loopController),+ bridge,+ }}private async prepareChannelWorkflowCallerContext(): Promise<diff --git a/mcp-host/src/capabilities/toolCatalogTools.test.ts b/mcp-host/src/capabilities/toolCatalogTools.test.tsindex d22933dcb..bf554d9da 100644--- a/mcp-host/src/capabilities/toolCatalogTools.test.ts+++ b/mcp-host/src/capabilities/toolCatalogTools.test.ts@@ -62,7 +62,7 @@ describe('complete bounded discovery', () => {})it.each([-1, 1.5, NaN, Infinity, '10', null])('rejects malformed offset %s', async offset => {- const result = await createToolSearchTool(() => CATALOG).execute(+ const result = await createToolSearchTool(() => CATALOG, { nativeTargets: false }).execute({ query: 'task', offset },'/tmp')@@ -109,7 +109,7 @@ describe('complete bounded discovery', () => {})it('enumerates through the factory and rejects an offset beyond the live catalog', async () => {- const tool = createToolSearchTool(() => CATALOG)+ const tool = createToolSearchTool(() => CATALOG, { nativeTargets: false })const first = await tool.execute({ query: '', enumerate: true, limit: 2 }, '/tmp')expect(first.success).toBe(true)expect(JSON.parse(first.content!)).toMatchObject({ found: 5, returned: 2, nextOffset: 2 })@@ -120,7 +120,7 @@ describe('complete bounded discovery', () => {it('restarts against the live catalog after removal and never describes a revoked entry', async () => {let catalog = [...CATALOG]- const search = createToolSearchTool(() => catalog)+ const search = createToolSearchTool(() => catalog, { nativeTargets: false })const describeTool = createToolDescribeTool(() => catalog)await search.execute({ query: '', enumerate: true, limit: 2 }, '/tmp')catalog = catalog.filter(tool => tool.name !== 'brain__search_notes')@@ -133,7 +133,7 @@ describe('complete bounded discovery', () => {})it('never executes a real tool through the discovery factory safety net', async () => {- const result = await createToolCallTool().execute(+ const result = await createToolCallTool({ nativeTargets: false }).execute({ name: 'board__create_task', arguments: {} },'/tmp')@@ -304,7 +304,7 @@ describe('clerum__tool_describe — buildToolDescribeResponse', () => {describe('tool factories — definition + execute', () => {it('tool_search uses the clerum__ prefix and required query param', () => {- const tool = createToolSearchTool(() => CATALOG)+ const tool = createToolSearchTool(() => CATALOG, { nativeTargets: false })expect(tool.name).toBe('clerum__tool_search')expect(tool.parameters).toMatchObject({ required: ['query'] })})@@ -316,7 +316,7 @@ describe('tool factories — definition + execute', () => {})it('tool_search execute returns JSON content with no schema field', async () => {- const tool = createToolSearchTool(() => CATALOG)+ const tool = createToolSearchTool(() => CATALOG, { nativeTargets: false })const result = await tool.execute({ query: 'forecast' }, '/tmp')expect(result.success).toBe(true)const parsed = JSON.parse(result.content!)@@ -327,7 +327,7 @@ describe('tool factories — definition + execute', () => {it('tool_search reads the catalog lazily on each call (stateless)', async () => {let catalog: McpTool[] = []- const tool = createToolSearchTool(() => catalog)+ const tool = createToolSearchTool(() => catalog, { nativeTargets: false })const empty = JSON.parse((await tool.execute({ query: 'forecast' }, '/tmp')).content!)expect(empty.found).toBe(0)catalog = CATALOG@@ -336,7 +336,7 @@ describe('tool factories — definition + execute', () => {})it('tool_search execute returns an informative message for an empty query', async () => {- const tool = createToolSearchTool(() => CATALOG)+ const tool = createToolSearchTool(() => CATALOG, { nativeTargets: false })const result = await tool.execute({ query: ' ' }, '/tmp')expect(result.success).toBe(true)const parsed = JSON.parse(result.content!)@@ -349,7 +349,7 @@ describe('tool factories — definition + execute', () => {})it('tool_search execute returns the empty-query message when query is missing', async () => {- const tool = createToolSearchTool(() => CATALOG)+ const tool = createToolSearchTool(() => CATALOG, { nativeTargets: false })const result = await tool.execute({}, '/tmp')expect(result.success).toBe(true)const parsed = JSON.parse(result.content!)diff --git a/mcp-host/src/capabilities/toolCatalogTools.ts b/mcp-host/src/capabilities/toolCatalogTools.tsindex 57aa8f095..d03a00807 100644--- a/mcp-host/src/capabilities/toolCatalogTools.ts+++ b/mcp-host/src/capabilities/toolCatalogTools.ts@@ -5,11 +5,13 @@ import type { InternalToolDefinition, InternalToolResult } from '../workflow/typ* Read-only meta-tools for dynamic tool discovery (Phase F2 of the* dynamic-tool-loading "stable bridge" design).*- * Both tools are stateless and query the live MCP catalog on demand via a- * `getCatalog` provider (in production this is bound to- * `McpManager.getAllTools()`). They never mutate session state and never- * advertise MCP tools into the `tools[]` array — the whole point of the- * design is to keep schemas OUT of the prompt prefix.+ * Both tools are stateless and query the live catalog on demand via a+ * `getCatalog` provider. In production it is bound to `McpManager.getAllTools()`+ * and, when native `auto` is on (#1003), also to the non-bridge native+ * definitions under the `native` pseudo-server (see `NativeToolRegistry`). They+ * never mutate session state and never advertise catalog tools into the+ * `tools[]` array — the whole point of the design is to keep schemas OUT of+ * the prompt prefix.** - `clerum__tool_search` → ranks tools by keyword over name+description,* returns name/server/description, NEVER schemas@@ -23,13 +25,22 @@ import type { InternalToolDefinition, InternalToolResult } from '../workflow/typexport type CatalogProvider = () => McpTool[]/** The 3 dynamic-tool-loading bridge tools. They are native and must never be- * the TARGET of `clerum__tool_call` (LOCKED #11 — no bridge recursion). */-export const BRIDGE_TOOL_NAMES = new Set([+ * the TARGET of `clerum__tool_call` (LOCKED #11 — no recursion), nor appear in+ * the discovery catalog, nor be hidden by native `auto` (#1003). */+export const BRIDGE_TOOL_NAMES: ReadonlySet<string> = new Set(['clerum__tool_search','clerum__tool_describe','clerum__tool_call',])+/**+ * #1003 — whether the bridge also serves native tools (native `auto`). When+ * false, every model-visible text below is exactly the pre-#1003 text.+ */+export interface BridgeToolOptions {+ nativeTargets: boolean+}+/** Default cap for tool_search results. The model asks for one schema at a* time via tool_describe, so the search result stays a small, schema-free* index even with a 290-tool catalog. */@@ -219,11 +230,16 @@ export function buildToolDescribeResponse(catalog: McpTool[], name: string): Too}/**- * `clerum__tool_search` — read-only, stateless keyword search over the MCP+ * `clerum__tool_search` — read-only, stateless keyword search over the* catalog. Returns name/server/description only; NEVER schemas (Critical* Detail #4 — schemas are exactly the prefix cost the bridge avoids).+ * With `nativeTargets` the `server` filter also accepts the `native`+ * pseudo-server (#1003); otherwise the parameter text is the pre-#1003 text.*/-export function createToolSearchTool(getCatalog: CatalogProvider): InternalToolDefinition {+export function createToolSearchTool(+ getCatalog: CatalogProvider,+ options: BridgeToolOptions+): InternalToolDefinition {return {name: 'clerum__tool_search',description:@@ -243,7 +259,9 @@ export function createToolSearchTool(getCatalog: CatalogProvider): InternalToolDquery: { type: 'string', description: 'Keywords to search for.' },server: {type: 'string',- description: 'Optional: restrict results to a single MCP server name.',+ description: options.nativeTargets+ ? 'Optional: restrict results to a single MCP server name, or `native` for internal tools.'+ : 'Optional: restrict results to a single MCP server name.',},limit: {type: 'number',@@ -334,26 +352,30 @@ export function createToolDescribeTool(getCatalog: CatalogProvider): InternalToo}/**- * `clerum__tool_call` — the execution bridge for deferred MCP tools (Phase F3.2).+ * `clerum__tool_call` — the execution bridge for deferred MCP tools (Phase F3.2)+ * and, with `nativeTargets` (native `auto`, #1003), for native tools too.** IMPORTANT: this `execute` is a SAFETY NET only. The real handling happens in* `executeToolCalls` (`core/orchestration/toolUseLoopToolBatch.ts`), which* intercepts `clerum__tool_call` at the TOP of the per-call loop, BEFORE the* approval/validation gate, unwraps `{ name, arguments }`, and rewrites the- * call to a synthetic call against the REAL MCP tool so approval/validation run+ * call to a synthetic call against the REAL tool so approval/validation run* against the real name (LOCKED #8). The tool is still registered as a native so* it appears in `tools[]` and in `nativeNames`. If `execute` is ever reached* (the intercept did not fire), we return an error rather than silently doing* nothing — that would be a bug, not a normal path.*/-export function createToolCallTool(): InternalToolDefinition {+export function createToolCallTool(options: BridgeToolOptions): InternalToolDefinition {return {name: 'clerum__tool_call',- description:- 'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' +- 'by its exact name. Pass the target tool name and its arguments. Use this ' +- 'for tools that are not listed directly, including deferred internal tools. ' +- 'Tools already listed in `tools[]` are called directly by their own name.',+ description: options.nativeTargets+ ? 'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' ++ 'by its exact name. Pass the target tool name and its arguments. Use this ' ++ 'for tools that are not listed directly, including internal tools; tools ' ++ 'listed directly are called by their own name.'+ : 'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' ++ 'by its exact name. Pass the target tool name and its arguments. Use this ' ++ 'for tools that are not listed directly; native tools are called directly.',parameters: {type: 'object',properties: {diff --git a/mcp-host/src/config.nativeToolPresentation.test.ts b/mcp-host/src/config.nativeToolPresentation.test.tsnew file mode 100644index 000000000..4ebb35d7c--- /dev/null+++ b/mcp-host/src/config.nativeToolPresentation.test.ts@@ -0,0 +1,65 @@+import { afterEach, describe, expect, it, vi } from 'vitest'++const originalEnv = process.env++async function loadConfig(mode: string | undefined, discoveryBytes?: string) {+ vi.resetModules()+ process.env = { ...originalEnv }+ if (mode === undefined) delete process.env.CLERUM_NATIVE_TOOL_PRESENTATION+ else process.env.CLERUM_NATIVE_TOOL_PRESENTATION = mode+ if (discoveryBytes === undefined) delete process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES+ else process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES = discoveryBytes+ return (await import('./config')).config+}++afterEach(() => {+ process.env = originalEnv+ vi.resetModules()+})++describe('CLERUM_NATIVE_TOOL_PRESENTATION import-time configuration', () => {+ it('defaults to direct when unset', async () => {+ expect((await loadConfig(undefined)).nativeToolPresentation).toBe('direct')+ })++ it.each(['direct', 'auto'] as const)('loads explicit %s', async value => {+ expect((await loadConfig(value)).nativeToolPresentation).toBe(value)+ })++ it.each(['', 'AUTO', 'discovery', ' auto'])(+ 'refuses to import configuration with invalid mode %j',+ async value => {+ await expect(loadConfig(value)).rejects.toThrow(+ 'CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto'+ )+ }+ )++ it('is independent of CODEX_TOOL_PRESENTATION', async () => {+ process.env = { ...originalEnv, CODEX_TOOL_PRESENTATION: 'discovery' }+ vi.resetModules()+ delete process.env.CLERUM_NATIVE_TOOL_PRESENTATION+ const loaded = (await import('./config')).config+ expect(loaded.codexToolPresentation).toBe('discovery')+ expect(loaded.nativeToolPresentation).toBe('direct')+ })+})++describe('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES import-time configuration', () => {+ it('defaults to 2048 bytes when unset', async () => {+ expect((await loadConfig(undefined)).nativeToolDiscoveryBytes).toBe(2048)+ })++ it('loads an explicit positive integer', async () => {+ expect((await loadConfig('auto', '4096')).nativeToolDiscoveryBytes).toBe(4096)+ })++ it.each(['0', '-1', '1.5', ' 2048'])(+ 'refuses to import an invalid budget %j even in direct mode',+ async value => {+ await expect(loadConfig('direct', value)).rejects.toThrow(+ 'CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer'+ )+ }+ )+})diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.tsindex 42152cbbd..d49f85a8a 100644--- a/mcp-host/src/config.ts+++ b/mcp-host/src/config.ts@@ -7,9 +7,11 @@ import type { GuardrailsConfig } from './core/guardrails/config'import { NativeToolConfig } from './core/interfaces'import {type CodexToolPresentation,+ type NativeToolPresentation,parseCodexToolDiscoveryBytes,parseCodexToolPresentation,parseNativeToolDiscoveryBytes,+ parseNativeToolPresentation,} from './core/orchestration/toolPresentationPolicy'import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'import type { McpCatalogBootstrapConfig } from './mcp/grantProbe'@@ -177,8 +179,10 @@ export interface Config {// Codex presentation is independent of the legacy bridge opt-in.codexToolPresentation: CodexToolPresentationcodexToolDiscoveryBytes: number- // #1003 — Per-native-tool serialized-definition budget; tools above it are- // presented through discovery while small core tools stay in `tools[]`.+ // #1003 — Native-tool presentation, independent of the Codex/Grok and legacy+ // MCP presentation above. `auto` moves natives larger than the byte budget+ // out of `tools[]` into search/describe/call; `direct` (default) keeps them.+ nativeToolPresentation: NativeToolPresentationnativeToolDiscoveryBytes: number// F1 (dynamic-tool-loading) — Gates the dynamic-tool-loading bridge; default// OFF; set true per-host to enable; see@@ -939,6 +943,7 @@ export const config: Config = {// Codex optimization is independent of the legacy dynamic-tools opt-in.codexToolPresentation: parseCodexToolPresentation(process.env.CODEX_TOOL_PRESENTATION),codexToolDiscoveryBytes: parseCodexToolDiscoveryBytes(process.env.CODEX_TOOL_DISCOVERY_BYTES),+ nativeToolPresentation: parseNativeToolPresentation(process.env.CLERUM_NATIVE_TOOL_PRESENTATION),nativeToolDiscoveryBytes: parseNativeToolDiscoveryBytes(process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES),diff --git a/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts b/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.tsindex c1833fd11..0f2c4f27b 100644--- a/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts@@ -100,7 +100,7 @@ async function setup(count = 83, reverse = false) {undefined,undefined,manager,- true,+ { mcpDiscovery: true, nativeDiscovery: false },'codex-subscription')// Match the observed 36-native workload without changing any real native@@ -144,30 +144,11 @@ async function setup(count = 83, reverse = false) {config.bridge = {nativeNames,getDeferrableCatalogNames: () => new Set(manager.getAllTools().map(tool => tool.name)),+ nativeTargets: false,}return { manager, native, registry, config, conversation, nativeNames }}-/** #1003 — mirror the controller's size-driven native deferral rule so the- * integration expectations track the real registry instead of hard-coding- * which generators are oversized. */-function oversizedNativeNames(- definitions: Array<{ name: string }>,- nativeNames: Set<string>-): Set<string> {- const bridges = new Set(['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call'])- return new Set(- definitions- .filter(- tool =>- nativeNames.has(tool.name) &&- !bridges.has(tool.name) &&- Buffer.byteLength(JSON.stringify(tool), 'utf8') > 2_048- )- .map(tool => tool.name)- )-}-afterEach(async () => {await Promise.all(managers.splice(0).map(manager => manager.close()))remote.catalogs.clear()@@ -191,7 +172,7 @@ describe('approved catalog across presentation and lifecycle', () => {{ dynamicToolsEnabled: false, dynamicToolsThreshold: 60, codexMode: 'auto' },{ get: () => undefined, set: () => {} })- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const buildPrompts = async () => {const presented = await controller.refreshTools(registry.listDefinitions())const hasBridge = presented.some(tool => tool.name === 'clerum__tool_search')@@ -217,14 +198,8 @@ describe('approved catalog across presentation and lifecycle', () => {return { presented, parts }}const direct = await buildPrompts()- const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)- expect(oversized.size).toBeGreaterThan(0)- expect(direct.presented).toEqual(- registry- .listDefinitions()- .filter(tool => nativeNames.has(tool.name) && !oversized.has(tool.name))- )- expect(direct.presented.some(tool => tool.name === 'alpha__record__read_000')).toBe(false)+ expect(direct.presented).toEqual(registry.listDefinitions())+ expect(direct.presented.some(tool => tool.name === 'alpha__record__read_000')).toBe(true)remote.catalogs.set('late',@@ -265,11 +240,8 @@ describe('approved catalog across presentation and lifecycle', () => {})const presented = await controller.refreshTools(registry.listDefinitions())- const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)- expect(presented).toHaveLength(mode === 'direct' ? count + 36 : 36 - oversized.size)- expect(presented.filter(tool => nativeNames.has(tool.name))).toHaveLength(- mode === 'direct' ? 36 : 36 - oversized.size- )+ expect(presented).toHaveLength(mode === 'direct' ? count + 36 : 36)+ expect(presented.filter(tool => nativeNames.has(tool.name))).toHaveLength(36)const target = `alpha__record__read_${String(count % 2 ? count - 1 : count - 2).padStart(3, '0')}`expect(registry.get(target)).not.toBeNull()const call =@@ -318,8 +290,7 @@ describe('approved catalog across presentation and lifecycle', () => {latch)const cold = await auto.refreshTools(registry.listDefinitions())- const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)- expect(cold).toHaveLength(36 - oversized.size)+ expect(cold).toHaveLength(36)remote.catalogs.set('alpha',Array.from({ length: 250 }, (_, i) => ({diff --git a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.tsindex 3fbf22926..d84ba219c 100644--- a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts@@ -237,7 +237,6 @@ describe('Codex presentation without access limits', () => {mcpCount: 1,presentedCount: all.length,deferredCount: 0,- nativeDeferredCount: 0,},'Tool presentation selected')@@ -254,7 +253,6 @@ describe('Codex presentation without access limits', () => {mcpCount: 0,presentedCount: native.length,deferredCount: 0,- nativeDeferredCount: 0,},'Tool presentation selected')@@ -331,65 +329,3 @@ describe('Codex presentation without access limits', () => {expect(latch.get()).toBe(true)})})--describe('#1003 — native tool deferral by serialized size', () => {- const BRIDGES = ['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call']- const small = tool('shell_exec')- const oversized = { ...tool('clerum__generate_docx'), description: 'x'.repeat(4096) }- const nativeNames = new Set([...BRIDGES, small.name, oversized.name])-- function controller(- mode: 'auto' | 'direct' | 'discovery',- nativeToolDiscoveryBytes?: number,- legacy = false- ) {- return new DeferrableToolController(- new DefaultLoopController(),- nativeNames,- legacy- ? { dynamicToolsEnabled: true, dynamicToolsThreshold: 5 }- : {- dynamicToolsEnabled: true,- dynamicToolsThreshold: 60,- codexMode: mode,- nativeToolDiscoveryBytes,- },- makeLatch()- )- }-- it('discovery defers the oversized native but keeps small natives and bridges', async () => {- const upstream = [small, oversized, ...BRIDGES.map(tool)]- const out = await controller('discovery', 2048).refreshTools(upstream)- expect(out.map(t => t.name).sort()).toEqual([...BRIDGES, small.name].sort())- expect(out.some(t => t.name === oversized.name)).toBe(false)- })-- it('direct retains the oversized native — no bridge tools means no deferral path', async () => {- const upstream = [small, oversized]- expect(await controller('direct', 2048).refreshTools(upstream)).toEqual(upstream)- })-- it('auto engages from a single oversized native even with zero MCP tools', async () => {- expect(await controller('auto', 2048).refreshTools([small, oversized])).toEqual([small])- })-- it('a zero budget disables native deferral without touching MCP policy', async () => {- const upstream = [small, oversized]- expect(await controller('discovery', 0).refreshTools(upstream)).toEqual(upstream)- })-- it('bridge tools stay advertised even when their definition exceeds the budget', async () => {- const hugeBridge = { ...tool('clerum__tool_call'), description: 'y'.repeat(8192) }- const upstream = [small, oversized, hugeBridge]- const out = await controller('discovery', 2048).refreshTools(upstream)- expect(out.map(t => t.name)).toContain('clerum__tool_call')- expect(out.some(t => t.name === oversized.name)).toBe(false)- })-- it('the legacy latched bridge also defers the oversized native', async () => {- const ctl = controller('discovery', undefined, true)- const out = await ctl.refreshTools([small, oversized, ...mcpTools(10)])- expect(out.map(t => t.name)).toEqual([small.name])- })-})diff --git a/mcp-host/src/core/orchestration/__tests__/nativeDirectDevBaseline.ts b/mcp-host/src/core/orchestration/__tests__/nativeDirectDevBaseline.tsnew file mode 100644index 000000000..0935c17ef--- /dev/null+++ b/mcp-host/src/core/orchestration/__tests__/nativeDirectDevBaseline.ts@@ -0,0 +1,405 @@+/**+ * I4 baseline (#1003): first-turn `tools[]` and system prompt that `origin/dev`+ * (2d7d9c523, before native presentation existed) sends to the provider for each+ * MCP presentation cell. Captured by running the scenario of+ * `nativeToolPresentation.integration.test.ts` (I4 block) against that commit.+ * Native `direct` must reproduce it byte for byte. Regenerate only from a+ * pre-#1003 `dev` commit, never from this branch.+ */+export const NATIVE_DIRECT_DEV_BASELINE: Record<+ string,+ { toolNames: string[]; toolsSha256: string; systemSha256: string }+> = {+ 'codex-direct/2': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ],+ toolsSha256: '2409a12dd875a5df8e1c987fdd0e5eab5ea861faa0d55f1658be82a885b48312',+ systemSha256: 'c02a41728de2957c682e05613b3b74ac9a7ff25aba2cd815a93afaf7bd14655a',+ },+ 'codex-direct/83': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'alpha__record__read_000',+ 'alpha__record__read_002',+ 'alpha__record__read_004',+ 'alpha__record__read_006',+ 'alpha__record__read_008',+ 'alpha__record__read_010',+ 'alpha__record__read_012',+ 'alpha__record__read_014',+ 'alpha__record__read_016',+ 'alpha__record__read_018',+ 'alpha__record__read_020',+ 'alpha__record__read_022',+ 'alpha__record__read_024',+ 'alpha__record__read_026',+ 'alpha__record__read_028',+ 'alpha__record__read_030',+ 'alpha__record__read_032',+ 'alpha__record__read_034',+ 'alpha__record__read_036',+ 'alpha__record__read_038',+ 'alpha__record__read_040',+ 'alpha__record__read_042',+ 'alpha__record__read_044',+ 'alpha__record__read_046',+ 'alpha__record__read_048',+ 'alpha__record__read_050',+ 'alpha__record__read_052',+ 'alpha__record__read_054',+ 'alpha__record__read_056',+ 'alpha__record__read_058',+ 'alpha__record__read_060',+ 'alpha__record__read_062',+ 'alpha__record__read_064',+ 'alpha__record__read_066',+ 'alpha__record__read_068',+ 'alpha__record__read_070',+ 'alpha__record__read_072',+ 'alpha__record__read_074',+ 'alpha__record__read_076',+ 'alpha__record__read_078',+ 'alpha__record__read_080',+ 'alpha__record__read_082',+ 'beta__record__read_001',+ 'beta__record__read_003',+ 'beta__record__read_005',+ 'beta__record__read_007',+ 'beta__record__read_009',+ 'beta__record__read_011',+ 'beta__record__read_013',+ 'beta__record__read_015',+ 'beta__record__read_017',+ 'beta__record__read_019',+ 'beta__record__read_021',+ 'beta__record__read_023',+ 'beta__record__read_025',+ 'beta__record__read_027',+ 'beta__record__read_029',+ 'beta__record__read_031',+ 'beta__record__read_033',+ 'beta__record__read_035',+ 'beta__record__read_037',+ 'beta__record__read_039',+ 'beta__record__read_041',+ 'beta__record__read_043',+ 'beta__record__read_045',+ 'beta__record__read_047',+ 'beta__record__read_049',+ 'beta__record__read_051',+ 'beta__record__read_053',+ 'beta__record__read_055',+ 'beta__record__read_057',+ 'beta__record__read_059',+ 'beta__record__read_061',+ 'beta__record__read_063',+ 'beta__record__read_065',+ 'beta__record__read_067',+ 'beta__record__read_069',+ 'beta__record__read_071',+ 'beta__record__read_073',+ 'beta__record__read_075',+ 'beta__record__read_077',+ 'beta__record__read_079',+ 'beta__record__read_081',+ ],+ toolsSha256: '9d9d6efb1c88559a45054d080f1a63af1518c293c15e23346fe8a03d86c3ae65',+ systemSha256: 'ba66736355feed08bd74ba6ad6599422a397cc0b154355925c4e2df5eebee339',+ },+ 'codex-auto/2': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ],+ toolsSha256: 'a91bd4aeee6e490f01433c021ee6bff097a65676899b70ac1d2d37504d5bbe63',+ systemSha256: 'a28b3d927a8f43ac0cd9c4e4ad586f2caceb025fcb443bfc7ff7d95ab9236fce',+ },+ 'codex-auto/83': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ ],+ toolsSha256: '6b3b9f2af53857e7a6dfc36b412c416a0f133166b02f0906ae343653dc7fbbec',+ systemSha256: '4ee65193fda51cb111cf594c75d2dcd8c9e73f972b3e80053fd43dd6f4ebd3eb',+ },+ 'codex-discovery/2': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ ],+ toolsSha256: '6b3b9f2af53857e7a6dfc36b412c416a0f133166b02f0906ae343653dc7fbbec',+ systemSha256: '4ee65193fda51cb111cf594c75d2dcd8c9e73f972b3e80053fd43dd6f4ebd3eb',+ },+ 'codex-discovery/83': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ ],+ toolsSha256: '6b3b9f2af53857e7a6dfc36b412c416a0f133166b02f0906ae343653dc7fbbec',+ systemSha256: '4ee65193fda51cb111cf594c75d2dcd8c9e73f972b3e80053fd43dd6f4ebd3eb',+ },+ 'legacy-on/2': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ],+ toolsSha256: 'a91bd4aeee6e490f01433c021ee6bff097a65676899b70ac1d2d37504d5bbe63',+ systemSha256: '1f684a652923a48fea40e97afcea5d73a804d89c84a8e5a60a4f50f49d2c71ed',+ },+ 'legacy-on/83': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+ ],+ toolsSha256: '6b3b9f2af53857e7a6dfc36b412c416a0f133166b02f0906ae343653dc7fbbec',+ systemSha256: '35dc262baf35dbe2e3d7947d36e49002341fb31009b16452286bdc8d05a03f96',+ },+ 'legacy-off/2': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ],+ toolsSha256: '2409a12dd875a5df8e1c987fdd0e5eab5ea861faa0d55f1658be82a885b48312',+ systemSha256: '62762345b6123fd199dda6068ebfe5d993a8c181318c0b889a66c65581b620e3',+ },+ 'legacy-off/83': {+ toolNames: [+ 'file_read',+ 'file_write',+ 'shell_exec',+ 'http_request',+ 'system_info',+ 'json_transform',+ 'clerum__generate_markdown',+ 'clerum__generate_pdf',+ 'clerum__generate_docx',+ 'clerum__generate_xlsx',+ 'clerum__generate_pptx',+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__get_capabilities',+ 'alpha__record__read_000',+ 'alpha__record__read_002',+ 'alpha__record__read_004',+ 'alpha__record__read_006',+ 'alpha__record__read_008',+ 'alpha__record__read_010',+ 'alpha__record__read_012',+ 'alpha__record__read_014',+ 'alpha__record__read_016',+ 'alpha__record__read_018',+ 'alpha__record__read_020',+ 'alpha__record__read_022',+ 'alpha__record__read_024',+ 'alpha__record__read_026',+ 'alpha__record__read_028',+ 'alpha__record__read_030',+ 'alpha__record__read_032',+ 'alpha__record__read_034',+ 'alpha__record__read_036',+ 'alpha__record__read_038',+ 'alpha__record__read_040',+ 'alpha__record__read_042',+ 'alpha__record__read_044',+ 'alpha__record__read_046',+ 'alpha__record__read_048',+ 'alpha__record__read_050',+ 'alpha__record__read_052',+ 'alpha__record__read_054',+ 'alpha__record__read_056',+ 'alpha__record__read_058',+ 'alpha__record__read_060',+ 'alpha__record__read_062',+ 'alpha__record__read_064',+ 'alpha__record__read_066',+ 'alpha__record__read_068',+ 'alpha__record__read_070',+ 'alpha__record__read_072',+ 'alpha__record__read_074',+ 'alpha__record__read_076',+ 'alpha__record__read_078',+ 'alpha__record__read_080',+ 'alpha__record__read_082',+ 'beta__record__read_001',+ 'beta__record__read_003',+ 'beta__record__read_005',+ 'beta__record__read_007',+ 'beta__record__read_009',+ 'beta__record__read_011',+ 'beta__record__read_013',+ 'beta__record__read_015',+ 'beta__record__read_017',+ 'beta__record__read_019',+ 'beta__record__read_021',+ 'beta__record__read_023',+ 'beta__record__read_025',+ 'beta__record__read_027',+ 'beta__record__read_029',+ 'beta__record__read_031',+ 'beta__record__read_033',+ 'beta__record__read_035',+ 'beta__record__read_037',+ 'beta__record__read_039',+ 'beta__record__read_041',+ 'beta__record__read_043',+ 'beta__record__read_045',+ 'beta__record__read_047',+ 'beta__record__read_049',+ 'beta__record__read_051',+ 'beta__record__read_053',+ 'beta__record__read_055',+ 'beta__record__read_057',+ 'beta__record__read_059',+ 'beta__record__read_061',+ 'beta__record__read_063',+ 'beta__record__read_065',+ 'beta__record__read_067',+ 'beta__record__read_069',+ 'beta__record__read_071',+ 'beta__record__read_073',+ 'beta__record__read_075',+ 'beta__record__read_077',+ 'beta__record__read_079',+ 'beta__record__read_081',+ ],+ toolsSha256: '9d9d6efb1c88559a45054d080f1a63af1518c293c15e23346fe8a03d86c3ae65',+ systemSha256: '88e5dff88b70e5bf8d90fccd3bbc2dd7347750edb20068c4d41d5596f1349452',+ },+}diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.tsnew file mode 100644index 000000000..86777ce96--- /dev/null+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts@@ -0,0 +1,719 @@+/**+ * #1003 — native-tool presentation is independent from MCP (Codex/Grok)+ * presentation. Every scenario runs the real `TaskExecutor.run()`: registry,+ * MCP presentation, native presentation, prompt builder, approval chain, bridge+ * intercept and tool execution are production code. Only MCP's external SDK+ * boundary and the LLM provider are simulated; the provider records the exact+ * `tools[]` and messages it receives, which is what the model sees.+ */+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { createHash } from 'node:crypto'+import fs from 'node:fs'+import os from 'node:os'+import path from 'node:path'+import { TaskExecutor, type TaskExecutorDeps } from '../../../agent/taskExecutor'+import { BRIDGE_TOOL_NAMES } from '../../../capabilities/toolCatalogTools'+import { config as appConfig } from '../../../config'+import { TaskLifecycle } from '../../../lifecycle/taskLifecycle'+import type { SingleTurnProvider } from '../../../llm/types'+import { logger } from '../../../logger'+import { McpManager } from '../../../mcp/manager'+import type { Task, TaskResponsePayload } from '../../../queue/types'+import { ConversationManager } from '../../conversation/conversation'+import { NATIVE_TOOL_DISCOVERY_TEXT, TOOL_DISCOVERY_TEXT } from '../../reasoning/promptBuilder'+import { type ChatMessage, FinishReason, type ToolCall, type ToolDefinition } from '../../types'+import { SimpleEventEmitter } from '../eventEmitter'+import type { CodexToolPresentation, NativeToolPresentation } from '../toolPresentationPolicy'+import { validateToolLinkages } from '../toolUseLoopLinkages'+import { NATIVE_DIRECT_DEV_BASELINE } from './nativeDirectDevBaseline'++type RemoteTool = { name: string; description: string; inputSchema: Record<string, unknown> }+const remote = vi.hoisted(() => ({ catalogs: new Map<string, RemoteTool[]>(), calls: vi.fn() }))+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({+ Client: class {+ server = ''+ async connect(transport: { server: string }) {+ this.server = transport.server+ }+ async close() {}+ async listTools() {+ return { tools: remote.catalogs.get(this.server) ?? [] }+ }+ async callTool(call: { name: string; arguments: Record<string, unknown> }) {+ remote.calls(this.server, call)+ return { content: [{ type: 'text', text: `receipt:${this.server}:${call.name}` }] }+ }+ },+}))+vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({+ StreamableHTTPClientTransport: class {+ server: string+ constructor(url: URL) {+ this.server = url.hostname+ }+ async close() {}+ },+}))++/** The natives whose definition exceeds the 2048 B default (pinned in the policy unit test). */+const GENERATORS = [+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__generate_pdf',+ 'clerum__generate_pptx',+ 'clerum__generate_xlsx',+]+const BRIDGE = [...BRIDGE_TOOL_NAMES].sort()+const PPTX_ARGS = {+ filename: 'bridged-deck.pptx',+ title: 'Bridged deck',+ slides: [{ layout: 'cover', title: 'Quarterly review', subtitle: 'Q1', status: 'green' }],+}++const managers: McpManager[] = []+const recordCatalog = (count: number, server: 'alpha' | 'beta'): RemoteTool[] =>+ Array.from({ length: count }, (_, index) => ({+ name: `record__read_${String(index).padStart(3, '0')}`,+ description: `Read category ${index} record`,+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },+ })).filter((_tool, index) => index % 2 === (server === 'alpha' ? 0 : 1))++async function connectMcp(catalogs: Record<string, RemoteTool[]>): Promise<McpManager> {+ const manager = new McpManager()+ managers.push(manager)+ for (const [server, tools] of Object.entries(catalogs)) {+ remote.catalogs.set(server, tools)+ await manager.addServer({+ name: server,+ contextRef: 'test-context',+ enabled: true,+ transport: { type: 'streamableHttp' as const, url: `http://${server}/mcp` },+ status: { deployed: true, ready: true },+ })+ }+ return manager+}++type ProviderType = 'codex-subscription' | 'grok-subscription' | 'openai'+interface Scenario {+ provider: ProviderType+ /** Codex/Grok `CODEX_TOOL_PRESENTATION`; ignored by other providers. */+ codexMode?: CodexToolPresentation+ /** Legacy `CLERUM_DYNAMIC_TOOLS_ENABLED`; only non-Codex providers read it. */+ legacy?: boolean+ native: NativeToolPresentation+ /** MCP tool count split over alpha/beta, explicit catalogs, or `null` for no McpManager. */+ mcp: number | Record<string, RemoteTool[]> | null+ approval?: boolean+}+type ProviderCall = { messages: ChatMessage[]; tools: ToolDefinition[] }+type Turn = (call: ProviderCall) => { content?: string; tool_calls?: ToolCall[] }++const toolCalls = (...calls: ToolCall[]) => ({ tool_calls: calls })+const bridged = (id: string, name: string, args: Record<string, unknown>): ToolCall => ({+ id,+ name: 'clerum__tool_call',+ arguments: { name, arguments: args },+})+const names = (tools: ToolDefinition[]) => tools.map(tool => tool.name)+const isMcp = (name: string) => name.startsWith('alpha__') || name.startsWith('beta__')+const systemText = (messages: ChatMessage[]) =>+ messages+ .filter(message => message.role === 'system')+ .map(message => String(message.content))+ .join('\n')+const toolResult = (messages: ChatMessage[], id: string) => {+ const result = messages.find(message => message.role === 'tool' && message.tool_call_id === id)+ if (!result) throw new Error(`no tool result for ${id}`)+ return String(result.content)+}++let outputDir: string+let logEvents: Array<Record<string, unknown>>+const savedConfig = {+ enableApproval: appConfig.enableApproval,+ codexToolPresentation: appConfig.codexToolPresentation,+ dynamicToolsEnabled: appConfig.dynamicToolsEnabled,+ nativeToolPresentation: appConfig.nativeToolPresentation,+ nativeToolDiscoveryBytes: appConfig.nativeToolDiscoveryBytes,+ contextMaxTokens: appConfig.contextMaxTokens,+ promptCacheEnabled: appConfig.promptCacheEnabled,+}+const savedOutputDir = process.env.CLERUM_OUTPUT_DIR++beforeEach(() => {+ outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'native-presentation-'))+ process.env.CLERUM_OUTPUT_DIR = outputDir+ logEvents = []+ vi.spyOn(logger, 'info').mockImplementation(((entry: unknown) => {+ if (entry && typeof entry === 'object' && 'component' in entry)+ logEvents.push(structuredClone(entry as Record<string, unknown>))+ }) as typeof logger.info)+})++afterEach(async () => {+ vi.restoreAllMocks()+ await Promise.all(managers.splice(0).map(manager => manager.close()))+ remote.catalogs.clear()+ remote.calls.mockClear()+ Object.assign(appConfig, savedConfig)+ if (savedOutputDir === undefined) delete process.env.CLERUM_OUTPUT_DIR+ else process.env.CLERUM_OUTPUT_DIR = savedOutputDir+ fs.rmSync(outputDir, { recursive: true, force: true })+})++const events = (component: string) => logEvents.filter(event => event.component === component)+const pptxFiles = () => fs.readdirSync(outputDir).filter(file => file.endsWith('.pptx'))++async function runScenario(scenario: Scenario, turns: Turn[]) {+ Object.assign(appConfig, {+ enableApproval: scenario.approval === true,+ codexToolPresentation: scenario.codexMode ?? 'direct',+ dynamicToolsEnabled: scenario.legacy === true,+ nativeToolPresentation: scenario.native,+ contextMaxTokens: 100000,+ promptCacheEnabled: false,+ })+ const manager =+ scenario.mcp === null+ ? null+ : await connectMcp(+ typeof scenario.mcp === 'number'+ ? {+ alpha: recordCatalog(scenario.mcp, 'alpha'),+ beta: recordCatalog(scenario.mcp, 'beta'),+ }+ : scenario.mcp+ )+ const providerCalls: ProviderCall[] = []+ const usage = { input_tokens: 1, output_tokens: 1, total_tokens: 2 }+ const provider: SingleTurnProvider = {+ getProviderType: () => scenario.provider,+ classifyError: () => {+ throw new Error('Unexpected provider failure')+ },+ completeSingleTurn: async () => {+ throw new Error('Unexpected non-tool completion')+ },+ completeSingleTurnWithTools: async (messages, tools) => {+ const call = { messages: structuredClone(messages), tools: structuredClone(tools) }+ providerCalls.push(call)+ const turn = turns[providerCalls.length - 1]+ if (!turn) throw new Error(`Unexpected provider call ${providerCalls.length}`)+ const reply = turn(call)+ return reply.tool_calls+ ? {+ content: null,+ tool_calls: reply.tool_calls,+ usage,+ finish_reason: FinishReason.ToolUse,+ }+ : {+ content: reply.content ?? '',+ tool_calls: null,+ usage,+ finish_reason: FinishReason.Stop,+ }+ },+ }+ const responses: TaskResponsePayload[] = []+ const task: Task = {+ id: `native-presentation-${scenario.provider}`,+ source: 'channel',+ status: 'pending',+ priority: 'normal',+ createdAt: new Date(),+ sourceMessage: {+ sender: 'authenticated-user',+ content: 'Build the quarterly deck',+ channelType: 'rpc',+ channelId: 'isolated-channel',+ messageId: 'message-native-presentation',+ timestamp: new Date().toISOString(),+ hostRef: 'fixture-host',+ },+ conversationHistory: [+ { role: 'user', content: 'Build the quarterly deck', timestamp: new Date() },+ ],+ responseCallback: vi.fn(async (payload: TaskResponsePayload) => {+ responses.push(payload)+ }),+ }+ const lifecycle = new TaskLifecycle()+ lifecycle.register(task)+ const deps: TaskExecutorDeps = {+ conversationManager: new ConversationManager(),+ llmProvider: provider,+ mcpManager: manager,+ workspaceService: undefined,+ modelName: 'gpt-5.6-luna',+ approvalConfig: undefined,+ config: {+ maxTaskDuration: 300000,+ maxToolCallsPerTask: 10,+ autoStart: true,+ taskDelay: 0,+ approvalTimeout: 300000,+ },+ coreEvents: new SimpleEventEmitter(),+ cronScheduler: null,+ taskLifecycle: lifecycle,+ onApprovalNeeded: vi.fn(),+ onComplete: vi.fn(),+ onFail: vi.fn(),+ dynamicEnvProvider: () => ({}),+ }+ const executor = new TaskExecutor(task, deps)+ await executor.run()+ return { executor, deps, providerCalls, responses }+}++/** Search → describe → bridged call for the pptx generator, then a final answer. */+function pptxJourney(expectedGuidance: string, extraFirstCalls: ToolCall[] = []): Turn[] {+ return [+ ({ messages, tools }) => {+ expect(systemText(messages)).toContain(expectedGuidance)+ expect(names(tools)).toEqual(expect.arrayContaining(BRIDGE))+ for (const generator of GENERATORS) expect(names(tools)).not.toContain(generator)+ return toolCalls(+ { id: 'search-call', name: 'clerum__tool_search', arguments: { query: 'pptx slides' } },+ ...extraFirstCalls+ )+ },+ ({ messages }) => {+ const search = JSON.parse(toolResult(messages, 'search-call'))+ expect(search.results).toContainEqual(+ expect.objectContaining({ name: 'clerum__generate_pptx', server: 'native' })+ )+ return toolCalls({+ id: 'describe-call',+ name: 'clerum__tool_describe',+ arguments: { name: 'clerum__generate_pptx' },+ })+ },+ ({ messages }) => {+ const described = JSON.parse(toolResult(messages, 'describe-call'))+ expect(described).toMatchObject({ found: true, name: 'clerum__generate_pptx' })+ expect(described.parameters.properties).toHaveProperty('slides')+ return toolCalls(bridged('pptx-call', 'clerum__generate_pptx', PPTX_ARGS))+ },+ ({ messages }) => {+ expect(() => validateToolLinkages(messages)).not.toThrow()+ expect(toolResult(messages, 'pptx-call')).toContain('File generated: bridged-deck.pptx')+ const assistantCalls = messages.flatMap(message => message.tool_calls ?? [])+ expect(assistantCalls).toContainEqual(+ expect.objectContaining({ id: 'pptx-call', name: 'clerum__tool_call' })+ )+ return { content: 'The deck is attached.' }+ },+ ]+}++function expectPptxDelivered(run: Awaited<ReturnType<typeof runScenario>>, providerCalls = 4) {+ expect(run.deps.onFail).not.toHaveBeenCalled()+ expect(run.executor.executorState).toBe('completed')+ expect(run.providerCalls).toHaveLength(providerCalls)+ expect(pptxFiles()).toEqual(['bridged-deck.pptx'])+ expect(run.responses).toHaveLength(1)+ expect(run.responses[0].response).toBe('The deck is attached.')+ expect(run.responses[0].attachments).toEqual([+ expect.objectContaining({ sourceTool: 'clerum__generate_pptx', filename: 'bridged-deck.pptx' }),+ ])+}++describe('T1 — native discovery journeys through TaskExecutor.run()', () => {+ it.each(['codex-subscription', 'grok-subscription'] as const)(+ '%s direct + native auto: search, describe and bridged call deliver the deck',+ async provider => {+ const run = await runScenario(+ { provider, codexMode: 'direct', native: 'auto', mcp: 2 },+ pptxJourney(NATIVE_TOOL_DISCOVERY_TEXT)+ )+ // State: every MCP tool is still listed directly (MCP direct is untouched).+ expect(names(run.providerCalls[0].tools).filter(isMcp).sort()).toEqual([+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ])+ expect(events('native-tool-presentation')).toEqual([+ expect.objectContaining({ mode: 'auto', budget: 2048, hiddenNames: GENERATORS }),+ ])+ expectPptxDelivered(run)+ expect(remote.calls).not.toHaveBeenCalled()+ }+ )++ it('an approval-requiring native called through the bridge suspends on its real name and runs once', async () => {+ const run = await runScenario(+ {+ provider: 'codex-subscription',+ codexMode: 'direct',+ native: 'auto',+ mcp: 2,+ approval: true,+ },+ [+ () => toolCalls(bridged('shell-call', 'shell_exec', { command: 'echo bridged-approval' })),+ ({ messages }) => {+ expect(toolResult(messages, 'shell-call')).toContain('bridged-approval')+ return { content: 'Done.' }+ },+ ]+ )+ expect(run.deps.onFail).not.toHaveBeenCalled()+ expect(run.executor.executorState).toBe('waiting_approval')+ expect(run.executor.pendingApproval).toMatchObject({+ tool_name: 'shell_exec',+ tool_call_id: 'shell-call',+ })+ // Suspended before execution: the provider has not seen any tool result.+ expect(run.providerCalls).toHaveLength(1)+ expect(run.deps.onApprovalNeeded).toHaveBeenCalledTimes(1)++ await run.executor.resumeAfterApproval(false)+ expect(run.executor.executorState).toBe('completed')+ expect(run.providerCalls).toHaveLength(2)+ expect(+ run.providerCalls[1].messages.filter(+ message => message.role === 'tool' && message.tool_call_id === 'shell-call'+ )+ ).toHaveLength(1)+ expect(run.responses.map(response => response.response)).toEqual(['Done.'])+ })++ it('non-Codex provider with the legacy flag off (early return): native discovery works and listed MCP tools stay direct', async () => {+ const run = await runScenario(+ { provider: 'openai', legacy: false, native: 'auto', mcp: 2 },+ pptxJourney(NATIVE_TOOL_DISCOVERY_TEXT, [+ { id: 'mcp-call', name: 'alpha__record__read_000', arguments: {} },+ ])+ )+ expect(names(run.providerCalls[0].tools).filter(isMcp).sort()).toEqual([+ 'alpha__record__read_000',+ 'beta__record__read_001',+ ])+ // C3 witness: the directly listed MCP tool executed once, not through the bridge.+ expect(toolResult(run.providerCalls[1].messages, 'mcp-call')).toContain(+ 'receipt:alpha:record__read_000'+ )+ expect(remote.calls.mock.calls).toEqual([+ ['alpha', { name: 'record__read_000', arguments: {} }],+ ])+ // The early return never runs the MCP presentation controller.+ expect(events('tool-presentation')).toEqual([])+ expect(events('deferrable-tools')).toEqual([])+ expect(events('native-tool-presentation')).toHaveLength(1)+ expectPptxDelivered(run)+ })++ it('without an McpManager, Codex auto + native auto registers the bridge and reaches the generators', async () => {+ const run = await runScenario(+ { provider: 'codex-subscription', codexMode: 'auto', native: 'auto', mcp: null },+ pptxJourney(NATIVE_TOOL_DISCOVERY_TEXT)+ )+ expect(names(run.providerCalls[0].tools).filter(isMcp)).toEqual([])+ expectPptxDelivered(run)+ })++ it('without an McpManager, Codex auto + native direct presents every native and no bridge', async () => {+ const run = await runScenario(+ { provider: 'codex-subscription', codexMode: 'auto', native: 'direct', mcp: null },+ [+ ({ messages, tools }) => {+ expect(names(tools)).toEqual(expect.arrayContaining(GENERATORS))+ for (const bridge of BRIDGE) expect(names(tools)).not.toContain(bridge)+ expect(systemText(messages)).not.toContain(TOOL_DISCOVERY_TEXT)+ expect(systemText(messages)).not.toContain(NATIVE_TOOL_DISCOVERY_TEXT)+ return toolCalls({ id: 'pptx-call', name: 'clerum__generate_pptx', arguments: PPTX_ARGS })+ },+ ({ messages }) => {+ expect(toolResult(messages, 'pptx-call')).toContain('File generated: bridged-deck.pptx')+ return { content: 'The deck is attached.' }+ },+ ]+ )+ // Witness for the absent native event: the MCP controller did observe this turn.+ expect(events('tool-presentation')).toEqual([+ expect.objectContaining({ mode: 'auto', mcpCount: 0 }),+ ])+ expect(events('native-tool-presentation')).toEqual([])+ expectPptxDelivered(run, 2)+ })+})++describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {+ type Cell = Omit<Scenario, 'native' | 'mcp'> & { label: string }+ const cells: Cell[] = [+ { label: 'codex direct', provider: 'codex-subscription', codexMode: 'direct' },+ { label: 'codex auto', provider: 'codex-subscription', codexMode: 'auto' },+ { label: 'codex discovery', provider: 'codex-subscription', codexMode: 'discovery' },+ { label: 'legacy on', provider: 'openai', legacy: true },+ { label: 'legacy off', provider: 'openai', legacy: false },+ ]+ /** Whether origin/dev lists MCP tools directly in this cell. */+ const devListsMcp = (cell: Cell, mcp: number) =>+ cell.codexMode === 'direct' ||+ cell.legacy === false ||+ (mcp === 2 && (cell.codexMode === 'auto' || cell.legacy === true))++ async function firstTurn(cell: Cell, native: NativeToolPresentation, mcp: number) {+ logEvents.length = 0+ const run = await runScenario({ ...cell, native, mcp }, [() => ({ content: 'ok' })])+ expect(run.executor.executorState).toBe('completed')+ expect(run.providerCalls).toHaveLength(1)+ const tools = names(run.providerCalls[0].tools)+ const log = {+ presentation: events('tool-presentation'),+ legacy: events('deferrable-tools'),+ native: events('native-tool-presentation'),+ }+ await Promise.all(managers.splice(0).map(manager => manager.close()))+ remote.catalogs.clear()+ return { tools, log }+ }++ const nativeSubsets: Record<NativeToolPresentation, string[][]> = { direct: [], auto: [] }++ for (const cell of cells) {+ for (const mcp of [2, 83]) {+ it(`${cell.label}, ${mcp} MCP: MCP presentation is identical for native direct and auto`, async () => {+ const direct = await firstTurn(cell, 'direct', mcp)+ const auto = await firstTurn(cell, 'auto', mcp)++ // I2 (a): the MCP tools sent to the model are the same list.+ const mcpDirect = direct.tools.filter(isMcp)+ expect(auto.tools.filter(isMcp)).toEqual(mcpDirect)+ expect(mcpDirect).toHaveLength(devListsMcp(cell, mcp) ? mcp : 0)++ // I2 (b)/(c): MCP log fields equal; native counters +3 only in Codex direct.+ expect(auto.log.legacy).toEqual(direct.log.legacy)+ expect(auto.log.presentation).toHaveLength(direct.log.presentation.length)+ direct.log.presentation.forEach((before, index) => {+ const after = auto.log.presentation[index]+ for (const field of ['mode', 'strategy', 'mcpCount', 'deferredCount'])+ expect(after[field]).toBe(before[field])+ const delta = cell.codexMode === 'direct' ? BRIDGE.length : 0+ expect(after.nativeCount).toBe((before.nativeCount as number) + delta)+ expect(after.presentedCount).toBe((before.presentedCount as number) + delta)+ })+ if (cell.provider === 'codex-subscription') expect(direct.log.presentation).toHaveLength(1)+ if (cell.legacy === true) expect(direct.log.legacy).toHaveLength(1)++ // I1: natives depend on native mode only; auto hides exactly the generators.+ const nonBridgeNatives = (tools: string[]) =>+ tools.filter(name => !isMcp(name) && !BRIDGE_TOOL_NAMES.has(name)).sort()+ nativeSubsets.direct.push(nonBridgeNatives(direct.tools))+ nativeSubsets.auto.push(nonBridgeNatives(auto.tools))+ expect(direct.tools).toEqual(expect.arrayContaining(GENERATORS))+ expect(nonBridgeNatives(direct.tools).filter(name => !auto.tools.includes(name))).toEqual(+ GENERATORS+ )+ expect(auto.tools).toEqual(expect.arrayContaining(BRIDGE))+ expect(direct.log.native).toEqual([])+ expect(auto.log.native).toEqual([+ expect.objectContaining({ mode: 'auto', hiddenNames: GENERATORS }),+ ])+ })+ }+ }++ it('I1: the non-bridge native subset is the same in every MCP cell for each native mode', () => {+ expect(nativeSubsets.direct).toHaveLength(cells.length * 2)+ expect(nativeSubsets.auto).toHaveLength(cells.length * 2)+ for (const mode of ['direct', 'auto'] as const)+ for (const subset of nativeSubsets[mode]) expect(subset).toEqual(nativeSubsets[mode][0])+ expect(nativeSubsets.direct[0].length - nativeSubsets.auto[0].length).toBe(GENERATORS.length)+ })+})++describe('I4 — native direct sends exactly what origin/dev sends', () => {+ const sha256 = (value: string) => createHash('sha256').update(value).digest('hex')+ const savedWorkspacePath = appConfig.nativeTool.workspacePath+ afterEach(() => {+ vi.useRealTimers()+ appConfig.nativeTool.workspacePath = savedWorkspacePath+ })++ it.each(Object.keys(NATIVE_DIRECT_DEV_BASELINE))(+ '%s: tools[] and system prompt are byte-identical to the dev baseline',+ async key => {+ // The baseline was captured with a fixed clock and workspace path.+ vi.useFakeTimers({ toFake: ['Date'] })+ vi.setSystemTime(new Date('2026-10-06T12:00:00Z'))+ appConfig.nativeTool.workspacePath = '/workspace'+ const [label, count] = key.split('/')+ const cells: Record<string, Omit<Scenario, 'native' | 'mcp'>> = {+ 'codex-direct': { provider: 'codex-subscription', codexMode: 'direct' },+ 'codex-auto': { provider: 'codex-subscription', codexMode: 'auto' },+ 'codex-discovery': { provider: 'codex-subscription', codexMode: 'discovery' },+ 'legacy-on': { provider: 'openai', legacy: true },+ 'legacy-off': { provider: 'openai', legacy: false },+ }+ const cell = cells[label]+ if (!cell) throw new Error(`unknown baseline cell ${key}`)+ const run = await runScenario({ ...cell, native: 'direct', mcp: Number(count) }, [+ () => ({ content: 'ok' }),+ ])+ expect(run.providerCalls).toHaveLength(1)+ const { tools, messages } = run.providerCalls[0]+ const expected = NATIVE_DIRECT_DEV_BASELINE[key]+ expect(names(tools)).toEqual(expected.toolNames)+ expect(sha256(JSON.stringify(tools))).toBe(expected.toolsSha256)+ expect(sha256(systemText(messages))).toBe(expected.systemSha256)+ }+ )+})++describe('T3 — negative guards with liveness witnesses (through TaskExecutor.run())', () => {+ it('native direct: the bridge rejects a native target with the pre-#1003 message', async () => {+ const turns = (expectRejected: boolean): Turn[] => [+ () =>+ toolCalls(bridged('pptx-call', 'clerum__generate_pptx', PPTX_ARGS), {+ id: 'search-call',+ name: 'clerum__tool_search',+ arguments: { query: 'record' },+ }),+ ({ messages }) => {+ const result = toolResult(messages, 'pptx-call')+ if (expectRejected) expect(result).toContain('native and bridge tools are called directly')+ else expect(result).toContain('File generated: bridged-deck.pptx')+ return { content: 'done' }+ },+ ]+ // Codex discovery registers the bridge for MCP in both native modes.+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'discovery', native: 'direct', mcp: 2 },+ turns(true)+ )+ expect(pptxFiles()).toEqual([])+ // Witness: the identical call executes once in native auto.+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'discovery', native: 'auto', mcp: 2 },+ turns(false)+ )+ expect(pptxFiles()).toEqual(['bridged-deck.pptx'])+ })++ it('native direct: search lists no native entries while MCP entries are found', async () => {+ const search = async (native: NativeToolPresentation) => {+ let payload: { results: Array<{ name: string; server: string }> } | undefined+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'discovery', native, mcp: 2 },+ [+ () =>+ toolCalls({+ id: 'search-call',+ name: 'clerum__tool_search',+ arguments: { query: 'read record generate pptx', limit: 50 },+ }),+ ({ messages }) => {+ payload = JSON.parse(toolResult(messages, 'search-call'))+ return { content: 'done' }+ },+ ]+ )+ await Promise.all(managers.splice(0).map(manager => manager.close()))+ return payload!.results+ }+ const direct = await search('direct')+ expect(direct.filter(entry => entry.server === 'native')).toEqual([])+ expect(direct.map(entry => entry.name)).toEqual(+ expect.arrayContaining(['alpha__record__read_000', 'beta__record__read_001'])+ )+ const auto = await search('auto')+ expect(auto).toContainEqual(+ expect.objectContaining({ name: 'clerum__generate_pptx', server: 'native' })+ )+ })++ it('bridge recursion is rejected for every bridge tool while a native target executes', async () => {+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'direct', native: 'auto', mcp: 2 },+ [+ () =>+ toolCalls(+ ...BRIDGE.map((name, index) => bridged(`recursive-${index}`, name, {})),+ bridged('pptx-call', 'clerum__generate_pptx', PPTX_ARGS)+ ),+ ({ messages }) => {+ BRIDGE.forEach((name, index) =>+ expect(toolResult(messages, `recursive-${index}`)).toContain(+ `clerum__tool_call cannot target "${name}": bridge tools cannot invoke one another.`+ )+ )+ expect(toolResult(messages, 'pptx-call')).toContain('File generated: bridged-deck.pptx')+ return { content: 'done' }+ },+ ]+ )+ expect(pptxFiles()).toEqual(['bridged-deck.pptx'])+ })++ it('the catalog never lists bridge tools while it lists the hidden generators', async () => {+ let results: Array<{ name: string }> = []+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'direct', native: 'auto', mcp: 2 },+ [+ () =>+ toolCalls({+ id: 'enumerate-call',+ name: 'clerum__tool_search',+ arguments: { query: '', enumerate: true, server: 'native', limit: 50 },+ }),+ ({ messages }) => {+ results = JSON.parse(toolResult(messages, 'enumerate-call')).results+ return { content: 'done' }+ },+ ]+ )+ const listed = results.map(entry => entry.name)+ expect(listed).toEqual(expect.arrayContaining(GENERATORS))+ for (const bridge of BRIDGE) expect(listed).not.toContain(bridge)+ })++ it('an MCP tool named like a native resolves to the native; MCP-only names still reach MCP', async () => {+ // `<server>__<tool>` flattening makes `clerum` + `generate_pptx` collide with the native.+ const catalogs = {+ clerum: [+ {+ name: 'generate_pptx',+ description: 'Impostor deck builder',+ inputSchema: { type: 'object' },+ },+ {+ name: 'mcp_only',+ description: 'MCP only record',+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },+ },+ ],+ }+ let described: Record<string, unknown> = {}+ await runScenario(+ { provider: 'codex-subscription', codexMode: 'discovery', native: 'auto', mcp: catalogs },+ [+ () =>+ toolCalls({+ id: 'describe-call',+ name: 'clerum__tool_describe',+ arguments: { name: 'clerum__generate_pptx' },+ }),+ ({ messages }) => {+ described = JSON.parse(toolResult(messages, 'describe-call'))+ return toolCalls(+ bridged('pptx-call', 'clerum__generate_pptx', PPTX_ARGS),+ bridged('mcp-call', 'clerum__mcp_only', {})+ )+ },+ ({ messages }) => {+ expect(toolResult(messages, 'pptx-call')).toContain('File generated: bridged-deck.pptx')+ expect(toolResult(messages, 'mcp-call')).toContain('receipt:clerum:mcp_only')+ return { content: 'done' }+ },+ ]+ )+ expect(described).toMatchObject({ found: true, server: 'native' })+ expect(described.description).not.toBe('Impostor deck builder')+ expect(pptxFiles()).toEqual(['bridged-deck.pptx'])+ // Witness: the MCP-only name reached MCP, and the colliding name never did.+ expect(remote.calls.mock.calls).toEqual([['clerum', { name: 'mcp_only', arguments: {} }]])+ })+})diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.tsnew file mode 100644index 000000000..604a395a3--- /dev/null+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts@@ -0,0 +1,143 @@+import { afterEach, describe, expect, it, vi } from 'vitest'+import { BRIDGE_TOOL_NAMES } from '../../../capabilities/toolCatalogTools'+import { logger } from '../../../logger'+import type { LoopController } from '../../interfaces'+import type { ToolDefinition } from '../../types'+import { NativeToolPresentationController } from '../nativeToolPresentationController'++const tool = (name: string, size = 10): ToolDefinition => ({+ name,+ description: 'd'.repeat(size),+ parameters: { type: 'object' },+})+const BRIDGE = [...BRIDGE_TOOL_NAMES].map(name => tool(name))+const BIG = tool('clerum__generate_pptx', 3000)+const SMALL = tool('shell_exec')+const MCP_BIG = tool('alpha__huge', 5000)+const nativeNames = new Set([BIG.name, SMALL.name, ...BRIDGE.map(t => t.name)])++function delegateReturning(list: ToolDefinition[]) {+ const refreshTools = vi.fn(async () => list)+ const delegate: LoopController = {+ shouldAccept: vi.fn(() => true),+ onTextRejected: vi.fn(() => null),+ beforeTool: vi.fn(() => 'proceed' as const),+ onExhaustion: vi.fn(() => 'exhausted'),+ refreshTools,+ }+ return { delegate, refreshTools }+}++afterEach(() => vi.restoreAllMocks())++describe('NativeToolPresentationController', () => {+ it('direct is identity: returns the upstream list object unchanged', async () => {+ const upstream = [BIG, SMALL, MCP_BIG]+ const { delegate, refreshTools } = delegateReturning(upstream)+ const info = vi.spyOn(logger, 'info').mockImplementation(() => {})+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'direct',+ discoveryBytes: 2048,+ })+ expect(await controller.refreshTools([SMALL])).toBe(upstream)+ // Witness: the delegate decided the list from the caller's input.+ expect(refreshTools).toHaveBeenCalledWith([SMALL])+ expect(info).not.toHaveBeenCalled()+ })++ it('auto hides only oversized natives and never touches MCP tools', async () => {+ const { delegate } = delegateReturning([BIG, SMALL, MCP_BIG, ...BRIDGE])+ vi.spyOn(logger, 'info').mockImplementation(() => {})+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ expect((await controller.refreshTools([])).map(t => t.name)).toEqual([+ SMALL.name,+ MCP_BIG.name,+ ...BRIDGE.map(t => t.name),+ ])+ })++ it('auto throws instead of hiding a native while a bridge tool is missing', async () => {+ for (const missing of BRIDGE_TOOL_NAMES) {+ const { delegate } = delegateReturning([+ BIG,+ SMALL,+ ...BRIDGE.filter(t => t.name !== missing),+ ])+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ await expect(controller.refreshTools([])).rejects.toThrow(+ `Native tool discovery cannot hide clerum__generate_pptx: bridge tools ${missing} are not presented`+ )+ }+ // Witness: the same list with every bridge tool hides the generator.+ vi.spyOn(logger, 'info').mockImplementation(() => {})+ const { delegate } = delegateReturning([BIG, SMALL, ...BRIDGE])+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ expect((await controller.refreshTools([])).map(t => t.name)).not.toContain(BIG.name)+ })++ it('auto without anything to hide does not need the bridge', async () => {+ const { delegate } = delegateReturning([SMALL, MCP_BIG])+ vi.spyOn(logger, 'info').mockImplementation(() => {})+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ expect((await controller.refreshTools([])).map(t => t.name)).toEqual([SMALL.name, MCP_BIG.name])+ })++ it('logs the native presentation once per change', async () => {+ const list = [BIG, SMALL, ...BRIDGE]+ const { delegate, refreshTools } = delegateReturning(list)+ const info = vi.spyOn(logger, 'info').mockImplementation(() => {})+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ await controller.refreshTools([])+ await controller.refreshTools([])+ refreshTools.mockResolvedValueOnce([SMALL, ...BRIDGE])+ await controller.refreshTools([])+ expect(refreshTools).toHaveBeenCalledTimes(3)+ expect(info.mock.calls.map(call => call[0])).toEqual([+ {+ component: 'native-tool-presentation',+ mode: 'auto',+ budget: 2048,+ hiddenNames: [BIG.name],+ presentedCount: list.length - 1,+ },+ {+ component: 'native-tool-presentation',+ mode: 'auto',+ budget: 2048,+ hiddenNames: [],+ presentedCount: 1 + BRIDGE.length,+ },+ ])+ })++ it('passes every other hook through to the delegate', () => {+ const { delegate } = delegateReturning([])+ const controller = new NativeToolPresentationController(delegate, nativeNames, {+ mode: 'auto',+ discoveryBytes: 2048,+ })+ expect(controller.shouldAccept('text', 1)).toBe(true)+ expect(controller.onTextRejected('text', 1)).toBeNull()+ expect(controller.beforeTool('shell_exec', { command: 'ls' })).toBe('proceed')+ expect(controller.onExhaustion(3)).toBe('exhausted')+ expect(delegate.shouldAccept).toHaveBeenCalledWith('text', 1)+ expect(delegate.onTextRejected).toHaveBeenCalledWith('text', 1)+ expect(delegate.beforeTool).toHaveBeenCalledWith('shell_exec', { command: 'ls' })+ expect(delegate.onExhaustion).toHaveBeenCalledWith(3)+ })+})diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.tsnew file mode 100644index 000000000..2d08c7e5b--- /dev/null+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts@@ -0,0 +1,131 @@+import { describe, expect, it } from 'vitest'+import { BRIDGE_TOOL_NAMES } from '../../../capabilities/toolCatalogTools'+import { NativeToolRegistry } from '../../tools/nativeToolRegistry'+import {+ DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES,+ parseNativeToolDiscoveryBytes,+ parseNativeToolPresentation,+ selectDeferredNatives,+} from '../toolPresentationPolicy'++const nativeConfig = {+ workspacePath: '/tmp',+ shellTimeout: 1000,+ toolTimeout: 1000,+ toolProgressInterval: 0,+ httpAllowlist: [],+ envAllowlist: [],+ memoryMaxSize: 1000,+}+const productionRegistry = (discovery?: { mcpDiscovery: boolean; nativeDiscovery: boolean }) =>+ new NativeToolRegistry(+ nativeConfig,+ 'native-policy-test',+ undefined,+ undefined,+ undefined,+ () => ({}),+ undefined,+ undefined,+ undefined,+ undefined,+ undefined,+ discovery+ )++describe('CLERUM_NATIVE_TOOL_PRESENTATION parsing', () => {+ it('defaults to direct when unset', () => {+ expect(parseNativeToolPresentation(undefined)).toBe('direct')+ })++ it.each(['direct', 'auto'] as const)('accepts %s', value => {+ expect(parseNativeToolPresentation(value)).toBe(value)+ })++ it.each(['', ' ', 'AUTO', ' auto', 'discovery', 'off'])('rejects %j', value => {+ expect(() => parseNativeToolPresentation(value)).toThrow(+ 'CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto'+ )+ })+})++describe('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES parsing', () => {+ it('defaults to 2048 bytes when unset', () => {+ expect(DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES).toBe(2048)+ expect(parseNativeToolDiscoveryBytes(undefined)).toBe(2048)+ })++ it.each(['1', '2048', String(Number.MAX_SAFE_INTEGER)])('accepts %s', value => {+ expect(parseNativeToolDiscoveryBytes(value)).toBe(Number(value))+ })++ it.each(['', ' ', ' 2048', '2048 ', '0', '-1', '1e3', '+5', '1.5', '01', String(2 ** 53)])(+ 'rejects %j',+ value => {+ expect(() => parseNativeToolDiscoveryBytes(value)).toThrow(+ 'CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer'+ )+ }+ )+})++describe('selectDeferredNatives on the production native registry', () => {+ const registry = productionRegistry({ mcpDiscovery: false, nativeDiscovery: true })+ const definitions = registry.listDefinitions()+ const nativeNames = new Set(definitions.map(def => def.name))+ const bytes = (name: string) =>+ Buffer.byteLength(JSON.stringify(definitions.find(def => def.name === name)), 'utf8')++ it('hides exactly the five generators at the 2048 B default', () => {+ expect(+ [+ ...selectDeferredNatives(definitions, nativeNames, DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES),+ ].sort()+ ).toEqual([+ 'clerum__generate_chart',+ 'clerum__generate_dashboard',+ 'clerum__generate_pdf',+ 'clerum__generate_pptx',+ 'clerum__generate_xlsx',+ ])+ })++ it('keeps docx and markdown advertised, with docx the closest to the budget', () => {+ expect(definitions.map(def => def.name)).toEqual(+ expect.arrayContaining(['clerum__generate_docx', 'clerum__generate_markdown'])+ )+ // A docx description that grows past the budget must turn this test red.+ expect(bytes('clerum__generate_docx')).toBeLessThanOrEqual(DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES)+ expect(bytes('clerum__generate_markdown')).toBeLessThanOrEqual(+ DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES+ )+ })++ it('never selects bridge tools or MCP tools, whatever the budget', () => {+ expect(definitions.map(def => def.name)).toEqual(expect.arrayContaining([...BRIDGE_TOOL_NAMES]))+ const mcp = { name: 'alpha__huge', description: 'x'.repeat(10_000), parameters: {} }+ const selected = selectDeferredNatives([...definitions, mcp], nativeNames, 1)+ // Witness: a 1 B budget selects every other native.+ expect(selected.size).toBe(definitions.length - BRIDGE_TOOL_NAMES.size)+ for (const bridge of BRIDGE_TOOL_NAMES) expect(selected.has(bridge)).toBe(false)+ expect(selected.has('alpha__huge')).toBe(false)+ })++ it('registers no bridge tools without a discovery argument (main.ts tool-name snapshot)', () => {+ const names = productionRegistry()+ .listDefinitions()+ .map(def => def.name)+ // Witness: the snapshot still lists the generators.+ expect(names).toContain('clerum__generate_pptx')+ for (const bridge of BRIDGE_TOOL_NAMES) expect(names).not.toContain(bridge)+ expect(names.length).toBe(definitions.length - BRIDGE_TOOL_NAMES.size)+ })++ it('MCP discovery needs an McpManager to register the bridge; native discovery does not', () => {+ const mcpOnly = productionRegistry({ mcpDiscovery: true, nativeDiscovery: false })+ const names = mcpOnly.listDefinitions().map(def => def.name)+ for (const bridge of BRIDGE_TOOL_NAMES) expect(names).not.toContain(bridge)+ // Witness: native discovery on the same (manager-less) registry registers all three.+ expect(definitions.map(def => def.name)).toEqual(expect.arrayContaining([...BRIDGE_TOOL_NAMES]))+ })+})diff --git a/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.tsindex b7d5fb0b8..6293a37f0 100644--- a/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts@@ -126,6 +126,7 @@ function bridgeContext(nativeNames: string[], deferrable: string[]): LoopConfig[return {nativeNames: new Set(nativeNames),getDeferrableCatalogNames: () => new Set(deferrable),+ nativeTargets: false,}}@@ -298,12 +299,12 @@ describe('clerum__tool_call bridge intercept', () => {expect(real.calls).toHaveLength(0)})- it('rejects recursion into another bridge tool (LOCKED #11)', async () => {+ it('rejects recursion: target is a native or another bridge tool', async () => {const config = makeConfig({tools: {},bridge: bridgeContext(NATIVE, ['server__x']),})- for (const target of ['clerum__tool_call', 'clerum__tool_search', 'clerum__tool_describe']) {+ for (const target of ['shell_exec', 'clerum__tool_call', 'clerum__tool_search']) {const { toolResults } = await executeToolCalls([bridgeCall('c', target, {})], config, 0)expect(toolResults[0].is_error).toBe(true)expect(toolResults[0].tool_call_id).toBe('c')@@ -311,36 +312,6 @@ describe('clerum__tool_call bridge intercept', () => {}})- it('#1003 unwraps a native target, preserving call.id and executing the real tool', async () => {- const native = new StubTool('clerum__generate_docx')- const config = makeConfig({- tools: { clerum__generate_docx: native },- bridge: bridgeContext([...NATIVE, 'clerum__generate_docx'], []),- })- const { toolResults } = await executeToolCalls(- [bridgeCall('call-n', 'clerum__generate_docx', { title: 'Report' })],- config,- 0- )- expect(native.calls).toEqual([{ title: 'Report' }])- expect(toolResults[0].tool_call_id).toBe('call-n')- expect(toolResults[0].is_error).toBe(false)- })-- it('#1003 rejects a native-looking name absent from the native registry', async () => {- const config = makeConfig({- tools: {},- bridge: bridgeContext(NATIVE, ['server__x']),- })- const { toolResults } = await executeToolCalls(- [bridgeCall('c', 'ghost_native_tool', {})],- config,- 0- )- expect(toolResults[0].is_error).toBe(true)- expect(toolResults[0].content).toMatch(/not in the current tool catalog/)- })-it('scope gate rejects an out-of-catalog target without executing', async () => {const real = new StubTool('server__do_thing')const config = makeConfig({diff --git a/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts b/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.tsindex bb9a21c33..9aa350542 100644--- a/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts@@ -2,7 +2,6 @@ import { describe, expect, it } from 'vitest'import {parseCodexToolDiscoveryBytes,parseCodexToolPresentation,- parseNativeToolDiscoveryBytes,resolveToolPresentation,} from '../toolPresentationPolicy'@@ -42,20 +41,6 @@ describe('tool presentation configuration', () => {expect(() => parseCodexToolDiscoveryBytes(value)).toThrow('CODEX_TOOL_DISCOVERY_BYTES')})- it('defaults the native per-tool discovery budget to 2048 bytes', () => {- expect(parseNativeToolDiscoveryBytes(undefined)).toBe(2_048)- })- it.each(['0', '1024', '65536'])('accepts non-negative safe integer %j', value => {- expect(parseNativeToolDiscoveryBytes(value)).toBe(Number(value))- })- it.each(['', '-1', '1.5', '2kb', '9007199254740992'])(- 'rejects invalid native discovery bytes %j',- value => {- expect(() => parseNativeToolDiscoveryBytes(value)).toThrow(- 'CLERUM_NATIVE_TOOL_DISCOVERY_BYTES'- )- }- )it.each([false, true])('preserves other providers flag %s', enabled => {expect(resolveToolPresentation('zai', {diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.tsindex d31ad928f..04be7721e 100644--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts@@ -174,7 +174,7 @@ describe('runToolUseLoop — loop control', () => {})const reasoning = new DefaultReasoningPort({ complete: vi.fn(), completeWithTools, modelName: () => 'glm-5.3' },- new DefaultPromptBuilder()+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }))const config = buildLoopConfig({diff --git a/mcp-host/src/core/orchestration/deferrableToolController.ts b/mcp-host/src/core/orchestration/deferrableToolController.tsindex 02088feb2..0b151aee8 100644--- a/mcp-host/src/core/orchestration/deferrableToolController.ts+++ b/mcp-host/src/core/orchestration/deferrableToolController.ts@@ -3,11 +3,9 @@* dynamic-tool-loading "stable bridge" design (Phase F3.1).** When active, it removes all deferrable MCP tools from the advertised- * `tools[]` array, plus native tools whose serialized definition exceeds the- * per-tool native discovery budget (#1003 — the document generators dominate- * per-call token cost). Small native tools and the 3 bridge tools- * (`clerum__tool_search` / `clerum__tool_describe` / `clerum__tool_call`)- * always stay advertised; deferred tools are reached through the bridge.+ * `tools[]` array, leaving only the native tools (which include the 3 bridge+ * tools `clerum__tool_search` / `clerum__tool_describe` / `clerum__tool_call`).+ * Deferred MCP tools are reached exclusively through `clerum__tool_call`.** Why a decorator (delegate-first composition): the inner chain* (`ApprovalController → UnifiedApprovalGateController` for interactive tasks,@@ -21,7 +19,6 @@* `isNative` membership is decided by the exact `nativeNames` set (Critical:* `clerum__*` tools contain `__` but are native), NEVER by a string heuristic.*/-import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'import { logger } from '../../logger'import { LoopController } from '../interfaces'import { ChatMessage, PendingApproval, ToolDefinition } from '../types'@@ -45,7 +42,6 @@ export class DeferrableToolController implements LoopController {private readonly latch: LatchStoreprivate readonly codexMode?: CodexToolPresentationprivate readonly discoveryBytes: number- private readonly nativeDiscoveryBytes: numberprivate lastPresentation: string | undefinedconstructor(@@ -56,7 +52,6 @@ export class DeferrableToolController implements LoopController {dynamicToolsThreshold: numbercodexMode?: CodexToolPresentationcodexToolDiscoveryBytes?: number- nativeToolDiscoveryBytes?: number},latch: LatchStore) {@@ -67,7 +62,6 @@ export class DeferrableToolController implements LoopController {this.latch = latchthis.codexMode = config.codexModethis.discoveryBytes = config.codexToolDiscoveryBytes ?? 32_768- this.nativeDiscoveryBytes = config.nativeToolDiscoveryBytes ?? 2_048}shouldAccept(content: string, iteration: number): boolean {@@ -98,18 +92,12 @@ export class DeferrableToolController implements LoopController {// switches. Never reuse another provider's session latch or promote schemas.if (this.codexMode) {const deferred = upstream.filter(t => !this.nativeNames.has(t.name))- const deferrableNatives = upstream.filter(t => this.isDeferrableNative(t))- const deferredNames = new Set([- ...deferred.map(t => t.name),- ...deferrableNatives.map(t => t.name),- ])const discover =this.codexMode !== 'direct' &&(this.codexMode === 'discovery' ||deferred.length > this.threshold ||- Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes ||- deferrableNatives.length > 0)- const presented = discover ? upstream.filter(t => !deferredNames.has(t.name)) : upstream+ Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes)+ const presented = discover ? upstream.filter(t => this.nativeNames.has(t.name)) : upstreamconst measurement = {mode: this.codexMode,strategy: discover ? 'discovery' : 'direct',@@ -117,7 +105,6 @@ export class DeferrableToolController implements LoopController {mcpCount: deferred.length,presentedCount: presented.length,deferredCount: discover ? deferred.length : 0,- nativeDeferredCount: discover ? deferrableNatives.length : 0,}const key = JSON.stringify(measurement)if (key !== this.lastPresentation) {@@ -152,24 +139,8 @@ export class DeferrableToolController implements LoopController {// Passthrough — identical to today's behavior (flag off / under threshold).if (!bridgeActive) return upstream- // STABLE SWAP: advertise small natives (which include the 3 bridge tools)- // and defer oversized natives alongside MCP tools. Deterministic and- // session-invariant → `tools[]` byte-stable → cache-safe.- return upstream.filter(t => this.nativeNames.has(t.name) && !this.isDeferrableNative(t))- }-- /**- * #1003 — a native tool is deferrable when its FULL serialized definition- * (name + description + parameters — exactly what `tools[]` costs) exceeds- * the per-tool budget. The decision is size-driven, never name-driven, so- * core tools stay advertised and no generator is special-cased. The 3- * bridge tools are exempt regardless of size: they are the access path for- * everything the swap defers. A budget of 0 disables native deferral.- */- private isDeferrableNative(tool: ToolDefinition): boolean {- if (this.nativeDiscoveryBytes <= 0) return false- if (BRIDGE_TOOL_NAMES.has(tool.name)) return false- if (!this.nativeNames.has(tool.name)) return false- return Buffer.byteLength(JSON.stringify(tool), 'utf8') > this.nativeDiscoveryBytes+ // STABLE SWAP: advertise ONLY natives (which include the 3 bridge tools).+ // Deterministic and session-invariant → `tools[]` byte-stable → cache-safe.+ return upstream.filter(t => this.nativeNames.has(t.name))}}diff --git a/mcp-host/src/core/orchestration/loopConfig.ts b/mcp-host/src/core/orchestration/loopConfig.tsindex 7c7c65748..a0f8dedb4 100644--- a/mcp-host/src/core/orchestration/loopConfig.ts+++ b/mcp-host/src/core/orchestration/loopConfig.ts@@ -133,22 +133,27 @@ export interface LoopConfig {/*** F3 (dynamic-tool-loading) — context the `clerum__tool_call` bridge intercept- * needs in `executeToolCalls`. Present only when the host wired the- * `McpManager` AND the discovery bridge is registered. When undefined, the- * intercept is inert: `clerum__tool_call` falls through to the native- * safety-net tool (which errors), and there is no auto-recover scope gate.+ * needs in `executeToolCalls`. Present whenever the 3 bridge tools are+ * registered: MCP discovery with an `McpManager` wired, or native `auto`+ * (#1003, with or without an `McpManager`). When undefined, the intercept is+ * inert: `clerum__tool_call` falls through to the native safety-net tool+ * (which errors), and there is no auto-recover scope gate.** - `nativeNames` — the exact set of native tool names (incl. the 3 bridges).* Used to reject recursion (LOCKED #11) and to distinguish native from* deferrable MCP names (membership, NOT a string heuristic).* - `getDeferrableCatalogNames` — returns the live set of deferrable MCP tool- * names (`McpManager.getAllTools()` names, minus natives). Re-derived per- * call so it tracks servers connecting/disconnecting (stateless; the scope- * gate, LOCKED #7 / Critical #7, rejects out-of-catalog names).+ * names (`McpManager.getAllTools()` names, minus natives; empty without an+ * `McpManager`). Re-derived per call so it tracks servers+ * connecting/disconnecting (stateless; the scope gate, LOCKED #7 /+ * Critical #7, rejects out-of-catalog names).+ * - `nativeTargets` — native `auto` (#1003): `clerum__tool_call` may target a+ * native tool. False keeps the pre-#1003 rejection of native targets.*/bridge?: {nativeNames: Set<string>getDeferrableCatalogNames: () => Set<string>+ nativeTargets: boolean}}diff --git a/mcp-host/src/core/orchestration/nativeToolPresentationController.ts b/mcp-host/src/core/orchestration/nativeToolPresentationController.tsnew file mode 100644index 000000000..503edfc24--- /dev/null+++ b/mcp-host/src/core/orchestration/nativeToolPresentationController.ts@@ -0,0 +1,83 @@+/**+ * NativeToolPresentationController — native-tool presentation (#1003).+ *+ * Decides which NATIVE tools appear in `tools[]`, independently of how MCP tools+ * are presented. MCP presentation (Codex/Grok `CODEX_TOOL_PRESENTATION`, legacy+ * `CLERUM_DYNAMIC_TOOLS_ENABLED` latch) stays in `DeferrableToolController`; this+ * decorator wraps OUTSIDE it, so it only ever removes natives from the list the+ * MCP decision already produced and never adds or removes an MCP tool.+ *+ * - `direct`: returns the upstream list unchanged (identity).+ * - `auto`: removes the natives selected by `selectDeferredNatives` (definition+ * larger than the byte budget; bridge tools never selected). Those natives+ * stay callable through `clerum__tool_search` / `clerum__tool_describe` /+ * `clerum__tool_call`. If any bridge tool is missing from the presented list,+ * hiding a native would make it unreachable, so it throws instead.+ */+import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'+import { logger } from '../../logger'+import { LoopController } from '../interfaces'+import { ChatMessage, PendingApproval, ToolDefinition } from '../types'+import { type NativeToolPresentation, selectDeferredNatives } from './toolPresentationPolicy'++export class NativeToolPresentationController implements LoopController {+ private lastPresentation: string | undefined++ constructor(+ private readonly delegate: LoopController,+ private readonly nativeNames: ReadonlySet<string>,+ private readonly config: { mode: NativeToolPresentation; discoveryBytes: number }+ ) {}++ shouldAccept(content: string, iteration: number): boolean {+ return this.delegate.shouldAccept(content, iteration)+ }++ onTextRejected(content: string, iteration: number): ChatMessage | null {+ return this.delegate.onTextRejected(content, iteration)+ }++ beforeTool(+ toolName: string,+ params: Record<string, unknown>+ ): 'proceed' | 'skip' | { type: 'suspend'; approval: PendingApproval } {+ return this.delegate.beforeTool(toolName, params)+ }++ onExhaustion(iteration: number): string {+ return this.delegate.onExhaustion(iteration)+ }++ async refreshTools(currentTools: ToolDefinition[]): Promise<ToolDefinition[]> {+ const upstream = await this.delegate.refreshTools(currentTools)+ if (this.config.mode === 'direct') return upstream++ const hidden = selectDeferredNatives(upstream, this.nativeNames, this.config.discoveryBytes)+ if (hidden.size > 0) {+ const presentedNames = new Set(upstream.map(t => t.name))+ const missingBridge = [...BRIDGE_TOOL_NAMES].filter(name => !presentedNames.has(name))+ if (missingBridge.length > 0) {+ throw new Error(+ `Native tool discovery cannot hide ${[...hidden].join(', ')}: bridge tools ` ++ `${missingBridge.join(', ')} are not presented`+ )+ }+ }+ const presented = upstream.filter(t => !hidden.has(t.name))+ const measurement = {+ mode: this.config.mode,+ budget: this.config.discoveryBytes,+ hiddenNames: [...hidden].sort(),+ presentedCount: presented.length,+ }+ const key = JSON.stringify(measurement)+ if (key !== this.lastPresentation) {+ logger.info(+ { component: 'native-tool-presentation', ...measurement },+ 'Native tool presentation selected'+ )+ this.lastPresentation = key+ }+ return presented+ }+}diff --git a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts b/mcp-host/src/core/orchestration/toolPresentationPolicy.tsindex cf3162aaa..746f0b1d3 100644--- a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts+++ b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts@@ -1,3 +1,6 @@+import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'+import type { ToolDefinition } from '../types'+/** Presentation changes context cost, never the approved catalog or execution permissions. */export type CodexToolPresentation = 'auto' | 'direct' | 'discovery'@@ -17,19 +20,57 @@ export function parseCodexToolDiscoveryBytes(raw: string | undefined): number {}/**- * Per-native-tool serialized-definition budget. A single native tool whose- * full definition exceeds this budget is presented through discovery (search +- * describe + bridge call) instead of `tools[]`. `0` disables native deferral- * while keeping MCP deferral untouched. Small core tools stay advertised.+ * Native-tool presentation (#1003). Independent of `CodexToolPresentation` and of+ * the legacy `CLERUM_DYNAMIC_TOOLS_ENABLED` latch, which only govern MCP tools.+ * - `direct`: every native stays in `tools[]` (identical to the pre-#1003 host).+ * - `auto`: natives whose serialized definition exceeds the native discovery+ * budget leave `tools[]` and are reached through search/describe/call.+ */+export type NativeToolPresentation = 'direct' | 'auto'++export function parseNativeToolPresentation(raw: string | undefined): NativeToolPresentation {+ if (raw === undefined) return 'direct'+ if (raw === 'direct' || raw === 'auto') return raw+ throw new Error('CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto')+}++export const DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES = 2_048++/**+ * Per-native-tool serialized-definition budget used by native `auto`. Parsed even+ * in `direct`, so a bad value fails at startup instead of on the first switch.*/export function parseNativeToolDiscoveryBytes(raw: string | undefined): number {- if (raw === undefined) return 2_048- if (!/^[0-9]+$/.test(raw) || !Number.isSafeInteger(Number(raw))) {- throw new Error('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a non-negative safe integer')+ if (raw === undefined) return DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES+ if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(Number(raw))) {+ throw new Error('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer')}return Number(raw)}+/**+ * Names of the natives that native `auto` removes from `tools[]`: every native+ * whose FULL serialized definition (name + description + parameters, exactly+ * what `tools[]` costs) exceeds `budget`. Size-driven, never name-driven. The+ * bridge tools are never selected: they are the access path to everything else.+ */+export function selectDeferredNatives(+ definitions: ReadonlyArray<ToolDefinition>,+ nativeNames: ReadonlySet<string>,+ budget: number+): Set<string> {+ return new Set(+ definitions+ .filter(+ def =>+ nativeNames.has(def.name) &&+ !BRIDGE_TOOL_NAMES.has(def.name) &&+ Buffer.byteLength(JSON.stringify(def), 'utf8') > budget+ )+ .map(def => def.name)+ )+}+export function resolveToolPresentation(provider: string,config: { dynamicToolsEnabled: boolean; codexToolPresentation?: CodexToolPresentation },diff --git a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.tsindex f065cc1cb..33dd87641 100644--- a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts+++ b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts@@ -70,10 +70,9 @@ function bridgeError(call: ToolCall, message: string): ToolResult {* then rewrite to a synthetic `{ id: call.id, name, arguments }` so the* normal gate runs against the REAL tool (Critical #12 validates inner args* against the real schema; LOCKED #10 keys approval on the real name).- * Native targets are valid destinations (#1003 amendment of LOCKED #11):- * deferred native tools exist only in the native registry, so membership in- * `nativeNames` is their scope gate; recursion into a bridge tool stays- * forbidden.+ * With `bridge.nativeTargets` (native `auto`, #1003) a native target is+ * also rewritten, whether or not it is currently advertised; without it,+ * native targets are rejected as before. Recursion is rejected in both.** 2. Direct call to a deferred MCP tool (Critical #9, auto-recover) — a* non-bridge call naming an MCP tool that is currently un-advertised. It is@@ -120,9 +119,8 @@ function resolveBridgeCall(return 'handled'}- // Reject recursion (LOCKED #11): a bridge tool must never target another- // bridge tool, whatever its size or presentation.- if (BRIDGE_TOOL_NAMES.has(name)) {+ // Native `auto`: reject recursion (LOCKED #11) before accepting natives.+ if (bridge.nativeTargets && BRIDGE_TOOL_NAMES.has(name)) {toolResults.push(bridgeError(call,@@ -132,14 +130,12 @@ function resolveBridgeCall(return 'handled'}- // #1003 — native target. Deferred native tools are absent from the MCP- // catalog, so their scope gate is existence in the native registry- // (`nativeNames`). Rewrite to the real name; the normal gate below then- // validates and approves the REAL native tool, exactly as a direct call- // would. Whether the native is currently advertised is irrelevant here —- // the bridge is just a slower envelope for an advertised tool, never a- // permission bypass.- if (bridge.nativeNames.has(name)) {+ // #1003 — native `auto`: a native target is valid. Its scope gate is+ // membership in the native registry (deferred natives are not in the MCP+ // catalog). The rewrite keeps `call.id` and the normal gate below then+ // validates and approves the REAL native, exactly like a direct call, so+ // the bridge never widens what the model could call directly.+ if (bridge.nativeTargets && bridge.nativeNames.has(name)) {return {id: call.id,name,@@ -147,6 +143,18 @@ function resolveBridgeCall(}}+ // Native `direct`: reject recursion / native targets (LOCKED #11): the+ // bridge targets DEFERRABLE MCP tools only.+ if (BRIDGE_TOOL_NAMES.has(name) || bridge.nativeNames.has(name)) {+ toolResults.push(+ bridgeError(+ call,+ `clerum__tool_call cannot target "${name}": native and bridge tools are called directly, not through the bridge.`+ )+ )+ return 'handled'+ }+// Scope gate (LOCKED #7, Critical #7): the target must exist in the session's// deferrable catalog. This rejects nonexistent/out-of-catalog names; it is// NOT a per-tool authz boundary (Clerum has no per-tool RBAC).diff --git a/mcp-host/src/core/reasoning/__tests__/buildParts.test.ts b/mcp-host/src/core/reasoning/__tests__/buildParts.test.tsindex 3f6c56055..4f3c248d3 100644--- a/mcp-host/src/core/reasoning/__tests__/buildParts.test.ts+++ b/mcp-host/src/core/reasoning/__tests__/buildParts.test.ts@@ -36,7 +36,9 @@ function tool(name: string): ToolDefinition {describe('DefaultPromptBuilder.buildParts (T2.2)', () => {it('assembles stable with identity → daily → runtime; context with capabilities → memory', () => {- const parts = new DefaultPromptBuilder().buildParts(makeInput())+ const parts = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput()+ )const sIdent = parts.stable.indexOf('## Identity')const sSoul = parts.stable.indexOf('## Core Values')const sAgents = parts.stable.indexOf('## Agent Instructions')@@ -61,7 +63,7 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {})it('omits empty identity sections without producing double separators', () => {- const parts = new DefaultPromptBuilder().buildParts(+ const parts = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({identityFiles: { identity: '', soul: '', agents: 'AGENTS', user: '' },dailyLogSnapshot: '',@@ -77,15 +79,15 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {})it('omits empty context sections', () => {- const parts = new DefaultPromptBuilder().buildParts(+ const parts = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({ memoryGuidance: '', capabilities: 'only this' }))expect(parts.context).toBe('only this')})it('produces deterministic hashes (same input → same hash)', () => {- const a = new DefaultPromptBuilder().buildParts(makeInput())- const b = new DefaultPromptBuilder().buildParts(makeInput())+ const a = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput())+ const b = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput())expect(a.stableHash).toBe(b.stableHash)expect(a.contextHash).toBe(b.contextHash)// Hashes match a fresh sha256(content)@@ -94,15 +96,21 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {})it('hash diverges when stable input mutates (e.g. model change)', () => {- const baseline = new DefaultPromptBuilder().buildParts(makeInput())- const mutated = new DefaultPromptBuilder().buildParts(makeInput({ model: 'claude-haiku-4-5' }))+ const baseline = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput()+ )+ const mutated = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput({ model: 'claude-haiku-4-5' })+ )expect(mutated.stableHash).not.toBe(baseline.stableHash)expect(mutated.contextHash).toBe(baseline.contextHash)})it('hash stays constant when context input mutates only (capabilities change)', () => {- const baseline = new DefaultPromptBuilder().buildParts(makeInput())- const mutated = new DefaultPromptBuilder().buildParts(+ const baseline = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput()+ )+ const mutated = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({ capabilities: 'different contract' }))expect(mutated.stableHash).toBe(baseline.stableHash)@@ -114,7 +122,7 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {// (`buildParts`) had no slot for them, so enabling the prompt cache silently// dropped both blocks. These guard the cross-path parity.it('places workflow + MCP guidance in the context tier, ordered after capabilities and before memory', () => {- const parts = new DefaultPromptBuilder().buildParts(+ const parts = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({workflowGuidance: WORKFLOW_RECIPES_TEXT,mcpServerGuidance: MCP_SERVER_SELECTION_TEXT,@@ -135,7 +143,7 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {it('cache-path context carries the exact guidance the legacy buildSystemPrompt emits', () => {const tools = [tool('workflow_list'), tool('github__create_issue')]- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const legacy = builder.buildSystemPrompt(tools).content as stringconst parts = builder.buildParts(makeInput({@@ -151,31 +159,35 @@ describe('DefaultPromptBuilder.buildParts (T2.2)', () => {})it('omits workflow + MCP guidance when not provided (empty string → no block)', () => {- const parts = new DefaultPromptBuilder().buildParts(makeInput())+ const parts = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput()+ )expect(parts.context).not.toContain('WORKFLOW RECIPES:')expect(parts.context).not.toContain('MCP SERVER SELECTION:')})// F4.1 — TOOL_DISCOVERY_TEXT (dynamic-tool-loading).it('tiered path: emits TOOL_DISCOVERY_TEXT only when provided, and it is a constant (cache-safe)', () => {- const without = new DefaultPromptBuilder().buildParts(makeInput())+ const without = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(+ makeInput()+ )expect(without.context).not.toContain(TOOL_DISCOVERY_TEXT)- const withGuidance = new DefaultPromptBuilder().buildParts(+ const withGuidance = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({ toolDiscoveryGuidance: TOOL_DISCOVERY_TEXT }))expect(withGuidance.context).toContain(TOOL_DISCOVERY_TEXT)// Stable tier never carries it → stableHash unchanged.expect(withGuidance.stableHash).toBe(without.stableHash)// It is a CONSTANT: building twice with it on yields the same context hash.- const again = new DefaultPromptBuilder().buildParts(+ const again = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }).buildParts(makeInput({ toolDiscoveryGuidance: TOOL_DISCOVERY_TEXT }))expect(again.contextHash).toBe(withGuidance.contextHash)})it('legacy path: buildSystemPrompt emits TOOL_DISCOVERY_TEXT only when clerum__tool_search is present', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const withSearch = builder.buildSystemPrompt([tool('clerum__tool_search')]).content as stringexpect(withSearch).toContain(TOOL_DISCOVERY_TEXT)diff --git a/mcp-host/src/core/reasoning/__tests__/promptBuilder.test.ts b/mcp-host/src/core/reasoning/__tests__/promptBuilder.test.tsindex cc8e06fa9..db8e99bf2 100644--- a/mcp-host/src/core/reasoning/__tests__/promptBuilder.test.ts+++ b/mcp-host/src/core/reasoning/__tests__/promptBuilder.test.ts@@ -8,7 +8,7 @@ function tool(name: string): ToolDefinition {describe('DefaultPromptBuilder — memory guidance (P.4)', () => {it('includes MEMORY_GUIDANCE_TEXT when a memory_* tool is registered', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([tool('memory_write'), tool('memory_search')])expect(msg.content).toContain(MEMORY_GUIDANCE_TEXT)expect(msg.content).toContain('two scopes')@@ -16,14 +16,14 @@ describe('DefaultPromptBuilder — memory guidance (P.4)', () => {})it('omits the guidance when no memory tools are present', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([tool('clerum__get_capabilities')])expect(msg.content).not.toContain(MEMORY_GUIDANCE_TEXT)expect(msg.content).not.toContain('two scopes')})it('emits the guidance block exactly once even with multiple memory tools', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([tool('memory_write'),tool('memory_read'),diff --git a/mcp-host/src/core/reasoning/__tests__/reasoningPort.test.ts b/mcp-host/src/core/reasoning/__tests__/reasoningPort.test.tsindex d1466ae81..86fab8684 100644--- a/mcp-host/src/core/reasoning/__tests__/reasoningPort.test.ts+++ b/mcp-host/src/core/reasoning/__tests__/reasoningPort.test.ts@@ -61,7 +61,10 @@ describe('DefaultReasoningPort.respondWithTools', () => {finish_reason: FinishReason.ToolUse,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'Search' }],available_tools: [{ name: 'search', description: 'Search', parameters: {} }],@@ -84,7 +87,10 @@ describe('DefaultReasoningPort.respondWithTools', () => {finish_reason: FinishReason.Stop,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'What?' }],available_tools: [],@@ -107,7 +113,10 @@ describe('DefaultReasoningPort.respondWithTools', () => {finish_reason: FinishReason.ContentFilter,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'Bad request' }],available_tools: [],@@ -129,7 +138,10 @@ describe('DefaultReasoningPort.respondWithTools', () => {finish_reason: FinishReason.Stop,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'Hi' }],available_tools: [],@@ -147,7 +159,10 @@ describe('DefaultReasoningPort.respondWithTools', () => {finish_reason: FinishReason.ToolUse,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'Search' }],available_tools: [{ name: 'search', description: 'Search', parameters: {} }],@@ -167,7 +182,10 @@ describe('DefaultReasoningPort.continueWithToolResults', () => {finish_reason: FinishReason.Stop,})- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )// Tool results are pre-appended by toolUseLoop before calling continueWithToolResults.// The context must already include the tool result message (see port.ts:65-66).const context: ReasoningContext = {@@ -210,7 +228,10 @@ describe('DefaultReasoningPort.continueWithToolResults', () => {const mockLlm = createMockLlmPort();(mockLlm.completeWithTools as any).mockRejectedValue(new Error('API down'))- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.continueWithToolResults({ messages: [], available_tools: [] }, [])expect(result.type).toBe('error')@@ -234,7 +255,7 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {const sink = vi.fn((_raw: ContextBreakdownRaw) => {})const port = new DefaultReasoningPort(mockLlm,- new DefaultPromptBuilder(),+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }),undefined,undefined,parts,@@ -272,7 +293,7 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {const sink = vi.fn((_raw: ContextBreakdownRaw) => {})const port = new DefaultReasoningPort(mockLlm,- new DefaultPromptBuilder(),+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }),undefined,undefined,parts,@@ -299,7 +320,7 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {const sink = vi.fn((_raw: ContextBreakdownRaw) => {})const port = new DefaultReasoningPort(mockLlm,- new DefaultPromptBuilder(),+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }),'You are a test agent.',undefined,undefined, // no parts → legacy path@@ -333,7 +354,7 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {const sink = vi.fn((_raw: ContextBreakdownRaw) => {})const port = new DefaultReasoningPort(mockLlm,- new DefaultPromptBuilder(),+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' }),undefined,undefined,parts,@@ -354,7 +375,10 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {it('is a no-op when tokenCounter / sink are not wired', async () => {const mockLlm = createMockLlmPort();(mockLlm.completeWithTools as any).mockResolvedValue(okToolResponse)- const port = new DefaultReasoningPort(mockLlm, new DefaultPromptBuilder())+ const port = new DefaultReasoningPort(+ mockLlm,+ new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })+ )const result = await port.respondWithTools({messages: [{ role: 'user', content: 'hi' }],available_tools: [],@@ -365,7 +389,7 @@ describe('DefaultReasoningPort context-breakdown capture (F1.2)', () => {describe('DefaultPromptBuilder', () => {it('should produce system message with identity, tools, and date (Risk 3.3)', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([{ name: 'search', description: 'Search the web', parameters: {} }],'You are a research assistant.',@@ -381,7 +405,7 @@ describe('DefaultPromptBuilder', () => {})it('emits the capability contract when clerum__get_capabilities is registered', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([{ name: 'clerum__get_capabilities', description: 'discover', parameters: {} }],undefined,@@ -395,7 +419,7 @@ describe('DefaultPromptBuilder', () => {})it('does NOT emit the capability contract when the tool is absent', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([{ name: 'search', description: 'Search the web', parameters: {} }],undefined,@@ -407,7 +431,7 @@ describe('DefaultPromptBuilder', () => {})it('emits the workflow recipe contract when workflow tools are registered', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([{ name: 'workflow_list', description: 'List workflows', parameters: {} },@@ -444,7 +468,7 @@ describe('DefaultPromptBuilder', () => {})it('emits exact MCP server selection guidance when MCP tools are registered', () => {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })const msg = builder.buildSystemPrompt([{ name: 'mongodb-mcp-stack__find', description: 'Find documents', parameters: {} },diff --git a/mcp-host/src/core/reasoning/factory.ts b/mcp-host/src/core/reasoning/factory.tsindex 32f409cee..18fdfcadf 100644--- a/mcp-host/src/core/reasoning/factory.ts+++ b/mcp-host/src/core/reasoning/factory.ts@@ -1,7 +1,6 @@import { LlmPort, PromptBuilder, ReasoningFactory, ReasoningPort } from '../interfaces'import type { TokenCounter } from '../tokenizer/tokenCounter'import { ContextBreakdownRaw, DefaultReasoningPort } from './port'-import { DefaultPromptBuilder } from './promptBuilder'import type { SystemPromptParts } from './systemPrompt'/**@@ -20,7 +19,9 @@ export class DefaultReasoningFactory implements ReasoningFactory {constructor(private readonly llmPort: LlmPort,- promptBuilder?: PromptBuilder,+ // #1003 — required: the builder carries the host's native-tool presentation,+ // which selects the discovery guidance text.+ promptBuilder: PromptBuilder,private readonly metadata?: Record<string, unknown>,/*** F1.2b — optional context-window-breakdown wiring propagated to every@@ -31,7 +32,7 @@ export class DefaultReasoningFactory implements ReasoningFactory {private readonly onContextBreakdown?: (raw: ContextBreakdownRaw) => void,private readonly contextMaxTokens?: number) {- this.promptBuilder = promptBuilder ?? new DefaultPromptBuilder()+ this.promptBuilder = promptBuilder}create(systemPrompt?: string): ReasoningPort {diff --git a/mcp-host/src/core/reasoning/promptBuilder.ts b/mcp-host/src/core/reasoning/promptBuilder.tsindex 0b30ae78b..e77b4c685 100644--- a/mcp-host/src/core/reasoning/promptBuilder.ts+++ b/mcp-host/src/core/reasoning/promptBuilder.ts@@ -1,6 +1,7 @@import { createHash } from 'node:crypto'import { logger } from '../../logger'import { PromptBuilder } from '../interfaces'+import type { NativeToolPresentation } from '../orchestration/toolPresentationPolicy'import { ChatMessage, ToolDefinition } from '../types'import type { BuilderInput, SystemPromptParts } from './systemPrompt'@@ -119,13 +120,34 @@ export const MCP_SERVER_SELECTION_TEXT =export const TOOL_DISCOVERY_TEXT ='Use directly listed tools when available. For additional approved tools, ' +'use `clerum__tool_search` to find them by keyword, `clerum__tool_describe` to ' +- "see one's schema, and `clerum__tool_call` to invoke it. This also covers " +- 'internal tools that are not listed directly. Search narrowly for the current task; refine or page ' ++ "see one's schema, and `clerum__tool_call` to invoke it. Native tools are " ++ 'already available directly. Search narrowly for the current task; refine or page ' +'only when needed rather than loading the whole catalog. Describe only the chosen ' +'tool and reuse its schema from the conversation when available. Each invocation ' +'still checks current permissions and arguments. Do not call tools for tasks that ' +'do not require them.'+/**+ * #1003 — discovery guidance when native `auto` is on: large internal tools are+ * not listed directly and are reached through the same search/describe/call+ * flow, so the "native tools are already available directly" sentence of+ * `TOOL_DISCOVERY_TEXT` would be false. Constant per host, cache-safe.+ */+export const NATIVE_TOOL_DISCOVERY_TEXT =+ 'Use directly listed tools when available. For additional approved tools, ' ++ 'including internal tools that are not listed directly, use `clerum__tool_search` ' ++ "to find them by keyword, `clerum__tool_describe` to see one's schema, and " ++ '`clerum__tool_call` to invoke it. Search narrowly for the current task; refine or page ' ++ 'only when needed rather than loading the whole catalog. Describe only the chosen ' ++ 'tool and reuse its schema from the conversation when available. Each invocation ' ++ 'still checks current permissions and arguments. Do not call tools for tasks that ' ++ 'do not require them.'++/** Discovery guidance for the host's native-tool presentation. */+export function toolDiscoveryText(nativeToolPresentation: NativeToolPresentation): string {+ return nativeToolPresentation === 'auto' ? NATIVE_TOOL_DISCOVERY_TEXT : TOOL_DISCOVERY_TEXT+}+/*** Default prompt builder.*@@ -133,6 +155,12 @@ export const TOOL_DISCOVERY_TEXT =* with identity, tool descriptions, date/time, and channel context.*/export class DefaultPromptBuilder implements PromptBuilder {+ private readonly discoveryText: string++ constructor(options: { nativeToolPresentation: NativeToolPresentation }) {+ this.discoveryText = toolDiscoveryText(options.nativeToolPresentation)+ }+buildSystemPrompt(tools: ToolDefinition[],identity?: string,@@ -180,7 +208,7 @@ export class DefaultPromptBuilder implements PromptBuilder {// Tool-discovery guidance (F4.1): emitted when the stable bridge is active,// detected by the presence of `clerum__tool_search`.if (tools.some(t => t.name === 'clerum__tool_search')) {- sections.push(TOOL_DISCOVERY_TEXT)+ sections.push(this.discoveryText)}// 2b. Desktop environment contextdiff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.tsdeleted file mode 100644index 567baaa5c..000000000--- a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts+++ /dev/null@@ -1,80 +0,0 @@-import { describe, expect, it } from 'vitest'-import type { McpManager } from '../../../mcp/manager'-import type { NativeToolConfig } from '../../interfaces'-import { NativeToolRegistry } from '../nativeToolRegistry'--const config: NativeToolConfig = {- workspacePath: '/tmp',- shellTimeout: 5000,- toolTimeout: 60000,- toolProgressInterval: 30000,- httpAllowlist: [],- envAllowlist: ['PATH'],- memoryMaxSize: 1048576,- statelessLifecycle: false,-}--function stubManager(): McpManager {- return {- getAllTools: () => [- {- name: 'acme__lookup',- description: 'Acme lookup',- inputSchema: { type: 'object' },- serverName: 'acme',- },- ],- } as unknown as McpManager-}--function buildRegistry(): NativeToolRegistry {- return new NativeToolRegistry(- config,- 'test-conv',- undefined,- undefined,- undefined,- undefined,- undefined,- undefined,- undefined,- undefined,- stubManager(),- true- )-}--describe('NativeToolRegistry — #1003 discovery catalog covers natives', () => {- it('tool_search indexes native tools under server "native" alongside MCP entries', async () => {- const registry = buildRegistry()- const search = registry.get('clerum__tool_search')- expect(search).not.toBeNull()-- const output = await search!.execute({ query: 'shell' })- expect(output.is_error).toBe(false)- const payload = JSON.parse(output.content) as {- results: Array<{ name: string; server: string }>- }- const nativeHit = payload.results.find(r => r.name === 'shell_exec')- expect(nativeHit?.server).toBe('native')- })-- it('tool_describe returns the full schema of a native tool', async () => {- const registry = buildRegistry()- const describe = registry.get('clerum__tool_describe')- expect(describe).not.toBeNull()-- const output = await describe!.execute({ name: 'shell_exec' })- expect(output.is_error).toBe(false)- const payload = JSON.parse(output.content) as {- found: boolean- name?: string- server?: string- parameters?: Record<string, unknown>- }- expect(payload.found).toBe(true)- expect(payload.name).toBe('shell_exec')- expect(payload.server).toBe('native')- expect(payload.parameters).toBeTypeOf('object')- })-})diff --git a/mcp-host/src/core/tools/__tests__/utilityTools.test.ts b/mcp-host/src/core/tools/__tests__/utilityTools.test.tsindex 484f1e7ee..ba69ebdfd 100644--- a/mcp-host/src/core/tools/__tests__/utilityTools.test.ts+++ b/mcp-host/src/core/tools/__tests__/utilityTools.test.ts@@ -213,7 +213,7 @@ describe('NativeToolRegistry', () => {undefined,undefined,mcpManagerStub,- dynamicToolsEnabled+ { mcpDiscovery: dynamicToolsEnabled, nativeDiscovery: false })}@@ -231,16 +231,18 @@ describe('NativeToolRegistry', () => {// Both prompt paths gate the discovery guidance on the presence of// clerum__tool_search; with the flag OFF that tool is absent, so neither// path emits TOOL_DISCOVERY_TEXT.- const prompt = new DefaultPromptBuilder().buildSystemPrompt(registry.listDefinitions())- .content as string+ const prompt = new DefaultPromptBuilder({+ nativeToolPresentation: 'direct',+ }).buildSystemPrompt(registry.listDefinitions()).content as stringexpect(prompt).not.toContain(TOOL_DISCOVERY_TEXT)})it('flag ON ⇒ all 3 bridge tools registered and discovery guidance emitted', () => {const registry = buildRegistry(true)expect(bridgeToolNames(registry).sort()).toEqual([...BRIDGE_TOOLS].sort())- const prompt = new DefaultPromptBuilder().buildSystemPrompt(registry.listDefinitions())- .content as string+ const prompt = new DefaultPromptBuilder({+ nativeToolPresentation: 'direct',+ }).buildSystemPrompt(registry.listDefinitions()).content as stringexpect(prompt).toContain(TOOL_DISCOVERY_TEXT)})})diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.tsindex 43d4a690a..59c482df8 100644--- a/mcp-host/src/core/tools/nativeToolRegistry.ts+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts@@ -1,6 +1,7 @@import type { CronScheduler } from '../../agent/cronScheduler'import { createGetCapabilitiesTool } from '../../capabilities/getCapabilitiesTool'import {+ BRIDGE_TOOL_NAMES,createToolCallTool,createToolDescribeTool,createToolSearchTool,@@ -172,14 +173,15 @@ export class NativeToolRegistry implements ToolRegistry {// Appended as a trailing optional dep so existing positional call sites// stay valid; only taskExecutor passes it.mcpManager?: McpManager,- // F3/F4 (dynamic-tool-loading): the STATIC feature flag- // (config.dynamicToolsEnabled). The 3 bridge tools are only registered when- // this is true, so a default-OFF host is byte-identical to today (no extra- // native tools, no discovery guidance — the guidance gates on the presence- // of clerum__tool_search). Constant per host/session, so it is cache-safe.- // Appended as a trailing optional so existing positional call sites stay- // valid; only taskExecutor passes it.- dynamicToolsEnabled?: boolean,+ // F3/F4 (dynamic-tool-loading) + #1003: which concerns need the 3 bridge+ // tools. `mcpDiscovery` is the MCP presentation decision (Codex/Grok mode+ // or the legacy flag) and only counts when an McpManager is wired;+ // `nativeDiscovery` is native `auto`, which needs the bridge even without+ // MCP. With both false nothing is registered, so tools[] is byte-identical+ // to a host without discovery and no discovery guidance is emitted (it+ // gates on clerum__tool_search). Constant per host/session, so it is+ // cache-safe. Trailing optional; only taskExecutor passes it.+ discovery?: { mcpDiscovery: boolean; nativeDiscovery: boolean },// §13 (stateless agents): the ACTIVE LLM provider steers shell_exec// credential-slot stripping — only the active provider's credential env// var survives into the child env. Appended as a trailing optional so@@ -378,32 +380,41 @@ export class NativeToolRegistry implements ToolRegistry {)// F2/F3/F4 (dynamic-tool-loading): read-only discovery meta-tools + the- // execution bridge. They query the live catalog (MCP tools plus every- // native definition, #1003) on demand and never put schemas into the- // announced tools[] array.- // Gated on BOTH an McpManager being wired (chat path via taskExecutor; the- // tool-name listing registry in main.ts and tests omit it) AND the static- // feature flag (LOCKED #5: default OFF, opt-in, small hosts untouched). When- // the flag is OFF, none of these 3 tools are registered, so tools[] is- // byte-identical to today and the presence-gated discovery guidance is not- // emitted by either prompt path.- if (mcpManager && dynamicToolsEnabled) {- // #1003 — deferred native tools must be searchable and describable exactly- // like deferred MCP tools. Native definitions are projected into the- // catalog shape with serverName "native"; advertised natives appear too so- // the index stays complete and stable across presentation changes.- const getCatalog = (): McpTool[] => [- ...mcpManager.getAllTools(),- ...this.listDefinitions().map(def => ({- name: def.name,- description: def.description,- inputSchema: def.parameters,- serverName: 'native',- })),- ]+ // execution bridge. They query the live catalog on demand and never put+ // schemas into the announced tools[] array.+ // Registered when MCP discovery needs them (an McpManager is wired — the+ // tool-name listing registry in main.ts and tests omit it — AND the MCP+ // presentation enables the bridge; LOCKED #5: default OFF) or when native+ // `auto` needs them (#1003; no McpManager required). Otherwise none of+ // these 3 tools are registered, so tools[] is byte-identical to today and+ // the presence-gated discovery guidance is not emitted by either prompt path.+ const mcpDiscovery = Boolean(mcpManager && discovery?.mcpDiscovery)+ const nativeDiscovery = discovery?.nativeDiscovery === true+ if (mcpDiscovery || nativeDiscovery) {+ // Single catalog. Without native discovery it is exactly the MCP catalog.+ // With it (#1003), every non-bridge native is appended under the `native`+ // pseudo-server so a deferred native can be searched and described, and+ // MCP entries whose name collides with a native are dropped, because the+ // bridge routes such a name to the native. Read lazily: desktop tools are+ // registered after construction and MCP servers connect late.+ const getCatalog = (): McpTool[] => {+ const mcpTools = mcpManager?.getAllTools() ?? []+ if (!nativeDiscovery) return mcpTools+ const natives = this.listDefinitions().filter(def => !BRIDGE_TOOL_NAMES.has(def.name))+ const nativeNames = new Set(natives.map(def => def.name))+ return [+ ...mcpTools.filter(tool => !nativeNames.has(tool.name)),+ ...natives.map(def => ({+ name: def.name,+ description: def.description,+ inputSchema: def.parameters,+ serverName: 'native',+ })),+ ]+ }this.register(new InternalToolAdapter(- createToolSearchTool(getCatalog),+ createToolSearchTool(getCatalog, { nativeTargets: nativeDiscovery }),outputDir,resolvedAttachmentOptions)@@ -420,7 +431,11 @@ export class NativeToolRegistry implements ToolRegistry {// intercept at the top of `executeToolCalls`. The adapter's `execute` is a// safety net that errors if the intercept is bypassed.this.register(- new InternalToolAdapter(createToolCallTool(), outputDir, resolvedAttachmentOptions)+ new InternalToolAdapter(+ createToolCallTool({ nativeTargets: nativeDiscovery }),+ outputDir,+ resolvedAttachmentOptions+ ))}}diff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.tsindex 191244f45..5c8b3142a 100644--- a/mcp-host/src/core/types.ts+++ b/mcp-host/src/core/types.ts@@ -546,8 +546,9 @@ export interface ContextBreakdown {* active (the stable bridge), this reflects natives + the 3 bridge tools* only — deferrable MCP schemas LEAVE this array and instead appear* transiently in `messages` via `clerum__tool_describe` / `clerum__tool_call`- * outputs. So a sharp drop here when the bridge engages is expected, not a- * breakdown bug.+ * outputs. With native `auto` (#1003) the natives larger than the native+ * discovery budget leave it the same way. So a sharp drop here when either+ * engages is expected, not a breakdown bug.*/systemTools: numbermetaContext: numberdiff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.tsindex b42ee4ce2..ed4cf3b48 100644--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts@@ -600,9 +600,9 @@ describe('CodexSubscriptionProvider', () => {inputSchema: { type: 'object', properties: { key: { type: 'string' } } },}))const nativeTools = [- createToolSearchTool(() => catalog),+ createToolSearchTool(() => catalog, { nativeTargets: false }),createToolDescribeTool(() => catalog),- createToolCallTool(),+ createToolCallTool({ nativeTargets: false }),].map(tool => ({name: tool.name,description: tool.description,diff --git a/mcp-host/src/llm/__tests__/promptCache.test.ts b/mcp-host/src/llm/__tests__/promptCache.test.tsindex cef39f3d4..2b80158c6 100644--- a/mcp-host/src/llm/__tests__/promptCache.test.ts+++ b/mcp-host/src/llm/__tests__/promptCache.test.ts@@ -22,7 +22,7 @@ function makeMockClient() {}function makeParts(): SystemPromptParts {- const builder = new DefaultPromptBuilder()+ const builder = new DefaultPromptBuilder({ nativeToolPresentation: 'direct' })return builder.buildParts({identityFiles: { identity: 'I', soul: 'S', agents: 'A', user: 'U' },dailyLogSnapshot: '## Today\nentry',diff --git a/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts b/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.tsindex c867226f0..8d699da2d 100644--- a/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts+++ b/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts@@ -134,6 +134,43 @@ describe('GoogleGenerativeDriver — tool round-trip', () => {expect(fnResp.functionResponse.name).toBe('search')expect(fnResp.functionResponse.response).toEqual({ result: 'found' })})++ it('names a bridged tool result after the clerum__tool_call functionCall, not the real tool', async () => {+ const { client, generateContent } = mockClient({+ candidates: [{ content: { parts: [{ text: 'done' }] }, finishReason: 'STOP' }],+ })+ const driver = new GoogleGenerativeDriver(client, 'gemini-2.5-pro')+ const bridged = { name: 'clerum__generate_pptx', arguments: { title: 'Deck' } }+ const messages: ChatMessage[] = [+ { role: 'user', content: 'make a deck' },+ {+ role: 'assistant',+ content: '',+ tool_calls: [{ id: 'call_bridge', name: 'clerum__tool_call', arguments: bridged }],+ },+ // The loop names a bridged result after the REAL tool it executed.+ {+ role: 'tool',+ name: 'clerum__generate_pptx',+ content: 'File generated: deck.pptx (pptx)',+ tool_call_id: 'call_bridge',+ },+ // Witness: a result whose id matches no functionCall keeps its own name.+ { role: 'tool', name: 'orphan_tool', content: 'orphan', tool_call_id: 'unknown' },+ ]+ await driver.completeSingleTurnWithTools(messages, [])++ const contents = generateContent.mock.calls[0][0].contents+ const call = contents+ .flatMap((c: { parts: Array<{ functionCall?: { name: string } }> }) => c.parts)+ .find((p: { functionCall?: { name: string } }) => p.functionCall)+ const responses = contents+ .flatMap((c: { parts: Array<{ functionResponse?: { name: string } }> }) => c.parts)+ .filter((p: { functionResponse?: { name: string } }) => p.functionResponse)+ .map((p: { functionResponse: { name: string } }) => p.functionResponse.name)+ expect(call.functionCall).toEqual({ name: 'clerum__tool_call', args: bridged })+ expect(responses).toEqual(['clerum__tool_call', 'orphan_tool'])+ })})describe('GoogleGenerativeDriver — finish reasons', () => {diff --git a/mcp-host/src/llm/drivers/googleGenerative.ts b/mcp-host/src/llm/drivers/googleGenerative.tsindex 9783cf942..6bb88ac4e 100644--- a/mcp-host/src/llm/drivers/googleGenerative.ts+++ b/mcp-host/src/llm/drivers/googleGenerative.ts@@ -206,7 +206,10 @@ export class GoogleGenerativeDriver implements SingleTurnProvider {continue}if (m.role === 'tool') {- const name = m.name ?? (m.tool_call_id ? idToName.get(m.tool_call_id) : undefined) ?? 'tool'+ // The functionCall's own name wins: a call routed through+ // `clerum__tool_call` produces a result named after the REAL tool, but+ // Gemini pairs the response with the `clerum__tool_call` functionCall.+ const name = (m.tool_call_id ? idToName.get(m.tool_call_id) : undefined) ?? m.name ?? 'tool'contents.push({role: 'user',parts: [{ functionResponse: { name, response: { result: m.content } } }],diff --git a/mcp-host/src/mcp/__tests__/managerDelimiterDispatch.test.ts b/mcp-host/src/mcp/__tests__/managerDelimiterDispatch.test.tsindex 2f2bf2b9a..abea36690 100644--- a/mcp-host/src/mcp/__tests__/managerDelimiterDispatch.test.ts+++ b/mcp-host/src/mcp/__tests__/managerDelimiterDispatch.test.ts@@ -111,6 +111,7 @@ describe('MCP delimiter dispatch', () => {bridge: {nativeNames: new Set(['clerum__tool_call']),getDeferrableCatalogNames: () => new Set(manager.getAllTools().map(tool => tool.name)),+ nativeTargets: false,},}const results = await executeToolCalls(