Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(mcp-host): defer oversized native tools through discovery

Alfredo Lopezfb84068b33d1
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 6dff9be3d..e27c32cf6 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"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 df246a7d9..566043608 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/__tests__/taskExecutor.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
index 35c51e850..0a4097e2f 100644
--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts
+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
@@ -1840,7 +1840,10 @@ describe('TaskExecutor Codex presentation wiring', () => {
}
const { executor } = makeExecutor('codex-subscription', manager)
const { registry, loopController, bridge } = await executor.createToolRegistry()
- const initial = await loopController.refreshTools(registry.listDefinitions())
+ 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)
expect(initial.map((t: any) => t.name)).toEqual(
expect.arrayContaining(['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call'])
)
@@ -1848,7 +1851,7 @@ describe('TaskExecutor Codex presentation wiring', () => {
for (const n of [83, 150, 250]) {
count = n
const full = registry.listDefinitions()
- expect(full).toHaveLength(initial.length + n)
+ expect(full).toHaveLength(fullInitial.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()
@@ -1921,6 +1924,7 @@ 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 abc48c9a7..fbd562dd1 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -2162,6 +2162,7 @@ export class TaskExecutor {
dynamicToolsEnabled: presentation.bridgeEnabled,
codexMode: presentation.codexMode,
codexToolDiscoveryBytes: appConfig.codexToolDiscoveryBytes,
+ nativeToolDiscoveryBytes: appConfig.nativeToolDiscoveryBytes,
dynamicToolsThreshold: appConfig.dynamicToolsThreshold,
},
{
diff --git a/mcp-host/src/capabilities/toolCatalogTools.ts b/mcp-host/src/capabilities/toolCatalogTools.ts
index e7986cfb3..57aa8f095 100644
--- a/mcp-host/src/capabilities/toolCatalogTools.ts
+++ b/mcp-host/src/capabilities/toolCatalogTools.ts
@@ -22,6 +22,14 @@ 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([
+ 'clerum__tool_search',
+ 'clerum__tool_describe',
+ 'clerum__tool_call',
+])
+
/** 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. */
@@ -344,7 +352,8 @@ export function createToolCallTool(): InternalToolDefinition {
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; native tools are called directly.',
+ 'for tools that are not listed directly, including deferred internal tools. ' +
+ 'Tools already listed in `tools[]` are called directly by their own name.',
parameters: {
type: 'object',
properties: {
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 66de689af..42152cbbd 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -9,6 +9,7 @@ import {
type CodexToolPresentation,
parseCodexToolDiscoveryBytes,
parseCodexToolPresentation,
+ parseNativeToolDiscoveryBytes,
} from './core/orchestration/toolPresentationPolicy'
import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'
import type { McpCatalogBootstrapConfig } from './mcp/grantProbe'
@@ -176,6 +177,9 @@ 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[]`.
+ nativeToolDiscoveryBytes: number
// F1 (dynamic-tool-loading) — Gates the dynamic-tool-loading bridge; default
// OFF; set true per-host to enable; see
// `.specs/dynamic-tool-loading/plan-hermes-bridge.es.md`.
@@ -935,6 +939,9 @@ 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),
+ nativeToolDiscoveryBytes: parseNativeToolDiscoveryBytes(
+ process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES
+ ),
// Legacy dynamic tools remain opt-in for other providers.
dynamicToolsEnabled: getEnvBool('CLERUM_DYNAMIC_TOOLS_ENABLED', false),
// F1 (dynamic-tool-loading) — Minimum deferrable (MCP) tool count above which
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 db4519389..c1833fd11 100644
--- a/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts
@@ -148,6 +148,26 @@ async function setup(count = 83, reverse = 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()
@@ -197,8 +217,14 @@ describe('approved catalog across presentation and lifecycle', () => {
return { presented, parts }
}
const direct = await buildPrompts()
- expect(direct.presented).toEqual(registry.listDefinitions())
- expect(direct.presented.some(tool => tool.name === 'alpha__record__read_000')).toBe(true)
+ 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)
remote.catalogs.set(
'late',
@@ -239,8 +265,11 @@ describe('approved catalog across presentation and lifecycle', () => {
}
)
const presented = await controller.refreshTools(registry.listDefinitions())
- expect(presented).toHaveLength(mode === 'direct' ? count + 36 : 36)
- expect(presented.filter(tool => nativeNames.has(tool.name))).toHaveLength(36)
+ 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
+ )
const target = `alpha__record__read_${String(count % 2 ? count - 1 : count - 2).padStart(3, '0')}`
expect(registry.get(target)).not.toBeNull()
const call =
@@ -289,7 +318,8 @@ describe('approved catalog across presentation and lifecycle', () => {
latch
)
const cold = await auto.refreshTools(registry.listDefinitions())
- expect(cold).toHaveLength(36)
+ const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)
+ expect(cold).toHaveLength(36 - oversized.size)
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 d84ba219c..3fbf22926 100644
--- a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts
@@ -237,6 +237,7 @@ describe('Codex presentation without access limits', () => {
mcpCount: 1,
presentedCount: all.length,
deferredCount: 0,
+ nativeDeferredCount: 0,
},
'Tool presentation selected'
)
@@ -253,6 +254,7 @@ describe('Codex presentation without access limits', () => {
mcpCount: 0,
presentedCount: native.length,
deferredCount: 0,
+ nativeDeferredCount: 0,
},
'Tool presentation selected'
)
@@ -329,3 +331,65 @@ 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__/toolCallBridge.test.ts b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts
index d384cf10a..b7d5fb0b8 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts
@@ -298,12 +298,12 @@ describe('clerum__tool_call bridge intercept', () => {
expect(real.calls).toHaveLength(0)
})
- it('rejects recursion: target is a native or another bridge tool', async () => {
+ it('rejects recursion into another bridge tool (LOCKED #11)', async () => {
const config = makeConfig({
tools: {},
bridge: bridgeContext(NATIVE, ['server__x']),
})
- for (const target of ['shell_exec', 'clerum__tool_call', 'clerum__tool_search']) {
+ for (const target of ['clerum__tool_call', 'clerum__tool_search', 'clerum__tool_describe']) {
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,6 +311,36 @@ 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 9aa350542..bb9a21c33 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
import {
parseCodexToolDiscoveryBytes,
parseCodexToolPresentation,
+ parseNativeToolDiscoveryBytes,
resolveToolPresentation,
} from '../toolPresentationPolicy'
@@ -41,6 +42,20 @@ 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/deferrableToolController.ts b/mcp-host/src/core/orchestration/deferrableToolController.ts
index 0b151aee8..02088feb2 100644
--- a/mcp-host/src/core/orchestration/deferrableToolController.ts
+++ b/mcp-host/src/core/orchestration/deferrableToolController.ts
@@ -3,9 +3,11 @@
* dynamic-tool-loading "stable bridge" design (Phase F3.1).
*
* When active, it removes all deferrable MCP tools from the advertised
- * `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`.
+ * `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.
*
* Why a decorator (delegate-first composition): the inner chain
* (`ApprovalController → UnifiedApprovalGateController` for interactive tasks,
@@ -19,6 +21,7 @@
* `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'
@@ -42,6 +45,7 @@ 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(
@@ -52,6 +56,7 @@ export class DeferrableToolController implements LoopController {
dynamicToolsThreshold: number
codexMode?: CodexToolPresentation
codexToolDiscoveryBytes?: number
+ nativeToolDiscoveryBytes?: number
},
latch: LatchStore
) {
@@ -62,6 +67,7 @@ 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 {
@@ -92,12 +98,18 @@ 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)
- const presented = discover ? upstream.filter(t => this.nativeNames.has(t.name)) : upstream
+ Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes ||
+ deferrableNatives.length > 0)
+ const presented = discover ? upstream.filter(t => !deferredNames.has(t.name)) : upstream
const measurement = {
mode: this.codexMode,
strategy: discover ? 'discovery' : 'direct',
@@ -105,6 +117,7 @@ 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) {
@@ -139,8 +152,24 @@ export class DeferrableToolController implements LoopController {
// Passthrough — identical to today's behavior (flag off / under threshold).
if (!bridgeActive) return upstream
- // 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))
+ // 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
}
}
diff --git a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
index 241c9d93f..cf3162aaa 100644
--- a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
+++ b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
@@ -16,6 +16,20 @@ export function parseCodexToolDiscoveryBytes(raw: string | undefined): number {
return Number(raw)
}
+/**
+ * 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.
+ */
+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')
+ }
+ return Number(raw)
+}
+
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 2d143948e..f065cc1cb 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
@@ -1,4 +1,5 @@
import { randomUUID } from 'crypto'
+import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'
import { extractToolIntent, getDisplayName } from '../../progress/intentExtraction.js'
import {
buildConnectRequiredApproval,
@@ -49,14 +50,6 @@ function buildGuardrailSuspension(
return { type: 'suspend', approval }
}
-/** The 3 dynamic-tool-loading bridge tools. They are native and must never be
- * the TARGET of `clerum__tool_call` (LOCKED #11 — no recursion). */
-const BRIDGE_TOOL_NAMES = new Set([
- 'clerum__tool_search',
- 'clerum__tool_describe',
- 'clerum__tool_call',
-])
-
function bridgeError(call: ToolCall, message: string): ToolResult {
// Preserve the original `call.id`/name so the provider pairs the result with
// the model's `clerum__tool_call` tool_use block (LOCKED #9).
@@ -77,6 +70,10 @@ 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.
*
* 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
@@ -123,18 +120,33 @@ function resolveBridgeCall(
return 'handled'
}
- // Reject recursion / native targets (LOCKED #11): the bridge targets
- // DEFERRABLE MCP tools only.
- if (BRIDGE_TOOL_NAMES.has(name) || bridge.nativeNames.has(name)) {
+ // Reject recursion (LOCKED #11): a bridge tool must never target another
+ // bridge tool, whatever its size or presentation.
+ if (BRIDGE_TOOL_NAMES.has(name)) {
toolResults.push(
bridgeError(
call,
- `clerum__tool_call cannot target "${name}": native and bridge tools are called directly, not through the bridge.`
+ `clerum__tool_call cannot target "${name}": bridge tools cannot invoke one another.`
)
)
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)) {
+ return {
+ id: call.id,
+ name,
+ arguments: (innerArgs as Record<string, unknown>) ?? {},
+ }
+ }
+
// 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/promptBuilder.ts b/mcp-host/src/core/reasoning/promptBuilder.ts
index 932e74f02..0b30ae78b 100644
--- a/mcp-host/src/core/reasoning/promptBuilder.ts
+++ b/mcp-host/src/core/reasoning/promptBuilder.ts
@@ -119,8 +119,8 @@ 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. Native tools are " +
- 'already available directly. Search narrowly for the current task; refine or page ' +
+ "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 ' +
'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 ' +
diff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts
new file mode 100644
index 000000000..567baaa5c
--- /dev/null
+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts
@@ -0,0 +1,80 @@
+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/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 368698bde..43d4a690a 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -15,6 +15,7 @@ import { createGfscClient, getGfsToolScopes } from '../../internalTools/gfsClien
import type { LlmProvider } from '../../llm/registryCore'
import type { McpManager } from '../../mcp/manager'
import type { IncomingMessage } from '../../server'
+import type { McpTool } from '../../types'
import { getOutputDir, resolveInternalTools } from '../../workflow/internalTools'
import type { InternalToolDefinition } from '../../workflow/types'
import { ScopedWorkspace } from '../../workspace/scopedWorkspace'
@@ -377,8 +378,9 @@ export class NativeToolRegistry implements ToolRegistry {
)
// F2/F3/F4 (dynamic-tool-loading): read-only discovery meta-tools + the
- // execution bridge. They query the live MCP catalog (McpManager.getAllTools())
- // on demand and never put schemas into the announced tools[] array.
+ // 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
@@ -386,7 +388,19 @@ export class NativeToolRegistry implements ToolRegistry {
// byte-identical to today and the presence-gated discovery guidance is not
// emitted by either prompt path.
if (mcpManager && dynamicToolsEnabled) {
- const getCatalog = () => mcpManager.getAllTools()
+ // #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',
+ })),
+ ]
this.register(
new InternalToolAdapter(
createToolSearchTool(getCatalog),