@myagentroam/agent 0.9.135 → 0.9.137

package/dist/tools/code-mode.js

@@ -1,13 +1,58 @@
 import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import { dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { StringDecoder } from 'node:string_decoder';
 import { MarAgentError, describeMarAgentError } from '../error.js';
 import { directLocalProcessExecutor, signalProcessTree } from '../host/local-process-executor.js';
 import { TOOL_EXECUTION_LIMITS as limits } from './execution-limits.js';
 import { createToolCallScheduler } from './scheduler.js';
 import { detectImageMime } from './view-image.js';
+import { allowsDirectTool, allowsToolCaller } from './callers.js';
+import { parseCodeModeStateMutations } from './code-mode/state.js';
 export const codeModeToolDefinition = {
     name: 'code_mode',
-    description: 'Run raw JavaScript in a fresh Node.js process to compose tool calls and process results in one model turn. Top-level await and dynamic Node module imports via await import(...) are supported. Call tools.NAME(input) using the available tool schemas; freeform tools accept their raw string. Results have content and optional data/images/truncated. Use Promise.all for independent calls and await dependencies. Runtime enforces safe/serial tool barriers. text(value) or console.log(value) emits selected output; image(value) emits one returned {mimeType,dataBase64} image. Tool errors reject with code/message and may be caught. Await every tool call; no JS state survives a cell. Whole-cell execution has the same Host policy hooks and OS permissions as exec, not a restricted JavaScript sandbox. Do not access or disclose secrets. Use tools for managed processes and tasks that must survive this cell; cell cleanup follows the Host process-tree mechanism and is not containment for detached descendants. Do not call code_mode recursively. Input max 1 MiB, emitted text max 1 MiB, max 128 nested calls, wall time 120 seconds. Output-limit and runtime failures do not roll back completed work.',
+    description: `Run JavaScript to orchestrate or compose tool calls.
+- Code Mode Only: call the programmatic tools listed below through tools.NAME inside this tool, including single-tool operations. They are omitted from the top-level tool list. Direct-only tools remain separate model tools and cannot be called here.
+- Use bounded combinations, parallel independent calls, and filtering of large intermediate results to reduce model round trips.
+- Evaluates source in a fresh restricted ECMAScript runtime with top-level await and Promise.all. It is not Node.js or a browser. JavaScript globals do not survive between cells; bounded JSON state is available through state.
+- Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences. Responses uses the source directly; Anthropic uses the code field of its tool input object. In either case, do not quote or fence the source again.
+- Use only standard ECMAScript built-ins and the explicitly documented tools, out, state, catalog and cell namespaces. Do not use Node.js, browser or Web APIs. Module imports, filesystem and network APIs are unavailable. Obtain external capabilities only through available tools. Use tools.exec for managed background processes when permitted.
+
+Tool calls:
+- tools.NAME(input) returns a Promise. Use the existing tool input schema; freeform tools such as apply_patch accept a raw string, not a JSON wrapper.
+- Results use the MAR envelope: { content: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string}>, truncated?: boolean }. content is rendered text, not raw file bytes. Use result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. Use only fields documented by that tool; do not invent success or ok flags.
+- Tool errors reject with code/message and may be caught. Await every call; unawaited calls fail the cell. Use Promise.all for independent calls and sequential await for dependencies. Runtime preserves safe/serial barriers and Host checks.
+- tool_search, question, code_mode and direct-only tools cannot be called here. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
+
+Built-in namespaces:
+- out.text(value): void emits text. Strings and scalar values are stringified; JSON-compatible objects/arrays are serialized as compact JSON. Cyclic or unsupported object values fail. Only explicitly emitted output reaches the model.
+- out.image(value: {mimeType:string,dataBase64:string}): void emits one returned image; for example out.image(result.images[0]) when that image exists and the model supports images. It does not accept a path, URL, or result.content.
+- state.get(key), state.has(key), state.set(key, value), state.delete(key) access bounded session JSON state. Mutations commit atomically only when the cell succeeds; failed or cancelled cells discard them.
+- catalog.tools() returns a read-only snapshot of the tools callable in this cell, including name, description, inputSchema and inputMode. It does not discover or authorize additional tools.
+- await cell.sleep(ms) performs a cancellable Host-side delay up to 30000 ms and remains subject to the cell deadline.
+- tools, out, state, catalog and cell are frozen bindings. Do not shadow their names.
+- Input/text output max 1 MiB, 128 calls, 120 seconds. Failures do not roll back completed tool work; do not replay successful operations blindly.
+
+Examples (copy the JavaScript source, not the fences; use only tools available in the current directory):
+Independent reads, emitting only source text:
+\`\`\`js
+const [a, b] = await Promise.all([
+  tools.read({ reads: [{ path: "a.txt" }] }),
+  tools.read({ reads: [{ path: "b.txt" }] })
+]);
+out.text({ a: a.data.results[0].text, b: b.data.results[0].text });
+\`\`\`
+Inspect before a dependent edit; successful await needs no invented success flag:
+\`\`\`js
+const inspected = await tools.read({ reads: [{ path: "source.txt" }] });
+const sourceText = inspected.data.results[0].text;
+if (!sourceText?.includes("original=1")) throw new Error("Unexpected source");
+const patched = await tools.apply_patch("*** Begin Patch\\n*** Update File: source.txt\\n@@\\n original=1\\n+updated=2\\n*** End Patch");
+out.text({ files: patched.data.files.length });
+\`\`\``,
     inputMode: 'freeform',
     inputSchema: {
         type: 'object',
@@ -15,71 +60,79 @@ export const codeModeToolDefinition = {
         required: ['code'],
         additionalProperties: false
     },
+    allowedCallers: ['direct'],
     parallelSafety: 'serial'
 };
-/** Render tool-owned result contracts without changing provider schemas or tool execution. */
-export function withCodeModeResultTypes(tools) {
-    if (!tools.some((tool) => tool.name === 'code_mode'))
-        return [...tools];
-    const declarations = [];
-    let bytes = 0;
-    for (const tool of tools) {
-        if (tool.name === 'code_mode' || !tool.outputSchema)
-            continue;
-        const declaration = `${JSON.stringify(tool.name)}: ${schemaType(tool.outputSchema)};`;
-        const size = Buffer.byteLength(declaration);
-        if (bytes + size > 16 * 1024)
-            continue;
-        declarations.push(declaration);
-        bytes += size;
-    }
-    const description = `${codeModeToolDefinition.description}
-
-tools.NAME(input) returns a result envelope, not its data fields directly. content is rendered tool text, not raw file bytes; read content includes line numbers and metadata. Tool-specific fields are in data (for example, an exec result uses result.data.exitCode and result.data.stdout). Names not listed below return { content: string; data?: unknown; images?: Array<{ mimeType: string; dataBase64: string }>; truncated?: boolean }.
-Return types for available tools; use their existing input schemas for arguments:
-\`\`\`ts
-type ToolResults = {
-${declarations.join('\n')}
-};
-\`\`\``;
-    return tools.map((tool) => (tool.name === 'code_mode' ? { ...tool, description } : tool));
+/** Deferred definitions travel in search results, not in the stable Code Mode description. */
+export function projectCodeModeTools(tools, residentTools = tools) {
+    const codeModeEnabled = tools.some((tool) => tool.name === 'code_mode' && allowsToolCaller(tool, 'direct'));
+    const direct = tools.filter((tool) => allowsDirectTool(tool, codeModeEnabled));
+    if (!codeModeEnabled)
+        return direct;
+    const programmatic = residentTools.filter((tool) => allowsToolCaller(tool, 'programmatic'));
+    const directory = JSON.stringify({
+        callableNames: programmatic.map((tool) => tool.name),
+        programmaticOnly: programmatic.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            inputMode: tool.inputMode ?? 'json'
+        }))
+    });
+    if (Buffer.byteLength(directory) > 32 * 1024)
+        throw new MarAgentError('MAR_AGENT_TOOL_EXPOSURE_LIMIT', 'Programmatic tool directory is too large.');
+    return direct.map((tool) => tool.name === 'code_mode'
+        ? {
+            ...tool,
+            description: `${codeModeToolDefinition.description}\nDeferred MCP definitions are returned by direct tool_search and become callable from the next model response, not later in the same response; they are not appended to this description.\nProgrammatic tools (call only inside code_mode): ${directory}`
+        }
+        : tool);
 }
