@strands-agents/sdk 1.0.0-rc.5 → 1.1.0

package/dist/src/agent/agent.js

@@ -54,16 +54,18 @@ import { AgentResult, } from '../types/agent.js';
 import { BedrockModel } from '../models/bedrock.js';
 import { contentBlockFromData, Message, TextBlock, ToolResultBlock, ToolUseBlock, } from '../types/messages.js';
 import { McpClient } from '../mcp.js';
-import {} from '../tools/tool.js';
+import { isValidToolName } from '../tools/tool.js';
 import { systemPromptFromData } from '../types/messages.js';
 import { normalizeError, ConcurrentInvocationError, StructuredOutputError } from '../errors.js';
 import { Model } from '../models/model.js';
+import { ModelPlugin } from '../plugins/model-plugin.js';
 import { isModelStreamEvent } from '../models/streaming.js';
 import { ToolRegistry } from '../registry/tool-registry.js';
 import { StateStore } from '../state-store.js';
 import { AgentPrinter, getDefaultAppender } from './printer.js';
 import { PluginRegistry } from '../plugins/registry.js';
 import { SlidingWindowConversationManager } from '../conversation-manager/sliding-window-conversation-manager.js';
+import { NullConversationManager } from '../conversation-manager/null-conversation-manager.js';
 import { ConversationManager } from '../conversation-manager/conversation-manager.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
 import { InitializedEvent, AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, HookableEvent, MessageAddedEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, AgentResultEvent, ToolStreamUpdateEvent, } from '../hooks/events.js';
@@ -74,6 +76,10 @@ import { Tracer } from '../telemetry/tracer.js';
 import { Meter } from '../telemetry/meter.js';
 import { logger } from '../logging/logger.js';
 import { CancelledError } from '../errors.js';
+import { DefaultModelRetryStrategy } from '../retry/default-model-retry-strategy.js';
+import { warnOnDuplicateRetryStrategyTypes } from '../retry/retry-strategy.js';
+import { InterruptError, InterruptState, interruptFromAgent } from '../interrupt.js';
+import { isInterruptResponseContent } from '../types/interrupt.js';
 /** Default name assigned to agents when none is provided. */
 const DEFAULT_AGENT_NAME = 'Strands Agent';
 /** Default identifier assigned to agents when none is provided. */
