@strands-agents/sdk 1.0.0 → 1.1.0

package/dist/src/agent/agent.js

@@ -54,7 +54,7 @@ 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';
@@ -76,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. */
@@ -140,6 +144,8 @@ 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;
     /**
@@ -178,11 +184,26 @@ export class Agent {
         this._mcpClients = mcpClients;
         // Initialize hooks registry
         this._hooksRegistry = new HookRegistryImplementation();
-        // Initialize plugin registry with all plugins to be initialized during initialize()
-        // ModelPlugin is registered last so that on AfterInvocationEvent (which uses reverse
-        // callback ordering), it runs first — clearing messages before SessionManager saves.
+        // `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),
@@ -201,6 +222,8 @@ 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;
     }
@@ -209,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
@@ -223,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) {
@@ -383,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, invocationState: result.value.invocationState }));
-                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) {
@@ -501,6 +558,15 @@ export class Agent {
         // 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) {
@@ -557,72 +623,115 @@ export class Agent {
                         }
                         currentArgs = undefined;
                     }
-                    const modelResult = yield* this._invokeModel(invocationState, 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, invocationState);
-                        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,
-                            invocationState,
-                        });
-                        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, invocationState);
-                        yield this._appendMessage(toolResultMessage, invocationState);
+                    // 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,
-                            invocationState,
-                        });
-                        return result;
+                        continue;
                     }
-                    // Execute tools
-                    const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry, invocationState);
+                    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, invocationState);
+                    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,
@@ -656,6 +765,10 @@ export class Agent {
                 });
                 return result;
             }
+            if (error instanceof InterruptError) {
+                result = this._createInterruptResult(invocationState);
+                return result;
+            }
             caughtError = error;
             throw error;
         }
@@ -701,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.
      *
@@ -720,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
@@ -773,108 +936,117 @@ export class Agent {
         if (toolChoice) {
             streamOptions.toolChoice = toolChoice;
         }
-        // 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 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,
-                stopData,
-                invocationState,
-            });
-            yield afterModelCallEvent;
-            if (afterModelCallEvent.retry) {
-                return yield* this._invokeModel(invocationState, toolChoice);
+        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);
             }
-            return { message, stopReason: 'endTurn' };
-        }
-        // 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);
+            catch (e) {
+                logger.debug(`error=<${e}> | token estimation failed, proceeding without estimate`);
             }
-            const stopData = {
-                message: result.message,
-                stopReason: result.stopReason,
-                ...(result.redaction && { redaction: result.redaction }),
-            };
-            const afterModelCallEvent = new AfterModelCallEvent({
+            const beforeModelCallEvent = new BeforeModelCallEvent({
                 agent: this,
                 model: this.model,
-                stopData,
                 invocationState,
+                ...(projectedInputTokens !== undefined && { projectedInputTokens }),
             });
-            yield afterModelCallEvent;
-            if (afterModelCallEvent.retry) {
-                return yield* this._invokeModel(invocationState, toolChoice);
+            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' };
             }
-            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,
-                invocationState,
+            // 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 }),
             });
-            // 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;
+            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;
             }
-            // After yielding, hooks have been invoked and may have set retry
-            if (errorEvent.retry) {
-                return yield* this._invokeModel(invocationState, toolChoice);
+            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;
             }
-            // Re-throw error
-            throw error;
         }
     }
     /**
@@ -894,6 +1066,7 @@ export class Agent {
      * @returns StreamAggregatedResult containing message, stop reason, and optional redaction message
      */
     async *_streamFromModel(messages, streamOptions, invocationState) {
+        messages = normalizeToolUseNames(messages);
         const streamGenerator = this.model.streamAggregated(messages, streamOptions);
         let result = await streamGenerator.next();
         while (!result.done) {
@@ -920,11 +1093,24 @@ export class Agent {
      *
      * @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, invocationState) {
+    async *executeTools(assistantMessage, toolRegistry, invocationState, completedToolResults) {
         const beforeToolsEvent = new BeforeToolsEvent({ agent: this, message: assistantMessage, invocationState });
-        yield beforeToolsEvent;
+        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
@@ -946,9 +1132,9 @@ export class Agent {
         }
         switch (this._toolExecutor) {
             case 'sequential':
-                return yield* this._executeToolsSequential(toolUseBlocks, toolRegistry, invocationState);
+                return yield* this._executeToolsSequential(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage);
             case 'concurrent':
-                return yield* this._executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState);
+                return yield* this._executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage);
             default: {
                 const _exhaustive = this._toolExecutor;
                 throw new Error(`Unknown toolExecutor: ${_exhaustive}`);
@@ -957,7 +1143,7 @@ export class Agent {
     }
     /**
      * Emits a `ToolResultEvent` for every block plus an `AfterToolsEvent`, and
-     * returns the resulting tool-result message. Used by the pre-launch cancel
+     * returns the resulting tool-result message and dispatched event. Used by the pre-launch cancel
      * paths shared across executors.
      */
     async *_yieldCancelledToolResults(toolUseBlocks, message, invocationState) {
@@ -966,18 +1152,28 @@ export class Agent {
             yield new ToolResultEvent({ agent: this, result, invocationState });
         }
         const toolResultMessage = new Message({ role: 'user', content: cancelBlocks });
-        yield new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
-        return toolResultMessage;
+        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) {
+    async *_executeToolsSequential(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage) {
         const toolResultBlocks = [];
         let toolResultMessage;
+        let afterToolsEvent;
         try {
             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;
+                }
                 if (this.isCancelled) {
                     const cancelBlock = new ToolResultBlock({
                         toolUseId: toolUseBlock.toolUseId,
@@ -988,16 +1184,40 @@ export class Agent {
                     yield new ToolResultEvent({ agent: this, result: cancelBlock, invocationState });
                     continue;
                 }
-                const toolResultBlock = yield* this.executeTool(toolUseBlock, toolRegistry, invocationState);
-                toolResultBlocks.push(toolResultBlock);
-                yield new ToolResultEvent({ agent: this, result: toolResultBlock, invocationState });
+                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,
+                        });
+                        throw error;
+                    }
+                    throw error;
+                }
             }
         }
         finally {
             toolResultMessage = new Message({ role: 'user', content: toolResultBlocks });
-            yield new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            afterToolsEvent = new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            yield afterToolsEvent;
         }
-        return toolResultMessage;
+        return { message: toolResultMessage, afterToolsEvent };
     }
     /**
      * Produces one error ToolResultBlock per tool use block, each carrying
@@ -1020,15 +1240,32 @@ export class Agent {
      * `executeTool`'s own `while(true)` loop, so one tool retrying does not
      * disturb its siblings.
      */
-    async *_executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState) {
+    async *_executeToolsConcurrent(toolUseBlocks, toolRegistry, invocationState, completedToolResults, assistantMessage) {
         let toolResultMessage;
+        let afterToolsEvent;
         const gens = toolUseBlocks.map((block) => ({
             block,
-            gen: this.executeTool(block, toolRegistry, invocationState),
+            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 }));
-        const pendingNext = new Map(gens.map((_, idx) => [idx, step(idx)]));
+        // 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());
@@ -1036,6 +1273,11 @@ export class Agent {
                 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 err = normalizeError(winner.error);
                     const result = new ToolResultBlock({
                         toolUseId: block.toolUseId,
@@ -1053,10 +1295,33 @@ export class Agent {
                     yield new ToolResultEvent({ agent: this, result: winner.res.value, invocationState });
                 }
                 else {
-                    yield winner.res.value;
+                    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 {
             // Close any generators still in-flight (e.g. consumer broke out of stream).
@@ -1079,9 +1344,10 @@ export class Agent {
                 }
             }
             toolResultMessage = new Message({ role: 'user', content: toolResultBlocks });
-            yield new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            afterToolsEvent = new AfterToolsEvent({ agent: this, message: toolResultMessage, invocationState });
+            yield afterToolsEvent;
         }
-        return toolResultMessage;
+        return { message: toolResultMessage, afterToolsEvent };
     }
     /**
      * Executes a single tool and returns the result.
@@ -1094,8 +1360,9 @@ export class Agent {
      * @returns Tool result block
      */
     async *executeTool(toolUseBlock, toolRegistry, invocationState) {
-        const tool = toolRegistry.get(toolUseBlock.name);
-        // Create toolUse object for hook events and telemetry
+        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,
@@ -1103,21 +1370,33 @@ export class Agent {
         };
         // Retry loop for tool execution
         while (true) {
-            const beforeToolCallEvent = new BeforeToolCallEvent({ agent: this, toolUse, tool, invocationState });
+            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 = typeof beforeToolCallEvent.cancel === 'string' ? beforeToolCallEvent.cancel : 'Tool cancelled by hook';
-                const toolResult = new ToolResultBlock({
-                    toolUseId: toolUseBlock.toolUseId,
+                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;
@@ -1134,24 +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.
@@ -1159,7 +1441,7 @@ 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, invocationState });
@@ -1169,9 +1451,9 @@ export class Agent {
                     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 {
@@ -1180,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({
@@ -1202,7 +1489,7 @@ export class Agent {
             const afterToolCallEvent = new AfterToolCallEvent({
                 agent: this,
                 toolUse,
-                tool,
+                tool: effectiveTool,
                 result: toolResult,
                 invocationState,
                 ...(error !== undefined && { error }),
@@ -1211,6 +1498,8 @@ export class Agent {
             if (afterToolCallEvent.retry) {
                 continue;
             }
+            // Return the (possibly mutated) result so hook transformations propagate
+            // to ToolResultEvent and the conversation message the model will see.
             return afterToolCallEvent.result;
         }
     }
@@ -1311,6 +1600,43 @@ export class Agent {
         return new MessageAddedEvent({ agent: this, message, invocationState });
     }
 }
+const INVALID_TOOL_NAME_PLACEHOLDER = 'INVALID_TOOL_NAME';
+/**
+ * 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 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.
  * @param tools - Tools or nested arrays of tools