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

package/cli/dist-server/types/node/tools/tool-risk-review/review-context.d.ts

@@ -0,0 +1,42 @@
+import { type Session } from '../../../vendor/cbc-core/node/index.js';
+import type { ToolRiskReviewHostFacts } from '../../../workspace/product/lib/common/index.js';
+import type { ToolActionProjection } from './protocol';
+export declare const REVIEW_CONTEXT_BUDGETS: {
+    readonly trustedUserIntent: 4000;
+    readonly priorUserContext: 1000;
+    readonly projectInstructions: 2000;
+    readonly projection: 8000;
+    readonly recentToolCallTurns: 1000;
+    readonly total: 16000;
+};
+export type ReviewContextTrust = 'trusted_user_intent' | 'prior_user_context' | 'background_only' | 'action_to_review' | 'action_history_only';
+export interface LengthPrefixedReviewContextBlock {
+    trust: ReviewContextTrust;
+    codePoints: number;
+    content: string;
+}
+export interface ToolRiskReviewContext {
+    hostFacts?: ToolRiskReviewHostFacts;
+    trustedUserIntent?: LengthPrefixedReviewContextBlock;
+    priorUserContext?: LengthPrefixedReviewContextBlock;
+    projectInstructions?: LengthPrefixedReviewContextBlock;
+    projection: LengthPrefixedReviewContextBlock;
+    recentToolCallTurns: {
+        trust: 'action_history_only';
+        codePoints: number;
+        items: LengthPrefixedReviewContextBlock[];
+    };
+    totalCodePoints: number;
+}
+export interface BuildToolRiskReviewContextInput {
+    session: Pick<Session, 'history'>;
+    hostFacts?: ToolRiskReviewHostFacts;
+    projectInstructions?: string;
+    projection: ToolActionProjection;
+    recentToolCallTurns: readonly ToolActionProjection[];
+}
+export declare function truncateCodePoints(value: string, maxCodePoints: number): string;
+export declare function extractDirectUserContext(session: Pick<Session, 'history'>): {
+    trustedUserIntent: string;
+    priorUserContext: string;
+};

package/cli/dist-server/types/node/tools/tool-risk-review/review-runtime.d.ts

@@ -0,0 +1,6 @@
+export { projectMcpToolAction } from './mcp-projector';
+export { builtinProjectorRegistry } from './projectors';
+export { isToolRiskProjectionComplete } from './prompt';
+export { buildToolRiskReviewContext } from './review-context-build';
+export { runToolRiskReviewer } from './reviewer-client-impl';
+export { isTrustedBuiltinCodeAction } from './trusted-builtin-code';

package/cli/dist-server/types/node/tools/tool-risk-review/reviewer-client-impl.d.ts

@@ -0,0 +1,3 @@
+import { type AgentService } from '../../../vendor/cbc-core/node/index.js';
+import { type ToolRiskReviewClientInput, type ToolRiskReviewClientResult } from './reviewer-client';
+export declare function runToolRiskReviewer(agentService: AgentService, input: ToolRiskReviewClientInput): Promise<ToolRiskReviewClientResult>;

package/cli/dist-server/types/node/tools/tool-risk-review/reviewer-client.d.ts

@@ -0,0 +1,37 @@
+import { type AgentService as IAgentService, type ReviewerRecovery, type Session } from '../../../vendor/cbc-core/node/index.js';
+import { type ReviewerAction, type ReviewUnavailableReason } from './protocol';
+import type { ToolRiskReviewContext } from './review-context';
+export declare const TOOL_RISK_REVIEW_TIMEOUT_MS = 60000;
+type ToolRiskReviewRuntime = typeof import('./review-runtime');
+/** 加载审查运行时；成功结果进程内缓存，失败抛出原始错误且不缓存。 */
+export declare function loadToolRiskReviewRuntime(): Promise<ToolRiskReviewRuntime>;
+export interface ToolRiskReviewClientInput {
+    context: ToolRiskReviewContext;
+    callerSession?: Session;
+    customRules?: readonly string[];
+    summaryLanguage?: 'zh-CN' | 'en';
+    signal?: AbortSignal;
+}
+export type ToolRiskReviewClientResult = ({
+    status: 'reviewed';
+    action: ReviewerAction;
+} | {
+    status: 'unavailable';
+    reason: ReviewUnavailableReason;
+}) & {
+    totalTokens?: number;
+    credit?: number;
+    recovery?: ReviewerRecovery;
+    requestAttempted?: boolean;
+};
+export declare const ToolRiskReviewClient: unique symbol;
+export interface ToolRiskReviewClient {
+    review(input: ToolRiskReviewClientInput): Promise<ToolRiskReviewClientResult>;
+}
+export declare class ToolRiskReviewClientImpl implements ToolRiskReviewClient {
+    private resolvedAgentService?;
+    protected get agentService(): IAgentService;
+    protected set agentService(value: IAgentService);
+    review(input: ToolRiskReviewClientInput): Promise<ToolRiskReviewClientResult>;
+}
+export {};