@@ -93,6 +99,12 @@ export class Agent {
      * State is not passed to the model during inference.
      */
     appState;
+    /**
+     * Runtime state for the model provider. Used by stateful models to persist
+     * provider-specific data (e.g., response IDs for conversation chaining)
+     * across invocations.
+     */
+    modelState;
     _conversationManager;
     /**
      * The model provider used by the agent for inference.
@@ -132,6 +144,10 @@ export class Agent {
     _tracer;
     /** Meter instance for accumulating loop metrics during invocation. */
     _meter;
+    /** Interrupt state for human-in-the-loop workflows. */
+    _interruptState;
+    /** Strategy for executing tool calls from a single assistant turn. */
+    _toolExecutor;
     /**
      * Creates an instance of the Agent.
      * @param config - The configuration for the agent.
@@ -140,7 +156,7 @@ export class Agent {
         // Initialize public fields
         this.messages = (config?.messages ?? []).map((msg) => (msg instanceof Message ? msg : Message.fromMessageData(msg)));
         this.appState = new StateStore(config?.appState);
-        this._conversationManager = config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+        this.modelState = new StateStore(config?.modelState);
         this.name = config?.name ?? DEFAULT_AGENT_NAME;
         this.id = config?.id ?? DEFAULT_AGENT_ID;
         if (config?.description !== undefined)
@@ -152,16 +168,45 @@ export class Agent {
         else {
             this.model = config?.model ?? new BedrockModel();
         }
+        // Validate and assign conversation manager
+        if (this.model.stateful) {
+            if (config?.conversationManager) {
+                throw new Error('Cannot use a conversationManager with a stateful model. The model manages conversation state server-side.');
+            }
+            this._conversationManager = new NullConversationManager();
+        }
+        else {
+            this._conversationManager =
+                config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+        }
         const { tools, mcpClients } = flattenTools(config?.tools ?? []);
         this._toolRegistry = new ToolRegistry(tools);
         this._mcpClients = mcpClients;
         // Initialize hooks registry
         this._hooksRegistry = new HookRegistryImplementation();
-        // Initialize plugin registry with all plugins to be initialized during initialize()
+        // `undefined` (omitted) → install the default; `null`/`[]` → explicit opt-out.
+        const retryStrategies = config?.retryStrategy === null
+            ? []
+            : config?.retryStrategy === undefined
+                ? [new DefaultModelRetryStrategy()]
+                : Array.isArray(config.retryStrategy)
+                    ? config.retryStrategy
+                    : [config.retryStrategy];
+        warnOnDuplicateRetryStrategyTypes(retryStrategies);
+        // Initialize plugin registry with all plugins to be initialized during initialize().
+        // Ordering notes:
+        // - ModelPlugin is registered last so that on AfterInvocationEvent (which uses
+        //   reverse callback ordering), it runs first — clearing messages before
+        //   SessionManager saves.
+        // - Retry-strategy ordering is not load-bearing for correctness: `DefaultModelRetryStrategy`
+        //   guards on `event.retry`, so a user hook that already set it short-circuits
+        //   the strategy regardless of registration order.
         this._pluginRegistry = new PluginRegistry([
             this._conversationManager,
+            ...retryStrategies,
             ...(config?.plugins ?? []),
             ...(config?.sessionManager ? [config.sessionManager] : []),
+            new ModelPlugin(this.model),
         ]);
         if (config?.systemPrompt !== undefined) {
             this.systemPrompt = systemPromptFromData(config.systemPrompt);
@@ -177,6 +222,9 @@ export class Agent {
         this._tracer = new Tracer(config?.traceAttributes);
         // Initialize meter for local metrics accumulation
         this._meter = new Meter();
+        // Initialize interrupt state for human-in-the-loop workflows
+        this._interruptState = new InterruptState();
+        this._toolExecutor = config?.toolExecutor ?? 'concurrent';
         this._initialized = false;
     }
     /**
@@ -184,6 +232,7 @@ export class Agent {
      *
      * @param eventType - The event class constructor to register the callback for
      * @param callback - The callback function to invoke when the event occurs
+     * @param options - Optional configuration including execution order
      * @returns Cleanup function that removes the callback when invoked
      *
      * @example
@@ -198,8 +247,8 @@ export class Agent {
      * cleanup()
      * ```
      */
-    addHook(eventType, callback) {
-        return this._hooksRegistry.addCallback(eventType, callback);
+    addHook(eventType, callback, options) {
+        return this._hooksRegistry.addCallback(eventType, callback, options);
     }
     async initialize() {
         if (this._initialized) {
@@ -358,53 +407,86 @@ export class Agent {
     async *stream(args, options) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            const _lock = __addDisposableResource(env_1, this.acquireLock()
-            // Create AbortController for this invocation and compose with external signal
-            , false);
-            // Create AbortController for this invocation and compose with external signal
-            this._abortController = new AbortController();
-            this._abortSignal = options?.cancelSignal
-                ? AbortSignal.any([this._abortController.signal, options.cancelSignal])
-                : this._abortController.signal;
+            const _lock = __addDisposableResource(env_1, this.acquireLock(), false);
             await this.initialize();
-            // Delegate to _stream and process events through printer and hooks
-            const streamGenerator = this._stream(args, options);
-            let caughtError;
-            try {
-                let result = await streamGenerator.next();
-                while (!result.done) {
-                    yield await this._invokeCallbacks(result.value);
-                    result = await streamGenerator.next();
-                }
-                yield await this._invokeCallbacks(new AgentResultEvent({ agent: this, result: result.value }));
-                return result.value;
-            }
-            catch (error) {
-                caughtError = error;
-                throw error;
-            }
-            finally {
-                // Drain _stream() so cleanup hooks and printer still fire.
-                // Yield only on error (consumer may still be iterating); on a consumer
-                // break, yielding would suspend the generator and leak the lock.
-                let result = await streamGenerator.return(undefined);
-                while (!result.done) {
-                    try {
-                        if (caughtError) {
-                            yield await this._invokeCallbacks(result.value);
+            let currentArgs = args;
+            // Outer loop: re-enters _stream when a hook sets AfterInvocationEvent.resume.
+            // One invocation lock spans the whole resume chain.
+            while (true) {
+                // Fresh AbortController per invocation iteration, composed with any external signal.
+                this._abortController = new AbortController();
+                this._abortSignal = options?.cancelSignal
+                    ? AbortSignal.any([this._abortController.signal, options.cancelSignal])
+                    : this._abortController.signal;
+                const streamGenerator = this._stream(currentArgs, options);
+                let caughtError;
+                let lastAfterInvocation;
+                let iterationResult;
+                try {
+                    iterationResult = await streamGenerator.next();
+                    while (!iterationResult.done) {
+                        try {
+                            const processed = await this._invokeCallbacks(iterationResult.value);
+                            if (processed instanceof AfterInvocationEvent) {
+                                lastAfterInvocation = processed;
+                            }
+                            yield processed;
+                            iterationResult = await streamGenerator.next();
                         }
-                        else {
-                            await this._invokeCallbacks(result.value);
+                        catch (error) {
+                            // Throw interrupt errors back into _stream so executeTools can store the
+                            // assistant message as pending execution state for resume.
+                            if (error instanceof InterruptError) {
+                                iterationResult = await streamGenerator.throw(error);
+                            }
+                            else {
+                                throw error;
+                            }
                         }
                     }
-                    catch (error) {
-                        logger.warn(`event_type=<${result.value.type}>, error=<${error}> | error invoking callbacks during cleanup`);
+                    // Suppress AgentResultEvent for resumed iterations — only the final
+                    // invocation in a resume chain reports an agent result.
+                    if (lastAfterInvocation?.resume === undefined) {
+                        yield await this._invokeCallbacks(new AgentResultEvent({
+                            agent: this,
+                            result: iterationResult.value,
+                            invocationState: iterationResult.value.invocationState,
+                        }));
                     }
-                    result = await streamGenerator.next();
                 }
-                // Reset controller and signal for next invocation
-                this._abortController = new AbortController();
-                this._abortSignal = this._abortController.signal;
+                catch (error) {
+                    caughtError = error;
+                    throw error;
+                }
+                finally {
+                    // Drain _stream() so cleanup hooks and printer still fire.
+                    // Yield only on error (consumer may still be iterating); on a consumer
+                    // break, yielding would suspend the generator and leak the lock.
+                    let drainResult = await streamGenerator.return(undefined);
+                    while (!drainResult.done) {
+                        try {
+                            if (caughtError) {
+                                yield await this._invokeCallbacks(drainResult.value);
+                            }
+                            else {
+                                await this._invokeCallbacks(drainResult.value);
+                            }
+                        }
+                        catch (error) {
+                            logger.warn(`event_type=<${drainResult.value.type}>, error=<${error}> | error invoking callbacks during cleanup`);
+                        }
+                        drainResult = await streamGenerator.next();
+                    }
+                    // Reset controller and signal for next iteration / invocation
+                    this._abortController = new AbortController();
+                    this._abortSignal = this._abortController.signal;
+                }
+                // Resume only on a clean invocation — errors propagate above.
+                if (lastAfterInvocation?.resume !== undefined) {
+                    currentArgs = lastAfterInvocation.resume;
+                    continue;
+                }
+                return iterationResult.value;
             }
         }
         catch (e_1) {
@@ -471,8 +553,35 @@ export class Agent {
         const structuredOutputSchema = options?.structuredOutputSchema ?? this._structuredOutputSchema;
         const structuredOutputTool = structuredOutputSchema ? new StructuredOutputTool(structuredOutputSchema) : undefined;
         let structuredOutputChoice;
-        // Emit event before the try block
-        yield new BeforeInvocationEvent({ agent: this });
+        // Resolve per-invocation state once. The same object is threaded through
+        // every lifecycle hook event, every tool context, and is surfaced on the
+        // AgentResult. Mutations by hooks/tools are visible across all recursive
+        // agent loop cycles within this invocation.
+        const invocationState = options?.invocationState ?? {};
+        // Handle interrupt responses if present in input
+        const interruptResponses = this._extractInterruptResponses(args);
+        if (interruptResponses.length > 0) {
+            this._interruptState.resume(interruptResponses);
+        }
+        // Reject non-interrupt input while in interrupted state
+        if (this._interruptState.activated && interruptResponses.length === 0) {
+            throw new TypeError('Agent is in an interrupted state. Resume by invoking with interruptResponse content blocks.');
+        }
+        const beforeInvocationEvent = new BeforeInvocationEvent({ agent: this, invocationState });
+        yield beforeInvocationEvent;
+        if (beforeInvocationEvent.cancel) {
+            const cancelText = typeof beforeInvocationEvent.cancel === 'string' ? beforeInvocationEvent.cancel : 'invocation denied by hook';
+            const message = new Message({ role: 'assistant', content: [new TextBlock(cancelText)] });
+            yield this._appendMessage(message, invocationState);
+            yield new AfterInvocationEvent({ agent: this, invocationState });
+            return new AgentResult({
+                stopReason: 'endTurn',
+                lastMessage: message,
+                traces: this._tracer.localTraces,
+                metrics: this._meter.metrics,
+                invocationState,
+            });
+        }
         // Normalize input to get the user messages for telemetry
         const inputMessages = this._normalizeInput(args);
         // Start agent trace span
@@ -510,77 +619,123 @@ export class Agent {
                     if (currentArgs !== undefined) {
                         const messagesToAppend = this._normalizeInput(currentArgs);
                         for (const message of messagesToAppend) {
-                            yield this._appendMessage(message);
+                            yield this._appendMessage(message, invocationState);
                         }
                         currentArgs = undefined;
                     }
-                    const modelResult = yield* this._invokeModel(structuredOutputChoice);
-                    if (modelResult.stopReason !== 'toolUse') {
-                        // If structured output is required, force it
-                        if (structuredOutputTool) {
+                    // Check if we're resuming from a tool interrupt
+                    const pendingExecution = this._interruptState.getPendingExecution();
+                    let assistantMessage;
+                    let completedToolResults;
+                    if (pendingExecution) {
+                        // Resume from stored state - skip model call
+                        assistantMessage = pendingExecution.assistantMessage;
+                        completedToolResults = pendingExecution.completedToolResults;
+                        this._interruptState.clearPendingToolExecution();
+                    }
+                    else {
+                        const modelResult = yield* this._invokeModel(invocationState, structuredOutputChoice);
+                        if (modelResult.stopReason !== 'toolUse') {
+                            // If structured output is required, force it
+                            if (structuredOutputTool) {
+                                if (structuredOutputChoice) {
+                                    throw new StructuredOutputError('The model failed to invoke the structured output tool even after it was forced.');
+                                }
+                                structuredOutputChoice = { tool: { name: STRUCTURED_OUTPUT_TOOL_NAME } };
+                            }
+                            this._meter.endCycle(cycleStartTime);
+                            this._tracer.endAgentLoopSpan(cycleSpan);
+                            yield this._appendMessage(modelResult.message, invocationState);
                             if (structuredOutputChoice) {
-                                throw new StructuredOutputError('The model failed to invoke the structured output tool even after it was forced.');
+                                continue;
                             }
-                            structuredOutputChoice = { tool: { name: STRUCTURED_OUTPUT_TOOL_NAME } };
+                            result = new AgentResult({
+                                stopReason: modelResult.stopReason,
+                                lastMessage: modelResult.message,
+                                traces: this._tracer.localTraces,
+                                metrics: this._meter.metrics,
+                                invocationState,
+                            });
+                            return result;
                         }
-                        this._meter.endCycle(cycleStartTime);
-                        this._tracer.endAgentLoopSpan(cycleSpan);
-                        yield this._appendMessage(modelResult.message);
-                        if (structuredOutputChoice) {
-                            continue;
+                        // Cancel before tool execution: create error results for all pending tools
+                        if (this.isCancelled) {
+                            const toolUseBlocks = modelResult.message.content.filter((block) => block.type === 'toolUseBlock');
+                            const cancelBlocks = toolUseBlocks.map((block) => new ToolResultBlock({
+                                toolUseId: block.toolUseId,
+                                status: 'error',
+                                content: [new TextBlock('Tool execution cancelled')],
+                            }));
+                            const toolResultMessage = new Message({ role: 'user', content: cancelBlocks });
+                            yield this._appendMessage(modelResult.message, invocationState);
+                            yield this._appendMessage(toolResultMessage, invocationState);
+                            this._meter.endCycle(cycleStartTime);
+                            this._tracer.endAgentLoopSpan(cycleSpan);
+                            result = new AgentResult({
+                                stopReason: 'cancelled',
+                                lastMessage: modelResult.message,
+                                traces: this._tracer.localTraces,
+                                metrics: this._meter.metrics,
+                                invocationState,
+                            });
+                            return result;
                         }
-                        result = new AgentResult({
-                            stopReason: modelResult.stopReason,
-                            lastMessage: modelResult.message,
-                            traces: this._tracer.localTraces,
-                            metrics: this._meter.metrics,
-                        });
-                        return result;
+                        assistantMessage = modelResult.message;
                     }
-                    // Cancel before tool execution: create error results for all pending tools
-                    if (this.isCancelled) {
-                        const toolUseBlocks = modelResult.message.content.filter((block) => block.type === 'toolUseBlock');
-                        const cancelBlocks = toolUseBlocks.map((block) => new ToolResultBlock({
-                            toolUseId: block.toolUseId,
-                            status: 'error',
-                            content: [new TextBlock('Tool execution cancelled')],
-                        }));
-                        const toolResultMessage = new Message({ role: 'user', content: cancelBlocks });
-                        yield this._appendMessage(modelResult.message);
-                        yield this._appendMessage(toolResultMessage);
+                    // Execute tools
+                    const toolsResult = yield* this.executeTools(assistantMessage, this._toolRegistry, invocationState, completedToolResults);
+                    // When the consumer breaks the stream (e.g. agent.cancel() + break),
+                    // yield* returns undefined because the inner generator was closed.
+                    if (!toolsResult) {
                         this._meter.endCycle(cycleStartTime);
                         this._tracer.endAgentLoopSpan(cycleSpan);
-                        result = new AgentResult({
-                            stopReason: 'cancelled',
-                            lastMessage: modelResult.message,
-                            traces: this._tracer.localTraces,
-                            metrics: this._meter.metrics,
-                        });
-                        return result;
+                        continue;
                     }
-                    // Execute tools
-                    const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry);
+                    const toolResultMessage = toolsResult.message;
                     /**
                      * Deferred append: both messages are added AFTER tool execution completes.
                      * This keeps agent.messages in a valid, reinvokable state at all times.
                      * If interrupted during tool execution, messages has no dangling toolUse
                      * without a matching toolResult, so the agent can be reinvoked cleanly.
                      */
-                    yield this._appendMessage(modelResult.message);
-                    yield this._appendMessage(toolResultMessage);
+                    yield this._appendMessage(assistantMessage, invocationState);
+                    yield this._appendMessage(toolResultMessage, invocationState);
+                    // Deactivate interrupt state after successful tool execution so the next
+                    // cycle starts with a clean slate (new interrupts can be raised again).
+                    if (this._interruptState.activated) {
+                        this._interruptState.deactivate();
+                    }
                     this._meter.endCycle(cycleStartTime);
                     this._tracer.endAgentLoopSpan(cycleSpan);
+                    // Hook requested halt: exit without calling the model again
+                    const { afterToolsEvent } = toolsResult;
+                    if (afterToolsEvent.endTurn) {
+                        const endTurnText = typeof afterToolsEvent.endTurn === 'string'
+                            ? afterToolsEvent.endTurn
+                            : 'Turn ended early by hook after tool execution';
+                        const lastMessage = new Message({ role: 'assistant', content: [new TextBlock(endTurnText)] });
+                        yield this._appendMessage(lastMessage, invocationState);
+                        result = new AgentResult({
+                            stopReason: 'endTurn',
+                            lastMessage,
+                            traces: this._tracer.localTraces,
+                            metrics: this._meter.metrics,
+                            invocationState,
+                        });
+                        return result;
+                    }
                     // Structured output captured: exit
                     const structuredOutput = structuredOutputTool
-                        ? this._extractStructuredOutput(modelResult.message, toolResultMessage)
+                        ? this._extractStructuredOutput(assistantMessage, toolResultMessage)
                         : undefined;
                     if (structuredOutput !== undefined) {
                         result = new AgentResult({
-                            stopReason: modelResult.stopReason,
-                            lastMessage: modelResult.message,
+                            stopReason: 'toolUse',
+                            lastMessage: assistantMessage,
                             traces: this._tracer.localTraces,
                             structuredOutput,
                             metrics: this._meter.metrics,
+                            invocationState,
                         });
                         return result;
                     }
@@ -600,15 +755,20 @@ export class Agent {
                     role: 'assistant',
                     content: [new TextBlock('Cancelled by user')],
                 });
-                yield this._appendMessage(cancelMessage);
+                yield this._appendMessage(cancelMessage, invocationState);
                 result = new AgentResult({
                     stopReason: 'cancelled',
                     lastMessage: cancelMessage,
                     traces: this._tracer.localTraces,
                     metrics: this._meter.metrics,
+                    invocationState,
                 });
                 return result;
             }
+            if (error instanceof InterruptError) {
+                result = this._createInterruptResult(invocationState);
+                return result;
+            }
             caughtError = error;
             throw error;
         }
@@ -621,7 +781,7 @@ export class Agent {
                     role: 'assistant',
                     content: [new TextBlock('Cancelled by user')],
                 });
-                yield this._appendMessage(cancelMessage);
+                yield this._appendMessage(cancelMessage, invocationState);
             }
             this._tracer.endAgentSpan(agentSpan, {
                 ...(caughtError && { error: caughtError }),
@@ -634,7 +794,7 @@ export class Agent {
                 this._toolRegistry.remove(STRUCTURED_OUTPUT_TOOL_NAME);
             }
             // Always emit final event
-            yield new AfterInvocationEvent({ agent: this });
+            yield new AfterInvocationEvent({ agent: this, invocationState });
         }
     }
     /**
@@ -654,6 +814,51 @@ export class Agent {
         const firstContent = toolResult.content[0];
         return firstContent?.type === 'jsonBlock' ? firstContent.json : undefined;
     }
+    /**
+     * Creates an AgentResult for an interrupt stop.
+     *
+     * @param invocationState - The current invocation state
+     * @returns AgentResult with stopReason 'interrupt'
+     */
+    _createInterruptResult(invocationState) {
+        this._interruptState.activate();
+        return new AgentResult({
+            stopReason: 'interrupt',
+            lastMessage: this.messages.length > 0
+                ? this.messages[this.messages.length - 1]
+                : new Message({ role: 'assistant', content: [new TextBlock('Interrupted')] }),
+            traces: this._tracer.localTraces,
+            metrics: this._meter.metrics,
+            interrupts: this._interruptState.getUnansweredInterrupts(),
+            invocationState,
+        });
+    }
+    /**
+     * Extracts interrupt response content blocks from invocation args.
+     *
+     * @param args - The invocation arguments
+     * @returns Array of InterruptResponseContent blocks, empty if none found
+     * @throws TypeError if args mix interrupt responses with other content
+     */
+    _extractInterruptResponses(args) {
+        if (!Array.isArray(args) || args.length === 0) {
+            return [];
+        }
+        const responses = [];
+        let hasNonInterrupt = false;
+        for (const item of args) {
+            if (isInterruptResponseContent(item)) {
+                responses.push(item);
+            }
+            else {
+                hasNonInterrupt = true;
+            }
+        }
+        if (responses.length > 0 && hasNonInterrupt) {
+            throw new TypeError('Must resume from interrupt with a list of interruptResponse content blocks only');
+        }
+        return responses;
+    }
     /**
      * Normalizes agent invocation input into an array of messages to append.
      *
@@ -673,6 +878,11 @@ export class Agent {
             }
             else if (Array.isArray(args) && args.length > 0) {
                 const firstElement = args[0];
+                // Check if it's interrupt responses - skip creating messages for these
+                if (isInterruptResponseContent(firstElement)) {
+                    // Pure interrupt responses: no messages to add
+                    return [];
+                }
                 // Check if it's Message[] or MessageData[]
                 if ('role' in firstElement && typeof firstElement.role === 'string') {
                     // Check if it's a Message instance or MessageData
@@ -716,9 +926,9 @@ export class Agent {
      * @param toolChoice - Optional tool choice to force specific tool usage
      * @returns Object containing the assistant message, stop reason, and optional redaction message
      */
-    async *_invokeModel(toolChoice) {
+    async *_invokeModel(invocationState, toolChoice) {
         const toolSpecs = this._toolRegistry.list().map((tool) => tool.toolSpec);
-        const streamOptions = { toolSpecs };
+        const streamOptions = { toolSpecs, modelState: this.modelState };
         if (this.systemPrompt !== undefined) {
             streamOptions.systemPrompt = this.systemPrompt;
         }
@@ -726,63 +936,117 @@ export class Agent {
         if (toolChoice) {
             streamOptions.toolChoice = toolChoice;
         }
-        yield new BeforeModelCallEvent({ agent: this, model: this.model });
-        // Start model span within loop span context
-        const modelId = this.model.modelId;
-        const modelSpan = this._tracer.startModelInvokeSpan({
-            messages: this.messages,
-            ...(modelId && { modelId }),
-            ...(this.systemPrompt !== undefined && { systemPrompt: this.systemPrompt }),
-        });
-        try {
-            const result = yield* this._streamFromModel(this.messages, streamOptions);
-            // Accumulate token usage and model latency metrics
-            this._meter.updateCycle(result.metadata);
-            // End model span with usage
-            const usage = result.metadata?.usage;
-            const metrics = result.metadata?.metrics;
-            this._tracer.endModelInvokeSpan(modelSpan, {
-                output: result.message,
-                stopReason: result.stopReason,
-                ...(usage && { usage }),
-                ...(metrics && { metrics }),
+        let attemptCount = 1;
+        while (true) {
+            // Estimate input tokens for the upcoming model call (non-fatal if estimation fails)
+            let projectedInputTokens;
+            try {
+                projectedInputTokens = await this._estimateInputTokens(streamOptions);
+            }
+            catch (e) {
+                logger.debug(`error=<${e}> | token estimation failed, proceeding without estimate`);
+            }
+            const beforeModelCallEvent = new BeforeModelCallEvent({
+                agent: this,
+                model: this.model,
+                invocationState,
+                ...(projectedInputTokens !== undefined && { projectedInputTokens }),
             });
-            yield new ModelMessageEvent({ agent: this, message: result.message, stopReason: result.stopReason });
-            // Handle user content redaction if guardrails blocked input
-            if (result.redaction?.userMessage) {
-                this._redactLastMessage(result.redaction.userMessage);
+            yield beforeModelCallEvent;
+            if (beforeModelCallEvent.cancel) {
+                const cancelText = typeof beforeModelCallEvent.cancel === 'string' ? beforeModelCallEvent.cancel : 'model call denied by hook';
+                const message = new Message({ role: 'assistant', content: [new TextBlock(cancelText)] });
+                const stopData = { message, stopReason: 'endTurn' };
+                const afterModelCallEvent = new AfterModelCallEvent({
+                    agent: this,
+                    model: this.model,
+                    attemptCount,
+                    stopData,
+                    invocationState,
+                });
+                yield afterModelCallEvent;
+                if (afterModelCallEvent.retry) {
+                    attemptCount += 1;
+                    continue;
+                }
+                return { message, stopReason: 'endTurn' };
             }
-            const stopData = {
-                message: result.message,
-                stopReason: result.stopReason,
-                ...(result.redaction && { redaction: result.redaction }),
-            };
-            const afterModelCallEvent = new AfterModelCallEvent({ agent: this, model: this.model, stopData });
-            yield afterModelCallEvent;
-            if (afterModelCallEvent.retry) {
-                return yield* this._invokeModel(toolChoice);
+            // Start model span within loop span context
+            const modelId = this.model.modelId;
+            const modelSpan = this._tracer.startModelInvokeSpan({
+                messages: this.messages,
+                ...(modelId && { modelId }),
+                ...(this.systemPrompt !== undefined && { systemPrompt: this.systemPrompt }),
+            });
+            try {
+                const result = yield* this._streamFromModel(this.messages, streamOptions, invocationState);
+                // Accumulate token usage and model latency metrics
+                this._meter.updateCycle(result.metadata);
+                // End model span with usage
+                const usage = result.metadata?.usage;
+                const metrics = result.metadata?.metrics;
+                this._tracer.endModelInvokeSpan(modelSpan, {
+                    output: result.message,
+                    stopReason: result.stopReason,
+                    ...(usage && { usage }),
+                    ...(metrics && { metrics }),
+                });
+                yield new ModelMessageEvent({
+                    agent: this,
+                    message: result.message,
+                    stopReason: result.stopReason,
+                    invocationState,
+                });
+                // Handle user content redaction if guardrails blocked input
+                if (result.redaction?.userMessage) {
+                    this._redactLastMessage(result.redaction.userMessage);
+                }
+                const stopData = {
+                    message: result.message,
+                    stopReason: result.stopReason,
+                    ...(result.redaction && { redaction: result.redaction }),
+                };
+                const afterModelCallEvent = new AfterModelCallEvent({
+                    agent: this,
+                    model: this.model,
+                    attemptCount,
+                    stopData,
+                    invocationState,
+                });
+                yield afterModelCallEvent;
+                if (afterModelCallEvent.retry) {
+                    attemptCount += 1;
+                    continue;
+                }
+                return result;
             }
-            return result;
-        }
-        catch (error) {
-            const modelError = normalizeError(error);
-            // End model span with error
-            this._tracer.endModelInvokeSpan(modelSpan, { error: modelError });
-            // Create error event
-            const errorEvent = new AfterModelCallEvent({ agent: this, model: this.model, error: modelError });
-            // Yield error event - stream will invoke hooks
-            yield errorEvent;
-            // Let CancelledError propagate directly — no retry
-            // (we emit the AfterModelCall because we already emitted Before and we guarentee the pair)
-            if (error instanceof CancelledError) {
+            catch (error) {
+                const modelError = normalizeError(error);
+                // End model span with error
+                this._tracer.endModelInvokeSpan(modelSpan, { error: modelError });
+                // Create error event
+                const errorEvent = new AfterModelCallEvent({
+                    agent: this,
+                    model: this.model,
+                    attemptCount,
+                    error: modelError,
+                    invocationState,
+                });
+                // Yield error event - stream will invoke hooks
+                yield errorEvent;
+                // Let CancelledError propagate directly — no retry
+                // (we emit the AfterModelCall because we already emitted Before and we guarentee the pair)
+                if (error instanceof CancelledError) {
+                    throw error;
+                }
+                // After yielding, hooks have been invoked and may have set retry
+                if (errorEvent.retry) {
+                    attemptCount += 1;
+                    continue;
+                }
+                // Re-throw error
                 throw error;
             }
-            // After yielding, hooks have been invoked and may have set retry
-            if (errorEvent.retry) {
-                return yield* this._invokeModel(toolChoice);
-            }
-            // Re-throw error
-            throw error;
         }
     }
     /**
@@ -801,7 +1065,8 @@ export class Agent {
      * @param streamOptions - Options for streaming
      * @returns StreamAggregatedResult containing message, stop reason, and optional redaction message
      */
-    async *_streamFromModel(messages, streamOptions) {
+    async *_streamFromModel(messages, streamOptions, invocationState) {
+        messages = normalizeToolUseNames(messages);
         const streamGenerator = this.model.streamAggregated(messages, streamOptions);
         let result = await streamGenerator.next();
         while (!result.done) {
@@ -809,11 +1074,11 @@ export class Agent {
             const event = result.value;
             if (isModelStreamEvent(event)) {
                 // ModelStreamEvent: wrap in ModelStreamUpdateEvent
-                yield new ModelStreamUpdateEvent({ agent: this, event });
+                yield new ModelStreamUpdateEvent({ agent: this, event, invocationState });
             }
             else {
                 // ContentBlock: wrap in ContentBlockEvent
-                yield new ContentBlockEvent({ agent: this, contentBlock: event });
+                yield new ContentBlockEvent({ agent: this, contentBlock: event, invocationState });
             }
             result = await streamGenerator.next();
         }
@@ -821,63 +1086,268 @@ export class Agent {
         return result.value;
     }
     /**
-     * Executes tools sequentially and streams all tool events.
+     * Emits `BeforeToolsEvent`, handles the pre-launch cancel paths, then
+     * delegates per-tool execution to the configured {@link ToolExecutorStrategy}.
+     * Always pairs `BeforeToolsEvent` with a terminal `AfterToolsEvent`, even on
+     * the invariant-violation throw path.
      *
      * @param assistantMessage - The assistant message containing tool use blocks
      * @param toolRegistry - Registry containing available tools
-     * @returns User message containing tool results
+     * @returns Tool-result message and the dispatched AfterToolsEvent
      */
-    async *executeTools(assistantMessage, toolRegistry) {
-        const beforeToolsEvent = new BeforeToolsEvent({ agent: this, message: assistantMessage });
-        yield beforeToolsEvent;
+    async *executeTools(assistantMessage, toolRegistry, invocationState, completedToolResults) {
+        const beforeToolsEvent = new BeforeToolsEvent({ agent: this, message: assistantMessage, invocationState });
+        try {
+            yield beforeToolsEvent;
+        }
+        catch (error) {
+            // Store pending state before re-throwing so the agent can resume from this point.
+            // The error must still propagate to _stream which handles the interrupt stop.
+            if (error instanceof InterruptError) {
+                this._interruptState.setPendingToolExecution({
+                    assistantMessageData: assistantMessage.toJSON(),
+                    completedToolResults: {},
+                });
+            }
+            throw error;
+        }
+        const toolUseBlocks = assistantMessage.content.filter((block) => block.type === 'toolUseBlock');
+        if (toolUseBlocks.length === 0) {
+            // Preserve BeforeToolsEvent/AfterToolsEvent bracket symmetry even on
+            // this invariant-violation branch.
+            yield new AfterToolsEvent({
+                agent: this,
+                message: new Message({ role: 'user', content: [] }),
+                invocationState,
+            });
+            throw new Error('Model indicated toolUse but no tool use blocks found in message');
+        }
+        // Pre-launch cancel paths are strategy-independent.
+        if (beforeToolsEvent.cancel) {
+            const message = typeof beforeToolsEvent.cancel === 'string' ? beforeToolsEvent.cancel : 'Tool cancelled by hook';
+            return yield* this._yieldCancelledToolResults(toolUseBlocks, message, invocationState);
+        }
+        if (this.isCancelled) {
+            return yield* this._yieldCancelledToolResults(toolUseBlocks, 'Tool execution cancelled', invocationState);
+        }
+        switch (this._toolExecutor) {
+            case 'sequential':
+                return yield* this._executeToolsSequential(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage);
+            case 'concurrent':
+                return yield* this._executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage);
+            default: {
+                const _exhaustive = this._toolExecutor;
+                throw new Error(`Unknown toolExecutor: ${_exhaustive}`);
+            }
+        }
+    }
+    /**
+     * Emits a `ToolResultEvent` for every block plus an `AfterToolsEvent`, and
+     * returns the resulting tool-result message and dispatched event. Used by the pre-launch cancel
+     * paths shared across executors.
+     */
+    async *_yieldCancelledToolResults(toolUseBlocks, message, invocationState) {
+        const cancelBlocks = this._cancelAllAsResults(toolUseBlocks, message);
+        for (const result of cancelBlocks) {
+            yield new ToolResultEvent({ agent: this, result, invocationState });
+        }
+        const toolResultMessage = new Message({ role: 'user', content: cancelBlocks });
+        const afterToolsEvent = new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+        yield afterToolsEvent;
+        return { message: toolResultMessage, afterToolsEvent };
+    }
+    /**
+     * Executes tools one at a time, honoring `agent.cancelSignal` between
+     * iterations to short-circuit not-yet-started tools.
+     */
+    async *_executeToolsSequential(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage) {
         const toolResultBlocks = [];
         let toolResultMessage;
+        let afterToolsEvent;
         try {
-            // Extract tool use blocks from assistant message
-            const toolUseBlocks = assistantMessage.content.filter((block) => block.type === 'toolUseBlock');
-            if (toolUseBlocks.length === 0) {
-                // No tool use blocks found even though stopReason is toolUse
-                throw new Error('Model indicated toolUse but no tool use blocks found in message');
-            }
-            // Cancel all tools if hook requested it
-            if (beforeToolsEvent.cancel) {
-                const cancelMessage = cancelToolMessage(beforeToolsEvent.cancel);
-                const cancelBlocks = toolUseBlocks.map((block) => new ToolResultBlock({
-                    toolUseId: block.toolUseId,
-                    status: 'error',
-                    content: [new TextBlock(cancelMessage)],
-                }));
-                for (const result of cancelBlocks) {
-                    yield new ToolResultEvent({ agent: this, result });
+            for (const toolUseBlock of toolUseBlocks) {
+                // Skip tools that were already completed before the interrupt
+                if (completedToolResults?.has(toolUseBlock.toolUseId)) {
+                    const completedResult = completedToolResults.get(toolUseBlock.toolUseId);
+                    // No events emitted for already-completed tools.
+                    // The result is included in the final tool result message.
+                    toolResultBlocks.push(completedResult);
+                    continue;
                 }
-                toolResultBlocks.push(...cancelBlocks);
-            }
-            else {
-                for (const toolUseBlock of toolUseBlocks) {
-                    if (this.isCancelled) {
-                        const cancelBlock = new ToolResultBlock({
-                            toolUseId: toolUseBlock.toolUseId,
-                            status: 'error',
-                            content: [new TextBlock('Tool execution cancelled')],
+                if (this.isCancelled) {
+                    const cancelBlock = new ToolResultBlock({
+                        toolUseId: toolUseBlock.toolUseId,
+                        status: 'error',
+                        content: [new TextBlock('Tool execution cancelled')],
+                    });
+                    toolResultBlocks.push(cancelBlock);
+                    yield new ToolResultEvent({ agent: this, result: cancelBlock, invocationState });
+                    continue;
+                }
+                try {
+                    const toolResultBlock = yield* this.executeTool(toolUseBlock, toolRegistry, invocationState);
+                    toolResultBlocks.push(toolResultBlock);
+                    yield new ToolResultEvent({ agent: this, result: toolResultBlock, invocationState });
+                }
+                catch (error) {
+                    if (error instanceof InterruptError) {
+                        // Store pending state with completed results so far
+                        const completedSoFar = {};
+                        for (const block of toolResultBlocks) {
+                            completedSoFar[block.toolUseId] = block.toJSON();
+                        }
+                        // Also include any previously completed results
+                        if (completedToolResults) {
+                            for (const [id, block] of completedToolResults) {
+                                completedSoFar[id] = block.toJSON();
+                            }
+                        }
+                        this._interruptState.setPendingToolExecution({
+                            assistantMessageData: assistantMessage.toJSON(),
+                            completedToolResults: completedSoFar,
                         });
-                        toolResultBlocks.push(cancelBlock);
-                        yield new ToolResultEvent({ agent: this, result: cancelBlock });
+                        throw error;
+                    }
+                    throw error;
+                }
+            }
+        }
+        finally {
+            toolResultMessage = new Message({ role: 'user', content: toolResultBlocks });
+            afterToolsEvent = new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            yield afterToolsEvent;
+        }
+        return { message: toolResultMessage, afterToolsEvent };
+    }
+    /**
+     * Produces one error ToolResultBlock per tool use block, each carrying
+     * `message` as its error text. Shared by pre-launch cancel paths.
+     */
+    _cancelAllAsResults(toolUseBlocks, message) {
+        return toolUseBlocks.map((block) => new ToolResultBlock({
+            toolUseId: block.toolUseId,
+            status: 'error',
+            content: [new TextBlock(message)],
+        }));
+    }
+    /**
+     * Executes tools concurrently by merging N per-tool {@link executeTool}
+     * async generators via `Promise.race`. Per-tool event order is preserved
+     * (because each generator is iterated serially); cross-tool events may
+     * interleave at race resolution boundaries.
+     *
+     * Per-tool retry (`AfterToolCallEvent.retry`) is isolated — it lives inside
+     * `executeTool`'s own `while(true)` loop, so one tool retrying does not
+     * disturb its siblings.
+     */
+    async *_executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage) {
+        let toolResultMessage;
+        let afterToolsEvent;
+        const gens = toolUseBlocks.map((block) => ({
+            block,
+            gen: completedToolResults?.has(block.toolUseId)
+                ? undefined // Skip already-completed tools
+                : this.executeTool(block, toolRegistry, invocationState),
+        }));
+        const step = (idx) => gens[idx].gen.next().then((res) => ({ idx, kind: 'next', res }), (error) => ({ idx, kind: 'throw', error }));
+        // Seed completed results from resume state
+        const resultsByToolUseId = new Map();
+        if (completedToolResults) {
+            for (const [id, result] of completedToolResults) {
+                resultsByToolUseId.set(id, result);
+            }
+        }
+        // Only race tools that need execution
+        const pendingNext = new Map();
+        for (let idx = 0; idx < gens.length; idx++) {
+            if (gens[idx].gen) {
+                pendingNext.set(idx, step(idx));
+            }
+        }
+        // Track interrupts — let all other tools finish before propagating
+        let interruptError;
+        try {
+            while (pendingNext.size > 0) {
+                const winner = await Promise.race(pendingNext.values());
+                const { idx } = winner;
+                const block = gens[idx].block;
+                if (winner.kind === 'throw') {
+                    pendingNext.delete(idx);
+                    // Detect InterruptError — don't convert to error result, track it
+                    if (winner.error instanceof InterruptError) {
+                        interruptError = winner.error;
                         continue;
                     }
-                    const toolResultBlock = yield* this.executeTool(toolUseBlock, toolRegistry);
-                    toolResultBlocks.push(toolResultBlock);
-                    yield new ToolResultEvent({ agent: this, result: toolResultBlock });
+                    const err = normalizeError(winner.error);
+                    const result = new ToolResultBlock({
+                        toolUseId: block.toolUseId,
+                        status: 'error',
+                        content: [new TextBlock(err.message)],
+                        error: err,
+                    });
+                    resultsByToolUseId.set(block.toolUseId, result);
+                    yield new ToolResultEvent({ agent: this, result, invocationState });
+                    continue;
+                }
+                if (winner.res.done) {
+                    pendingNext.delete(idx);
+                    resultsByToolUseId.set(block.toolUseId, winner.res.value);
+                    yield new ToolResultEvent({ agent: this, result: winner.res.value, invocationState });
+                }
+                else {
+                    try {
+                        yield winner.res.value;
+                    }
+                    catch (e) {
+                        // InterruptError thrown back into generator from stream() error injection
+                        if (e instanceof InterruptError) {
+                            interruptError = e;
+                            pendingNext.delete(idx);
+                            continue;
+                        }
+                        throw e;
+                    }
+                    pendingNext.set(idx, step(idx));
                 }
             }
+            // After all tools finish, propagate interrupt if one was raised
+            if (interruptError) {
+                const completedSoFar = {};
+                for (const [id, result] of resultsByToolUseId) {
+                    completedSoFar[id] = result.toJSON();
+                }
+                this._interruptState.setPendingToolExecution({
+                    assistantMessageData: assistantMessage.toJSON(),
+                    completedToolResults: completedSoFar,
+                });
+                throw interruptError;
+            }
         }
         finally {
-            toolResultMessage = new Message({
-                role: 'user',
-                content: toolResultBlocks,
-            });
-            yield new AfterToolsEvent({ agent: this, message: toolResultMessage });
+            // Close any generators still in-flight (e.g. consumer broke out of stream).
+            await Promise.allSettled(Array.from(pendingNext.keys(), (idx) => gens[idx].gen.return(undefined)));
+            // Build the result message from whatever completed, in source order.
+            // Missing entries get a fallback error block so the message always
+            // accounts for every toolUseBlock the model emitted.
+            const toolResultBlocks = [];
+            for (const block of toolUseBlocks) {
+                const result = resultsByToolUseId.get(block.toolUseId);
+                if (result) {
+                    toolResultBlocks.push(result);
+                }
+                else {
+                    toolResultBlocks.push(new ToolResultBlock({
+                        toolUseId: block.toolUseId,
+                        status: 'error',
+                        content: [new TextBlock('Tool execution interrupted')],
+                    }));
+                }
+            }
+            toolResultMessage = new Message({ role: 'user', content: toolResultBlocks });
+            afterToolsEvent = new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            yield afterToolsEvent;
         }
-        return toolResultMessage;
+        return { message: toolResultMessage, afterToolsEvent };
     }
     /**
      * Executes a single tool and returns the result.
@@ -889,9 +1359,10 @@ export class Agent {
      * @param toolRegistry - Registry containing available tools
      * @returns Tool result block
      */
-    async *executeTool(toolUseBlock, toolRegistry) {
-        const tool = toolRegistry.get(toolUseBlock.name);
-        // Create toolUse object for hook events and telemetry
+    async *executeTool(toolUseBlock, toolRegistry, invocationState) {
+        const registryTool = toolRegistry.get(toolUseBlock.name);
+        // Create toolUse object for hook events and telemetry. Callbacks may mutate
+        // this object's fields (input/name/toolUseId) inside BeforeToolCallEvent.
         const toolUse = {
             name: toolUseBlock.name,
             toolUseId: toolUseBlock.toolUseId,
@@ -899,27 +1370,40 @@ export class Agent {
         };
         // Retry loop for tool execution
         while (true) {
-            const beforeToolCallEvent = new BeforeToolCallEvent({ agent: this, toolUse, tool });
+            const beforeToolCallEvent = new BeforeToolCallEvent({
+                agent: this,
+                toolUse,
+                tool: registryTool,
+                invocationState,
+            });
             yield beforeToolCallEvent;
+            // Resolve the tool that would actually execute. selectedTool wins;
+            // otherwise if the hook renamed toolUse.name, re-resolve from the
+            // registry under the new name; otherwise use the original registry
+            // lookup. Resolved before the cancel check so AfterToolCallEvent.tool
+            // is consistent whether the cancel or execution branch runs.
+            const effectiveTool = beforeToolCallEvent.selectedTool ??
+                (toolUse.name !== toolUseBlock.name ? toolRegistry.get(toolUse.name) : registryTool);
             // Cancel individual tool if hook requested it
             if (beforeToolCallEvent.cancel) {
-                const cancelMessage = cancelToolMessage(beforeToolCallEvent.cancel);
-                const toolResult = new ToolResultBlock({
-                    toolUseId: toolUseBlock.toolUseId,
+                const cancelMessage = typeof beforeToolCallEvent.cancel === 'string' ? beforeToolCallEvent.cancel : 'Tool cancelled by hook';
+                const cancelResult = new ToolResultBlock({
+                    toolUseId: toolUse.toolUseId,
                     status: 'error',
                     content: [new TextBlock(cancelMessage)],
                 });
                 const afterToolCallEvent = new AfterToolCallEvent({
                     agent: this,
                     toolUse,
-                    tool,
-                    result: toolResult,
+                    tool: effectiveTool,
+                    result: cancelResult,
+                    invocationState,
                 });
                 yield afterToolCallEvent;
                 if (afterToolCallEvent.retry) {
                     continue;
                 }
-                return toolResult;
+                return afterToolCallEvent.result;
             }
             // Start tool span within loop span context
             const toolSpan = this._tracer.startToolCallSpan({
@@ -929,23 +1413,27 @@ export class Agent {
             const toolStartTime = Date.now();
             let toolResult;
             let error;
-            if (!tool) {
+            if (!effectiveTool) {
                 // Tool not found
                 toolResult = new ToolResultBlock({
-                    toolUseId: toolUseBlock.toolUseId,
+                    toolUseId: toolUse.toolUseId,
                     status: 'error',
-                    content: [new TextBlock(`Tool '${toolUseBlock.name}' not found in registry`)],
+                    content: [new TextBlock(`Tool '${toolUse.name}' not found in registry`)],
                 });
             }
             else {
                 // Execute tool within the tool span context
                 const toolContext = {
                     toolUse: {
-                        name: toolUseBlock.name,
-                        toolUseId: toolUseBlock.toolUseId,
-                        input: toolUseBlock.input,
+                        name: toolUse.name,
+                        toolUseId: toolUse.toolUseId,
+                        input: toolUse.input,
                     },
                     agent: this,
+                    invocationState,
+                    interrupt: (params) => {
+                        return interruptFromAgent(this, `tool:${toolUseBlock.toolUseId}:${params.name}`, params);
+                    },
                 };
                 try {
                     // Manually iterate tool stream to wrap each ToolStreamEvent in ToolStreamUpdateEvent.
@@ -953,19 +1441,19 @@ export class Agent {
                     // without knowledge of agents or hooks, and we wrap at the boundary.
                     // Tool execution is ran within the tool span's context so that
                     // downstream calls (e.g., MCP clients) can propagate trace context
-                    const toolGenerator = this._tracer.withSpanContext(toolSpan, () => tool.stream(toolContext));
+                    const toolGenerator = this._tracer.withSpanContext(toolSpan, () => effectiveTool.stream(toolContext));
                     let toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
                     while (!toolNext.done) {
-                        yield new ToolStreamUpdateEvent({ agent: this, event: toolNext.value });
+                        yield new ToolStreamUpdateEvent({ agent: this, event: toolNext.value, invocationState });
                         toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
                     }
                     const result = toolNext.value;
                     if (!result) {
                         // Tool didn't return a result
                         toolResult = new ToolResultBlock({
-                            toolUseId: toolUseBlock.toolUseId,
+                            toolUseId: toolUse.toolUseId,
                             status: 'error',
-                            content: [new TextBlock(`Tool '${toolUseBlock.name}' did not return a result`)],
+                            content: [new TextBlock(`Tool '${toolUse.name}' did not return a result`)],
                         });
                     }
                     else {
@@ -974,17 +1462,22 @@ export class Agent {
                     }
                 }
                 catch (e) {
+                    // Re-throw InterruptError to allow interrupt handling
+                    if (e instanceof InterruptError) {
+                        throw e;
+                    }
                     // Tool execution failed with error
                     error = normalizeError(e);
                     toolResult = new ToolResultBlock({
-                        toolUseId: toolUseBlock.toolUseId,
+                        toolUseId: toolUse.toolUseId,
                         status: 'error',
                         content: [new TextBlock(error.message)],
                         error,
                     });
                 }
             }
-            // End tool span
+            // End tool span with the raw tool result — telemetry reflects what the
+            // tool actually returned, independent of AfterToolCallEvent mutations.
             this._tracer.endToolCallSpan(toolSpan, { toolResult, ...(error && { error }) });
             // End tool metrics tracking
             this._meter.endToolCall({
@@ -996,15 +1489,18 @@ export class Agent {
             const afterToolCallEvent = new AfterToolCallEvent({
                 agent: this,
                 toolUse,
-                tool,
+                tool: effectiveTool,
                 result: toolResult,
+                invocationState,
                 ...(error !== undefined && { error }),
             });
             yield afterToolCallEvent;
             if (afterToolCallEvent.retry) {
                 continue;
             }
-            return toolResult;
+            // Return the (possibly mutated) result so hook transformations propagate
+            // to ToolResultEvent and the conversation message the model will see.
+            return afterToolCallEvent.result;
         }
     }
     /**
@@ -1052,24 +1548,94 @@ export class Agent {
             }
         }
     }
+    /**
+     * Estimate the input token count for the next model call.
+     *
+     * Uses the token counting strategy: reads inputTokens + outputTokens
+     * from the last assistant message's metadata as a known baseline, then estimates
+     * only new messages added after it. Falls back to full estimation when no metadata
+     * is available (cold start or first call).
+     *
+     * @param streamOptions - The stream options containing system prompt and tool specs
+     * @returns Estimated input token count
+     */
+    async _estimateInputTokens(streamOptions) {
+        // Find the last assistant message with usage metadata
+        let lastAssistantIdx = -1;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            if (this.messages[i].role === 'assistant' && this.messages[i].metadata?.usage) {
+                lastAssistantIdx = i;
+                break;
+            }
+        }
+        let estimate;
+        if (lastAssistantIdx >= 0) {
+            const usage = this.messages[lastAssistantIdx].metadata.usage;
+            const knownBaseline = usage.inputTokens + usage.outputTokens;
+            const newMessages = this.messages.slice(lastAssistantIdx + 1);
+            if (newMessages.length === 0) {
+                estimate = knownBaseline;
+            }
+            else {
+                // System prompt and tool spec tokens are already included in the baseline from the prior model call
+                estimate = knownBaseline + (await this.model.countTokens(newMessages));
+            }
+        }
+        else {
+            estimate = await this.model.countTokens(this.messages, {
+                ...(streamOptions.systemPrompt !== undefined && { systemPrompt: streamOptions.systemPrompt }),
+                ...(streamOptions.toolSpecs !== undefined && { toolSpecs: streamOptions.toolSpecs }),
+            });
+        }
+        return estimate;
+    }
     /**
      * Appends a message to the conversation history and returns the event for yielding.
      *
      * @param message - The message to append
      * @returns MessageAddedEvent to be yielded
      */
-    _appendMessage(message) {
+    _appendMessage(message, invocationState) {
         this.messages.push(message);
-        return new MessageAddedEvent({ agent: this, message });
+        return new MessageAddedEvent({ agent: this, message, invocationState });
     }
 }
+const INVALID_TOOL_NAME_PLACEHOLDER = 'INVALID_TOOL_NAME';
 /**
- * Returns the cancel message for a cancelled tool.
- * @param cancelTool - The cancel value (true or custom message)
- * @returns The cancel message string
+ * Replaces invalid tool-use names on assistant messages with `INVALID_TOOL_NAME`
+ * so providers that reject malformed names don't fail the whole request.
+ * Returns the input unchanged (same reference) when nothing needs replacing.
  */
-function cancelToolMessage(cancelTool) {
-    return typeof cancelTool === 'string' ? cancelTool : 'tool cancelled by hook';
+function normalizeToolUseNames(messages) {
+    let replaced = false;
+    const next = messages.map((message) => {
+        if (!message || message.role !== 'assistant')
+            return message;
+        let messageReplaced = false;
+        const content = message.content.map((block) => {
+            if (block.type !== 'toolUseBlock')
+                return block;
+            if (isValidToolName(block.name))
+                return block;
+            messageReplaced = true;
+            logger.debug(`tool_name=<${block.name}> | replacing invalid tool name with ${INVALID_TOOL_NAME_PLACEHOLDER}`);
+            return new ToolUseBlock({
+                name: INVALID_TOOL_NAME_PLACEHOLDER,
+                toolUseId: block.toolUseId,
+                input: block.input,
+                ...(block.reasoningSignature !== undefined && { reasoningSignature: block.reasoningSignature }),
+            });
+        });
+        if (!messageReplaced)
+            return message;
+        replaced = true;
+        return new Message({
+            role: message.role,
+            content,
+            ...(message.metadata !== undefined && { metadata: message.metadata }),
+        });
+    });
+    return replaced ? next : messages;
 }
 /**
  * Recursively flattens nested arrays of tools into a single flat array.