Skip to content

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.md
index 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 a
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 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 the
Responses-shaped Grok wire (sibling of Codex #648). Agent tool presentation
uses 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 outcomes
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 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.json
index 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.ts
index 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.ts
index 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 = n
const 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.ts
index 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 {
: baseController
const 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.ts
index 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.ts
index 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/typ
export 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): InternalToolD
query: { 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.ts
new file mode 100644
index 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.ts
index 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: CodexToolPresentation
codexToolDiscoveryBytes: 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: NativeToolPresentation
nativeToolDiscoveryBytes: 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: LatchStore
private readonly codexMode?: CodexToolPresentation
private readonly discoveryBytes: number
- private readonly nativeDiscoveryBytes: number
private lastPresentation: string | undefined
constructor(
@@ -56,7 +52,6 @@ export class DeferrableToolController implements LoopController {
dynamicToolsThreshold: number
codexMode?: CodexToolPresentation
codexToolDiscoveryBytes?: number
- nativeToolDiscoveryBytes?: number
},
latch: LatchStore
) {
@@ -67,7 +62,6 @@ export class DeferrableToolController implements LoopController {
this.latch = latch
this.codexMode = config.codexMode
this.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)) : upstream
const 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 string
const 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 string
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 context
diff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts
deleted file mode 100644
index 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.ts
index 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 string
expect(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 string
expect(prompt).toContain(TOOL_DISCOVERY_TEXT)
})
})
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 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.ts
index 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: number
metaContext: number
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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(