@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/node/tools/create-colleague-tool.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CreateColleague —— agent 自主建同事（自治组队第一步）。
+ *
+ * 建的是 `~/.codebuddy/agent-home/directory.json` 里的 AgentHomeProfile：
+ * 没有 job，等有人 @ / 派任务时才被唤醒起 job。
+ * 规则（配额 / 深度 / 频率）全在 agent-home-agent-create，工具只做映射。
+ */
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { SettingsManager } from '../settings/settings-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolNames, ToolResult } from './tool-protocol';
+export declare class CreateColleagueTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly settingsManager?: SettingsManager;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    shouldShowInToolSearch: () => boolean;
+    parameters: z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        engine: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        permissionMode: z.ZodOptional<z.ZodString>;
+        homeCwd: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+        title?: string | undefined;
+        model?: string | undefined;
+        permissionMode?: string | undefined;
+        engine?: string | undefined;
+        homeCwd?: string | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+        title?: string | undefined;
+        model?: string | undefined;
+        permissionMode?: string | undefined;
+        engine?: string | undefined;
+        homeCwd?: string | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    toAutoClassifierInput(_input: unknown): string;
+    isEnabled: (args?: {
+        runContext?: RunContext<Session>;
+        agent?: {
+            name?: string;
+        };
+    }) => Promise<boolean>;
+    execute(input: {
+        name?: string;
+        title?: string;
+        description?: string;
+        engine?: string;
+        model?: string;
+        permissionMode?: string;
+        homeCwd?: string;
+    }, context?: RunContext<Session>): Promise<ToolResult>;
+}

package/cli/dist-server/types/node/tools/cron-create-tool.d.ts

@@ -0,0 +1,46 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { CronCreateFullSchema } from '../../workspace/cbc-cron/lib/node/index.js';
+import { Agent, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+export declare class CronCreateTool extends BaseTool implements Tool {
+    private readonly stateManager;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        cron: z.ZodString;
+        prompt: z.ZodString;
+        recurring: z.ZodOptional<z.ZodBoolean>;
+        durable: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        prompt: string;
+        cron: string;
+        recurring?: boolean | undefined;
+        durable?: boolean | undefined;
+    }, {
+        prompt: string;
+        cron: string;
+        recurring?: boolean | undefined;
+        durable?: boolean | undefined;
+    }>;
+    strict: boolean;
+    /**
+     * Session-only 任务随会话消亡、副作用可控，无需授权。durable 任务会写盘并在
+     * 无人值守的任务会话里反复执行，属于持久化副作用，每次创建都必须过一次审批。
+     */
+    needsApproval: (_runContext: RunContext<Session>, input: z.infer<typeof CronCreateFullSchema>) => Promise<boolean>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (_args: {
+        runContext: RunContext<Session>;
+        agent: Agent;
+    }) => Promise<boolean>;
+    /**
+     * Auto mode classifier projection: `${cron}: ${prompt}` (Claude alignment,
+     * decision D1) — a scheduled/delayed-execution action; the prompt is the
+     * deferred risk. Consumed in history (CronCreate has `needsApproval = false`).
+     */
+    toAutoClassifierInput(input: unknown): string;
+    execute(input: z.infer<typeof CronCreateFullSchema>, _context?: RunContext<Session>): Promise<ToolResult>;
+}

package/cli/dist-server/types/node/tools/cron-delete-tool.d.ts

@@ -0,0 +1,28 @@
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { CronDeleteSchema } from '../../workspace/cbc-cron/lib/node/index.js';
+import { Agent } from '../../vendor/cbc-shared/node/index.js';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+export declare class CronDeleteTool extends BaseTool implements Tool {
+    private readonly stateManager;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+    }, {
+        id: string;
+    }>;
+    strict: boolean;
+    needsApproval: boolean;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (_args: {
+        runContext: RunContext<Session>;
+        agent: Agent;
+    }) => Promise<boolean>;
+    execute(input: z.infer<typeof CronDeleteSchema>, _context?: RunContext<Session>): Promise<ToolResult>;
+}

package/cli/dist-server/types/node/tools/cron-list-tool.d.ts