-function schemaType(value, depth = 0) {
-    if (!value || typeof value !== 'object' || Array.isArray(value) || depth > 8)
-        return 'unknown';
-    const schema = value;
-    if (Array.isArray(schema.enum))
-        return (schema.enum
-            .slice(0, 32)
-            .map((item) => JSON.stringify(item))
-            .join(' | ') || 'unknown');
-    if (Array.isArray(schema.anyOf))
-        return (schema.anyOf
-            .slice(0, 8)
-            .map((item) => schemaType(item, depth + 1))
-            .join(' | ') || 'unknown');
-    if (Array.isArray(schema.type))
-        return schema.type
-            .slice(0, 8)
-            .map((type) => schemaType({ ...schema, type }, depth + 1))
-            .join(' | ');
-    if (schema.type === 'array')
-        return `Array<${schemaType(schema.items, depth + 1)}>`;
-    if (schema.type === 'object') {
-        const properties = schema.properties;
-        if (!properties || typeof properties !== 'object' || Array.isArray(properties))
-            return 'Record<string, unknown>';
-        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-        return `{ ${Object.entries(properties)
-            .slice(0, 32)
-            .map(([name, property]) => `${JSON.stringify(name)}${required.has(name) ? '' : '?'}: ${schemaType(property, depth + 1)};`)
-            .join(' ')} }`;
-    }
-    if (schema.type === 'integer' || schema.type === 'number')
-        return 'number';
-    return ['string', 'boolean', 'null'].includes(String(schema.type))
-        ? String(schema.type)
-        : 'unknown';
+/** Preserve native search definitions while providing the same discovery evidence to other protocols. */
+export function projectCodeModeSearchResult(message, codeModeEnabled) {
+    if (!message.toolSearchTools)
+        return message;
+    if (!codeModeEnabled)
+        return {
+            ...message,
+            toolSearchTools: message.toolSearchTools.filter((tool) => allowsToolCaller(tool, 'direct'))
+        };
+    const tools = message.toolSearchTools.map((tool) => ({
+        name: tool.name,
+        description: allowsToolCaller(tool, 'programmatic')
+            ? `Call only as tools.${tool.name} inside code_mode, never as a direct model tool.\n${tool.description}`
+            : tool.description,
+        inputSchema: tool.inputSchema,
+        inputMode: tool.inputMode ?? 'json',
+        caller: allowsToolCaller(tool, 'programmatic') ? 'programmatic' : 'direct'
+    }));
+    return {
+        ...message,
+        content: JSON.stringify({ tools }),
+        toolSearchTools: tools.map(({ caller: _caller, ...tool }) => tool)
+    };
+}
+function defaultEngineFactory() {
+    const core = import.meta.resolve('quickjs-emscripten-core');
+    const variant = import.meta.resolve('@jitl/quickjs-wasmfile-release-sync');
+    const ffi = pathToFileURL(createRequire(core).resolve('@jitl/quickjs-ffi-types')).href;
+    const dependencyRoot = (url) => {
+        const root = dirname(dirname(fileURLToPath(url)));
+        // pnpm's sibling dependencies are symlinks; keep the package-local node_modules tree visible.
+        return root.includes(`${sep}.pnpm${sep}`) ? dirname(dirname(root)) : root;
+    };
+    return {
+        moduleUrl: new URL('./code-mode/quickjs-engine.js', import.meta.url).href,
+        runtimeDirectories: [
+            ...new Set([
+                fileURLToPath(new URL('./code-mode/', import.meta.url)),
+                dependencyRoot(core),
+                dependencyRoot(variant),
+                dependencyRoot(ffi)
+            ])
+        ],
+        options: { coreModuleUrl: core, variantModuleUrl: variant }
+    };
 }
 const environmentKeys = [
     'PATH',
@@ -96,11 +149,13 @@ export class CodeModeTool {
     paths;
     environment;
     executor;
+    engineFactory;
     #active = new Map();
-    constructor(paths, environment = {}, executor = directLocalProcessExecutor) {
+    constructor(paths, environment = {}, executor = directLocalProcessExecutor, engineFactory = defaultEngineFactory()) {
         this.paths = paths;
         this.environment = environment;
         this.executor = executor;
+        this.engineFactory = engineFactory;
     }
     async execute(value, context) {
         const code = typeof value === 'string'
@@ -157,12 +212,13 @@ export class CodeModeTool {
                 `--max-old-space-size=${limits.codeHeapMegabytes}`,
                 '--input-type=module',
                 '--eval',
-                nodeCell
+                await readFile(new URL('./code-mode/worker.js', import.meta.url), 'utf8')
             ],
             cwd,
             shell: false,
             environment,
             environmentKeys: Object.keys(environment),
+            runtimeDirectories: this.engineFactory.runtimeDirectories,
             detached: process.platform !== 'win32',
             owner: { sessionId: context.sessionId, executionId: context.executionId },
             signal: context.signal
@@ -173,6 +229,7 @@ export class CodeModeTool {
         let transportBytes = 0;
         let calls = 0;
         let complete = false;
+        let stateMutations = [];
         let failure;
         let stderr = '';
         let buffered = '';
@@ -212,7 +269,9 @@ export class CodeModeTool {
             context.signal.throwIfAborted();
             return context.codeMode.invoke(call, context.signal);
         });
-        const available = new Set(context.codeMode.tools.map((tool) => tool.name));
+        const available = new Set(context
+            .codeMode.tools.filter((tool) => allowsToolCaller(tool, 'programmatic'))
+            .map((tool) => tool.name));
         const receive = (frame) => {
             if (complete)
                 throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent data after completion.');
@@ -266,6 +325,7 @@ export class CodeModeTool {
                 // Child completion cannot undo Host tool effects from calls it did not await.
                 if (pending.size)
                     throw new MarAgentError('MAR_AGENT_CODE_INCOMPLETE', 'Code Mode returned with unawaited tool calls; completed operations are not rolled back.');
+                stateMutations = parseCodeModeStateMutations(frame.stateMutations);
                 complete = true;
                 void signalProcessTree(child, 'SIGKILL').catch(fail);
             }
@@ -324,12 +384,39 @@ export class CodeModeTool {
             if (context.signal.aborted)
                 abort();
             else
-                await write({ code });
+                await write({
+                    code,
+                    tools: [...available],
+                    catalog: context
+                        .codeMode.tools.filter((tool) => available.has(tool.name))
+                        .map((tool) => ({
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                        inputMode: tool.inputMode ?? 'json'
+                    })),
+                    state: context.codeMode.state ?? [],
+                    engine: this.engineFactory,
+                    limits: {
+                        memoryBytes: limits.codeMemoryBytes,
+                        stackBytes: limits.codeStackBytes,
+                        timeoutMs: limits.codeTimeoutMs,
+                        outputBytes: limits.codeMaxOutputBytes,
+                        stateEntries: limits.codeStateMaxEntries,
+                        stateMutations: limits.codeStateMaxMutations,
+                        stateKeyBytes: limits.codeStateMaxKeyBytes,
+                        stateValueBytes: limits.codeStateMaxValueBytes,
+                        stateTotalBytes: limits.codeStateMaxTotalBytes,
+                        sleepMs: limits.codeSleepMaxMs
+                    }
+                });
             await exit;
             if (failure !== undefined)
                 throw failure;
             if (!complete)
                 throw new MarAgentError('MAR_AGENT_CODE_INCOMPLETE', 'Code Mode exited without a completion message.');
+            if (stateMutations.length)
+                await context.codeMode.commitState?.(stateMutations);
             return {
                 content: text.join('\n') || 'Code Mode completed without emitted text.',
                 data: { toolCalls: calls },
@@ -367,56 +454,3 @@ function parseImage(value) {
         throw invalid();
     return { mimeType: image.mimeType, dataBase64: image.dataBase64 };
 }
-// The cell runs only in a Host-managed child process, never in the credential-bearing runtime.
-const nodeCell = String.raw `
-import { createInterface } from 'node:readline';
-import { formatWithOptions } from 'node:util';
-const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
-const send = message => process.stdout.write(JSON.stringify(message) + '\n');
-const requests = new Map();
-let sequence = 0;
-const tools = new Proxy(Object.create(null), {
-  get: (_, name) => name === 'then' ? undefined : arguments_ => new Promise((resolve, reject) => {
-    const id = ++sequence;
-    requests.set(id, { resolve, reject });
-    send({ kind: 'call', id, name, arguments: arguments_ });
-  })
-});
-const format = value => {
-  if (typeof value === 'string') return value;
-  try {
-    const json = JSON.stringify(value);
-    if (json !== undefined) return json;
-  } catch {}
-  return formatWithOptions({ colors: false }, value);
-};
-const text = value => send({ kind: 'text', value: format(value) });
-const image = value => send({ kind: 'image', value });
-for (const name of ['log', 'info', 'warn', 'error', 'debug'])
-  console[name] = (...values) => text(formatWithOptions({ colors: false }, ...values));
-let started = false;
-lines.on('line', async line => {
-  try {
-    const frame = JSON.parse(line);
-    if (!started) {
-      started = true;
-      const AsyncFunction = Object.getPrototypeOf(async function() {}).constructor;
-      try {
-        await new AsyncFunction('tools', 'text', 'image', frame.code)(tools, text, image);
-        await new Promise(resolve => process.stdout.write(JSON.stringify({ kind: 'done' }) + '\n', resolve));
-      } catch (error) {
-        await new Promise(resolve => process.stdout.write(JSON.stringify({
-          kind: 'error', code: typeof error?.code === 'string' ? error.code : 'MAR_AGENT_CODE_FAILED',
-          message: String(error?.message ?? error)
-        }) + '\n', resolve));
-      }
-    } else {
-      const request = requests.get(frame.id);
-      if (!request) return;
-      requests.delete(frame.id);
-      if (frame.ok) request.resolve(frame.output);
-      else request.reject(Object.assign(new Error(frame.error.message), { code: frame.error.code }));
-    }
-  } catch { process.exit(1); }
-});
-`;

package/dist/tools/exec.js

@@ -5,6 +5,7 @@ import { MarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const execToolDefinition = {
     name: 'exec',
+    allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
     description: 'Unrestricted general system execution. Providing command starts any platform-native command, script, text/file tool, builder, generator, network client, or program in workspace/default cwd; action may be omitted for start. poll waits up to yieldMs for new output or termination and returns incremental stdout/stderr while running; after termination, poll returns a bounded cached result with earlier output for up to five minutes while the Session remains hosted. write sends stdin to running processes; cancel terminates a running process or removes a completed result. Returns status, processId, stdout/stderr, cumulative stdoutBytes/stderrBytes, per-result dropped bytes, exitCode, and truncated; a completed status does not imply exitCode 0. Always inspect stderr/exitCode and consume terminal output or cancel.',
     outputSchema: {

package/dist/tools/execution-limits.d.ts

@@ -21,7 +21,15 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     codeMaxTransportBytes: 67108864;
     codeMaxCalls: 128;
     codeMaxConcurrentCells: 4;
+    codeStateMaxEntries: 128;
+    codeStateMaxMutations: 128;
+    codeStateMaxKeyBytes: 256;
+    codeStateMaxValueBytes: 65536;
+    codeStateMaxTotalBytes: 1048576;
+    codeSleepMaxMs: 30000;
     codeHeapMegabytes: 128;
+    codeMemoryBytes: 33554432;
+    codeStackBytes: 524288;
     codeTimeoutMs: 120000;
     patchMaxBytes: 4194304;
     patchMaxFiles: 100;

package/dist/tools/execution-limits.js

@@ -21,7 +21,15 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     codeMaxTransportBytes: 67_108_864,
     codeMaxCalls: 128,
     codeMaxConcurrentCells: 4,
+    codeStateMaxEntries: 128,
+    codeStateMaxMutations: 128,
+    codeStateMaxKeyBytes: 256,
+    codeStateMaxValueBytes: 65_536,
+    codeStateMaxTotalBytes: 1_048_576,
+    codeSleepMaxMs: 30_000,
     codeHeapMegabytes: 128,
+    codeMemoryBytes: 33_554_432,
+    codeStackBytes: 524_288,
     codeTimeoutMs: 120_000,
     patchMaxBytes: 4_194_304,
     patchMaxFiles: 100,

package/dist/tools/local-registry.d.ts

@@ -1,3 +1,4 @@
+import type { CodeModeEngineFactory } from './code-mode/engine.js';
 import type { LocalProcessExecutor } from '../host/local-process-executor.js';
 import type { ToolCall, ToolExecutionContext, ToolExecutionResult } from '../sdk/types.js';
 import { type WorkspacePathMount } from './shared/path-resolver.js';
@@ -11,6 +12,7 @@ export declare class LocalToolRegistry {
         webFetch?: boolean;
         allowUntrustedTls?: boolean;
         processExecutor?: LocalProcessExecutor;
+        codeModeEngineFactory?: CodeModeEngineFactory;
         restrictPaths?: boolean;
         workspaceWritable?: boolean;
         pathMounts?: readonly WorkspacePathMount[];

package/dist/tools/local-registry.js

@@ -23,7 +23,7 @@ export class LocalToolRegistry {
         const viewImage = new ViewImageTool(paths);
         const patch = new ApplyPatchTool(paths);
         this.#exec = new ExecTool(paths, undefined, undefined, environment, shell, web.processExecutor);
-        this.#code = new CodeModeTool(paths, environment, web.processExecutor);
+        this.#code = new CodeModeTool(paths, environment, web.processExecutor, web.codeModeEngineFactory);
         this.#handlers = new Map([
             ['code_mode', (arguments_, context) => this.#code.execute(arguments_, context)],
             [

package/dist/tools/question.js

@@ -3,6 +3,7 @@ import { MarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const questionToolDefinition = {
     name: 'question',
+    allowedCallers: ['direct'],
     parallelSafety: 'serial',
     description: 'Pause for one to three tightly related user-owned decisions that materially change the result and cannot be inferred from the request, conversation, or relevant safe discovery. Prefer asking over guessing in Plan mode; do not avoid clarification by inventing configuration, branches, abstractions, or support for multiple outcomes. Provide 2-3 mutually exclusive options with consequences, put the recommended option first and identify it in its label or description, and use another question round if key ambiguity remains. This is not a permission/approval tool and should not interrupt routine in-scope work.',
     inputSchema: {

package/dist/tools/read.js

@@ -5,6 +5,7 @@ import { MarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const readToolDefinition = {
     name: 'read',
+    allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
     outputSchema: {
         type: 'object',

package/dist/tools/registry.js

@@ -13,8 +13,10 @@ import { executeTodoWrite, todoWriteToolDefinition } from './todo-write.js';
 import { webFetchToolDefinition } from './web-fetch.js';
 import { webSearchToolDefinition } from './web-search.js';
 import { executeSkill, skillToolDefinition } from './skill.js';
+import { executeToolSearch, toolSearchToolDefinition } from './tool-search.js';
 export const BUILTIN_TOOL_DEFINITIONS = [
     skillToolDefinition,
+    toolSearchToolDefinition,
     readToolDefinition,
     viewImageToolDefinition,
     execToolDefinition,
@@ -32,6 +34,7 @@ export const BUILTIN_TOOL_DEFINITIONS = [
 ];
 export const AGENT_TOOL_HANDLERS = new Map([
     ['skill', executeSkill],
+    ['tool_search', executeToolSearch],
     ['question', executeQuestion],
     ['todo_read', (_arguments, context) => executeTodoRead(context)],
     ['todo_write', executeTodoWrite],

package/dist/tools/runtime-context.d.ts

@@ -47,5 +47,7 @@ export interface ToolRuntimeContext {
     codeMode?: import('../sdk/types.js').ToolExecutionContext['codeMode'];
     skills: ReadonlyMap<string, AgentSkill>;
     recentImages?: readonly ToolRuntimeImage[];
+    searchMcpTools?: (input: unknown, signal: AbortSignal) => Promise<import('../sdk/types.js').ToolExecutionResult>;
+    expectedMcpTool?: import('../sdk/types.js').McpToolCallContext['expectedTool'];
     emit(event: ToolRuntimeEvent): Promise<void>;
 }

package/dist/tools/runtime.js

@@ -10,7 +10,9 @@ export async function executeRegisteredTool(name, arguments_, callId, context) {
             throw new MarAgentError('MAR_AGENT_MCP_FAILED', 'MCP execution is unavailable.');
         return context.host.callMcpTool(call, context.signal, {
             sessionId: context.sessionId,
-            executionId: context.executionId
+            executionId: context.executionId,
+            mode: context.mode,
+            ...(context.expectedMcpTool ? { expectedTool: context.expectedMcpTool } : {})
         });
     }
     return context.host.executeTool(call, {

package/dist/tools/skill.js

@@ -2,6 +2,7 @@ import { MarAgentError } from '../error.js';
 import { agentSkillSource, loadAgentSkill } from '../runtime/instructions.js';
 export const skillToolDefinition = {
     name: 'skill',
+    allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
     description: 'Load a specialized Skill when the task matches one listed in the system prompt. Returns its instructions and source; file-based Skills also include a base directory and resource-path sample. Host-provided skills have no filesystem base. The name must exactly match the advertised catalog.',
     inputSchema: {

package/dist/tools/todo-read.js

@@ -1,5 +1,6 @@
 export const todoReadToolDefinition = {
     name: 'todo_read',
+    allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
     description: 'Read this session’s current Todo revision and items. Use before updating when the revision may have changed. Do not read an empty or new Todo merely to decide whether straightforward bounded work needs one.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false }

package/dist/tools/todo-write.js

@@ -2,6 +2,7 @@ import { MarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const todoWriteToolDefinition = {
     name: 'todo_write',
+    allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'serial',
     description: 'Replace this session’s entire Todo list using optimistic expectedRevision. Preserve stable IDs and statuses only when extending the same objective. For a materially different objective, include only the new objective’s items. Do not retain completed items from an earlier objective; when all current items are completed, default a substantive new request to replacement unless the user explicitly asks to continue, extend, verify, or follow up. Use only after Todo has been chosen for coordination-heavy work; straightforward bounded work does not need it. Keep at most one in_progress item and update statuses after meaningful stage changes. When another substantive tool call is already ready and does not depend on the Todo result, include both in the same model response instead of spending a response only for Todo bookkeeping.',
     inputSchema: {

package/dist/tools/tool-search.d.ts

@@ -0,0 +1,43 @@
+import type { ClientToolDefinition } from '../model/contracts.js';
+import type { McpCatalogTool, McpToolCatalog, ToolExecutionResult } from '../sdk/types.js';
+import type { ToolRuntimeContext } from './runtime-context.js';
+export declare const TOOL_SEARCH_LIMITS: Readonly<{
+    defaultLimit: 5;
+    maximumLimit: 20;
+    queryBytes: 4096;
+    catalogBytes: number;
+    maximumDefinitionTokens: 16384;
+    definitionWindowFraction: 0.25;
+    minimumContinuationTokens: 1024;
+}>;
+export declare const toolSearchToolDefinition: ClientToolDefinition;
+export declare function parseToolSearchInput(input: unknown): {
+    query: string;
+    limit: number;
+};
+/** Deferred discovery state reconstructed from the current post-GC model history. */
+export declare class DeferredMcpRegistry {
+    #private;
+    constructor(discoveredNames: readonly string[]);
+    restore(discoveredNames: readonly string[]): void;
+    update(catalog: McpToolCatalog, eligible: (tool: McpCatalogTool) => boolean): void;
+    get hasDeferred(): boolean;
+    snapshot(): readonly string[];
+    expectedTool(name: string): {
+        sourceIdentity: string;
+        definitionRevision: string;
+    } | undefined;
+    restoredDefinitions(names: readonly string[]): readonly ClientToolDefinition[];
+    projectDirect(base: readonly ClientToolDefinition[]): ClientToolDefinition[];
+    project(base: readonly ClientToolDefinition[], selection?: readonly string[], executionSelection?: Set<string>): ClientToolDefinition[];
+    search(query: string, limit: number): McpCatalogTool[];
+    expose(input: unknown, context: {
+        signal: AbortSignal;
+        base: readonly ClientToolDefinition[];
+        window: number;
+        system: string;
+    }): Promise<ToolExecutionResult>;
+    assertBudget(base: readonly ClientToolDefinition[], window: number, system: string, selection?: readonly string[], executionSelection?: ReadonlySet<string>): void;
+    navigation(): string | undefined;
+}
+export declare function executeToolSearch(input: unknown, context: ToolRuntimeContext): Promise<ToolExecutionResult>;