@ai-sdk/workflow 1.0.0-beta.10 → 1.0.0-beta.100

package/src/workflow-agent.ts

@@ -1,5 +1,4 @@
 import type {
-  JSONValue,
   LanguageModelV4CallOptions,
   LanguageModelV4Prompt,
   LanguageModelV4StreamPart,
@@ -7,48 +6,74 @@ import type {
   SharedV4ProviderOptions,
 } from '@ai-sdk/provider';
 import {
-  type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
+  getErrorMessage,
+  validateTypes,
+  type Context,
+  type HasRequiredKey,
+  type InferToolSetContext,
+} from '@ai-sdk/provider-utils';
+import {
+  Output,
+  experimental_filterActiveTools as filterActiveTools,
   type FinishReason,
   type LanguageModelResponseMetadata,
   type LanguageModelUsage,
+  type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
   type ModelMessage,
-  Output,
   type StepResult,
   type StopCondition,
-  type StreamTextOnStepFinishCallback,
-  type SystemModelMessage,
+  type GenerateTextOnStepEndCallback,
+  type ActiveTools,
   type ToolCallRepairFunction,
   type ToolChoice,
   type ToolSet,
   type UIMessage,
-  LanguageModel,
+  type LanguageModel,
+  type Prompt,
+  type TelemetryOptions as CoreTelemetryOptions,
+  type Instructions,
 } from 'ai';
 import {
+  createRestrictedTelemetryDispatcher,
+  collectToolApprovals,
   convertToLanguageModelPrompt,
   mergeAbortSignals,
   mergeCallbacks,
   standardizePrompt,
+  validateApprovedToolApprovals,
 } from 'ai/internal';
+import { createLanguageModelToolResultOutput } from './create-language-model-tool-result-output.js';
 import { streamTextIterator } from './stream-text-iterator.js';
-import type { CompatibleLanguageModel } from './types.js';
 
 // Re-export for consumers
 export type { CompatibleLanguageModel } from './types.js';
 
 /**
  * Callback function to be called after each step completes.
- * Alias for the AI SDK's StreamTextOnStepFinishCallback, using
+ * Alias for the AI SDK's GenerateTextOnStepEndCallback, using
  * WorkflowAgent-consistent naming.
  */
+export type WorkflowAgentOnStepEndCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = GenerateTextOnStepEndCallback<TTools, TRuntimeContext>;
+
+/**
+ * Callback function to be called after each step completes.
+ * Deprecated alias for `WorkflowAgentOnStepEndCallback`.
+ *
+ * @deprecated Use `WorkflowAgentOnStepEndCallback` instead.
+ */
 export type WorkflowAgentOnStepFinishCallback<
   TTools extends ToolSet = ToolSet,
-> = StreamTextOnStepFinishCallback<TTools, any>;
+  TRuntimeContext extends Context = Context,
+> = WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>;
 
 /**
  * Infer the type of the tools of a workflow agent.
  */
 export type InferWorkflowAgentTools<WORKFLOW_AGENT> =
-  WORKFLOW_AGENT extends WorkflowAgent<infer TOOLS> ? TOOLS : never;
+  WORKFLOW_AGENT extends WorkflowAgent<infer TOOLS, any> ? TOOLS : never;
 
 /**
  * Infer the UI message type of a workflow agent.
@@ -89,54 +114,14 @@ export interface OutputSpecification<OUTPUT, PARTIAL> {
  */
 export type ProviderOptions = SharedV4ProviderOptions;
 
-/**
- * Telemetry settings for observability.
- */
-export interface TelemetrySettings {
-  /**
-   * Enable or disable telemetry. Defaults to true.
-   */
-  isEnabled?: boolean;
-
-  /**
-   * Identifier for this function. Used to group telemetry data by function.
-   */
-  functionId?: string;
-
-  /**
-   * Additional information to include in the telemetry data.
-   */
-  metadata?: Record<
-    string,
-    | string
-    | number
-    | boolean
-    | Array<string | number | boolean>
-    | null
-    | undefined
-  >;
-
-  /**
-   * Enable or disable input recording. Enabled by default.
-   *
-   * You might want to disable input recording to avoid recording sensitive
-   * information, to reduce data transfers, or to increase performance.
-   */
-  recordInputs?: boolean;
-
-  /**
-   * Enable or disable output recording. Enabled by default.
-   *
-   * You might want to disable output recording to avoid recording sensitive
-   * information, to reduce data transfers, or to increase performance.
-   */
-  recordOutputs?: boolean;
-
-  /**
-   * Custom tracer for the telemetry.
-   */
-  tracer?: unknown;
-}
+type WorkflowAgentToolsContextParameter<TTools extends ToolSet> =
+  HasRequiredKey<InferToolSetContext<TTools>> extends true
+    ? { toolsContext: InferToolSetContext<TTools> }
+    : { toolsContext?: never };
+export type TelemetryOptions<
+  TRuntimeContext extends Context = Context,
+  TTools extends ToolSet = ToolSet,
+> = CoreTelemetryOptions<TRuntimeContext, TTools>;
 
 /**
  * A transformation that is applied to the stream.
@@ -253,7 +238,10 @@ export interface GenerationSettings {
 /**
  * Information passed to the prepareStep callback.
  */
-export interface PrepareStepInfo<TTools extends ToolSet = ToolSet> {
+export interface PrepareStepInfo<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> {
   /**
    * The current model configuration (string or function).
    * The function should return a LanguageModelV4 instance.
@@ -268,7 +256,7 @@ export interface PrepareStepInfo<TTools extends ToolSet = ToolSet> {
   /**
    * All previous steps with their results.
    */
-  steps: StepResult<TTools, any>[];
+  steps: StepResult<TTools, TRuntimeContext>[];
 
   /**
    * The messages that will be sent to the model.
@@ -277,16 +265,29 @@ export interface PrepareStepInfo<TTools extends ToolSet = ToolSet> {
   messages: LanguageModelV4Prompt;
 
   /**
-   * The context passed via the experimental_context setting (experimental).
+   * The runtime context that flows through the agent loop.
+   * Treat the value as immutable; return a new `runtimeContext` from
+   * `prepareStep` to update it for the current and subsequent steps.
    */
-  experimental_context: unknown;
+  runtimeContext: TRuntimeContext;
+
+  /**
+   * Per-tool context, keyed by tool name. Each tool receives only its own
+   * validated entry as `context` during execution.
+   * Treat the value as immutable; return a new `toolsContext` from
+   * `prepareStep` to update it for the current and subsequent steps.
+   */
+  toolsContext: InferToolSetContext<TTools>;
 }
 
 /**
  * Return type from the prepareStep callback.
  * All properties are optional - only return the ones you want to override.
  */
-export interface PrepareStepResult extends Partial<GenerationSettings> {
+export interface PrepareStepResult<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> extends Partial<GenerationSettings> {
   /**
    * Override the model for this step.
    */
@@ -315,32 +316,53 @@ export interface PrepareStepResult extends Partial<GenerationSettings> {
   activeTools?: string[];
 
   /**
-   * Context that is passed into tool execution. Experimental.
-   * Changing the context will affect the context in this step and all subsequent steps.
+   * Updated runtime context for the current and subsequent steps.
+   * Returning a value replaces the agent's runtime context.
+   */
+  runtimeContext?: TRuntimeContext;
+
+  /**
+   * Updated per-tool context for the current and subsequent steps.
+   * Returning a value replaces the agent's tools context.
    */
-  experimental_context?: unknown;
+  toolsContext?: InferToolSetContext<TTools>;
 }
 
 /**
  * Callback function called before each step in the agent loop.
  * Use this to modify settings, manage context, or implement dynamic behavior.
  */
-export type PrepareStepCallback<TTools extends ToolSet = ToolSet> = (
-  info: PrepareStepInfo<TTools>,
-) => PrepareStepResult | Promise<PrepareStepResult>;
+export type PrepareStepCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = (
+  info: PrepareStepInfo<TTools, TRuntimeContext>,
+) =>
+  | PrepareStepResult<TTools, TRuntimeContext>
+  | undefined
+  | Promise<PrepareStepResult<TTools, TRuntimeContext> | undefined>;
 
 /**
  * Options passed to the prepareCall callback.
  */
 export interface PrepareCallOptions<
   TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
 > extends Partial<GenerationSettings> {
   model: LanguageModel;
   tools: TTools;
-  instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+  instructions?: Instructions;
   toolChoice?: ToolChoice<TTools>;
-  experimental_telemetry?: TelemetrySettings;
-  experimental_context?: unknown;
+  telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
+  /**
+   * Runtime context that flows through the agent loop.
+   * Treat as immutable; return a new `runtimeContext` to update it for the call.
+   */
+  runtimeContext?: TRuntimeContext;
+  /**
+   * Per-tool context, keyed by tool name.
+   */
+  toolsContext?: InferToolSetContext<TTools>;
   messages: ModelMessage[];
 }
 
@@ -350,172 +372,207 @@ export interface PrepareCallOptions<
  * Note: `tools` cannot be overridden via prepareCall because they are
  * bound at construction time for type safety.
  */
-export type PrepareCallResult<TTools extends ToolSet = ToolSet> = Partial<
-  Omit<PrepareCallOptions<TTools>, 'tools'>
->;
+export type PrepareCallResult<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = Partial<Omit<PrepareCallOptions<TTools, TRuntimeContext>, 'tools'>>;
 
 /**
  * Callback called once before the agent loop starts to transform call parameters.
  */
-export type PrepareCallCallback<TTools extends ToolSet = ToolSet> = (
-  options: PrepareCallOptions<TTools>,
-) => PrepareCallResult<TTools> | Promise<PrepareCallResult<TTools>>;
+export type PrepareCallCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = (
+  options: PrepareCallOptions<TTools, TRuntimeContext>,
+) =>
+  | PrepareCallResult<TTools, TRuntimeContext>
+  | Promise<PrepareCallResult<TTools, TRuntimeContext>>;
 
 /**
  * Configuration options for creating a {@link WorkflowAgent} instance.
  */
-export interface WorkflowAgentOptions<
+export type WorkflowAgentOptions<
   TTools extends ToolSet = ToolSet,
-> extends GenerationSettings {
-  /**
-   * The id of the agent.
-   */
-  id?: string;
+  TRuntimeContext extends Context = Context,
+> = GenerationSettings &
+  WorkflowAgentToolsContextParameter<TTools> & {
+    /**
+     * The id of the agent.
+     */
+    id?: string;
 
-  /**
-   * The model provider to use for the agent.
-   *
-   * This should be a string compatible with the Vercel AI Gateway (e.g., 'anthropic/claude-opus'),
-   * or a LanguageModelV4 instance from a provider.
-   */
-  model: LanguageModel;
+    /**
+     * The model provider to use for the agent.
+     *
+     * This should be a string compatible with the Vercel AI Gateway (e.g., 'anthropic/claude-opus'),
+     * or a LanguageModelV4 instance from a provider.
+     */
+    model: LanguageModel;
 
-  /**
-   * A set of tools available to the agent.
-   * Tools can be implemented as workflow steps for automatic retries and persistence,
-   * or as regular workflow-level logic using core library features like sleep() and Hooks.
-   */
-  tools?: TTools;
+    /**
+     * A set of tools available to the agent.
+     * Tools can be implemented as workflow steps for automatic retries and persistence,
+     * or as regular workflow-level logic using core library features like sleep() and Hooks.
+     */
+    tools?: TTools;
 
-  /**
-   * Agent instructions. Can be a string, a SystemModelMessage, or an array of SystemModelMessages.
-   * Supports provider-specific options (e.g., caching) when using the SystemModelMessage form.
-   */
-  instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+    /**
+     * Agent instructions. Can be a string, a SystemModelMessage, or an array of SystemModelMessages.
+     * Supports provider-specific options (e.g., caching) when using the SystemModelMessage form.
+     */
+    instructions?: Instructions;
 
-  /**
-   * Optional system prompt to guide the agent's behavior.
-   * @deprecated Use `instructions` instead.
-   */
-  system?: string;
+    /**
+     * Optional system prompt to guide the agent's behavior.
+     * @deprecated Use `instructions` instead.
+     */
+    system?: string;
 
-  /**
-   * The tool choice strategy. Default: 'auto'.
-   */
-  toolChoice?: ToolChoice<TTools>;
+    /**
+     * The tool choice strategy. Default: 'auto'.
+     */
+    toolChoice?: ToolChoice<TTools>;
 
-  /**
-   * Optional telemetry configuration (experimental).
-   */
-  experimental_telemetry?: TelemetrySettings;
+    /**
+     * Optional telemetry configuration.
+     */
+    telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
 
-  /**
-   * Default context that is passed into tool execution for every stream call on this agent.
-   *
-   * Per-stream `experimental_context` values passed to `stream()` override this default.
-   * Experimental (can break in patch releases).
-   * @default undefined
-   */
-  experimental_context?: unknown;
+    /**
+     * Default runtime context for every stream call on this agent.
+     *
+     * The runtime context flows through `prepareStep`, lifecycle callbacks,
+     * and step results.
+     * Treat as immutable; return a new `runtimeContext` from `prepareStep`
+     * to update it between steps.
+     *
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Per-stream `runtimeContext` values passed to `stream()` override this default.
+     */
+    runtimeContext?: TRuntimeContext;
 
-  /**
-   * Default stop condition for the agent loop. When the condition is an array,
-   * any of the conditions can be met to stop the generation.
-   *
-   * Per-stream `stopWhen` values passed to `stream()` override this default.
-   */
-  stopWhen?:
-    | StopCondition<NoInfer<ToolSet>, any>
-    | Array<StopCondition<NoInfer<ToolSet>, any>>;
+    /**
+     * Default stop condition for the agent loop. When the condition is an array,
+     * any of the conditions can be met to stop the generation.
+     *
+     * Per-stream `stopWhen` values passed to `stream()` override this default.
+     */
+    stopWhen?:
+      | StopCondition<NoInfer<ToolSet>, any>
+      | Array<StopCondition<NoInfer<ToolSet>, any>>;
 
-  /**
-   * Default set of active tools that limits which tools the model can call,
-   * without changing the tool call and result types in the result.
-   *
-   * Per-stream `activeTools` values passed to `stream()` override this default.
-   */
-  activeTools?: Array<keyof NoInfer<TTools>>;
+    /**
+     * Default set of active tools that limits which tools the model can call,
+     * without changing the tool call and result types in the result.
+     *
+     * Per-stream `activeTools` values passed to `stream()` override this default.
+     */
+    activeTools?: ActiveTools<NoInfer<TTools>>;
 
-  /**
-   * Default output specification for structured outputs.
-   * Use `Output.object({ schema })` for structured output or `Output.text()` for text output.
-   *
-   * Per-stream `output` values passed to `stream()` override this default.
-   */
-  output?: OutputSpecification<any, any>;
+    /**
+     * Default output specification for structured outputs.
+     * Use `Output.object({ schema })` for structured output or `Output.text()` for text output.
+     *
+     * Per-stream `output` values passed to `stream()` override this default.
+     */
+    output?: OutputSpecification<any, any>;
 
-  /**
-   * Default function that attempts to repair a tool call that failed to parse.
-   *
-   * Per-stream `experimental_repairToolCall` values passed to `stream()` override this default.
-   */
-  experimental_repairToolCall?: ToolCallRepairFunction<TTools>;
+    /**
+     * Default function that attempts to repair a tool call that failed to parse.
+     *
+     * Per-stream `experimental_repairToolCall` values passed to `stream()` override this default.
+     */
+    experimental_repairToolCall?: ToolCallRepairFunction<TTools>;
 
-  /**
-   * Default custom download function to use for URLs.
-   *
-   * Per-stream `experimental_download` values passed to `stream()` override this default.
-   */
-  experimental_download?: DownloadFunction;
+    /**
+     * Default custom download function to use for URLs.
+     *
+     * Per-stream `experimental_download` values passed to `stream()` override this default.
+     */
+    experimental_download?: DownloadFunction;
 
-  /**
-   * Default callback function called before each step in the agent loop.
-   * Use this to modify settings, manage context, or inject messages dynamically
-   * for every stream call on this agent instance.
-   *
-   * Per-stream `prepareStep` values passed to `stream()` override this default.
-   */
-  prepareStep?: PrepareStepCallback<TTools>;
+    /**
+     * Default callback function called before each step in the agent loop.
+     * Use this to modify settings, manage context, or inject messages dynamically
+     * for every stream call on this agent instance.
+     *
+     * Per-stream `prepareStep` values passed to `stream()` override this default.
+     */
+    prepareStep?: PrepareStepCallback<TTools, TRuntimeContext>;
 
-  /**
-   * Callback function to be called after each step completes.
-   */
-  onStepFinish?: WorkflowAgentOnStepFinishCallback<ToolSet>;
+    /**
+     * Callback function to be called after each step completes.
+     */
+    onStepEnd?: WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>;
 
-  /**
-   * Callback that is called when the LLM response and all request tool executions are finished.
-   */
-  onFinish?: WorkflowAgentOnFinishCallback<ToolSet>;
+    /**
+     * Callback function to be called after each step completes.
+     *
+     * @deprecated Use `onStepEnd` instead.
+     */
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
 
-  /**
-   * Callback called when the agent starts streaming, before any LLM calls.
-   */
-  experimental_onStart?: WorkflowAgentOnStartCallback;
+    /**
+     * Callback that is called when the LLM response and all request tool executions are finished.
+     */
+    onEnd?: WorkflowAgentOnEndCallback<TTools, TRuntimeContext>;
 
-  /**
-   * Callback called before each step (LLM call) begins.
-   */
-  experimental_onStepStart?: WorkflowAgentOnStepStartCallback;
+    /**
+     * Callback that is called when the LLM response and all request tool executions are finished.
+     *
+     * @deprecated Use `onEnd` instead.
+     */
+    onFinish?: WorkflowAgentOnFinishCallback<TTools, TRuntimeContext>;
 
-  /**
-   * Callback called before a tool's execute function runs.
-   */
-  experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+    /**
+     * Callback called when the agent starts streaming, before any LLM calls.
+     */
+    experimental_onStart?: WorkflowAgentOnStartCallback<
+      TTools,
+      TRuntimeContext
+    >;
 
-  /**
-   * Callback called after a tool execution completes.
-   */
-  experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+    /**
+     * Callback called before each step (LLM call) begins.
+     */
+    experimental_onStepStart?: WorkflowAgentOnStepStartCallback<
+      TTools,
+      TRuntimeContext
+    >;
 
-  /**
-   * Prepare the parameters for the stream call.
-   * Called once before the agent loop starts. Use this to transform
-   * model, tools, instructions, or other settings based on runtime context.
-   */
-  prepareCall?: PrepareCallCallback<TTools>;
-}
+    /**
+     * Callback called before a tool's execute function runs.
+     */
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
+
+    /**
+     * Callback called after a tool execution completes.
+     */
+    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TTools>;
+
+    /**
+     * Prepare the parameters for the stream call.
+     * Called once before the agent loop starts. Use this to transform
+     * model, tools, instructions, or other settings based on runtime context.
+     */
+    prepareCall?: PrepareCallCallback<TTools, TRuntimeContext>;
+  };
 
 /**
  * Callback that is called when the LLM response and all request tool executions are finished.
  */
-export type WorkflowAgentOnFinishCallback<
+export type WorkflowAgentOnEndCallback<
   TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
   OUTPUT = never,
 > = (event: {
   /**
    * Details for all steps.
    */
-  readonly steps: StepResult<TTools, any>[];
+  readonly steps: StepResult<TTools, TRuntimeContext>[];
 
   /**
    * The final messages including all tool calls and results.
@@ -532,15 +589,25 @@ export type WorkflowAgentOnFinishCallback<
    */
   readonly finishReason: FinishReason;
 
+  /**
+   * The total token usage across all steps.
+   */
+  readonly usage: LanguageModelUsage;
+
   /**
    * The total token usage across all steps.
    */
   readonly totalUsage: LanguageModelUsage;
 
   /**
-   * Context that is passed into tool execution.
+   * The runtime context at the end of the agent loop.
+   */
+  readonly runtimeContext: TRuntimeContext;
+
+  /**
+   * The per-tool context at the end of the agent loop.
    */
-  readonly experimental_context: unknown;
+  readonly toolsContext: InferToolSetContext<TTools>;
 
   /**
    * The generated structured output. It uses the `output` specification.
@@ -549,6 +616,17 @@ export type WorkflowAgentOnFinishCallback<
   readonly output: OUTPUT;
 }) => PromiseLike<void> | void;
 
+/**
+ * Callback that is called when the LLM response and all request tool executions are finished.
+ *
+ * @deprecated Use `WorkflowAgentOnEndCallback` instead.
+ */
+export type WorkflowAgentOnFinishCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+  OUTPUT = never,
+> = WorkflowAgentOnEndCallback<TTools, TRuntimeContext, OUTPUT>;
+
 /**
  * Callback that is invoked when an error occurs during streaming.
  */
@@ -570,36 +648,57 @@ export type WorkflowAgentOnAbortCallback<TTools extends ToolSet = ToolSet> =
 /**
  * Callback that is called when the agent starts streaming, before any LLM calls.
  */
-export type WorkflowAgentOnStartCallback = (event: {
+export type WorkflowAgentOnStartCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = (event: {
   /** The model being used */
   readonly model: LanguageModel;
   /** The messages being sent */
   readonly messages: ModelMessage[];
+  /** Shared runtime context for this agent loop */
+  readonly runtimeContext: TRuntimeContext;
+  /** Per-tool context map for this agent loop */
+  readonly toolsContext: InferToolSetContext<TTools>;
 }) => PromiseLike<void> | void;
 
 /**
  * Callback that is called before each step (LLM call) begins.
  */
-export type WorkflowAgentOnStepStartCallback<TTools extends ToolSet = ToolSet> =
-  (event: {
-    /** The current step number (0-based) */
-    readonly stepNumber: number;
-    /** The model being used for this step */
-    readonly model: LanguageModel;
-    /** The messages being sent for this step */
-    readonly messages: ModelMessage[];
-    /** Results from all previously finished steps */
-    readonly steps: ReadonlyArray<StepResult<TTools, any>>;
-  }) => PromiseLike<void> | void;
+export type WorkflowAgentOnStepStartCallback<
+  TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> = (event: {
+  /** The current step number (0-based) */
+  readonly stepNumber: number;
+  /** The model being used for this step */
+  readonly model: LanguageModel;
+  /** The messages being sent for this step */
+  readonly messages: ModelMessage[];
+  /** Results from all previously finished steps */
+  readonly steps: ReadonlyArray<StepResult<TTools, TRuntimeContext>>;
+  /** Shared runtime context for this step */
+  readonly runtimeContext: TRuntimeContext;
+  /** Per-tool context map for this step */
+  readonly toolsContext: InferToolSetContext<TTools>;
+}) => PromiseLike<void> | void;
 
 /**
  * Callback that is called before a tool's execute function runs.
  */
-export type WorkflowAgentOnToolCallStartCallback = (event: {
+export type WorkflowAgentOnToolExecutionStartCallback<
+  TTools extends ToolSet = ToolSet,
+> = (event: {
   /** The tool call being executed */
   readonly toolCall: ToolCall;
   /** The current step number (0-based) */
   readonly stepNumber: number;
+  /** Messages sent to the language model for the step that produced the call */
+  readonly messages: ModelMessage[];
+  /** Tool-specific context passed to the tool */
+  readonly toolContext:
+    | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+    | undefined;
 }) => PromiseLike<void> | void;
 
 /**
@@ -607,7 +706,9 @@ export type WorkflowAgentOnToolCallStartCallback = (event: {
  * Uses a discriminated union pattern: check `success` to determine
  * whether `output` or `error` is available.
  */
-export type WorkflowAgentOnToolCallFinishCallback = (
+export type WorkflowAgentOnToolExecutionEndCallback<
+  TTools extends ToolSet = ToolSet,
+> = (
   event:
     | {
         /** The tool call that was executed */
@@ -616,6 +717,12 @@ export type WorkflowAgentOnToolCallFinishCallback = (
         readonly stepNumber: number;
         /** Execution time in milliseconds */
         readonly durationMs: number;
+        /** Messages sent to the language model for the step that produced the call */
+        readonly messages: ModelMessage[];
+        /** Tool-specific context passed to the tool */
+        readonly toolContext:
+          | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+          | undefined;
         /** Whether the tool call succeeded */
         readonly success: true;
         /** The tool result */
@@ -629,6 +736,12 @@ export type WorkflowAgentOnToolCallFinishCallback = (
         readonly stepNumber: number;
         /** Execution time in milliseconds */
         readonly durationMs: number;
+        /** Messages sent to the language model for the step that produced the call */
+        readonly messages: ModelMessage[];
+        /** Tool-specific context passed to the tool */
+        readonly toolContext:
+          | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+          | undefined;
         /** Whether the tool call succeeded */
         readonly success: false;
         /** The error that occurred */
@@ -642,6 +755,7 @@ export type WorkflowAgentOnToolCallFinishCallback = (
  */
 export type WorkflowAgentStreamOptions<
   TTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
   OUTPUT = never,
   PARTIAL_OUTPUT = never,
 > = Partial<GenerationSettings> &
@@ -714,13 +828,6 @@ export type WorkflowAgentStreamOptions<
       | StopCondition<NoInfer<ToolSet>, any>
       | Array<StopCondition<NoInfer<ToolSet>, any>>;
 
-    /**
-     * Maximum number of sequential LLM calls (steps), e.g. when you use tool calls.
-     * A maximum number can be set to prevent infinite loops in the case of misconfigured tools.
-     * By default, it's unlimited (the agent loops until completion).
-     */
-    maxSteps?: number;
-
     /**
      * The tool choice strategy. Default: 'auto'.
      * Overrides the toolChoice from the constructor if provided.
@@ -731,19 +838,37 @@ export type WorkflowAgentStreamOptions<
      * Limits the tools that are available for the model to call without
      * changing the tool call and result types in the result.
      */
-    activeTools?: Array<keyof NoInfer<TTools>>;
+    activeTools?: ActiveTools<NoInfer<TTools>>;
 
     /**
-     * Optional telemetry configuration (experimental).
+     * Optional telemetry configuration.
      */
-    experimental_telemetry?: TelemetrySettings;
+    telemetry?: TelemetryOptions<TRuntimeContext, TTools>;
 
     /**
-     * Context that is passed into tool execution.
-     * Experimental (can break in patch releases).
-     * @default undefined
+     * Runtime context that flows through the agent loop.
+     *
+     * Treat as immutable; return a new `runtimeContext` from `prepareStep`
+     * to update it between steps.
+     *
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Overrides the constructor-level `runtimeContext` if provided.
      */
-    experimental_context?: unknown;
+    runtimeContext?: TRuntimeContext;
+
+    /**
+     * Per-tool context, keyed by tool name. Each tool receives only its own
+     * validated entry as `context` during execution. Tools that declare a
+     * `contextSchema` validate their entry against the schema.
+     *
+     * In workflow context, keep values serializable so they can cross workflow
+     * and step boundaries.
+     *
+     * Overrides the constructor-level `toolsContext` if provided.
+     */
+    toolsContext?: InferToolSetContext<TTools>;
 
     /**
      * Optional specification for parsing structured outputs from the LLM response.
@@ -801,7 +926,14 @@ export type WorkflowAgentStreamOptions<
     /**
      * Callback function to be called after each step completes.
      */
-    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools>;
+    onStepEnd?: WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>;
+
+    /**
+     * Callback function to be called after each step completes.
+     *
+     * @deprecated Use `onStepEnd` instead.
+     */
+    onStepFinish?: WorkflowAgentOnStepFinishCallback<TTools, TRuntimeContext>;
 
     /**
      * Callback that is invoked when an error occurs during streaming.
@@ -813,7 +945,15 @@ export type WorkflowAgentStreamOptions<
      * Callback that is called when the LLM response and all request tool executions
      * (for tools that have an `execute` function) are finished.
      */
-    onFinish?: WorkflowAgentOnFinishCallback<TTools, OUTPUT>;
+    onEnd?: WorkflowAgentOnEndCallback<TTools, TRuntimeContext, OUTPUT>;
+
+    /**
+     * Callback that is called when the LLM response and all request tool executions
+     * (for tools that have an `execute` function) are finished.
+     *
+     * @deprecated Use `onEnd` instead.
+     */
+    onFinish?: WorkflowAgentOnFinishCallback<TTools, TRuntimeContext, OUTPUT>;
 
     /**
      * Callback that is called when the operation is aborted.
@@ -823,22 +963,28 @@ export type WorkflowAgentStreamOptions<
     /**
      * Callback called when the agent starts streaming, before any LLM calls.
      */
-    experimental_onStart?: WorkflowAgentOnStartCallback;
+    experimental_onStart?: WorkflowAgentOnStartCallback<
+      TTools,
+      TRuntimeContext
+    >;
 
     /**
      * Callback called before each step (LLM call) begins.
      */
-    experimental_onStepStart?: WorkflowAgentOnStepStartCallback;
+    experimental_onStepStart?: WorkflowAgentOnStepStartCallback<
+      TTools,
+      TRuntimeContext
+    >;
 
     /**
      * Callback called before a tool's execute function runs.
      */
-    experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+    onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TTools>;
 
     /**
      * Callback called after a tool execution completes.
      */
-    experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+    onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TTools>;
 
     /**
      * Callback function called before each step in the agent loop.
@@ -858,7 +1004,7 @@ export type WorkflowAgentStreamOptions<
      * }
      * ```
      */
-    prepareStep?: PrepareStepCallback<TTools>;
+    prepareStep?: PrepareStepCallback<TTools, TRuntimeContext>;
 
     /**
      * Timeout in milliseconds for the stream operation.
@@ -910,6 +1056,12 @@ export interface ToolResult {
   output: unknown;
 }
 
+type WorkflowToolExecutionResult = {
+  modelResult: LanguageModelV4ToolResultPart;
+  rawOutput: unknown;
+  isError: boolean;
+};
+
 /**
  * Result of the WorkflowAgent.stream method.
  */
@@ -988,7 +1140,10 @@ export interface WorkflowAgentStreamResult<
  * });
  * ```
  */
-export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
+export class WorkflowAgent<
+  TBaseTools extends ToolSet = ToolSet,
+  TRuntimeContext extends Context = Context,
+> {
   /**
    * The id of the agent.
    */
@@ -999,51 +1154,63 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
    * The tool set configured for this agent.
    */
   public readonly tools: TBaseTools;
-  private instructions?:
-    | string
-    | SystemModelMessage
-    | Array<SystemModelMessage>;
+  private instructions?: Instructions;
   private generationSettings: GenerationSettings;
   private toolChoice?: ToolChoice<TBaseTools>;
-  private telemetry?: TelemetrySettings;
-  private experimentalContext: unknown;
+  private telemetry?: TelemetryOptions<TRuntimeContext, TBaseTools>;
+  private runtimeContext?: TRuntimeContext;
+  private toolsContext?: InferToolSetContext<TBaseTools>;
   private stopWhen?:
     | StopCondition<ToolSet, any>
     | Array<StopCondition<ToolSet, any>>;
-  private activeTools?: Array<keyof TBaseTools>;
+  private activeTools?: ActiveTools<TBaseTools>;
   private output?: OutputSpecification<any, any>;
   private experimentalRepairToolCall?: ToolCallRepairFunction<TBaseTools>;
   private experimentalDownload?: DownloadFunction;
-  private prepareStep?: PrepareStepCallback<TBaseTools>;
-  private constructorOnStepFinish?: WorkflowAgentOnStepFinishCallback<ToolSet>;
-  private constructorOnFinish?: WorkflowAgentOnFinishCallback<ToolSet>;
-  private constructorOnStart?: WorkflowAgentOnStartCallback;
-  private constructorOnStepStart?: WorkflowAgentOnStepStartCallback;
-  private constructorOnToolCallStart?: WorkflowAgentOnToolCallStartCallback;
-  private constructorOnToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
-  private prepareCall?: PrepareCallCallback<TBaseTools>;
-
-  constructor(options: WorkflowAgentOptions<TBaseTools>) {
+  private prepareStep?: PrepareStepCallback<TBaseTools, TRuntimeContext>;
+  private constructorOnStepEnd?: WorkflowAgentOnStepEndCallback<
+    TBaseTools,
+    TRuntimeContext
+  >;
+  private constructorOnEnd?: WorkflowAgentOnEndCallback<
+    TBaseTools,
+    TRuntimeContext
+  >;
+  private constructorOnStart?: WorkflowAgentOnStartCallback<
+    TBaseTools,
+    TRuntimeContext
+  >;
+  private constructorOnStepStart?: WorkflowAgentOnStepStartCallback<
+    TBaseTools,
+    TRuntimeContext
+  >;
+  private constructorOnToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback<TBaseTools>;
+  private constructorOnToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback<TBaseTools>;
+  private prepareCall?: PrepareCallCallback<TBaseTools, TRuntimeContext>;
+
+  constructor(options: WorkflowAgentOptions<TBaseTools, TRuntimeContext>) {
     this.id = options.id;
     this.model = options.model;
     this.tools = (options.tools ?? {}) as TBaseTools;
     // `instructions` takes precedence over deprecated `system`
     this.instructions = options.instructions ?? options.system;
     this.toolChoice = options.toolChoice;
-    this.telemetry = options.experimental_telemetry;
-    this.experimentalContext = options.experimental_context;
+    this.telemetry = options.telemetry;
+    this.runtimeContext = options.runtimeContext;
+    this.toolsContext = options.toolsContext;
     this.stopWhen = options.stopWhen;
     this.activeTools = options.activeTools;
     this.output = options.output;
     this.experimentalRepairToolCall = options.experimental_repairToolCall;
     this.experimentalDownload = options.experimental_download;
     this.prepareStep = options.prepareStep;
-    this.constructorOnStepFinish = options.onStepFinish;
-    this.constructorOnFinish = options.onFinish;
+    this.constructorOnStepEnd = options.onStepEnd ?? options.onStepFinish;
+    const { onFinish, onEnd = onFinish } = options;
+    this.constructorOnEnd = onEnd;
     this.constructorOnStart = options.experimental_onStart;
     this.constructorOnStepStart = options.experimental_onStepStart;
-    this.constructorOnToolCallStart = options.experimental_onToolCallStart;
-    this.constructorOnToolCallFinish = options.experimental_onToolCallFinish;
+    this.constructorOnToolExecutionStart = options.onToolExecutionStart;
+    this.constructorOnToolExecutionEnd = options.onToolExecutionEnd;
     this.prepareCall = options.prepareCall;
 
     // Extract generation settings
@@ -1072,8 +1239,15 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     OUTPUT = never,
     PARTIAL_OUTPUT = never,
   >(
-    options: WorkflowAgentStreamOptions<TTools, OUTPUT, PARTIAL_OUTPUT>,
+    options: WorkflowAgentStreamOptions<
+      TTools,
+      TRuntimeContext,
+      OUTPUT,
+      PARTIAL_OUTPUT
+    >,
   ): Promise<WorkflowAgentStreamResult<TTools, OUTPUT>> {
+    const { onFinish, onEnd = onFinish } = options;
+
     // Call prepareCall to transform parameters before the agent loop
     let effectiveModel: LanguageModel = this.model;
     let effectiveInstructions = options.system ?? this.instructions;
@@ -1081,11 +1255,16 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       options.prompt;
     let effectiveMessages: Array<ModelMessage> | undefined = options.messages;
     let effectiveGenerationSettings = { ...this.generationSettings };
-    let effectiveExperimentalContext =
-      options.experimental_context ?? this.experimentalContext;
+    let effectiveRuntimeContext: TRuntimeContext = (options.runtimeContext ??
+      this.runtimeContext ??
+      {}) as TRuntimeContext;
+    let effectiveToolsContext: Record<string, Context | undefined> =
+      (options.toolsContext ?? this.toolsContext ?? {}) as unknown as Record<
+        string,
+        Context | undefined
+      >;
     let effectiveToolChoiceFromPrepare = options.toolChoice ?? this.toolChoice;
-    let effectiveTelemetryFromPrepare =
-      options.experimental_telemetry ?? this.telemetry;
+    let effectiveTelemetryFromPrepare = options.telemetry ?? this.telemetry;
 
     // Resolve messages for prepareCall: use messages directly, or convert prompt
     const resolvedMessagesForPrepareCall: ModelMessage[] =
@@ -1101,11 +1280,12 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         tools: this.tools,
         instructions: effectiveInstructions,
         toolChoice: effectiveToolChoiceFromPrepare as ToolChoice<TBaseTools>,
-        experimental_telemetry: effectiveTelemetryFromPrepare,
-        experimental_context: effectiveExperimentalContext,
+        telemetry: effectiveTelemetryFromPrepare,
+        runtimeContext: effectiveRuntimeContext,
+        toolsContext: effectiveToolsContext as InferToolSetContext<TBaseTools>,
         messages: resolvedMessagesForPrepareCall,
         ...effectiveGenerationSettings,
-      } as PrepareCallOptions<TBaseTools>);
+      } as PrepareCallOptions<TBaseTools, TRuntimeContext>);
 
       if (prepared.model !== undefined) effectiveModel = prepared.model;
       if (prepared.instructions !== undefined)
@@ -1114,13 +1294,18 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         effectiveMessages = prepared.messages as Array<ModelMessage>;
         effectivePrompt = undefined; // messages from prepareCall take precedence
       }
-      if (prepared.experimental_context !== undefined)
-        effectiveExperimentalContext = prepared.experimental_context;
+      if (prepared.runtimeContext !== undefined)
+        effectiveRuntimeContext = prepared.runtimeContext;
+      if (prepared.toolsContext !== undefined)
+        effectiveToolsContext = prepared.toolsContext as Record<
+          string,
+          Context | undefined
+        >;
       if (prepared.toolChoice !== undefined)
         effectiveToolChoiceFromPrepare =
           prepared.toolChoice as ToolChoice<TBaseTools>;
-      if (prepared.experimental_telemetry !== undefined)
-        effectiveTelemetryFromPrepare = prepared.experimental_telemetry;
+      if (prepared.telemetry !== undefined)
+        effectiveTelemetryFromPrepare = prepared.telemetry;
       if (prepared.maxOutputTokens !== undefined)
         effectiveGenerationSettings.maxOutputTokens = prepared.maxOutputTokens;
       if (prepared.temperature !== undefined)
@@ -1144,61 +1329,257 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         effectiveGenerationSettings.providerOptions = prepared.providerOptions;
     }
 
+    const effectiveTelemetry = effectiveTelemetryFromPrepare;
+    const telemetryDispatcher = createRestrictedTelemetryDispatcher<
+      any,
+      any,
+      any
+    >({
+      telemetry: effectiveTelemetry as any,
+      includeRuntimeContext: effectiveTelemetry?.includeRuntimeContext,
+      includeToolsContext: effectiveTelemetry?.includeToolsContext,
+    }) as any;
+
     const prompt = await standardizePrompt({
       system: effectiveInstructions,
+      allowSystemInMessages: true, // TODO: consider exposing this as a parameter
       ...(effectivePrompt != null
         ? { prompt: effectivePrompt }
         : { messages: effectiveMessages! }),
-    });
+    } as Prompt);
+    const download = options.experimental_download ?? this.experimentalDownload;
 
     // Process tool approval responses before starting the agent loop.
     // This mirrors how stream-text.ts handles tool-approval-response parts:
     // approved tools are executed, denied tools get denial results, and
     // approval parts are stripped from the messages.
-    const { approvedToolApprovals, deniedToolApprovals } =
-      collectToolApprovalsFromMessages(prompt.messages);
+    // Use the AI SDK core collector so this path cannot drift from the
+    // hardened generateText/streamText implementation. The collected approvals
+    // are mapped to the flat shape used below; the original (nested) approval
+    // is carried on `collected` for re-validation.
+    const collectedApprovals = collectToolApprovals<ToolSet>({
+      messages: prompt.messages,
+    });
+    const approvedToolApprovals = collectedApprovals.approvedToolApprovals.map(
+      collected => ({
+        toolCallId: collected.toolCall.toolCallId,
+        toolName: collected.toolCall.toolName,
+        input: collected.toolCall.input,
+        reason: collected.approvalResponse.reason,
+        providerExecuted: collected.toolCall.providerExecuted === true,
+        collected,
+      }),
+    );
+    const deniedToolApprovals = collectedApprovals.deniedToolApprovals.map(
+      collected => ({
+        toolCallId: collected.toolCall.toolCallId,
+        toolName: collected.toolCall.toolName,
+        input: collected.toolCall.input,
+        reason: collected.approvalResponse.reason,
+        providerExecuted: collected.toolCall.providerExecuted === true,
+      }),
+    );
+
+    // Approval ids of provider-executed tool calls. Provider-executed tools
+    // (e.g. MCP via the Responses API) cannot be resolved locally — the
+    // provider owns execution. We therefore skip them from local execution
+    // and preserve their approval responses in the messages so the provider
+    // receives the approval on the next call. The discriminator is sourced
+    // from the original `tool-call` part (matching how core's stream-text.ts
+    // decides), not from the response part which may be missing the flag.
+    const providerExecutedApprovalIds = new Set<string>(
+      [
+        ...collectedApprovals.approvedToolApprovals,
+        ...collectedApprovals.deniedToolApprovals,
+      ]
+        .filter(collected => collected.toolCall.providerExecuted === true)
+        .map(collected => collected.approvalResponse.approvalId),
+    );
 
     if (approvedToolApprovals.length > 0 || deniedToolApprovals.length > 0) {
       const _toolResultMessages: ModelMessage[] = [];
-      const toolResultContent: Array<{
-        type: 'tool-result';
+      const toolResultContent: LanguageModelV4ToolResultPart[] = [];
+      const approvedRawResults: Array<{
         toolCallId: string;
         toolName: string;
-        output:
-          | { type: 'text'; value: string }
-          | { type: 'json'; value: JSONValue }
-          | { type: 'execution-denied'; reason: string | undefined };
+        input: unknown;
+        output: unknown;
       }> = [];
 
       // Execute approved tools
       for (const approval of approvedToolApprovals) {
+        // Provider-executed approvals are forwarded to the provider via the
+        // preserved approval response below, not executed locally.
+        if (approval.providerExecuted) {
+          continue;
+        }
         const tool = (this.tools as ToolSet)[approval.toolName];
         if (tool && typeof tool.execute === 'function') {
+          if (!tool.needsApproval) {
+            const reason = `Tool "${approval.toolName}" does not require approval`;
+            toolResultContent.push({
+              type: 'tool-result' as const,
+              toolCallId: approval.toolCallId,
+              toolName: approval.toolName,
+              output: await createLanguageModelToolResultOutput({
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+                output: reason,
+                tool,
+                errorMode: 'text',
+                supportedUrls: {},
+                download,
+              }),
+            });
+            continue;
+          }
+
+          // Re-validate through the shared core implementation: input schema,
+          // HMAC signature (when configured), and approval policy. It throws on
+          // invalid input/signature; convert that to a denial result so the
+          // agent loop can continue gracefully.
+          let revalidationReason: string | undefined;
+          try {
+            const { deniedToolApprovals: policyDenied } =
+              await validateApprovedToolApprovals({
+                approvedToolApprovals: [approval.collected],
+                tools: this.tools as ToolSet,
+                toolApproval: undefined,
+                messages: prompt.messages,
+                toolsContext:
+                  effectiveToolsContext as InferToolSetContext<ToolSet>,
+                runtimeContext: effectiveRuntimeContext,
+              });
+            if (policyDenied.length > 0) {
+              revalidationReason =
+                policyDenied[0].approvalResponse.reason ??
+                'Tool approval denied';
+            }
+          } catch (error) {
+            revalidationReason = getErrorMessage(error);
+          }
+
+          if (revalidationReason != null) {
+            toolResultContent.push({
+              type: 'tool-result' as const,
+              toolCallId: approval.toolCallId,
+              toolName: approval.toolName,
+              output: await createLanguageModelToolResultOutput({
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+                output: revalidationReason,
+                tool,
+                errorMode: 'text',
+                supportedUrls: {},
+                download,
+              }),
+            });
+            continue;
+          }
+
           try {
             const { execute } = tool;
-            const toolResult = await execute(approval.input, {
+            const resolvedContext = await resolveToolContext({
+              toolName: approval.toolName,
+              tool,
+              toolsContext: effectiveToolsContext,
+            });
+            const toolCallEvent: ToolCall = {
+              type: 'tool-call',
               toolCallId: approval.toolCallId,
-              messages: [],
-              context: effectiveExperimentalContext,
+              toolName: approval.toolName,
+              input: approval.input,
+            };
+            const messages = prompt.messages as unknown as ModelMessage[];
+            await telemetryDispatcher.onToolExecutionStart?.({
+              toolCall: toolCallEvent,
+              stepNumber: 0,
+              messages,
+              toolContext: resolvedContext,
+            });
+            const startTime = Date.now();
+            const executeApprovedTool = () =>
+              execute(approval.input, {
+                toolCallId: approval.toolCallId,
+                messages: [],
+                context: resolvedContext,
+              });
+            const toolResult =
+              telemetryDispatcher.executeTool != null
+                ? await telemetryDispatcher.executeTool({
+                    callId: 'workflow-agent',
+                    toolCallId: approval.toolCallId,
+                    execute: executeApprovedTool,
+                  })
+                : await executeApprovedTool();
+            await telemetryDispatcher.onToolExecutionEnd?.({
+              toolCall: toolCallEvent,
+              stepNumber: 0,
+              durationMs: Date.now() - startTime,
+              messages,
+              toolContext: resolvedContext,
+              success: true,
+              output: toolResult,
             });
             toolResultContent.push({
               type: 'tool-result' as const,
               toolCallId: approval.toolCallId,
               toolName: approval.toolName,
-              output:
-                typeof toolResult === 'string'
-                  ? { type: 'text' as const, value: toolResult }
-                  : { type: 'json' as const, value: toolResult },
+              output: await createLanguageModelToolResultOutput({
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+                output: toolResult,
+                tool,
+                errorMode: 'none',
+                supportedUrls: {},
+                download,
+              }),
+            });
+            approvedRawResults.push({
+              toolCallId: approval.toolCallId,
+              toolName: approval.toolName,
+              input: approval.input,
+              output: toolResult,
             });
           } catch (error) {
+            const errorMessage = getErrorMessage(error);
+            await telemetryDispatcher.onToolExecutionEnd?.({
+              toolCall: {
+                type: 'tool-call',
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+              },
+              stepNumber: 0,
+              durationMs: 0,
+              messages: prompt.messages as unknown as ModelMessage[],
+              toolContext: undefined,
+              success: false,
+              error,
+            });
             toolResultContent.push({
               type: 'tool-result' as const,
               toolCallId: approval.toolCallId,
               toolName: approval.toolName,
-              output: {
-                type: 'text' as const,
-                value: getErrorMessage(error),
-              },
+              output: await createLanguageModelToolResultOutput({
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+                output: errorMessage,
+                tool,
+                errorMode: 'text',
+                supportedUrls: {},
+                download,
+              }),
+            });
+            approvedRawResults.push({
+              toolCallId: approval.toolCallId,
+              toolName: approval.toolName,
+              input: approval.input,
+              output: errorMessage,
             });
           }
         }
@@ -1206,6 +1587,11 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
 
       // Create denial results for denied tools
       for (const denial of deniedToolApprovals) {
+        // Provider-executed denials are forwarded to the provider via the
+        // preserved approval response below, not turned into a local result.
+        if (denial.providerExecuted) {
+          continue;
+        }
         toolResultContent.push({
           type: 'tool-result' as const,
           toolCallId: denial.toolCallId,
@@ -1217,20 +1603,33 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         });
       }
 
-      // Strip approval parts from messages and inject tool results
+      // Strip approval parts that we resolved locally and inject tool results.
+      // Provider-executed approval parts are preserved so the next call to
+      // `convertToLanguageModelPrompt` forwards the approval response to the
+      // provider (it only forwards responses flagged `providerExecuted`).
       const cleanedMessages: ModelMessage[] = [];
       for (const msg of prompt.messages) {
         if (msg.role === 'assistant' && Array.isArray(msg.content)) {
           const filtered = (msg.content as any[]).filter(
-            (p: any) => p.type !== 'tool-approval-request',
+            (p: any) =>
+              p.type !== 'tool-approval-request' ||
+              providerExecutedApprovalIds.has(p.approvalId),
           );
           if (filtered.length > 0) {
             cleanedMessages.push({ ...msg, content: filtered });
           }
         } else if (msg.role === 'tool') {
-          const filtered = (msg.content as any[]).filter(
-            (p: any) => p.type !== 'tool-approval-response',
-          );
+          const filtered = (msg.content as any[]).flatMap((p: any) => {
+            if (p.type !== 'tool-approval-response') {
+              return [p];
+            }
+            if (!providerExecutedApprovalIds.has(p.approvalId)) {
+              return [];
+            }
+            // Re-stamp `providerExecuted` so the conversion layer forwards the
+            // response even if the client omitted the flag on the response part.
+            return [{ ...p, providerExecuted: true }];
+          });
           if (filtered.length > 0) {
             cleanedMessages.push({ ...msg, content: filtered });
           }
@@ -1253,22 +1652,12 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       // can transition approved/denied tool parts to the correct state
       // and properly separate them from the subsequent model step.
       if (options.writable && toolResultContent.length > 0) {
-        const approvedResults = toolResultContent
-          .filter(r => r.output.type !== 'execution-denied')
-          .map(r => ({
-            toolCallId: r.toolCallId,
-            toolName: r.toolName,
-            input: approvedToolApprovals.find(
-              a => a.toolCallId === r.toolCallId,
-            )?.input,
-            output: 'value' in r.output ? r.output.value : undefined,
-          }));
         const deniedResults = toolResultContent
           .filter(r => r.output.type === 'execution-denied')
           .map(r => ({ toolCallId: r.toolCallId }));
         await writeApprovalToolResults(
           options.writable,
-          approvedResults,
+          approvedRawResults,
           deniedResults,
         );
       }
@@ -1277,14 +1666,12 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     const modelPrompt = await convertToLanguageModelPrompt({
       prompt,
       supportedUrls: {},
-      download: options.experimental_download ?? this.experimentalDownload,
+      download,
     });
 
     const effectiveAbortSignal = mergeAbortSignals(
       options.abortSignal ?? effectiveGenerationSettings.abortSignal,
-      options.timeout != null
-        ? AbortSignal.timeout(options.timeout)
-        : undefined,
+      options.timeout,
     );
 
     // Merge generation settings: constructor defaults < prepareCall < stream options
@@ -1321,52 +1708,59 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     };
 
     // Merge constructor + stream callbacks (constructor first, then stream)
-    const mergedOnStepFinish = mergeCallbacks(
-      this.constructorOnStepFinish as
-        | WorkflowAgentOnStepFinishCallback<TTools>
+    const mergedOnStepEnd = mergeCallbacks(
+      this.constructorOnStepEnd as
+        | WorkflowAgentOnStepEndCallback<TTools, TRuntimeContext>
         | undefined,
-      options.onStepFinish,
+      options.onStepEnd ?? options.onStepFinish,
     );
-    const mergedOnFinish = mergeCallbacks(
-      this.constructorOnFinish as
-        | WorkflowAgentOnFinishCallback<TTools, OUTPUT>
+    const mergedOnEnd = mergeCallbacks(
+      this.constructorOnEnd as
+        | WorkflowAgentOnEndCallback<TTools, TRuntimeContext, OUTPUT>
         | undefined,
-      options.onFinish,
+      onEnd,
     );
     const mergedOnStart = mergeCallbacks(
-      this.constructorOnStart,
+      this.constructorOnStart as
+        | WorkflowAgentOnStartCallback<TTools, TRuntimeContext>
+        | undefined,
       options.experimental_onStart,
     );
     const mergedOnStepStart = mergeCallbacks(
-      this.constructorOnStepStart,
+      this.constructorOnStepStart as
+        | WorkflowAgentOnStepStartCallback<TTools, TRuntimeContext>
+        | undefined,
       options.experimental_onStepStart,
     );
-    const mergedOnToolCallStart = mergeCallbacks(
-      this.constructorOnToolCallStart,
-      options.experimental_onToolCallStart,
+    const mergedOnToolExecutionStart = mergeCallbacks(
+      this.constructorOnToolExecutionStart,
+      options.onToolExecutionStart,
     );
-    const mergedOnToolCallFinish = mergeCallbacks(
-      this.constructorOnToolCallFinish,
-      options.experimental_onToolCallFinish,
+    const mergedOnToolExecutionEnd = mergeCallbacks(
+      this.constructorOnToolExecutionEnd,
+      options.onToolExecutionEnd,
     );
 
     // Determine effective tool choice
     const effectiveToolChoice = effectiveToolChoiceFromPrepare;
 
-    // Merge telemetry settings
-    const effectiveTelemetry = effectiveTelemetryFromPrepare;
-
     // Filter tools if activeTools is specified (stream-level overrides constructor default)
     const effectiveActiveTools = options.activeTools ?? this.activeTools;
     const effectiveTools =
       effectiveActiveTools && effectiveActiveTools.length > 0
-        ? filterTools(this.tools, effectiveActiveTools as string[])
+        ? (filterActiveTools({
+            tools: this.tools,
+            activeTools: effectiveActiveTools,
+          }) ?? this.tools)
         : this.tools;
+    const effectiveModelInfo = getModelInfo(effectiveModel);
 
     // Initialize context
-    let experimentalContext = effectiveExperimentalContext;
+    let runtimeContext: TRuntimeContext = effectiveRuntimeContext;
+    let toolsContext: Record<string, Context | undefined> =
+      effectiveToolsContext;
 
-    const steps: StepResult<TTools, any>[] = [];
+    const steps: StepResult<TTools, TRuntimeContext>[] = [];
 
     // Track tool calls and results from the last step for the result
     let lastStepToolCalls: ToolCall[] = [];
@@ -1377,17 +1771,45 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       await mergedOnStart({
         model: effectiveModel,
         messages: prompt.messages,
+        runtimeContext,
+        toolsContext: toolsContext as unknown as InferToolSetContext<TTools>,
       });
     }
+    await telemetryDispatcher.onStart?.({
+      callId: 'workflow-agent',
+      operationId: 'ai.workflowAgent.stream',
+      provider: effectiveModelInfo.provider,
+      modelId: effectiveModelInfo.modelId,
+      system: undefined,
+      messages: prompt.messages,
+      tools: effectiveTools,
+      toolChoice: effectiveToolChoice,
+      activeTools: effectiveActiveTools as never,
+      maxOutputTokens: mergedGenerationSettings.maxOutputTokens,
+      temperature: mergedGenerationSettings.temperature,
+      topP: mergedGenerationSettings.topP,
+      topK: mergedGenerationSettings.topK,
+      presencePenalty: mergedGenerationSettings.presencePenalty,
+      frequencyPenalty: mergedGenerationSettings.frequencyPenalty,
+      stopSequences: mergedGenerationSettings.stopSequences,
+      seed: mergedGenerationSettings.seed,
+      maxRetries: mergedGenerationSettings.maxRetries ?? 2,
+      timeout: undefined,
+      headers: mergedGenerationSettings.headers,
+      providerOptions: mergedGenerationSettings.providerOptions,
+      output: (options.output ?? this.output) as never,
+      runtimeContext,
+      toolsContext: toolsContext as unknown as InferToolSetContext<TTools>,
+    });
 
-    // Helper to wrap executeTool with onToolCallStart/onToolCallFinish callbacks
+    // Helper to wrap executeTool with onToolExecutionStart/onToolExecutionEnd callbacks
     const executeToolWithCallbacks = async (
       toolCall: { toolCallId: string; toolName: string; input: unknown },
       tools: ToolSet,
       messages: LanguageModelV4Prompt,
-      context?: unknown,
+      perToolContexts: Record<string, Context | undefined>,
       currentStepNumber: number = 0,
-    ): Promise<LanguageModelV4ToolResultPart> => {
+    ): Promise<WorkflowToolExecutionResult> => {
       const toolCallEvent: ToolCall = {
         type: 'tool-call',
         toolCallId: toolCall.toolCallId,
@@ -1395,62 +1817,172 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         input: toolCall.input,
       };
 
-      if (mergedOnToolCallStart) {
-        await mergedOnToolCallStart({
+      const tool = tools[toolCall.toolName];
+      const resolvedContext = tool
+        ? await resolveToolContext({
+            toolName: toolCall.toolName,
+            tool,
+            toolsContext: perToolContexts,
+          })
+        : undefined;
+      const modelMessages = getToolCallbackMessages(messages);
+
+      if (mergedOnToolExecutionStart) {
+        await mergedOnToolExecutionStart({
           toolCall: toolCallEvent,
           stepNumber: currentStepNumber,
+          messages: modelMessages,
+          toolContext: resolvedContext as
+            | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+            | undefined,
         });
       }
+      await telemetryDispatcher.onToolExecutionStart?.({
+        toolCall: toolCallEvent,
+        stepNumber: currentStepNumber,
+        messages: modelMessages,
+        toolContext: resolvedContext as
+          | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+          | undefined,
+      });
 
       const startTime = Date.now();
-      let result: LanguageModelV4ToolResultPart;
+      let result: WorkflowToolExecutionResult;
       try {
-        result = await executeTool(toolCall, tools, messages, context);
+        const execute = () =>
+          executeTool(toolCall, tools, messages, resolvedContext, download);
+        result =
+          telemetryDispatcher.executeTool != null
+            ? await telemetryDispatcher.executeTool({
+                callId: 'workflow-agent',
+                toolCallId: toolCall.toolCallId,
+                execute,
+              })
+            : await execute();
       } catch (err) {
         const durationMs = Date.now() - startTime;
-        if (mergedOnToolCallFinish) {
-          await mergedOnToolCallFinish({
+        if (mergedOnToolExecutionEnd) {
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
+            messages: modelMessages,
+            toolContext: resolvedContext as
+              | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+              | undefined,
             success: false,
             error: err,
           });
         }
+        await telemetryDispatcher.onToolExecutionEnd?.({
+          toolCall: toolCallEvent,
+          stepNumber: currentStepNumber,
+          durationMs,
+          messages: modelMessages,
+          toolContext: resolvedContext as
+            | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+            | undefined,
+          success: false,
+          error: err,
+        });
         throw err;
       }
 
       const durationMs = Date.now() - startTime;
-      if (mergedOnToolCallFinish) {
-        const isError =
-          result.output &&
-          'type' in result.output &&
-          (result.output.type === 'error-text' ||
-            result.output.type === 'error-json');
-        if (isError) {
-          await mergedOnToolCallFinish({
+      if (mergedOnToolExecutionEnd) {
+        if (result.isError) {
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
+            messages: modelMessages,
+            toolContext: resolvedContext as
+              | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+              | undefined,
             success: false,
-            error: 'value' in result.output ? result.output.value : undefined,
+            error: result.rawOutput,
           });
         } else {
-          await mergedOnToolCallFinish({
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
+            messages: modelMessages,
+            toolContext: resolvedContext as
+              | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+              | undefined,
             success: true,
-            output:
-              result.output && 'value' in result.output
-                ? result.output.value
-                : undefined,
+            output: result.rawOutput,
           });
         }
       }
+      if (result.isError) {
+        await telemetryDispatcher.onToolExecutionEnd?.({
+          toolCall: toolCallEvent,
+          stepNumber: currentStepNumber,
+          durationMs,
+          messages: modelMessages,
+          toolContext: resolvedContext as
+            | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+            | undefined,
+          success: false,
+          error: result.rawOutput,
+        });
+      } else {
+        await telemetryDispatcher.onToolExecutionEnd?.({
+          toolCall: toolCallEvent,
+          stepNumber: currentStepNumber,
+          durationMs,
+          messages: modelMessages,
+          toolContext: resolvedContext as
+            | InferToolSetContext<TTools>[keyof InferToolSetContext<TTools>]
+            | undefined,
+          success: true,
+          output: result.rawOutput,
+        });
+      }
       return result;
     };
 
+    const recordProviderExecutedToolTelemetry = async (
+      toolCall: { toolCallId: string; toolName: string; input: unknown },
+      result: WorkflowToolExecutionResult,
+      messages: LanguageModelV4Prompt,
+      currentStepNumber: number,
+    ) => {
+      const toolCallEvent: ToolCall = {
+        type: 'tool-call',
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: toolCall.input,
+      };
+      const modelMessages = getToolCallbackMessages(messages);
+
+      await telemetryDispatcher.onToolExecutionStart?.({
+        toolCall: toolCallEvent,
+        stepNumber: currentStepNumber,
+        messages: modelMessages,
+        toolContext: undefined,
+      });
+
+      await telemetryDispatcher.onToolExecutionEnd?.({
+        toolCall: toolCallEvent,
+        stepNumber: currentStepNumber,
+        durationMs: 0,
+        messages: modelMessages,
+        toolContext: undefined,
+        ...(result.isError
+          ? {
+              success: false as const,
+              error: result.rawOutput,
+            }
+          : {
+              success: true as const,
+              output: result.rawOutput,
+            }),
+      });
+    };
+
     // Check for abort before starting
     if (mergedGenerationSettings.abortSignal?.aborted) {
       if (options.onAbort) {
@@ -1471,17 +2003,19 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       writable: options.writable,
       prompt: modelPrompt,
       stopConditions: options.stopWhen ?? this.stopWhen,
-      maxSteps: options.maxSteps,
-      onStepFinish: mergedOnStepFinish,
-      onStepStart: mergedOnStepStart,
+
+      onStepEnd: mergedOnStepEnd as any,
+      onStepStart: mergedOnStepStart as any,
       onError: options.onError,
-      prepareStep:
-        options.prepareStep ??
-        (this.prepareStep as PrepareStepCallback<ToolSet> | undefined),
+      prepareStep: (options.prepareStep ??
+        (this.prepareStep as
+          | PrepareStepCallback<ToolSet, TRuntimeContext>
+          | undefined)) as any,
       generationSettings: mergedGenerationSettings,
       toolChoice: effectiveToolChoice as ToolChoice<ToolSet>,
-      experimental_context: experimentalContext,
-      experimental_telemetry: effectiveTelemetry,
+      runtimeContext,
+      toolsContext,
+      telemetry: effectiveTelemetry,
       includeRawChunks: options.includeRawChunks ?? false,
       repairToolCall: (options.experimental_repairToolCall ??
         this.experimentalRepairToolCall) as
@@ -1511,25 +2045,34 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
           toolCalls,
           messages: iterMessages,
           step,
-          context,
+          runtimeContext: yieldedRuntimeContext,
+          toolsContext: yieldedToolsContext,
           providerExecutedToolResults,
         } = result.value;
         // Capture current step number before pushing (0-based)
         const currentStepNumber = steps.length;
         if (step) {
-          steps.push(step as unknown as StepResult<TTools, any>);
+          steps.push(step as unknown as StepResult<TTools, TRuntimeContext>);
         }
-        if (context !== undefined) {
-          experimentalContext = context;
+        if (yieldedRuntimeContext !== undefined) {
+          runtimeContext = yieldedRuntimeContext as TRuntimeContext;
+        }
+        if (yieldedToolsContext !== undefined) {
+          toolsContext = yieldedToolsContext;
         }
 
         // Only execute tools if there are tool calls
         if (toolCalls.length > 0) {
+          const invalidToolCalls = toolCalls.filter(tc => tc.invalid === true);
+          const validToolCalls = toolCalls.filter(tc => tc.invalid !== true);
+
           // Separate provider-executed tool calls from client-executed ones
-          const nonProviderToolCalls = toolCalls.filter(
+          const nonProviderToolCalls = validToolCalls.filter(
             tc => !tc.providerExecuted,
           );
-          const providerToolCalls = toolCalls.filter(tc => tc.providerExecuted);
+          const providerToolCalls = validToolCalls.filter(
+            tc => tc.providerExecuted,
+          );
 
           // Check which tools need approval (can be async)
           const approvalNeeded = await Promise.all(
@@ -1539,10 +2082,16 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
               if (tool.needsApproval == null) return false;
               if (typeof tool.needsApproval === 'boolean')
                 return tool.needsApproval;
+              const resolvedContext = await resolveToolContext({
+                toolName: tc.toolName,
+                tool,
+                toolsContext:
+                  toolsContext as unknown as InferToolSetContext<TTools>,
+              });
               return tool.needsApproval(tc.input, {
                 toolCallId: tc.toolCallId,
                 messages: iterMessages as unknown as ModelMessage[],
-                context: experimentalContext,
+                context: resolvedContext,
               });
             }),
           );
@@ -1573,27 +2122,49 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             // Execute any executable tools that were also called in this step
             const executableResults = await Promise.all(
               executableToolCalls.map(
-                (toolCall): Promise<LanguageModelV4ToolResultPart> =>
+                (toolCall): Promise<WorkflowToolExecutionResult> =>
                   executeToolWithCallbacks(
                     toolCall,
                     effectiveTools as ToolSet,
                     iterMessages,
-                    experimentalContext,
+                    toolsContext,
                     currentStepNumber,
                   ),
               ),
             );
 
             // Collect provider tool results
-            const providerResults: LanguageModelV4ToolResultPart[] =
-              providerToolCalls.map(toolCall =>
-                resolveProviderToolResult(
-                  toolCall,
-                  providerExecutedToolResults,
+            const providerResults: WorkflowToolExecutionResult[] =
+              await Promise.all(
+                providerToolCalls.map(toolCall =>
+                  resolveProviderToolResult(
+                    toolCall,
+                    providerExecutedToolResults,
+                    effectiveTools as ToolSet,
+                    download,
+                  ),
                 ),
               );
+            await Promise.all(
+              providerToolCalls.map((toolCall, index) =>
+                recordProviderExecutedToolTelemetry(
+                  toolCall,
+                  providerResults[index],
+                  iterMessages,
+                  currentStepNumber,
+                ),
+              ),
+            );
 
-            const resolvedResults = [...executableResults, ...providerResults];
+            const continuationInvalidResults = invalidToolCalls.map(
+              createInvalidToolResult,
+            );
+            const resolvedResults: LanguageModelV4ToolResultPart[] = [
+              ...executableResults.map(result => result.modelResult),
+              ...providerResults.map(result => result.modelResult),
+              ...continuationInvalidResults,
+            ];
+            const executedResults = [...executableResults, ...providerResults];
 
             const allToolCalls: ToolCall[] = toolCalls.map(tc => ({
               type: 'tool-call' as const,
@@ -1602,13 +2173,14 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
               input: tc.input,
             }));
 
-            const allToolResults: ToolResult[] = resolvedResults.map(r => ({
+            const allToolResults: ToolResult[] = executedResults.map(r => ({
               type: 'tool-result' as const,
-              toolCallId: r.toolCallId,
-              toolName: r.toolName,
-              input: toolCalls.find(tc => tc.toolCallId === r.toolCallId)
-                ?.input,
-              output: 'value' in r.output ? r.output.value : undefined,
+              toolCallId: r.modelResult.toolCallId,
+              toolName: r.modelResult.toolName,
+              input: toolCalls.find(
+                tc => tc.toolCallId === r.modelResult.toolCallId,
+              )?.input,
+              output: r.rawOutput,
             }));
 
             if (resolvedResults.length > 0) {
@@ -1620,18 +2192,33 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
 
             const messages = iterMessages as unknown as ModelMessage[];
 
-            if (mergedOnFinish && !wasAborted) {
+            if (mergedOnEnd && !wasAborted) {
               const lastStep = steps[steps.length - 1];
-              await mergedOnFinish({
+              const totalUsage = aggregateUsage(steps);
+              await mergedOnEnd({
                 steps,
                 messages,
                 text: lastStep?.text ?? '',
                 finishReason: lastStep?.finishReason ?? 'other',
-                totalUsage: aggregateUsage(steps),
-                experimental_context: experimentalContext,
+                usage: totalUsage,
+                totalUsage,
+                runtimeContext,
+                toolsContext:
+                  toolsContext as unknown as InferToolSetContext<TTools>,
                 output: undefined as OUTPUT,
               });
             }
+            if (!wasAborted && steps.length > 0) {
+              const telemetrySteps = steps.map(normalizeStepForTelemetry);
+              const lastStep = telemetrySteps[telemetrySteps.length - 1];
+              const totalUsage = aggregateUsage(steps);
+              await telemetryDispatcher.onEnd?.({
+                ...lastStep,
+                steps: telemetrySteps,
+                usage: totalUsage,
+                totalUsage,
+              });
+            }
 
             // Emit tool-approval-request chunks for tools that need approval
             // so useChat can show the approval UI
@@ -1674,40 +2261,67 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
           // Execute client tools (all have execute functions at this point)
           const clientToolResults = await Promise.all(
             nonProviderToolCalls.map(
-              (toolCall): Promise<LanguageModelV4ToolResultPart> =>
+              (toolCall): Promise<WorkflowToolExecutionResult> =>
                 executeToolWithCallbacks(
                   toolCall,
                   effectiveTools as ToolSet,
                   iterMessages,
-                  experimentalContext,
+                  toolsContext,
                   currentStepNumber,
                 ),
             ),
           );
 
           // For provider-executed tools, use the results from the stream
-          const providerToolResults: LanguageModelV4ToolResultPart[] =
-            providerToolCalls.map(toolCall =>
-              resolveProviderToolResult(toolCall, providerExecutedToolResults),
+          const providerToolResults: WorkflowToolExecutionResult[] =
+            await Promise.all(
+              providerToolCalls.map(toolCall =>
+                resolveProviderToolResult(
+                  toolCall,
+                  providerExecutedToolResults,
+                  effectiveTools as ToolSet,
+                  download,
+                ),
+              ),
             );
+          await Promise.all(
+            providerToolCalls.map((toolCall, index) =>
+              recordProviderExecutedToolTelemetry(
+                toolCall,
+                providerToolResults[index],
+                iterMessages,
+                currentStepNumber,
+              ),
+            ),
+          );
+          const continuationInvalidToolResults = invalidToolCalls.map(
+            createInvalidToolResult,
+          );
 
-          // Combine results in the original order
-          const toolResults = toolCalls.map(tc => {
+          // Combine executable/provider results in the original order,
+          // while preserving invalid tool calls as error results for the
+          // next model step without emitting them as synthetic UI success.
+          const executedToolResults = toolCalls.flatMap(tc => {
             const clientResult = clientToolResults.find(
-              r => r.toolCallId === tc.toolCallId,
+              r => r.modelResult.toolCallId === tc.toolCallId,
             );
-            if (clientResult) return clientResult;
+            if (clientResult) return [clientResult];
             const providerResult = providerToolResults.find(
+              r => r.modelResult.toolCallId === tc.toolCallId,
+            );
+            if (providerResult) return [providerResult];
+            return [];
+          });
+          const continuationToolResults = toolCalls.flatMap(tc => {
+            const invalidResult = continuationInvalidToolResults.find(
               r => r.toolCallId === tc.toolCallId,
             );
-            if (providerResult) return providerResult;
-            // This should never happen, but return empty result as fallback
-            return {
-              type: 'tool-result' as const,
-              toolCallId: tc.toolCallId,
-              toolName: tc.toolName,
-              output: { type: 'text' as const, value: '' },
-            };
+            if (invalidResult) return [invalidResult];
+            const executedResult = executedToolResults.find(
+              r => r.modelResult.toolCallId === tc.toolCallId,
+            );
+            if (executedResult) return [executedResult.modelResult];
+            return [];
           });
 
           // Write tool results and step boundaries to the stream so the
@@ -1716,12 +2330,13 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
           if (options.writable) {
             await writeToolResultsWithStepBoundary(
               options.writable,
-              toolResults.map(r => ({
-                toolCallId: r.toolCallId,
-                toolName: r.toolName,
-                input: toolCalls.find(tc => tc.toolCallId === r.toolCallId)
-                  ?.input,
-                output: 'value' in r.output ? r.output.value : undefined,
+              executedToolResults.map(r => ({
+                toolCallId: r.modelResult.toolCallId,
+                toolName: r.modelResult.toolName,
+                input: toolCalls.find(
+                  tc => tc.toolCallId === r.modelResult.toolCallId,
+                )?.input,
+                output: r.rawOutput,
               })),
             );
           }
@@ -1733,15 +2348,17 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             toolName: tc.toolName,
             input: tc.input,
           }));
-          lastStepToolResults = toolResults.map(r => ({
+          lastStepToolResults = executedToolResults.map(r => ({
             type: 'tool-result' as const,
-            toolCallId: r.toolCallId,
-            toolName: r.toolName,
-            input: toolCalls.find(tc => tc.toolCallId === r.toolCallId)?.input,
-            output: 'value' in r.output ? r.output.value : undefined,
+            toolCallId: r.modelResult.toolCallId,
+            toolName: r.modelResult.toolName,
+            input: toolCalls.find(
+              tc => tc.toolCallId === r.modelResult.toolCallId,
+            )?.input,
+            output: r.rawOutput,
           }));
 
-          result = await iterator.next(toolResults);
+          result = await iterator.next(continuationToolResults);
         } else {
           // Final step with no tool calls - reset tracking
           lastStepToolCalls = [];
@@ -1766,7 +2383,8 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         // Call onError for non-abort errors (including tool execution errors)
         await options.onError({ error });
       }
-      // Don't throw yet - we want to call onFinish first
+      await telemetryDispatcher.onError?.(error);
+      // Don't throw yet - we want to call onEnd first
     }
 
     // Use the final messages from the iterator, or fall back to standardized messages
@@ -1799,19 +2417,33 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       }
     }
 
-    // Call onFinish callback if provided (always call, even on errors, but not on abort)
-    if (mergedOnFinish && !wasAborted) {
+    // Call onEnd callback if provided (always call, even on errors, but not on abort)
+    if (mergedOnEnd && !wasAborted) {
       const lastStep = steps[steps.length - 1];
-      await mergedOnFinish({
+      const totalUsage = aggregateUsage(steps);
+      await mergedOnEnd({
         steps,
         messages: messages as ModelMessage[],
         text: lastStep?.text ?? '',
         finishReason: lastStep?.finishReason ?? 'other',
-        totalUsage: aggregateUsage(steps),
-        experimental_context: experimentalContext,
+        usage: totalUsage,
+        totalUsage,
+        runtimeContext,
+        toolsContext: toolsContext as unknown as InferToolSetContext<TTools>,
         output: experimentalOutput,
       });
     }
+    if (!wasAborted && steps.length > 0) {
+      const telemetrySteps = steps.map(normalizeStepForTelemetry);
+      const lastStep = telemetrySteps[telemetrySteps.length - 1];
+      const totalUsage = aggregateUsage(steps);
+      await telemetryDispatcher.onEnd?.({
+        ...lastStep,
+        steps: telemetrySteps,
+        usage: totalUsage,
+        totalUsage,
+      });
+    }
 
     // Re-throw any error that occurred
     if (encounteredError) {
@@ -1845,6 +2477,25 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
   }
 }
 
+function getModelInfo(model: LanguageModel): {
+  provider: string;
+  modelId: string;
+} {
+  return typeof model === 'string'
+    ? { provider: model.split('/')[0] ?? 'gateway', modelId: model }
+    : { provider: model.provider, modelId: model.modelId };
+}
+
+function normalizeStepForTelemetry<
+  TOOLS extends ToolSet,
+  RUNTIME_CONTEXT extends Context,
+>(step: StepResult<TOOLS, RUNTIME_CONTEXT>) {
+  return {
+    ...step,
+    model: step.model ?? { provider: 'unknown', modelId: 'unknown' },
+  };
+}
+
 /**
  * Filter tools to only include the specified active tools.
  */
@@ -1965,6 +2616,33 @@ async function writeApprovalToolResults(
   }
 }
 
+/**
+ * Resolve the per-tool context that gets passed into a tool's `execute`
+ * (and `needsApproval`) function. When the tool declares a `contextSchema`,
+ * the entry is validated against it.
+ */
+async function resolveToolContext({
+  toolName,
+  tool,
+  toolsContext,
+}: {
+  toolName: string;
+  tool: ToolSet[string];
+  toolsContext: Record<string, Context | undefined> | undefined;
+}): Promise<unknown> {
+  const contextSchema = (tool as { contextSchema?: unknown }).contextSchema;
+  const entry = toolsContext?.[toolName];
+  if (contextSchema == null) {
+    return entry;
+  }
+
+  return await validateTypes({
+    value: entry,
+    schema: contextSchema as Parameters<typeof validateTypes>[0]['schema'],
+    context: { field: 'tool context', entityName: toolName },
+  });
+}
+
 function aggregateUsage(steps: StepResult<any, any>[]): LanguageModelUsage {
   let inputTokens = 0;
   let outputTokens = 0;
@@ -1979,43 +2657,15 @@ function aggregateUsage(steps: StepResult<any, any>[]): LanguageModelUsage {
   } as LanguageModelUsage;
 }
 
-function filterTools<TTools extends ToolSet>(
-  tools: TTools,
-  activeTools: string[],
-): ToolSet {
-  const filtered: ToolSet = {};
-  for (const toolName of activeTools) {
-    if (toolName in tools) {
-      filtered[toolName] = tools[toolName];
-    }
-  }
-  return filtered;
-}
-
-// Matches AI SDK's getErrorMessage from @ai-sdk/provider-utils
-function getErrorMessage(error: unknown): string {
-  if (error == null) {
-    return 'unknown error';
-  }
-
-  if (typeof error === 'string') {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return JSON.stringify(error);
-}
-
-function resolveProviderToolResult(
-  toolCall: { toolCallId: string; toolName: string },
+async function resolveProviderToolResult(
+  toolCall: { toolCallId: string; toolName: string; input: unknown },
   providerExecutedToolResults?: Map<
     string,
     { toolCallId: string; toolName: string; result: unknown; isError?: boolean }
   >,
-): LanguageModelV4ToolResultPart {
+  tools?: ToolSet,
+  download?: DownloadFunction,
+): Promise<WorkflowToolExecutionResult> {
   const streamResult = providerExecutedToolResults?.get(toolCall.toolCallId);
   if (!streamResult) {
     console.warn(
@@ -2023,45 +2673,79 @@ function resolveProviderToolResult(
         `did not receive a result from the stream. This may indicate a provider issue.`,
     );
     return {
-      type: 'tool-result' as const,
-      toolCallId: toolCall.toolCallId,
-      toolName: toolCall.toolName,
-      output: {
-        type: 'text' as const,
-        value: '',
+      modelResult: {
+        type: 'tool-result' as const,
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: {
+          type: 'text' as const,
+          value: '',
+        },
       },
+      rawOutput: '',
+      isError: false,
     };
   }
 
   const result = streamResult.result;
-  const isString = typeof result === 'string';
+  const errorMode = streamResult.isError
+    ? typeof result === 'string'
+      ? 'text'
+      : 'json'
+    : 'none';
+
+  return {
+    modelResult: {
+      type: 'tool-result' as const,
+      toolCallId: toolCall.toolCallId,
+      toolName: toolCall.toolName,
+      output: await createLanguageModelToolResultOutput({
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: toolCall.input,
+        output: result,
+        tool: tools?.[toolCall.toolName],
+        errorMode,
+        supportedUrls: {},
+        download,
+      }),
+    },
+    rawOutput: result,
+    isError: streamResult.isError === true,
+  };
+}
 
+function createInvalidToolResult(toolCall: {
+  toolCallId: string;
+  toolName: string;
+  error?: unknown;
+}): LanguageModelV4ToolResultPart {
   return {
     type: 'tool-result' as const,
     toolCallId: toolCall.toolCallId,
     toolName: toolCall.toolName,
-    output: isString
-      ? streamResult.isError
-        ? { type: 'error-text' as const, value: result }
-        : { type: 'text' as const, value: result }
-      : streamResult.isError
-        ? {
-            type: 'error-json' as const,
-            value: result as JSONValue,
-          }
-        : {
-            type: 'json' as const,
-            value: result as JSONValue,
-          },
+    output: {
+      type: 'error-text' as const,
+      value: getErrorMessage(toolCall.error),
+    },
   };
 }
 
+function getToolCallbackMessages(
+  messages: LanguageModelV4Prompt,
+): ModelMessage[] {
+  const withoutAssistantToolCall =
+    messages.at(-1)?.role === 'assistant' ? messages.slice(0, -1) : messages;
+  return withoutAssistantToolCall as unknown as ModelMessage[];
+}
+
 async function executeTool(
   toolCall: { toolCallId: string; toolName: string; input: unknown },
   tools: ToolSet,
   messages: LanguageModelV4Prompt,
-  experimentalContext?: unknown,
-): Promise<LanguageModelV4ToolResultPart> {
+  context?: unknown,
+  download?: DownloadFunction,
+): Promise<WorkflowToolExecutionResult> {
   const tool = tools[toolCall.toolName];
   if (!tool) throw new Error(`Tool "${toolCall.toolName}" not found`);
   if (typeof tool.execute !== 'function') {
@@ -2072,6 +2756,7 @@ async function executeTool(
   }
   // Input is already parsed and validated by streamModelCall's parseToolCall
   const parsedInput = toolCall.input;
+  let toolResult: unknown;
 
   try {
     // Extract execute function to avoid binding `this` to the tool object.
@@ -2080,149 +2765,56 @@ async function executeTool(
     // When the execute function is a workflow step (marked with 'use step'),
     // the step system captures `this` for serialization, causing failures.
     const { execute } = tool;
-    const toolResult = await execute(parsedInput, {
+    toolResult = await execute(parsedInput, {
       toolCallId: toolCall.toolCallId,
       // Pass the conversation messages to the tool so it has context about the conversation
       messages,
-      // Pass context to the tool
-      context: experimentalContext,
+      // Pass per-tool context to the tool (resolved from `toolsContext`)
+      context,
     });
-
-    // Use the appropriate output type based on the result
-    // AI SDK supports 'text' for strings and 'json' for objects
-    const output =
-      typeof toolResult === 'string'
-        ? { type: 'text' as const, value: toolResult }
-        : { type: 'json' as const, value: toolResult };
-
-    return {
-      type: 'tool-result' as const,
-      toolCallId: toolCall.toolCallId,
-      toolName: toolCall.toolName,
-      output,
-    };
   } catch (error) {
     // Convert tool errors to error-text results sent back to the model,
     // allowing the agent to recover rather than killing the entire stream.
     // This aligns with AI SDK's streamText behavior for individual tool failures.
+    const errorMessage = getErrorMessage(error);
     return {
-      type: 'tool-result',
-      toolCallId: toolCall.toolCallId,
-      toolName: toolCall.toolName,
-      output: {
-        type: 'error-text',
-        value: getErrorMessage(error),
+      modelResult: {
+        type: 'tool-result',
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: await createLanguageModelToolResultOutput({
+          toolCallId: toolCall.toolCallId,
+          toolName: toolCall.toolName,
+          input: parsedInput,
+          output: errorMessage,
+          tool,
+          errorMode: 'text',
+          supportedUrls: {},
+          download,
+        }),
       },
+      rawOutput: errorMessage,
+      isError: true,
     };
   }
-}
 
-/**
- * Collected tool approval information for a single tool call.
- */
-interface CollectedApproval {
-  toolCallId: string;
-  toolName: string;
-  input: unknown;
-  approvalId: string;
-  reason?: string;
-}
-
-/**
- * Collect tool approval responses from model messages.
- * Mirrors the logic from `collectToolApprovals` in the AI SDK core
- * (`packages/ai/src/generate-text/collect-tool-approvals.ts`).
- *
- * Scans the last tool message for `tool-approval-response` parts,
- * matches them with `tool-approval-request` parts in assistant messages
- * and the corresponding `tool-call` parts.
- */
-function collectToolApprovalsFromMessages(messages: ModelMessage[]): {
-  approvedToolApprovals: CollectedApproval[];
-  deniedToolApprovals: CollectedApproval[];
-} {
-  const lastMessage = messages.at(-1);
-
-  if (lastMessage?.role !== 'tool') {
-    return { approvedToolApprovals: [], deniedToolApprovals: [] };
-  }
-
-  // Gather tool calls from assistant messages
-  const toolCallsByToolCallId: Record<
-    string,
-    { toolName: string; input: unknown }
-  > = {};
-  for (const message of messages) {
-    if (message.role === 'assistant' && Array.isArray(message.content)) {
-      for (const part of message.content as any[]) {
-        if (part.type === 'tool-call') {
-          toolCallsByToolCallId[part.toolCallId] = {
-            toolName: part.toolName,
-            input: part.input ?? part.args,
-          };
-        }
-      }
-    }
-  }
-
-  // Gather approval requests from assistant messages
-  const approvalRequestsByApprovalId: Record<
-    string,
-    { approvalId: string; toolCallId: string }
-  > = {};
-  for (const message of messages) {
-    if (message.role === 'assistant' && Array.isArray(message.content)) {
-      for (const part of message.content as any[]) {
-        if (part.type === 'tool-approval-request') {
-          approvalRequestsByApprovalId[part.approvalId] = {
-            approvalId: part.approvalId,
-            toolCallId: part.toolCallId,
-          };
-        }
-      }
-    }
-  }
-
-  // Gather existing tool results to avoid re-executing
-  const existingToolResults = new Set<string>();
-  for (const part of lastMessage.content as any[]) {
-    if (part.type === 'tool-result') {
-      existingToolResults.add(part.toolCallId);
-    }
-  }
-
-  const approvedToolApprovals: CollectedApproval[] = [];
-  const deniedToolApprovals: CollectedApproval[] = [];
-
-  // Collect approval responses from the last tool message
-  const approvalResponses = (lastMessage.content as any[]).filter(
-    (part: any) => part.type === 'tool-approval-response',
-  );
-
-  for (const response of approvalResponses) {
-    const approvalRequest = approvalRequestsByApprovalId[response.approvalId];
-    if (approvalRequest == null) continue;
-
-    // Skip if there's already a tool result for this tool call
-    if (existingToolResults.has(approvalRequest.toolCallId)) continue;
-
-    const toolCall = toolCallsByToolCallId[approvalRequest.toolCallId];
-    if (toolCall == null) continue;
-
-    const approval: CollectedApproval = {
-      toolCallId: approvalRequest.toolCallId,
+  return {
+    modelResult: {
+      type: 'tool-result' as const,
+      toolCallId: toolCall.toolCallId,
       toolName: toolCall.toolName,
-      input: toolCall.input,
-      approvalId: response.approvalId,
-      reason: response.reason,
-    };
-
-    if (response.approved) {
-      approvedToolApprovals.push(approval);
-    } else {
-      deniedToolApprovals.push(approval);
-    }
-  }
-
-  return { approvedToolApprovals, deniedToolApprovals };
+      output: await createLanguageModelToolResultOutput({
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: parsedInput,
+        output: toolResult,
+        tool,
+        errorMode: 'none',
+        supportedUrls: {},
+        download,
+      }),
+    },
+    rawOutput: toolResult,
+    isError: false,
+  };
 }