@@ -0,0 +1,27 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { Agent, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext } from '@openai/agents';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+/** Max prompt length shown in a CronList line before truncating with an ellipsis. */
+export declare const CRON_LIST_PROMPT_PREVIEW_LENGTH = 80;
+/**
+ * Truncate a job's prompt to the preview length shown in CronList output.
+ * Anything relying on this preview being visible (e.g. the /loop marker
+ * lookup in loop-skill-provider.ts) must stay within this length.
+ */
+export declare function truncatePromptPreview(prompt: string): string;
+export declare class CronListTool extends BaseTool implements Tool {
+    private readonly stateManager;
+    name: ToolNames;
+    description: string;
+    parameters: import("zod").ZodObject<{}, "strict", import("zod").ZodTypeAny, {}, {}>;
+    strict: boolean;
+    needsApproval: boolean;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (_args: {
+        runContext: RunContext<Session>;
+        agent: Agent;
+    }) => Promise<boolean>;
+    execute(_input?: unknown, _context?: RunContext<Session>): Promise<ToolResult>;
+}

package/cli/dist-server/types/node/tools/defer-execute-tool.d.ts

@@ -0,0 +1,265 @@
+import { AgentManager, Session, SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { type FunctionCallItem, RunContext, ToolExecuteArgument, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { AcpBroadcastService } from '../acp/acp-protocol';
+import { AgentScopedMcpManager, McpConfigManager, McpManager } from '../mcp/mcp-protocol';
+import { BaseTool } from './base-tool';
+import { DeferToolConfigService } from './defer-tool-config-protocol';
+import { Tool, ToolCallArgumentRenderer, ToolManager, ToolResult } from './tool-protocol';
+import { ToolSearchService } from './tool-search-protocol';
+import { AgentToolDeferOverlayCache } from './tool-spec';
+/**
+ * Parameters for the DeferExecuteTool
+ */
+declare const DeferExecuteParameters: z.ZodObject<{
+    toolName: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    params: Record<string, any>;
+}, {
+    toolName: string;
+    params: Record<string, any>;
+}>;
+/**
+ * Proxy tool for executing deferred-loading tools without injecting their
+ * definitions into the LLM tools list.
+ *
+ * Supports built-in deferred tools (e.g., ImageGen, LSP), canonical MCP tools
+ * (`mcp__server__tool`), and bare-name MCP tools from transparent proxy.
+ *
+ * Tool Enable & SDK Filtering:
+ * Built-in deferred tools use the AgentManager wrapped isEnabled chain, including
+ * defer activation bypass, original tool availability, SDK allow/deny options,
+ * delegate-mode restrictions, and other visibility gates.
+ *
+ * Deferred MCP tools are not listed in agent.tools. They bypass the agent tool-name
+ * filter here, but are still subject to the subagent MCP whitelist
+ * (McpSubagentToolManager, when the agent registered one) and to
+ * ToolPermissionService deny/approval checks before execution.
+ *
+ * Flow:
+ * 1. Model calls ToolSearch → gets tool name, description, and full parameter schema
+ * 2. Model calls DeferExecuteTool({ toolName, params }) → checks isEnabled + SDK filters
+ * 3. If tool passes all checks, validates params against schema and delegates to the real tool
+ *
+ * This keeps the LLM context prefix (system prompt + tools list) stable,
+ * maximizing KV cache hit rate on providers that support prefix caching.
+ */
+export declare class DeferExecuteTool extends BaseTool implements Tool {
+    protected readonly toolManager: ToolManager;
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly deferToolConfigService: DeferToolConfigService;
+    protected readonly agentToolDeferOverlayCache: AgentToolDeferOverlayCache;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    isEnabled: () => Promise<boolean>;
+    parameters: z.ZodObject<{
+        toolName: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        toolName: string;
+        params: Record<string, any>;
+    }, {
+        toolName: string;
+        params: Record<string, any>;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    protected readonly mcpManager: McpManager;
+    protected readonly agentScopedMcpManager: AgentScopedMcpManager;
+    protected readonly mcpConfigManager: McpConfigManager;
+    protected readonly sessionManager: SessionManager;
+    protected readonly agentManager: AgentManager;
+    /**
+     * Optional because ACP only exists when the CLI runs as an ACP backend
+     * (Web UI, IDE, workbuddy-desktop). In SDK / headless mode this stays undefined
+     * and MCP progress is silently dropped — same as before this feature existed.
+     */
+    protected readonly acpBroadcastService?: AcpBroadcastService;
+    private ajv;
+    private validateCache;
+    /**
+     * Override needsApproval to support dual-mode permission matching:
+     *
+     * Phase 1: Check DeferExecuteTool's own permission rules.
+     *   Supports rules like "DeferExecuteTool(*)" and "DeferExecuteTool(TeamCreate)".
+     *   The targetToolName is passed as a Command arg so that
+     *   "DeferExecuteTool(TeamCreate)" matches via matchCommandRule.
+     *
+     * Phase 2: Delegate to the target tool's permission check.
+     *   Supports rules like "TeamCreate" and "TeamCreate(*)".
+     *   This ensures each target tool's own permission rules still apply.
+     */
+    needsApproval: (runContext: RunContext<Session>, input: ToolExecuteArgument<any>, callId?: string) => Promise<boolean>;
+    /**
+     * Fallback: check permission against DeferExecuteTool itself.
+     */
+    private defaultNeedsApproval;
+    private isMandatoryApprovalEnabled;
+    execute(input: z.infer<typeof DeferExecuteParameters>, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /**
+     * Public routing entry for callers outside the LLM tool-call path — currently the
+     * REPL sandbox, whose preloaded tool globals dispatch through here.
+     *
+     * Differs from {@link execute} in two ways, both required by the REPL:
+     *  1. **No deferred-index requirement.** The sandbox preloads *all* session tools,
+     *     including non-deferred builtins (Bash/Read/...) that are absent from the
+     *     ToolSearchService index. `execute` rejects those with "not found".
+     *  2. **No param validation against the index.** Schema validation happens inside
+     *     each execution path; the index may not hold a schema for inline builtins.
+     *
+     * Tool-availability filtering (`--tools` / agent whitelist) IS enforced here via
+     * `checkToolAllowed`, same as {@link execute} — otherwise the REPL sandbox could
+     * invoke a builtin (e.g. Bash) that the whitelist excludes, bypassing `--tools`.
+     *
+     * Interactive *permission* (approval prompting) is NOT done here — the caller must
+     * run `checkPermission` itself (the REPL broker does, see mcp-code-mode-design.md
+     * §4.8). Keeping approval outside avoids double-prompting when a caller has its own
+     * approval semantics. Availability filtering and approval are distinct gates.
+     */
+    routeToolCall(toolName: string, params: Record<string, unknown>, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /**
+     * Execute a built-in deferred tool via ToolManager.
+     */
+    private executeBuiltinTool;
+    /**
+     * Execute an MCP tool via the MCP server's callTool method.
+     *
+     * MCP tools are not managed by ToolManager; they live on MCPServer instances.
+     * Deferred MCP names can be canonical "mcp__serverName__rawToolName" or
+     * bare names from transparent proxy, such as "connect_cloud_service".
+     *
+     * When `toolCallId` is available (i.e. running under an ACP backend) and an
+     * `AcpBroadcastService` is wired, we install an `__onProgress` callback in
+     * `meta` so MCP server progress notifications are broadcast as ACP
+     * `tool_call_update` events with `metaData.mcpProgress`. The MCP renderer
+     * (cb-chat-ui) reads that field and shows live progress in the UI.
+     */
+    private executeMcpTool;
+    /**
+     * 解析本次工具调用应透传的模型 ID。
+     *
+     * 优先级对齐 ModelConfigAgentRunInterceptor：
+     *   session.requestOptions.model（运行时切模型：SDK set_model / ACP 切模型 / 命令 frontmatter）
+     *   > session.options.model（--model 启动参数）
+     *   > agent 默认模型（headless/-p 场景下前两者通常为空，这里回退保证 modelId 不丢）。
+     *
+     * agent 默认模型解析失败时静默返回 undefined：modelId 透传是“尽力而为”，
+     * 不应因取模型失败而阻断工具调用。
+     */
+    private resolveCurrentModelId;
+    /**
+     * Convert MCP CallToolResultContent to ToolResult.
+     *
+     * @param content   工具返回的 content 数组（text/image/resource 块）
+     * @param resultMeta CallToolResult 顶层的 structuredContent / _meta（经 sideband sink 捞回）。
+     *                   存在 MCP Apps `_meta.ui` 等扩展时，挂到结果上供下游 ACP 透传渲染。
+     */
+    private convertMcpResult;
+    /**
+     * MCP Apps（io.modelcontextprotocol/ui）：委托共享广播实现。
+     * 直连 FunctionTool 路径由 mcp-server-manager.callTool 出口同样调用该实现（#80575）。
+     */
+    private maybeBroadcastMcpUi;
+    /**
+     * Unified builtin deferred tool filtering check using getAllowedToolsForAgent.
+     * MCP deferred tools, including bare-name transparent-proxy tools, bypass this
+     * agent tool-name filter, but `mcp__` tools are still gated by the subagent MCP
+     * whitelist (McpSubagentToolManager) when the current agent registered one.
+     *
+     * Returns a ToolResult error if blocked, or undefined if allowed.
+     */
+    private checkToolAllowed;
+    /**
+     * Normalize the nested `params` field before validation/dispatch.
+     *
+     * Weaker models sometimes double-encode this object field as a JSON string
+     * (e.g. emit `params: "{}"` instead of `params: {}`). Since the SDK only
+     * JSON.parses the outer tool arguments and does not coerce nested fields,
+     * such a string would reach validateParams and fail with "root: must be
+     * object", breaking every MCP tool routed through DeferExecuteTool.
+     *
+     * Only a string that parses into a plain object is unwrapped. Anything else
+     * (already an object, or a string that is not a JSON object) is returned
+     * unchanged so validateParams can still surface the original schema error.
+     */
+    private normalizeParams;
+    /**
+     * Recover long numeric IDs whose precision `JSON.parse` already destroyed.
+     *
+     * A JSON integer beyond `Number.MAX_SAFE_INTEGER` cannot survive parsing:
+     * `1070198486138087566` becomes `1070198486138087600`, so the downstream tool
+     * looks up a resource that does not exist. The exact digits only survive in the
+     * raw tool-call arguments, so walk the raw JSON tree and put the original
+     * literal back — as a string — before validation.
+     *
+     * No schema gate is applied. AJV runs next with `coerceTypes`, so a field the
+     * schema declares as number is coerced straight back to a number (unchanged
+     * behavior), while string-typed and schema-free fields keep the exact digits.
+     * Gating on "schema says string" would miss the common proxy shape, where the
+     * real business params are nested inside a free-form object (e.g. a connector's
+     * `proxy_execute_tool(tool_name, tool_args)`) that the proxy schema declares
+     * only as `type: object` and therefore says nothing about the inner ID.
+     */
+    private restoreUnsafeIntegerLiterals;
+    /**
+     * Walk a parsed container in lockstep with its raw JSON node. Recursion is
+     * required because the corrupted ID is frequently nested: proxy tools carry
+     * business params inside a free-form object, and batch APIs carry them in arrays.
+     */
+    private restoreUnsafeIntegersIn;
+    private restoreUnsafeIntegerAt;
+    private isPlainObject;
+    private isDeferExecuteToolCall;
+    private parseRawParamsNode;
+    private shouldRestoreUnsafeInteger;
+    /**
+     * Validate params against a JSON Schema.
+     * Returns a ToolResult with a detailed error message if validation fails, or undefined if valid.
+     */
+    private validateParams;
+    private formatValidationError;
+    private describeType;
+    private collectTypesByJsonPointer;
+    private valueAtJsonPointer;
+    private describeExpectedType;
+    /**
+     * Parse the deferred MCP tool name format without importing mcp-utils, which
+     * pulls in debug/session modules during isolated unit tests.
+     */
+    private parseMcpToolFullName;
+    /**
+     * Convert a bare-name MCP tool to the canonical mcp__server__tool name for permission matching.
+     */
+    private getMcpPermissionToolName;
+    /**
+     * 透明代理回退：当虚拟 server name（如 'playwright'）在 connectedServers 中不存在时，
+     * 查找声明了对应 server/tool 路由的 transparent_proxy server。
+     *
+     * 兜底匹配策略（顺序，issue #49128）：
+     * 1. 静态 toolsConfig 路由命中（启动期 mcp-config 显式声明 server_name 映射）—— 最强
+     * 2. 运行期热补 toolsConfig 路由命中（mcp-server-manager 在 tools/list 响应里
+     *    根据 _meta.serverName 写入的同 server_name 条目，issue #33921）—— 次强
+     * 3. 透明代理回退（任意 transparent_proxy: true 的 server）—— 兜底，应对
+     *    set(DYNAMIC) 反复覆盖 toolsConfig 导致两层路由都 miss 的间隙
+     *
+     * 路径 3 的安全性论证：
+     * - 只对 mcp__<X>__<Y> 形态的调用生效（caller 已经判定 isPrefixedMcpTool）
+     * - 透明代理 server (connector-proxy) 的 callTool 反向路由
+     *   (mcp-server-manager.ts:364-368) 会把 mcp__lexiang__xxx 转回 lexiang_xxx
+     *   传给 proxy；proxy 内部按 short name 找到 client，找不到就返回 MCP error，
+     *   等价于 "工具未连接" 的语义错误，不会越权调到其它 server
+     * - 路径 1/2 命中时不进入 3，所以 ardot / netdrive 显式预塞的兜底语义保留
+     */
+    private findTransparentProxyServer;
+    /**
+     * 裸名 MCP 工具没有 server 前缀，只能通过 transparent_proxy 配置定位实际 MCP server。
+     */
+    private findTransparentProxyServerForBareTool;
+}
+export {};

package/cli/dist-server/types/node/tools/defer-tool-config-protocol.d.ts

@@ -0,0 +1,88 @@
+import { McpConfig } from '../mcp/mcp-protocol';
+import type { ToolDeferOverlay } from './tool-spec';
+export declare const DeferToolConfigService: unique symbol;
+/**
+ * Maximum number of deferred tools to display with full description.
+ * Tools beyond this limit will only show their names.
+ * @deprecated Kept for shouldShowAllTools compatibility. Use DEFAULT_DEFERRED_TOOLS_CHAR_BUDGET instead.
+ */
+export declare const DEFAULT_MAX_TOOLS_WITH_DESCRIPTION = 50;
+/**
+ * Character budget for the deferred tools description block.
+ * Controls the total size of the formatted tool list injected into the system prompt.
+ * Overridable via environment variable CODEBUDDY_DEFERRED_TOOLS_CHAR_BUDGET.
+ *
+ * ~20000 chars ≈ ~5000 tokens — enough for ~15 MCP servers with ~10 tools each.
+ */
+export declare const DEFAULT_DEFERRED_TOOLS_CHAR_BUDGET = 20000;
+/**
+ * Maximum characters for a single MCP server description in the group header.
+ * Descriptions longer than this are truncated with "…".
+ */
+export declare const MCP_SERVER_DESC_MAX_CHARS = 100;
+/**
+ * Service for managing deferred tool loading configuration.
+ *
+ * Configuration priority (highest to lowest):
+ * 0. Claude-compatible server `alwaysLoad: true` hard guarantee
+ * 1. Session-scoped overlay (Defer(...) / NoDefer(...) modifiers from --tools / agent frontmatter)
+ * 2. Tool-level MCP config (tools[name].defer_loading)
+ * 3. Server-level MCP config (defer_loading)
+ * 4. Environment variable (CODEBUDDY_DEFER_TOOL_LOADING)
+ * 5. Settings (deferToolLoading)
+ * 6. Product default (true)
+ *
+ * Within the overlay, `NoDefer(...)` wins over `Defer(...)` — explicit opt-out
+ * is the strongest user intent.
+ */
+export interface DeferToolConfigService {
+    /**
+     * Check if global defer loading is enabled.
+     * Respects configuration priority: env var > settings > product default.
+     */
+    isGlobalDeferLoadingEnabled(): Promise<boolean>;
+    /**
+     * Check if the deferred-tools prompt listing should bypass the character budget.
+     * When enabled, all server groups are included, but per-tool formatting stays unchanged.
+     * Configurable via environment variable CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS.
+     */
+    shouldShowAllTools(): boolean;
+    /**
+     * Calculate effective defer loading status for an MCP tool.
+     *
+     * Backward-compatible shim: equivalent to {@link isToolDeferLoadingWithOverlay}
+     * with `overlay = undefined`.
+     *
+     * @param config MCP server configuration
+     * @param toolNames Tool name candidates in priority order (e.g. rawToolName, original tool.name)
+     */
+    isToolDeferLoading(config: McpConfig, ...toolNames: string[]): Promise<boolean>;
+    /**
+     * Overlay-aware version of {@link isToolDeferLoading}. The first toolName
+     * matched by the overlay wins (force-no-defer beats force-defer beats all
+     * other sources except the server-wide `alwaysLoad` hard guarantee).
+     *
+     * @param overlay  Session-scoped overlay; `undefined` falls back to the legacy path.
+     * @param config   MCP server configuration.
+     * @param toolNames Tool name candidates in priority order.
+     */
+    isToolDeferLoadingWithOverlay(overlay: ToolDeferOverlay | undefined, config: McpConfig, ...toolNames: string[]): Promise<boolean>;
+    /**
+     * Effective defer status for a *builtin* (non-MCP) tool.
+     *
+     * Priority:
+     * 1. Session overlay (NoDefer wins over Defer).
+     * 2. Product default (i.e. `Tool.defer_loading` populated from
+     *    `product.tools[].deferLoading` by ToolManager).
+     *
+     * The global `isGlobalDeferLoadingEnabled` switch is *not* consulted here —
+     * callers (agent-manager.createIsEnabledChecker) gate on it separately so
+     * that a single global "off" toggle continues to disable the entire
+     * deferred-loading machinery without forcing every callsite to query both.
+     *
+     * @param toolName        Tool name (e.g. `Read`, `Glob`).
+     * @param productDefault  Static defer flag from product config.
+     * @param overlay         Session-scoped overlay; `undefined` is treated as EMPTY.
+     */
+    isBuiltinToolDeferLoading(toolName: string, productDefault: boolean, overlay: ToolDeferOverlay | undefined): boolean;
+}

package/cli/dist-server/types/node/tools/defer-tool-config-service.d.ts

@@ -0,0 +1,23 @@
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { McpConfig } from '../mcp/mcp-protocol';
+import { SettingsManager } from '../settings/settings-protocol';
+import { DeferToolConfigService } from './defer-tool-config-protocol';
+import { ToolDeferOverlay } from './tool-spec';
+export declare class DeferToolConfigServiceImpl implements DeferToolConfigService {
+    protected readonly settingsManager: SettingsManager;
+    protected readonly productManager: ProductManager;
+    isGlobalDeferLoadingEnabled(): Promise<boolean>;
+    shouldShowAllTools(): boolean;
+    isToolDeferLoading(config: McpConfig, ...toolNames: string[]): Promise<boolean>;
+    isToolDeferLoadingWithOverlay(overlay: ToolDeferOverlay | undefined, config: McpConfig, ...toolNames: string[]): Promise<boolean>;
+    isBuiltinToolDeferLoading(toolName: string, productDefault: boolean, overlay: ToolDeferOverlay | undefined): boolean;
+    /**
+     * Parse environment variable as boolean.
+     * Supports: true/false/1/0 (case-insensitive)
+     */
+    private parseEnvBoolean;
+    /**
+     * Get defer tool loading config from product.json productFeatures
+     */
+    private getProductConfig;
+}

package/cli/dist-server/types/node/tools/deferred-tool-bridge.d.ts

@@ -0,0 +1,50 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+/**
+ * Coerce the SDK's parsed input to a plain object usable as DeferExecuteTool's `params`.
+ * The SDK parses tool arguments through the schema, so `input` is usually an object.
+ * Guard against string/undefined edge cases.
+ *
+ * 关键：部分模型 / streaming 路径会把 arguments 以 JSON **字符串**交给
+ * `parameters.parse()`。若 schema 是裸 `z.object(...)`，会在 invoke 之前就抛
+ * `Expected object, received string`，直调 deferred MCP 工具失败；模型再走
+ * DeferExecuteTool 重试。对非幂等工具（如 ardot create_design）会叠加 Host
+ * bootstrap，远端创建两份文件。
+ */
+export declare function coerceDeferredToolParams(input: unknown): Record<string, any>;
+/** SDK `parameters.parse` 用：接受 object 或 JSON string，统一成 plain object。 */
+export declare const deferredToolParametersSchema: z.ZodEffects<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, unknown>;
+/**
+ * Bridge that registers `globalThis.__codebuddyResolveDeferredTool`.
+ *
+ * When the SDK's tool-resolution loop (`resolveFunctionOrHandoff` in the patched
+ * @openai/agents-core) fails to find a tool in the functionMap, the patch consults
+ * this bridge. If the bridge returns a synthetic FunctionTool, the SDK executes it
+ * transparently — no ModelBehaviorError, no wasted round-trip, no user-visible error.
+ *
+ * The synthetic tool wraps the original call parameters and routes through
+ * `DeferExecuteTool.execute()`, reusing all existing logic (param validation, MCP
+ * routing, ACP broadcast, permission checks).
+ *
+ * **Code Mode 例外（Issue #123022）**：Code Mode（PTC / Minimal / 协调器 overlay）
+ * 下 REPL 是唯一直连工具，这条桥必须让位——`invoke` 检测到 Code Mode 就不再执行，
+ * 改为返回 Code Mode 引导（把工具指回 REPL 沙箱）；`needsApproval` 同步短路，
+ * 避免空审批弹窗。overlay 轮沙箱本就不收 MCP，重叠由派出的子代理承接。
+ */
+export declare class DeferredToolBridge {
+    protected readonly logger: Logger;
+    /**
+     * Registers the global resolver bridge. Called once during CellJS container init.
+     * Uses lazy ContainerUtil access at RESOLUTION time to avoid circular DI.
+     */
+    init(): void;
+    /**
+     * Build a synthetic SDK-compatible FunctionTool for the given deferred tool.
+     * The `invoke` method wraps the original arguments into DeferExecuteTool's
+     * `{ toolName, params }` shape and delegates execution.
+     *
+     * `sandboxCallName` = 该工具在 REPL 沙箱里的准确调用名（延迟索引的
+     * serverName/rawToolName 拼出）；Code Mode 拒绝直连时用它给引导。
+     */
+    private buildSyntheticTool;
+}

package/cli/dist-server/types/node/tools/delegate-tool.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Delegate Tool - Executes tools delegated from client-side tool providers
+ *
+ * This tool enables the agent to invoke tools that are provided by external
+ * client-side tool providers (e.g., IDE extensions, plugins). The actual tool
+ * execution happens on the client side via the ACP delegateTool extension method.
+ */
+import { Logger } from '@celljs/core';
+import { z } from 'zod';
+import { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+/**
+ * Schema for delegate tool execution
+ * Accepts tool ID, input parameters, and optional timeout
+ */
+declare const DelegateToolSchema: z.ZodObject<{
+    toolId: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodAny>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    input: Record<string, any>;
+    toolId: string;
+    timeout?: number | undefined;
+}, {
+    input: Record<string, any>;
+    toolId: string;
+    timeout?: number | undefined;
+}>;
+export type DelegateToolInput = z.infer<typeof DelegateToolSchema>;
+/**
+ * Delegate Tool Implementation
+ *
+ * This tool is automatically instantiated and registered by DelegateToolManager.
+ * It serves as a proxy for executing tools delegated from client-side providers.
+ */
+export declare class DelegateToolImpl extends BaseTool implements Tool {
+    readonly logger: Logger;
+    name: ToolNames;
+    readonly promptCacheStability: "volatile";
+    description: string;
+    parameters: z.ZodObject<{
+        toolId: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodAny>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        input: Record<string, any>;
+        toolId: string;
+        timeout?: number | undefined;
+    }, {
+        input: Record<string, any>;
+        toolId: string;
+        timeout?: number | undefined;
+    }>;
+    needsApproval: boolean;
+    /**
+     * DelegateTool is always enabled, but only becomes useful when delegate tools are registered
+     */
+    isEnabled: boolean;
+    /**
+     * Execute a delegate tool on the client side via ACP extension method
+     */
+    execute(input: DelegateToolInput, context?: RunContext<Session>): Promise<ToolResult>;
+    /**
+     * Extract raw response for hook usage
+     */
+    extractRawResponse(result: ToolResult): unknown;
+}
+export {};