package/cli/dist-server/types/node/tools/tool-risk-review/scope.d.ts

@@ -0,0 +1,6 @@
+export declare const TRUSTED_BUILTIN_CANDIDATE_TOOLS: Set<string>;
+export declare const IN_SCOPE_BUILTIN_TOOL_NAMES: readonly ["Bash", "PowerShell", "Write", "Edit", "MultiEdit", "NotebookEdit", "Read", "Glob", "Grep", "WebFetch", "WebSearch"];
+export type InScopeBuiltinToolName = typeof IN_SCOPE_BUILTIN_TOOL_NAMES[number];
+export declare const IN_SCOPE_BUILTIN_TOOLS: Set<string>;
+export declare function isToolRiskReviewInScope(toolName: string): toolName is InScopeBuiltinToolName;
+export declare function isToolRiskIdentityInScope(identity: import('./protocol').ToolIdentity): boolean;

package/cli/dist-server/types/node/tools/tool-risk-review/service.d.ts

@@ -0,0 +1,75 @@
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { type SecurityReviewGate as SecurityReviewGateContract } from '../../security-review';
+import { type SensitiveModelBoundary as ISensitiveModelBoundary } from '../../sensitive-content/sensitive-content-protocol';
+import { type SettingsManager as ISettingsManager } from '../../settings/settings-protocol';
+import { type SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../../telemetry/sandbox-telemetry-protocol';
+import { ToolResultContentReviewer } from './content-review';
+import { type ToolRiskProjectorRegistry } from './projector-registry';
+import { type AuthorizeExecutionInput, type ExecutionApprovalAdapter as IExecutionApprovalAdapter, type ExecutionAuthorization, type RecheckFinalActionInput, type ReviewPermissionInput, type ReviewPermissionResult, type ToolIdentity, type ToolRiskApprovalDecisionInput, type ToolRiskApprovalMetadata, type ToolRiskExecutionStatus, type ToolRiskHostDeniedInput, type ToolRiskReviewService as IToolRiskReviewService } from './protocol';
+import { type ToolRiskReviewClient as IToolRiskReviewClient } from './reviewer-client';
+import { ToolRiskReviewSessionStateStore } from './session-state';
+export { MAX_TOOL_RISK_REVIEW_RECORDS } from './session-state';
+export declare class ToolRiskReviewStateCapacityError extends Error {
+    constructor();
+}
+export declare class ToolRiskReviewServiceImpl implements IToolRiskReviewService {
+    protected readonly securityReviewGate: SecurityReviewGateContract;
+    protected readonly reviewerClient: IToolRiskReviewClient;
+    protected readonly sandboxTelemetryReporter?: ISandboxTelemetryReporter;
+    protected readonly logger?: Logger;
+    protected readonly settingsManager?: ISettingsManager;
+    protected readonly contentReviewer: ToolResultContentReviewer;
+    protected readonly sensitiveModelBoundary?: ISensitiveModelBoundary;
+    protected readonly contentApprovalAdapter?: IExecutionApprovalAdapter;
+    private readonly contentAdmissions;
+    private readonly pendingContentApprovals;
+    /** 未注入时 project 使用审查运行时内置投影器，createActionHash 直接使用 Host 哈希。 */
+    protected projectorRegistry?: ToolRiskProjectorRegistry;
+    private readonly trustedBuiltinCalls;
+    private readonly builtinQueryCaches;
+    protected readonly sessionStates: ToolRiskReviewSessionStateStore;
+    reviewPermission(input: ReviewPermissionInput): Promise<ReviewPermissionResult>;
+    recordHostDenied(input: ToolRiskHostDeniedInput): void;
+    getPendingApproval(session: ReviewPermissionInput['session'], toolCallId: string): ToolRiskApprovalMetadata | undefined;
+    recordApprovalDecision(input: ToolRiskApprovalDecisionInput): void;
+    private reportApproval;
+    private emitTelemetry;
+    consumeApproval(input: Omit<ToolRiskApprovalDecisionInput, 'decision' | 'reviewId'>): boolean;
+    authorizeExecution(input: AuthorizeExecutionInput): Promise<ExecutionAuthorization>;
+    recheckFinalAction(input: RecheckFinalActionInput): Promise<ExecutionAuthorization>;
+    recordExecutionStatus(session: ReviewPermissionInput['session'], toolCallId: string, status: ToolRiskExecutionStatus): void;
+    recordBuiltinToolCall(session: ReviewPermissionInput['session'], toolName: string, toolCallId: string): void;
+    recordMcpToolCall(session: ReviewPermissionInput['session'], identity: Extract<ToolIdentity, {
+        source: 'mcp';
+    }>, toolCallId: string): void;
+    private recordToolResultIdentity;
+    recordBuiltinToolResult(session: ReviewPermissionInput['session'], toolName: string, toolCallId: string, outcome: 'succeeded' | 'failed'): void;
+    recordMcpToolResult(session: ReviewPermissionInput['session'], identity: Extract<ToolIdentity, {
+        source: 'mcp';
+    }>, toolCallId: string, outcome: 'succeeded' | 'failed'): void;
+    private recordToolResultOutcome;
+    markResultProtectionIncomplete(session: ReviewPermissionInput['session'], toolName: string, toolCallId: string): void;
+    /**
+     * 在 hook 与 IDE 改写之后、执行之前登记最终参数；工具返回的豁免只认这里的判定，
+     * 未登记的调用（如恢复的历史会话）按不可信处理。
+     */
+    recordExecutedToolInput(session: ReviewPermissionInput['session'], toolCallId: string, toolName: string, finalInput: unknown): void;
+    /** 同一调用复用执行环境一致的 shell 查询，最终来源判定仍使用当前参数与文件系统。 */
+    isTrustedBuiltinCodeAction(session: ReviewPermissionInput['session'], toolCallId: string, toolName: string, toolInput: unknown, cwd?: string): Promise<boolean>;
+    isTrustedBuiltinCall(session: ReviewPermissionInput['session'], toolCallId: string): Promise<boolean>;
+    admitToolContent(session: ReviewPermissionInput['session'], toolCallId: string, content: unknown, toolName?: string): Promise<boolean>;
+    private reviewToolContent;
+    protectModelRequest(session: ReviewPermissionInput['session'], modelInput: unknown): Promise<unknown>;
+    private reconcileResultIdentityLedger;
+    private prepareActionHash;
+    private createActionHash;
+    private wrapToolMessageContent;
+    private injectTrustInstructions;
+    private reportResultProtectionFailure;
+    private reportResultProtection;
+    private createApproval;
+    private fallbackUnreviewedAction;
+    private saveRecord;
+    private currentReviewPolicyFingerprint;
+    private report;
+}

package/cli/dist-server/types/node/tools/tool-risk-review/session-state.d.ts

@@ -0,0 +1,49 @@
+import type { Session } from '../../../vendor/cbc-core/node/index.js';
+import type { ReviewerDecision, ReviewStatus, ToolActionProjection, ToolIdentity, ToolRiskApprovalMetadata } from './protocol';
+export declare const MAX_TOOL_RISK_REVIEW_RECORDS = 128;
+export interface ToolRiskReviewRecord {
+    reviewId: string;
+    toolIdentity: ToolIdentity;
+    inputSchemaFingerprint: string;
+    projectionHash: string;
+    reviewPolicyFingerprint: string;
+    sensitiveProjectionRequired?: boolean;
+    reviewerDecision?: ReviewerDecision;
+    approvalRequired: boolean;
+    userDecision?: 'allow_once' | 'cancel';
+    approvalConsumed?: boolean;
+    lifecycleComplete?: boolean;
+    approvalMetadata?: ToolRiskApprovalMetadata;
+    reviewStatus?: ReviewStatus;
+}
+export interface ToolRiskReviewSessionState {
+    records: Map<string, ToolRiskReviewRecord>;
+    recentProjections: ToolActionProjection[];
+    toolResultIdentities: Map<string, {
+        toolIdentity: ToolIdentity;
+        terminalStatus?: 'succeeded' | 'failed';
+        wrappedResultHashes: Set<string>;
+        resultProtectionReported?: boolean;
+    }>;
+    reportedResultProtectionFailures: Set<string>;
+    resultIdentityFailures: Map<string, {
+        reason: 'identity_record_failed';
+        toolCallId: string;
+        toolName: string;
+    }>;
+    unboundResultIdentityFailure?: {
+        reason: 'identity_record_failed';
+        toolName: string;
+    };
+}
+export declare class ToolRiskReviewSessionStateStore {
+    private readonly states;
+    get(session: Session): ToolRiskReviewSessionState;
+    setRecord(session: Session, toolCallId: string, record: ToolRiskReviewRecord): boolean;
+    getRecord(session: Session, toolCallId: string): ToolRiskReviewRecord | undefined;
+    deleteRecord(session: Session, toolCallId: string): void;
+    addRecentProjection(session: Session, projection: ToolActionProjection): void;
+    recordToolResultIdentity(session: Session, toolCallId: string, toolIdentity: ToolIdentity): 'recorded' | 'already_recorded' | 'identity_record_failed';
+    reconcileToolResultIdentities(session: Session, retainedToolCallIds: ReadonlySet<string>): void;
+}
+export declare function displayToolIdentity(identity: ToolIdentity): string;

package/cli/dist-server/types/node/tools/tool-risk-review/trusted-builtin-code.d.ts

@@ -0,0 +1,25 @@
+import type { Session } from '../../../vendor/cbc-core/node/index.js';
+/**
+ * 宿主提供的信任目录。专家市场只豁免 plugins 子目录，市场配置与管理文件不在范围内。
+ */
+export interface TrustedRoot {
+    path: string;
+    plugin?: string;
+    collection?: 'skills' | 'experts';
+}
+/**
+ * 只豁免整条命令中来源可确认的内置脚本及受限配套操作；文件只豁免 Read 的真实目标。
+ * 查询失败回到正常审查。判定只在本次调用内复用，避免 PATH、快照或插件更新后继续使用旧来源。
+ */
+export declare function isTrustedBuiltinCodeAction(action: {
+    toolName: string;
+    toolInput: unknown;
+    cwd?: string;
+    session?: Session;
+    queries?: Map<string, Promise<string>>;
+}, resolveRoots?: () => Promise<readonly TrustedRoot[]>): Promise<boolean>;
+/**
+ * 信任根：内置 Skill 目录、宿主托管专家市场目录，以及当前已加载插件中来自内置市场或该专家市场的安装目录。
+ * `experts` 需同时匹配宿主注册的目录源，同名的用户市场与 `my-experts` 不属于信任根。
+ */
+export declare function resolveTrustedBuiltinCodeRoots(): Promise<TrustedRoot[]>;

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

@@ -0,0 +1,286 @@
+import type { Event } from '@celljs/core';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '@openai/agents';
+import type { ToolInputParameters } from './tool-protocol';
+import type { ToolDeferOverlay } from './tool-spec';
+export declare const ToolSearchService: unique symbol;
+/**
+ * Result from tool search operation
+ */
+export interface ToolSearchResult {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Similarity score (0-1, higher is better) */
+    score: number;
+}
+/**
+ * Full tool information for deferred tools
+ */
+export interface DeferredToolInfo {
+    /** Tool name */
+    name: string;
+    /** Full tool description (rendered from product config template) */
+    description: string;
+    /** Short summary for ToolSearch prompt listing (one-liner from tool class) */
+    summary: string;
+    /** Tool input schema */
+    parameters: ToolInputParameters;
+    /** Whether this MCP tool is indexed with a bare name (no mcp__ prefix). */
+    isBare?: boolean;
+    /** MCP server that provides this tool. Undefined for builtin deferred tools. */
+    serverName?: string;
+    /** Raw MCP tool name as listed by the server. Undefined for builtin deferred tools. */
+    rawToolName?: string;
+    /** Untrusted MCP behavior hints retained as Reviewer evidence. */
+    annotations?: Record<string, unknown>;
+    /**
+     * 工具结果的敏感内容处理策略（来自 MCP _meta.sensitiveResultPolicy）。
+     * 仅信任 builtin_tools 声明的值。设为 'automatic-protection' 时，
+     * 敏感准入层跳过弹窗直接走静默加密路径。
+     */
+    sensitiveResultPolicy?: string;
+}
+/**
+ * Summary of a deferred tool (for system prompt hints)
+ */
+export interface DeferredToolSummary {
+    /** Tool name */
+    name: string;
+    /** Short summary for display in ToolSearch prompt hint */
+    summary: string;
+}
+/**
+ * Options for filtering deferred tools summary
+ */
+export interface DeferredToolsFilterOptions {
+    /**
+     * Filter by agent's tool names. Only show builtin deferred tools that are in this list.
+     * MCP tools, including mcp__-prefixed and indexed bare-name MCP tools, are always included.
+     */
+    filterByAgentTools?: string[];
+    /**
+     * 会话级 defer overlay。命中 forceNoDefer 的工具将被静默剔除——它们已通过
+     * NoDefer(...) 暴露在 LLM tools list 里，不应再在 deferred-tools 提示中重复
+     * 出现，否则模型会困惑「应该直接调还是走 DeferExecuteTool 调」。
+     */
+    overlay?: ToolDeferOverlay;
+}
+/**
+ * Options for tool search
+ */
+export interface ToolSearchOptions {
+    /**
+     * Filter search results by allowed tool names.
+     * Builtin deferred tools must be in this list; MCP tools, including mcp__-prefixed
+     * and indexed bare-name MCP tools, are always included regardless of this filter.
+     */
+    allowedTools?: string[];
+    /**
+     * 会话级 defer overlay。命中 forceNoDefer 的工具会从搜索/lookup 结果中剔除
+     * （静默——ToolSearch 是探索性 API，搜不到等同于不存在，不报错）。
+     */
+    overlay?: ToolDeferOverlay;
+    /** 当前 session，用于加入 subagent scoped MCP tools。 */
+    session?: Session;
+    /**
+     * A2 相关性下限（Issue #113176）：相对最高分的比例（0–1）。低于 `top1 * ratio`
+     * 的结果被丢弃。缺省用服务级默认（env `CODEBUDDY_TOOL_SEARCH_MIN_SCORE_RATIO`，否则 0.3）。
+     * 传 `0` 完全关闭阈值——lookup 的模糊兜底 `search(name, 1)` 用它保证"总能给最接近的一个"。
+     */
+    minScoreRatio?: number;
+}
+/**
+ * Service for searching and managing deferred tools.
+ * Uses MiniSearch for full-text search with BM25 ranking.
+ */
+export interface ToolSearchService {
+    /**
+     * Initialize the service.
+     * Should be called during application startup.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if the service is ready for use.
+     */
+    isReady(): boolean;
+    /**
+     * Index a tool for later search.
+     * Only tools with defer_loading: true should be indexed.
+     *
+     * @param tool Tool definition to index
+     */
+    indexTool(tool: {
+        name: string;
+        /** Full tool description for search matching and ToolSearch results */
+        description: string;
+        /** Short one-line summary for ToolSearch prompt listing */
+        summary: string;
+        parameters: ToolInputParameters;
+        defer_loading?: boolean;
+        /** Optional callback to dynamically control tool visibility in search results and system prompt. */
+        shouldShow?(): boolean;
+        /**
+         * Optional callback reporting whether this deferred tool is currently
+         * enabled (mirrors {@link Tool.isEnabled}, evaluated without a session).
+         * When present and it resolves false, the tool is dropped from the
+         * `<available_deferred_tools>` system-prompt hint so the prompt stays in
+         * sync with what ToolSearch / DeferExecuteTool will actually allow.
+         */
+        isEnabled?(): boolean | Promise<boolean>;
+        /** Whether this tool uses a bare name (no mcp__ prefix). Bare-name tools bypass agent whitelist filtering. */
+        isBare?: boolean;
+        /** MCP server that provides this tool. Undefined for builtin deferred tools. */
+        serverName?: string;
+        /** Raw MCP tool name as listed by the server. Undefined for builtin deferred tools. */
+        rawToolName?: string;
+        /** Untrusted MCP behavior hints retained as Reviewer evidence. */
+        annotations?: Record<string, unknown>;
+        /** Sensitive result policy from MCP _meta (trusted builtin_tools only). */
+        sensitiveResultPolicy?: string;
+    }): Promise<void>;
+    /**
+     * Search for tools matching the query.
+     * Supports prefix matching and fuzzy search for typo tolerance.
+     *
+     * @param query Search query - can be a string or array of keywords
+     * @param topK Maximum number of results to return (default: 5)
+     * @param options Optional search options for filtering results
+     * @returns Array of matching tools sorted by relevance
+     */
+    search(query: string | string[], topK?: number, options?: ToolSearchOptions): Promise<ToolSearchResult[]>;
+    /**
+     * Get full information about a tool by name.
+     *
+     * @param toolName The tool name to look up
+     * @returns Tool info if found, undefined otherwise
+     */
+    describe(toolName: string): DeferredToolInfo | undefined;
+    /**
+     * Resolve an agents-core model-visible function name to one canonical
+     * indexed name. Returns undefined when normalization is ambiguous.
+     */
+    resolveModelToolName(modelVisibleName: string): string | undefined;
+    /** Get full information about a global or session-scoped deferred tool. */
+    describeForSession(toolName: string, session?: Session, overlay?: ToolDeferOverlay): Promise<DeferredToolInfo | undefined>;
+    /**
+     * Return true when the indexed tool is a bare-name MCP tool.
+     */
+    isBareTool(toolName: string): boolean;
+    /**
+     * 判断某工具是否被会话级 overlay 强制设为非 defer（即用户写了 `NoDefer(X)`）。
+     * 命中时该工具应该从 ToolSearch / DeferExecuteTool 的视野中剔除，由
+     * agent-manager / mcp-server-manager 路径让它正常出现在 LLM tools list。
+     *
+     * overlay 为 undefined 或 EMPTY 时一律返回 false。
+     */
+    isHiddenByOverlay(toolName: string, overlay: ToolDeferOverlay | undefined): boolean;
+    /**
+     * Get summaries of all indexed deferred tools.
+     * Used for injecting hints into the system prompt.
+     *
+     * @param options Optional filter options
+     * @returns Array of tool summaries
+     */
+    getDeferredToolsSummary(options?: DeferredToolsFilterOptions): DeferredToolSummary[];
+    /**
+     * Given a set of deferred-tool summaries, drop the builtin ones whose
+     * {@link indexTool} `isEnabled` check currently resolves false.
+     *
+     * This closes the gap between {@link getDeferredToolsSummary} (which lists
+     * a tool purely from the agent's static tools config) and the actual
+     * ToolSearch / DeferExecuteTool gating (which runs `isEnabled`). Without it,
+     * a product variant that disables a feature (e.g. `productFeatures.ImageGen
+     * = false`) would still advertise the tool in `<available_deferred_tools>`,
+     * leading the model to call a tool that is then rejected as "not available".
+     *
+     * MCP tools (no registered `isEnabled` check) and any tool whose check
+     * throws are kept (fail-open), matching the ToolSearch gating semantics.
+     * Evaluated without a session — safe because builtin deferred tools' checks
+     * do not read the run context.
+     */
+    filterEnabledDeferredTools(summaries: DeferredToolSummary[]): Promise<DeferredToolSummary[]>;
+    /**
+     * Same visibility semantics as {@link getDeferredToolsSummary} (isToolVisible +
+     * overlay + agent-tool filtering), but returns the **full** {@link DeferredToolInfo}
+     * instead of the two-field summary.
+     *
+     * Needed by consumers that must render parameter shapes — most notably the REPL
+     * skeleton catalog, which needs `parameters` to derive a one-line parameter
+     * skeleton. `getDeferredToolsSummary` omits `parameters`, and
+     * `describeForSession` only resolves one tool per call (N awaits for N tools).
+     *
+     * @param options Optional filter options
+     */
+    listDeferredToolInfos(options?: DeferredToolsFilterOptions): DeferredToolInfo[];
+    /** Includes the current session's MCP tools without populating a second index. */
+    listDeferredToolInfosForSession(session?: Session, options?: DeferredToolsFilterOptions): Promise<DeferredToolInfo[]>;
+    /**
+     * Clear all indexed tools.
+     * Useful for resetting the service.
+     */
+    clearIndex(): void;
+    /**
+     * Remove all tools indexed for a specific MCP server.
+     * Used when an MCP server reports tools/list_changed to clear stale tools.
+     *
+     * @param serverName The MCP server name (tools are prefixed with mcp__{serverName}__)
+     */
+    removeToolsByServer(serverName: string): void;
+    /**
+     * Atomically replace every indexed tool of one MCP server.
+     *
+     * Callers must resolve the whole group first and commit it in one call.
+     * Indexing tool-by-tool via {@link indexTool} publishes each partial state
+     * to readers: every write bumps the index epoch, and that epoch is what
+     * makes the run path re-bake an agent's tool list — so the re-bake lands
+     * mid-write and renders a ToolSearch description missing the tools that
+     * were not stored yet (issue #95034).
+     *
+     * The implementation must stay synchronous. On a single-threaded runtime a
+     * synchronous function cannot yield, which is what makes the swap atomic
+     * without any locking.
+     *
+     * @param serverName MCP server owning the group
+     * @param tools Complete replacement set; an empty array clears the group
+     */
+    replaceServerTools(serverName: string, tools: DeferredToolInfo[]): void;
+    /**
+     * Get allowed built-in tool names for the specified agent and session.
+     *
+     * Uses the AgentManager wrapped isEnabled chain, including defer activation bypass,
+     * original tool availability, SDK tools/disallowedTools, delegate-mode and visibility checks.
+     * Then intersects it with the current session-level `--tools` whitelist when present.
+     * Permission deny/ask rules are evaluated later by ToolPermissionService, not here.
+     *
+     * @param agentName The agent name to look up
+     * @param context The current run context (passed to isEnabled checks)
+     * @returns Array of allowed tool names, or undefined if no filtering should be applied
+     */
+    getAllowedToolsForAgent(agentName: string | undefined, context: RunContext<Session>): Promise<string[] | undefined>;
+    /**
+     * Fires whenever the deferred-tool index mutates (a tool is indexed, discarded,
+     * removed by server, or the whole index is cleared).
+     *
+     * Consumers that cache anything derived from the index — most importantly the
+     * rendered `ToolSearch` tool description — subscribe to this to invalidate their
+     * cache. MCP servers connect and index their deferred tools asynchronously after
+     * startup, and nothing else in the config/agent fingerprint reflects that change,
+     * so without this signal a description cached before the MCP tools were indexed
+     * would be reused for the first prompt (missing e.g. `mcp__wb-issues__*`).
+     */
+    readonly onDidChangeIndex: Event<void>;
+    /**
+     * Monotonically increasing counter, bumped on every index mutation (same
+     * moments {@link onDidChangeIndex} fires).
+     *
+     * `onDidChangeIndex` lets a consumer invalidate a *cache*, but it does not
+     * rebuild structures that already froze a snapshot of the index — e.g. the
+     * ToolSearch description baked into an `Agent`'s tool array at buildTools
+     * time. Such consumers stamp the epoch they built against and compare later
+     * to detect staleness (the run path uses this to refresh a stale agent
+     * before the first run, without blocking `initialize` / `get_available_models`).
+     */
+    readonly indexEpoch: number;
+}