@google/adk 1.6.0 → 2.1.0

package/dist/types/tools/function_tool.d.ts

@@ -20,14 +20,40 @@ export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TPara
 /**
  * The signature of the user-provided function executed by a {@link FunctionTool}.
  */
-export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: Context) => Promise<unknown> | unknown;
+export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, toolContext?: Context) => Promise<unknown> | unknown;
+/**
+ * Whether a {@link FunctionTool} requires user confirmation before it runs: a
+ * boolean, or a predicate over the (validated) call arguments and tool context.
+ * See {@link ToolOptions.requireConfirmation}.
+ */
+export type RequireConfirmation<TParameters extends ToolInputParameters> = boolean | ((input: ToolExecuteArgument<TParameters>, toolContext?: Context) => boolean | Promise<boolean>);
 /**
  * The configuration options for creating a function-based tool.
- * The `name`, `description` and `parameters` fields are used to generate the
- * tool definition that is passed to the LLM prompt.
  *
- * Note: Unlike Python's ADK, JSDoc on the `execute` function is ignored
- * for tool definition generation.
+ * What the model is shown about the tool is built from these options: `name`,
+ * `description` and the `parameters` schema become its function declaration.
+ * TypeScript types and JSDoc are erased at runtime and cannot be read back, so
+ * `description` is required and per-argument descriptions have to live in the
+ * schema — typically as Zod `.describe()` calls.
+ *
+ * ```ts
+ * new FunctionTool({
+ *   name: 'get_weather',
+ *   description: 'Returns the current weather for a city.',
+ *   parameters: z.object({
+ *     city: z.string().describe('City name, e.g. "San Francisco".'),
+ *   }),
+ *   execute: async ({city}) => fetchWeather(city),
+ * });
+ * ```
+ *
+ * A subclass may add to the declaration it derives from these options: given
+ * the identical options, {@link LongRunningFunctionTool} appends a sentence to
+ * `description` telling the model not to re-invoke a call that is still in
+ * flight.
+ *
+ * `parameters` is a description for the model, and only a Zod object schema is
+ * additionally enforced at call time — see {@link FunctionTool.runAsync}.
  */
 export type ToolOptions<TParameters extends ToolInputParameters> = {
     name?: string;
@@ -35,6 +61,24 @@ export type ToolOptions<TParameters extends ToolInputParameters> = {
     parameters?: TParameters;
     execute: ToolExecuteFunction<TParameters>;
     isLongRunning?: boolean;
+    /**
+     * Whether this tool requires user confirmation before it runs. A boolean, or
+     * a predicate over the (validated) call arguments and tool context returning
+     * a boolean.
+     *
+     * The HITL gate is enforced when the tool is invoked through an `LlmAgent`
+     * turn: `agents/functions.ts` surfaces an `adk_request_confirmation`
+     * interrupt from the tool's `requestedToolConfirmations`, and the tool only
+     * executes once the user approves (via the
+     * `RequestConfirmationLlmRequestProcessor`).
+     *
+     * NOTE: a workflow `ToolNode` does not yet route through that path, so a
+     * `requireConfirmation` tool used directly as a node does not pause — it
+     * returns the "requires confirmation" error as its node output. Approval for
+     * workflow nodes is not wired up. Mirrors Python's
+     * `FunctionTool(require_confirmation=...)`.
+     */
+    requireConfirmation?: RequireConfirmation<TParameters>;
 };
 /**
  * A unique symbol to identify ADK agent classes.
@@ -50,16 +94,27 @@ export declare function isFunctionTool(obj: unknown): obj is FunctionTool;
 /**
  * A tool that wraps a user-defined function, making it callable by an LLM.
  *
- * The function's name, description, and parameter schema are exposed to the
+ * The tool's name, description, and parameter schema are exposed to the
  * model as a function declaration. When the model requests a call, the
- * framework validates the arguments and invokes the user-provided `execute`
- * callback.
+ * framework invokes the user-provided `execute` callback with the arguments
+ * the model produced.
+ *
+ * Those arguments are checked only when `parameters` is a Zod object schema:
+ * it is applied with `parse()`, so a call that does not match is rejected and
+ * `execute` receives the parsed value. Keys the schema does not declare are
+ * handled however that schema says: a plain `z.object()` drops them,
+ * `.passthrough()` forwards them, `.strict()` rejects the call. A plain
+ * genai `Schema`, or no `parameters` at all, is shown to the model but is not
+ * a runtime guard — the arguments reach `execute` exactly as the model
+ * produced them, wrong types and extra keys included. Validate them inside
+ * `execute` on that path.
  */
 export declare class FunctionTool<TParameters extends ToolInputParameters = undefined> extends BaseTool {
     /** A unique symbol to identify ADK function tool class. */
     readonly [FUNCTION_TOOL_SIGNATURE_SYMBOL] = true;
     private readonly execute;
     private readonly parameters?;
+    private readonly requireConfirmation;
     /**
      * The constructor acts as the user-friendly factory.
      * @param options The configuration for the tool.
@@ -71,12 +126,35 @@ export declare class FunctionTool<TParameters extends ToolInputParameters = unde
      */
     _getDeclaration(): FunctionDeclaration;
     /**
-     * Validates the model-provided arguments against the parameter schema and
-     * invokes the user-defined `execute` function.
+     * Invokes the user-defined `execute` function with the model-provided
+     * arguments, after parsing them when `parameters` is a Zod object schema.
+     * Any other `parameters` value is passed through unchecked.
      *
      * @param req The tool request containing arguments and tool context.
      * @returns A promise resolving to the function's return value.
+     * @throws {Error} Wrapped as `Error in tool '<name>': …` when a Zod
+     *     `parameters` schema rejects the arguments or `execute` throws.
      */
     runAsync(req: RunAsyncToolRequest): Promise<unknown>;
+    /**
+     * Whether this call is gated on human approval — the static flag, or the
+     * predicate evaluated against the validated arguments.
+     *
+     * @param args The arguments the tool would run with.
+     * @param toolContext The context of the call, when there is one.
+     * @return Whether the call requires confirmation.
+     */
+    checkRequireConfirmation(args: Record<string, unknown>, toolContext?: Context): Promise<boolean>;
+    /** Parses `args` against the parameter schema, when one is declared. */
+    private validateArgs;
+    /** Resolves `requireConfirmation`, which may be a flag or a predicate. */
+    private evaluateRequireConfirmation;
+    /**
+     * Evaluates the confirmation gate. Returns `undefined` if the tool may
+     * proceed; otherwise returns the function response payload to surface instead
+     * of running (a request-for-confirmation on the first pass, or a rejection
+     * once the user declined).
+     */
+    private checkConfirmation;
 }
 export {};

package/dist/types/tools/google_maps_grounding_tool.d.ts

@@ -1,5 +1,6 @@
 import { LlmRequest } from '../models/llm_request.js';
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * Applies Google Maps grounding to the LLM request if supported.
  */
@@ -11,10 +12,9 @@ export declare function applyGoogleMapsGrounding(llmRequest: LlmRequest): void;
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class GoogleMapsGroundingTool extends BaseTool {
+export declare class GoogleMapsGroundingTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link GoogleMapsGroundingTool}.

package/dist/types/tools/google_search_tool.d.ts

@@ -1,4 +1,5 @@
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * A built-in tool that is automatically invoked by Gemini 2 models to retrieve
  * search results from Google Search.
@@ -6,10 +7,9 @@ import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class GoogleSearchTool extends BaseTool {
+export declare class GoogleSearchTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link GoogleSearchTool}.

package/dist/types/tools/long_running_tool.d.ts

@@ -10,7 +10,7 @@ import { FunctionTool, ToolInputParameters, ToolOptions } from './function_tool.
  * asynchronously.
  *
  * The framework invokes the user-provided function and delivers the response
- * back to the model once it completes, identified by the `function_call_id`.
+ * back to the model once it completes, matched up by the function call's `id`.
  * The model is also instructed not to re-invoke the tool while a call is
  * already in flight.
  */

package/dist/types/tools/mcp/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * `@google/adk/tools/mcp` subpath: the MCP tools only, without the full ADK
+ * barrel. Also re-exported from `@google/adk`.
+ */
+export * from './load_mcp_resource_tool.js';
+export * from './mcp_session_manager.js';
+export * from './mcp_tool.js';
+export * from './mcp_toolset.js';

package/dist/types/tools/mcp/mcp_session_manager.d.ts

@@ -3,9 +3,9 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 /**
  * Defines the parameters for establishing a connection to an MCP server using
  * standard input/output (stdio). This is typically used for running MCP servers

package/dist/types/tools/mcp/mcp_tool.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { FunctionDeclaration } from '@google/genai';
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
 import { MCPSessionManager } from './mcp_session_manager.js';
 /**

package/dist/types/tools/mcp/mcp_toolset.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BlobResourceContents, Resource, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+import type { BlobResourceContents, Resource, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
 import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { BaseTool } from '../base_tool.js';
 import { BaseToolset, ToolPredicate } from '../base_toolset.js';
@@ -24,18 +24,19 @@ import { MCPConnectionParams } from './mcp_session_manager.js';
  * LLM invokes the prefixed tool, this toolset transparently strips the prefix
  * before sending the request to the underlying MCP server.
  *
- * Usage:
- *   import { MCPToolset } from '@google/adk';
- *   import { StreamableHTTPConnectionParamsSchema } from '@google/adk';
+ * @example
+ * ```ts
+ * import {MCPToolset} from '@google/adk';
+ * import type {StreamableHTTPConnectionParams} from '@google/adk';
  *
- *   const connectionParams = StreamableHTTPConnectionParamsSchema.parse({
- *     type: "StreamableHTTPConnectionParams",
- *     url: "http://localhost:8788/mcp"
- *   });
- *
- *   const mcpToolset = new MCPToolset(connectionParams);
- *   const tools = await mcpToolset.getTools();
+ * const connectionParams: StreamableHTTPConnectionParams = {
+ *   type: 'StreamableHTTPConnectionParams',
+ *   url: 'http://localhost:8788/mcp',
+ * };
  *
+ * const mcpToolset = new MCPToolset(connectionParams);
+ * const tools = await mcpToolset.getTools();
+ * ```
  */
 export declare class MCPToolset extends BaseToolset {
     private readonly mcpSessionManager;

package/dist/types/tools/openapi_tool/auth/auth_helpers.d.ts

@@ -8,11 +8,16 @@ import { AuthCredential } from '../../../auth/auth_credential.js';
 /**
  * Applies the given credential to the request headers and URL.
  *
+ * An HTTP credential that carries no usable token throws, so the caller never
+ * sends an unauthenticated request in place of an authenticated one.
+ *
  * @param url The target URL.
  * @param headers The request headers.
  * @param credential The auth credential.
  * @param authScheme The auth scheme from OpenAPI spec.
  * @returns The updated URL (if modified by query params).
+ * @throws {Error} If an HTTP credential holds basic credentials, or holds no
+ *   credentials at all.
  */
 export declare function applyCredential(url: string, headers: Record<string, string>, credential?: AuthCredential, authScheme?: OpenAPIV3.SecuritySchemeObject): string;
 /**

package/dist/types/tools/openapi_tool/auth/credential_exchangers/auto_auth_credential_exchanger.d.ts

@@ -8,7 +8,6 @@ import { AuthScheme } from '../../../../auth/auth_schemes.js';
 import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
 /**
  * Automatically selects the appropriate credential exchanger based on the auth scheme.
- * Ported from Python implementation.
  */
 export declare class AutoAuthCredentialExchanger implements BaseCredentialExchanger {
     private exchangers;

package/dist/types/tools/openapi_tool/auth/credential_exchangers/service_account_exchanger.d.ts

@@ -8,7 +8,6 @@ import { AuthScheme } from '../../../../auth/auth_schemes.js';
 import { BaseCredentialExchanger, ExchangeResult } from '../../../../auth/exchanger/base_credential_exchanger.js';
 /**
  * Fetches credentials for Google Service Account.
- * Ported from Python implementation.
  */
 export declare class ServiceAccountCredentialExchanger implements BaseCredentialExchanger {
     exchange(params: {

package/dist/types/tools/preload_memory_tool.d.ts

@@ -7,7 +7,7 @@ import { BaseTool, RunAsyncToolRequest, ToolProcessLlmRequest } from './base_too
 /**
  * A tool that preloads the memory for the current user.
  *
- * This tool will be automatically executed for each llm_request, and it won't be
+ * This tool is automatically executed for each `LlmRequest`, and it won't be
  * called by the model.
  *
  * NOTE: Currently this tool only uses text part from the memory.

package/dist/types/tools/request_input_tool.d.ts

@@ -8,8 +8,13 @@ import { LongRunningFunctionTool } from './long_running_tool.js';
 /**
  * A long-running tool that presents a custom message to the user and awaits
  * unstructured or structured input.
+ *
+ * `response_schema` is spelled the way a workflow's `RequestInput` spells it on
+ * the wire (`RESPONSE_SCHEMA_ARG` in `workflow/utils/hitl_utils`), so a client
+ * reads one key whichever way the pause was raised — the dev UI builds its
+ * reply form from it either way.
  */
 export declare const requestInputTool: LongRunningFunctionTool<z.ZodObject<{
     message: z.ZodString;
-    responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    response_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>>;

package/dist/types/tools/resume_inputs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Inputs handed to a tool call that is being resumed after it paused for them,
+ * keyed by the id of the interrupt that asked for each one. JSON-serializable.
+ *
+ * Deliberately separate from `ToolConfirmation`. Both travel the same
+ * route — built by a resume processor, threaded through `handleFunctionCallList`
+ * onto the tool context — but they say different things. A `ToolConfirmation`
+ * says a human looked at an action and approved it, and the confirmation gate
+ * runs a tool on the strength of that. `ResumeInputs` says only that the user
+ * answered a question the tool asked; it carries no authority and cannot
+ * satisfy a gate, which is why it has no `confirmed` field to set.
+ *
+ * Named here rather than left as a bare mapping so the distinction above has
+ * somewhere to live, but the shape mirrors `Context.resume_inputs` in
+ * `google/adk-python` (`agents/context.py`): the same flat mapping keyed by
+ * interrupt id, defaulting to empty rather than absent.
+ *
+ * @experimental  (Experimental, subject to change)
+ */
+export type ResumeInputs = Record<string, unknown>;

package/dist/types/tools/retrieval/base_retrieval_tool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool } from '../base_tool.js';
+/**
+ * The base class for tools that answer a single natural-language query by
+ * retrieving text the framework fetches itself.
+ *
+ * Subclasses supply `runAsync`; this class supplies the declaration the model
+ * sees, so every retrieval tool advertises the same one-argument `query`
+ * signature whatever store backs it.
+ *
+ * Ported from adk-python
+ * `src/google/adk/tools/retrieval/base_retrieval_tool.py` at ref `v0.1.0`.
+ */
+export declare abstract class BaseRetrievalTool extends BaseTool {
+    _getDeclaration(): FunctionDeclaration;
+}

package/dist/types/tools/retrieval/files_retrieval.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LlamaIndexRetrieval, LlamaIndexRetriever } from './llama_index_retrieval.js';
+/** Parameters shared by the `FilesRetrieval` constructor and `create`. */
+export interface FilesRetrievalParams {
+    name: string;
+    description: string;
+    /** The directory whose files are indexed. */
+    inputDir: string;
+}
+/** Parameters for the `FilesRetrieval` constructor. */
+export interface FilesRetrievalConstructorParams extends FilesRetrievalParams {
+    /** A retriever already built over `inputDir`. */
+    retriever: LlamaIndexRetriever;
+}
+/**
+ * A retrieval tool over the files in a local directory.
+ *
+ * Ported from adk-python `src/google/adk/tools/retrieval/files_retrieval.py`
+ * at ref `v0.1.0`.
+ *
+ * adk-python reads the directory and builds the index inside `__init__`.
+ * Both steps are asynchronous in LlamaIndexTS, so they live in the static
+ * `create` instead; the constructor takes the finished retriever, which also
+ * lets a caller supply one built some other way.
+ *
+ * @example
+ * ```ts
+ * const tool = await FilesRetrieval.create({
+ *   name: 'docs',
+ *   description: 'Company documentation.',
+ *   inputDir: './docs',
+ * });
+ * ```
+ */
+export declare class FilesRetrieval extends LlamaIndexRetrieval {
+    readonly inputDir: string;
+    constructor(params: FilesRetrievalConstructorParams);
+    /**
+     * Indexes every file under `inputDir` and returns a tool that retrieves
+     * from it.
+     *
+     * Requires the optional `llamaindex` and `@llamaindex/readers` packages,
+     * and a configured LlamaIndex embedding model.
+     */
+    static create(params: FilesRetrievalParams): Promise<FilesRetrieval>;
+}

package/dist/types/tools/retrieval/llama_index_retrieval.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { RunAsyncToolRequest } from '../base_tool.js';
+import { BaseRetrievalTool } from './base_retrieval_tool.js';
+/**
+ * The part of LlamaIndexTS's `BaseNode` this tool reads.
+ *
+ * A vector retriever returns `TextNode`s, which carry the chunk text on
+ * `text`. The interface is structural so that `llamaindex` stays an optional
+ * dependency — nothing here imports it, matching how adk-python keeps the
+ * import under `TYPE_CHECKING`.
+ */
+export interface LlamaIndexNode {
+    /** The chunk text. */
+    text?: string;
+}
+/** LlamaIndexTS's `NodeWithScore`. */
+export interface LlamaIndexNodeWithScore {
+    node: LlamaIndexNode;
+    score?: number;
+}
+/**
+ * The part of LlamaIndexTS's `BaseRetriever` this tool calls.
+ *
+ * `retrieve` accepts a `QueryType`, which includes a plain string, so passing
+ * the model's `query` argument straight through matches adk-python.
+ */
+export interface LlamaIndexRetriever {
+    retrieve(query: string): Promise<LlamaIndexNodeWithScore[]>;
+}
+/** Parameters for the `LlamaIndexRetrieval` constructor. */
+export interface LlamaIndexRetrievalParams {
+    name: string;
+    description: string;
+    retriever: LlamaIndexRetriever;
+}
+/**
+ * A retrieval tool backed by a LlamaIndex retriever.
+ *
+ * Answers with the text of the single highest-scoring node, as adk-python
+ * does.
+ *
+ * Ported from adk-python
+ * `src/google/adk/tools/retrieval/llama_index_retrieval.py` at ref `v0.1.0`.
+ *
+ * @example
+ * ```ts
+ * const tool = new LlamaIndexRetrieval({
+ *   name: 'docs',
+ *   description: 'Company documentation.',
+ *   retriever: index.asRetriever(),
+ * });
+ * ```
+ */
+export declare class LlamaIndexRetrieval extends BaseRetrievalTool {
+    readonly retriever: LlamaIndexRetriever;
+    constructor(params: LlamaIndexRetrievalParams);
+    runAsync({ args }: RunAsyncToolRequest): Promise<unknown>;
+}

package/dist/types/tools/skill/skill_toolset.d.ts

@@ -17,8 +17,10 @@ export declare class SkillToolset extends BaseToolset {
     additionalTools: Array<BaseTool | BaseToolset>;
     codeExecutor?: BaseCodeExecutor;
     registry?: SkillRegistry;
+    private readonly scriptOutputDir?;
     private toolCache;
     private fetchedSkillCache;
+    private tempOutputDir?;
     constructor(skills: Record<string, Skill> | Skill[], options?: {
         codeExecutor?: BaseCodeExecutor;
         additionalTools?: Array<BaseTool | BaseToolset>;
@@ -32,10 +34,34 @@ export declare class SkillToolset extends BaseToolset {
          * confirmation.
          */
         allowInlineScripts?: boolean;
+        /**
+         * Directory that files produced by `run_skill_script` /
+         * `run_skill_inline_script` are written into. Output file names come from
+         * the executed script, so this must be a directory dedicated to
+         * throwaway script output — never the application's working directory or
+         * a source tree.
+         *
+         * Defaults to a private, randomly named directory created under the OS
+         * temp dir on first use. Nothing removes that directory: `close()` runs
+         * once per invocation on a toolset instance that concurrent invocations
+         * share (see `Runner`), so it cannot tell whose output is still in use.
+         * Set this to own the location and the lifetime of the output.
+         */
+        scriptOutputDir?: string;
     });
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
     close(): Promise<void>;
     getSkill(name: string): Skill | undefined;
+    /**
+     * Resolves the directory that script output files are materialized into.
+     *
+     * Script output file names are attacker-influenced (a prompt-injected skill
+     * controls what its script writes), so they must never be resolved against
+     * the host application's working directory. When no `scriptOutputDir` was
+     * configured this hands back a private temp directory instead, created once
+     * and reused for the lifetime of the toolset.
+     */
+    getScriptOutputDir(): Promise<string>;
     getOrFetchSkill(name: string, invocationId?: string): Promise<Skill | undefined>;
     processLlmRequest(toolContext: Context, llmRequest: LlmRequest): Promise<void>;
     private resolveAdditionalTools;

package/dist/types/tools/tool_confirmation.d.ts

@@ -23,3 +23,50 @@ export declare class ToolConfirmation {
         payload?: unknown;
     });
 }
+/**
+ * Why a confirmation was refused. Each value is one of the checks the resume
+ * path makes before it runs a tool call a human approved.
+ */
+export type IntentMismatchReason = 
+/** The `adk_request_confirmation` call was not raised by the agent. */
+'untrusted_request'
+/** The `adk_request_confirmation` call carries no usable pinned call. */
+ | 'malformed_request'
+/** The pinned call is absent from session history. */
+ | 'unknown_original_call'
+/** The pinned call names a tool the agent does not have. */
+ | 'unregistered_tool'
+/** The pinned tool does not gate on confirmation, so nothing was approved. */
+ | 'confirmation_not_required'
+/** The pinned tool name disagrees with the call in history. */
+ | 'tool_name_mismatch'
+/** The pinned arguments disagree with the call in history. */
+ | 'arguments_mismatch';
+/**
+ * Raised when a tool confirmation does not bind to the action it claims to
+ * approve — the approval and the action about to run are not the same thing.
+ *
+ * The framework fails closed on this: a mismatch aborts the invocation rather
+ * than running an action no human agreed to. It is worth alerting on, so the
+ * message names the reason and the call, and deliberately carries no argument
+ * values — a rejected payload is attacker-controlled and does not belong in
+ * logs.
+ */
+export declare class IntentMismatchError extends Error {
+    /** Which binding check refused the confirmation. */
+    readonly reason: IntentMismatchReason;
+    /** The id of the pinned call, when one was named. */
+    readonly functionCallId?: string;
+    constructor(options: {
+        reason: IntentMismatchReason;
+        functionCallId?: string;
+    });
+}
+/**
+ * Type guard for {@link IntentMismatchError}.
+ *
+ * Matches on `name` rather than `instanceof` so it stays correct when the error
+ * crosses a package boundary (two copies of adk-js in one runtime would fail an
+ * `instanceof` check between them).
+ */
+export declare function isIntentMismatchError(e: unknown): e is IntentMismatchError;

package/dist/types/tools/url_context_tool.d.ts

@@ -1,4 +1,5 @@
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 /**
  * A built-in tool that allows Gemini 2+ models to retrieve content from URLs
  * provided in the conversation.
@@ -6,10 +7,9 @@ import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
  * This tool operates internally within the model and does not require or
  * perform local code execution.
  */
-export declare class UrlContextTool extends BaseTool {
+export declare class UrlContextTool extends BuiltInTool {
     constructor();
-    runAsync(): Promise<unknown>;
-    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }
 /**
  * A global instance of {@link UrlContextTool}.

package/dist/types/tools/vertex_ai_search_tool.d.ts

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { ReadonlyContext } from '../agents/readonly_context.js';
-import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+import { ToolProcessLlmRequest } from './base_tool.js';
+import { BuiltInTool } from './built_in_tool.js';
 export interface VertexAISearchDataStoreSpec {
     dataStore?: string;
 }
@@ -34,7 +35,7 @@ export type VertexAiSearchToolParams = DataStoreParams | SearchEngineParams;
 /**
  * A built-in tool using Vertex AI Search.
  */
-export declare class VertexAiSearchTool extends BaseTool {
+export declare class VertexAiSearchTool extends BuiltInTool {
     readonly dataStoreId?: string;
     readonly dataStoreSpecs?: VertexAISearchDataStoreSpec[];
     readonly searchEngineId?: string;
@@ -42,7 +43,6 @@ export declare class VertexAiSearchTool extends BaseTool {
     readonly maxResults?: number;
     readonly bypassMultiToolsLimit: boolean;
     constructor(params: VertexAiSearchToolParams);
-    runAsync(): Promise<unknown>;
     /**
      * Builds the VertexAISearch configuration.
      *
@@ -51,5 +51,5 @@ export declare class VertexAiSearchTool extends BaseTool {
      * state).
      */
     protected buildVertexAiSearchConfig(_readonlyContext: ReadonlyContext): VertexAISearchConfig;
-    processLlmRequest({ toolContext, llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+    protected applyBuiltInConfig({ toolContext, llmRequest, }: ToolProcessLlmRequest): Promise<void>;
 }