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

package/dist/src/agent/__tests__/agent.hook.test.js

@@ -1,10 +1,11 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import { Agent } from '../agent.js';
-import { AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, MessageAddedEvent, ModelStreamUpdateEvent, InitializedEvent, HookableEvent, } from '../../hooks/index.js';
+import { AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, AgentResultEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, MessageAddedEvent, ModelStreamUpdateEvent, InitializedEvent, HookableEvent, ModelMessageEvent, } from '../../hooks/index.js';
 import { MockMessageModel } from '../../__fixtures__/mock-message-model.js';
 import { MockPlugin } from '../../__fixtures__/mock-plugin.js';
 import { collectIterator } from '../../__fixtures__/model-test-helpers.js';
 import { createMockTool } from '../../__fixtures__/tool-helpers.js';
+import { expectAgentResult } from '../../__fixtures__/agent-helpers.js';
 import { Message, TextBlock, ToolResultBlock } from '../../types/messages.js';
 describe('Agent Hooks Integration', () => {
     let mockPlugin;
@@ -19,12 +20,23 @@ describe('Agent Hooks Integration', () => {
             await agent.invoke('Hi');
             expect(lifecyclePlugin.invocations).toHaveLength(7);
             expect(lifecyclePlugin.invocations[0]).toEqual(new InitializedEvent({ agent }));
-            expect(lifecyclePlugin.invocations[1]).toEqual(new BeforeInvocationEvent({ agent }));
-            expect(lifecyclePlugin.invocations[2]).toEqual(new MessageAddedEvent({ agent, message: new Message({ role: 'user', content: [new TextBlock('Hi')] }) }));
-            expect(lifecyclePlugin.invocations[3]).toEqual(new BeforeModelCallEvent({ agent, model: agent.model }));
+            expect(lifecyclePlugin.invocations[1]).toEqual(new BeforeInvocationEvent({ agent, invocationState: {} }));
+            expect(lifecyclePlugin.invocations[2]).toEqual(new MessageAddedEvent({
+                agent,
+                message: new Message({ role: 'user', content: [new TextBlock('Hi')] }),
+                invocationState: {},
+            }));
+            expect(lifecyclePlugin.invocations[3]).toEqual(new BeforeModelCallEvent({
+                agent,
+                model: agent.model,
+                invocationState: {},
+                projectedInputTokens: expect.any(Number),
+            }));
             expect(lifecyclePlugin.invocations[4]).toEqual(new AfterModelCallEvent({
                 agent,
                 model: agent.model,
+                invocationState: {},
+                attemptCount: 1,
                 stopData: {
                     stopReason: 'endTurn',
                     message: new Message({ role: 'assistant', content: [new TextBlock('Hello')] }),
@@ -33,8 +45,9 @@ describe('Agent Hooks Integration', () => {
             expect(lifecyclePlugin.invocations[5]).toEqual(new MessageAddedEvent({
                 agent,
                 message: new Message({ role: 'assistant', content: [new TextBlock('Hello')] }),
+                invocationState: {},
             }));
-            expect(lifecyclePlugin.invocations[6]).toEqual(new AfterInvocationEvent({ agent }));
+            expect(lifecyclePlugin.invocations[6]).toEqual(new AfterInvocationEvent({ agent, invocationState: {} }));
         });
         it('fires hooks during stream', async () => {
             const lifecyclePlugin = new MockPlugin();
@@ -43,15 +56,23 @@ describe('Agent Hooks Integration', () => {
             await collectIterator(agent.stream('Hi'));
             expect(lifecyclePlugin.invocations).toHaveLength(7);
             expect(lifecyclePlugin.invocations[0]).toEqual(new InitializedEvent({ agent }));
-            expect(lifecyclePlugin.invocations[1]).toEqual(new BeforeInvocationEvent({ agent }));
+            expect(lifecyclePlugin.invocations[1]).toEqual(new BeforeInvocationEvent({ agent, invocationState: {} }));
             expect(lifecyclePlugin.invocations[2]).toEqual(new MessageAddedEvent({
                 agent,
                 message: new Message({ role: 'user', content: [new TextBlock('Hi')] }),
+                invocationState: {},
+            }));
+            expect(lifecyclePlugin.invocations[3]).toEqual(new BeforeModelCallEvent({
+                agent,
+                model: agent.model,
+                invocationState: {},
+                projectedInputTokens: expect.any(Number),
             }));
-            expect(lifecyclePlugin.invocations[3]).toEqual(new BeforeModelCallEvent({ agent, model: agent.model }));
             expect(lifecyclePlugin.invocations[4]).toEqual(new AfterModelCallEvent({
                 agent,
                 model: agent.model,
+                invocationState: {},
+                attemptCount: 1,
                 stopData: {
                     stopReason: 'endTurn',
                     message: new Message({ role: 'assistant', content: [new TextBlock('Hello')] }),
@@ -60,8 +81,9 @@ describe('Agent Hooks Integration', () => {
             expect(lifecyclePlugin.invocations[5]).toEqual(new MessageAddedEvent({
                 agent,
                 message: new Message({ role: 'assistant', content: [new TextBlock('Hello')] }),
+                invocationState: {},
             }));
-            expect(lifecyclePlugin.invocations[6]).toEqual(new AfterInvocationEvent({ agent }));
+            expect(lifecyclePlugin.invocations[6]).toEqual(new AfterInvocationEvent({ agent, invocationState: {} }));
         });
     });
     describe('runtime hook registration', () => {
@@ -78,8 +100,8 @@ describe('Agent Hooks Integration', () => {
             });
             await agent.invoke('Hi');
             expect(invocations).toHaveLength(2);
-            expect(invocations[0]).toEqual(new BeforeInvocationEvent({ agent }));
-            expect(invocations[1]).toEqual(new AfterInvocationEvent({ agent }));
+            expect(invocations[0]).toEqual(new BeforeInvocationEvent({ agent, invocationState: {} }));
+            expect(invocations[1]).toEqual(new AfterInvocationEvent({ agent, invocationState: {} }));
         });
     });
     describe('multi-turn conversations', () => {
@@ -129,6 +151,7 @@ describe('Agent Hooks Integration', () => {
                 agent,
                 toolUse: { name: 'testTool', toolUseId: 'tool-1', input: {} },
                 tool,
+                invocationState: {},
             }));
             // Verify AfterToolCallEvent
             const afterToolCall = afterToolCallEvents[0];
@@ -141,6 +164,7 @@ describe('Agent Hooks Integration', () => {
                     status: 'success',
                     content: [new TextBlock('Tool result')],
                 }),
+                invocationState: {},
             }));
         });
         it('fires AfterToolCallEvent with error when tool fails', async () => {
@@ -173,6 +197,7 @@ describe('Agent Hooks Integration', () => {
                     content: [new TextBlock('Tool execution failed')],
                 }),
                 error: new Error('Tool execution failed'),
+                invocationState: {},
             }));
         });
     });
@@ -214,10 +239,12 @@ describe('Agent Hooks Integration', () => {
             expect(messageAddedEvents[0]).toEqual(new MessageAddedEvent({
                 agent,
                 message: new Message({ role: 'user', content: [new TextBlock('New message')] }),
+                invocationState: {},
             }));
             expect(messageAddedEvents[1]).toEqual(new MessageAddedEvent({
                 agent,
                 message: new Message({ role: 'assistant', content: [new TextBlock('Response')] }),
+                invocationState: {},
             }));
         });
     });
@@ -411,7 +438,7 @@ describe('Agent Hooks Integration', () => {
             expect(afterEvent.result).toEqual(new ToolResultBlock({
                 toolUseId: 'tool-1',
                 status: 'error',
-                content: [new TextBlock('tool cancelled by hook')],
+                content: [new TextBlock('Tool cancelled by hook')],
             }));
         });
         it('cancels individual tool call with custom message when cancel is a string', async () => {
@@ -495,7 +522,7 @@ describe('Agent Hooks Integration', () => {
             expect(afterEvent.message.content[0]).toEqual(new ToolResultBlock({
                 toolUseId: 'tool-1',
                 status: 'error',
-                content: [new TextBlock('tool cancelled by hook')],
+                content: [new TextBlock('Tool cancelled by hook')],
             }));
         });
         it('cancels all tools with custom message when BeforeToolsEvent.cancel is a string', async () => {
@@ -615,6 +642,691 @@ describe('Agent Hooks Integration', () => {
             expect(beforeCount).toBe(2);
             expect(toolCallCount).toBe(1); // Only executed on second attempt
         });
+        it('allows hooks to replace result on AfterToolCallEvent', async () => {
+            const tool = createMockTool('myTool', () => {
+                return new ToolResultBlock({
+                    toolUseId: 'tool-1',
+                    status: 'success',
+                    content: [new TextBlock('original result')],
+                });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolCallEvent, (event) => {
+                event.result = new ToolResultBlock({
+                    toolUseId: event.result.toolUseId,
+                    status: 'success',
+                    content: [new TextBlock('replaced result')],
+                });
+            });
+            await agent.invoke('Test');
+            const toolResultMessage = agent.messages.find((m) => m.role === 'user' && m.content.some((b) => b.type === 'toolResultBlock'));
+            const toolResultBlock = toolResultMessage.content.find((b) => b.type === 'toolResultBlock');
+            expect(toolResultBlock).toStrictEqual(new ToolResultBlock({
+                toolUseId: 'tool-1',
+                status: 'success',
+                content: [new TextBlock('replaced result')],
+            }));
+        });
+    });
+    describe('AfterToolsEvent.endTurn', () => {
+        const makeSingleToolSetup = () => ({
+            tool: createMockTool('myTool', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('result')] });
+            }),
+            model: new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Should not reach this' }),
+        });
+        it('halts the loop when endTurn is true with default message', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool], plugins: [mockPlugin] });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = true;
+            });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({
+                    role: 'assistant',
+                    content: expect.arrayContaining([
+                        expect.objectContaining({ type: 'textBlock', text: 'Turn ended early by hook after tool execution' }),
+                    ]),
+                }),
+            }));
+            expect(model.callCount).toBe(1);
+        });
+        it('halts the loop with custom assistant message when endTurn is a string', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = 'enough information gathered';
+            });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({
+                    role: 'assistant',
+                    content: expect.arrayContaining([
+                        expect.objectContaining({ type: 'textBlock', text: 'enough information gathered' }),
+                    ]),
+                }),
+            }));
+            expect(model.callCount).toBe(1);
+        });
+        it('does not halt when endTurn is false (default)', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({ role: 'assistant' }),
+            }));
+            expect(model.callCount).toBe(2);
+        });
+        it('treats empty string endTurn as falsy (does not halt)', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = '';
+            });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({ role: 'assistant' }),
+            }));
+            expect(model.callCount).toBe(2);
+        });
+        it('appends tool results and default endTurn message to conversation history', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = true;
+            });
+            await agent.invoke('Test');
+            expect(agent.messages).toHaveLength(4);
+            expect(agent.messages[0].role).toBe('user');
+            expect(agent.messages[1].role).toBe('assistant');
+            expect(agent.messages[1].content).toEqual(expect.arrayContaining([expect.objectContaining({ type: 'toolUseBlock' })]));
+            expect(agent.messages[2].role).toBe('user');
+            expect(agent.messages[2].content).toEqual(expect.arrayContaining([expect.objectContaining({ type: 'toolResultBlock' })]));
+            expect(agent.messages[3].role).toBe('assistant');
+            expect(agent.messages[3].content).toEqual(expect.arrayContaining([
+                expect.objectContaining({ type: 'textBlock', text: 'Turn ended early by hook after tool execution' }),
+            ]));
+        });
+        it('halts the loop with concurrent tool execution', async () => {
+            const tool1 = createMockTool('tool1', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('Result 1')] });
+            });
+            const tool2 = createMockTool('tool2', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-2', status: 'success', content: [new TextBlock('Result 2')] });
+            });
+            const model = new MockMessageModel()
+                .addTurn([
+                { type: 'toolUseBlock', name: 'tool1', toolUseId: 'tool-1', input: {} },
+                { type: 'toolUseBlock', name: 'tool2', toolUseId: 'tool-2', input: {} },
+            ])
+                .addTurn({ type: 'textBlock', text: 'Should not reach this' });
+            const agent = new Agent({ model, tools: [tool1, tool2], toolExecutor: 'concurrent' });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = true;
+            });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({ role: 'assistant' }),
+            }));
+            expect(model.callCount).toBe(1);
+        });
+        it('emits AfterToolsEvent with endTurn via stream()', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = true;
+            });
+            const items = await collectIterator(agent.stream('Test'));
+            const afterToolsEvents = items.filter((e) => e instanceof AfterToolsEvent);
+            expect(afterToolsEvents).toHaveLength(1);
+            expect(afterToolsEvents[0].endTurn).toBe(true);
+            const resultEvents = items.filter((e) => e instanceof AgentResultEvent);
+            expect(resultEvents).toHaveLength(1);
+            expect(resultEvents[0].result.stopReason).toBe('endTurn');
+        });
+        it('halts even when set on a cancelled-tools AfterToolsEvent', async () => {
+            const { tool, model } = makeSingleToolSetup();
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(BeforeToolsEvent, (event) => {
+                event.cancel = true;
+            });
+            agent.addHook(AfterToolsEvent, (event) => {
+                event.endTurn = true;
+            });
+            const result = await agent.invoke('Test');
+            expect(result).toEqual(expect.objectContaining({
+                type: 'agentResult',
+                stopReason: 'endTurn',
+                lastMessage: expect.objectContaining({ role: 'assistant' }),
+            }));
+            expect(model.callCount).toBe(1);
+        });
+    });
+    describe('cancel invocation via hooks', () => {
+        it('cancels invocation with default message when cancel is true', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeInvocationEvent, (event) => {
+                event.cancel = true;
+            });
+            const result = await agent.invoke('Test');
+            expect(result.stopReason).toBe('endTurn');
+            expect(result.lastMessage.content[0]).toEqual(new TextBlock('invocation denied by hook'));
+            const beforeModelCallEvents = mockPlugin.invocations.filter((e) => e instanceof BeforeModelCallEvent);
+            expect(beforeModelCallEvents).toHaveLength(0);
+        });
+        it('cancels invocation with custom message when cancel is a string', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeInvocationEvent, (event) => {
+                event.cancel = 'Unauthorized user';
+            });
+            const result = await agent.invoke('Test');
+            expect(result.stopReason).toBe('endTurn');
+            expect(result.lastMessage.content[0]).toEqual(new TextBlock('Unauthorized user'));
+        });
+        it('does not append user message when invocation is cancelled', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model });
+            agent.addHook(BeforeInvocationEvent, (event) => {
+                event.cancel = true;
+            });
+            await agent.invoke('Test');
+            expect(agent.messages).toHaveLength(1);
+            expect(agent.messages[0].role).toBe('assistant');
+        });
+        it('emits AfterInvocationEvent when invocation is cancelled', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeInvocationEvent, (event) => {
+                event.cancel = true;
+            });
+            await agent.invoke('Test');
+            const beforeInvocationEvents = mockPlugin.invocations.filter((e) => e instanceof BeforeInvocationEvent);
+            const afterInvocationEvents = mockPlugin.invocations.filter((e) => e instanceof AfterInvocationEvent);
+            expect(beforeInvocationEvents).toHaveLength(1);
+            expect(afterInvocationEvents).toHaveLength(1);
+        });
+    });
+    describe('cancel model call via hooks', () => {
+        it('cancels model call with default message when cancel is true', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeModelCallEvent, (event) => {
+                event.cancel = true;
+            });
+            const result = await agent.invoke('Test');
+            expect(result.stopReason).toBe('endTurn');
+            expect(result.lastMessage.content[0]).toEqual(new TextBlock('model call denied by hook'));
+        });
+        it('cancels model call with custom message when cancel is a string', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeModelCallEvent, (event) => {
+                event.cancel = 'Rate limited';
+            });
+            const result = await agent.invoke('Test');
+            expect(result.stopReason).toBe('endTurn');
+            expect(result.lastMessage.content[0]).toEqual(new TextBlock('Rate limited'));
+        });
+        it('emits AfterModelCallEvent when model call is cancelled', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeModelCallEvent, (event) => {
+                event.cancel = true;
+            });
+            await agent.invoke('Test');
+            const beforeModelCallEvents = mockPlugin.invocations.filter((e) => e instanceof BeforeModelCallEvent);
+            const afterModelCallEvents = mockPlugin.invocations.filter((e) => e instanceof AfterModelCallEvent);
+            expect(beforeModelCallEvents).toHaveLength(1);
+            expect(afterModelCallEvents).toHaveLength(1);
+        });
+        it('does not emit ModelMessageEvent when model call is cancelled', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeModelCallEvent, (event) => {
+                event.cancel = true;
+            });
+            await agent.invoke('Test');
+            const modelMessageEvents = mockPlugin.invocations.filter((e) => e instanceof ModelMessageEvent);
+            expect(modelMessageEvents).toHaveLength(0);
+        });
+        it('allows retry after cancel on model call', async () => {
+            let beforeCount = 0;
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [mockPlugin] });
+            agent.addHook(BeforeModelCallEvent, (event) => {
+                beforeCount++;
+                if (beforeCount === 1) {
+                    event.cancel = 'Not yet';
+                }
+            });
+            agent.addHook(AfterModelCallEvent, (event) => {
+                if (beforeCount === 1) {
+                    event.retry = true;
+                }
+            });
+            const result = await agent.invoke('Test');
+            expect(result.stopReason).toBe('endTurn');
+            expect(beforeCount).toBe(2);
+            expect(result.lastMessage.content[0]).toEqual(new TextBlock('Hello'));
+        });
+    });
+    describe('BeforeToolCallEvent selectedTool', () => {
+        it('invokes the replacement tool instead of the registry tool', async () => {
+            let originalExecuted = false;
+            let replacementExecuted = false;
+            const originalTool = createMockTool('originalTool', () => {
+                originalExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('original')] });
+            });
+            const replacementTool = createMockTool('replacementTool', () => {
+                replacementExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('replacement')] });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'originalTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [originalTool], plugins: [mockPlugin] });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                event.selectedTool = replacementTool;
+            });
+            await agent.invoke('Test');
+            expect(originalExecuted).toBe(false);
+            expect(replacementExecuted).toBe(true);
+            const afterToolCallEvents = mockPlugin.invocations.filter((e) => e instanceof AfterToolCallEvent);
+            expect(afterToolCallEvents).toHaveLength(1);
+            expect(afterToolCallEvents[0].result.content).toEqual([new TextBlock('replacement')]);
+        });
+        it('cancel wins over selectedTool', async () => {
+            let replacementExecuted = false;
+            const replacementTool = createMockTool('replacementTool', () => {
+                replacementExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('replacement')] });
+            });
+            const registryTool = createMockTool('registryTool', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('registry')] });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'registryTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [registryTool], plugins: [mockPlugin] });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                event.selectedTool = replacementTool;
+                event.cancel = 'blocked';
+            });
+            await agent.invoke('Test');
+            expect(replacementExecuted).toBe(false);
+            // AfterToolCallEvent.tool should report the selectedTool even on the cancel path,
+            // so observability hooks see a consistent `tool` value regardless of branch.
+            const afterToolCallEvents = mockPlugin.invocations.filter((e) => e instanceof AfterToolCallEvent);
+            expect(afterToolCallEvents).toHaveLength(1);
+            expect(afterToolCallEvents[0].tool).toBe(replacementTool);
+        });
+        it('works with concurrent tool executor', async () => {
+            let originalExecuted = false;
+            let replacementExecuted = false;
+            const originalTool = createMockTool('originalTool', () => {
+                originalExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('original')] });
+            });
+            const replacementTool = createMockTool('replacementTool', () => {
+                replacementExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('replacement')] });
+            });
+            const otherTool = createMockTool('otherTool', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-2', status: 'success', content: [new TextBlock('other')] });
+            });
+            const model = new MockMessageModel()
+                .addTurn([
+                { type: 'toolUseBlock', name: 'originalTool', toolUseId: 'tool-1', input: {} },
+                { type: 'toolUseBlock', name: 'otherTool', toolUseId: 'tool-2', input: {} },
+            ])
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({
+                model,
+                tools: [originalTool, otherTool],
+                toolExecutor: 'concurrent',
+            });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                if (event.toolUse.name === 'originalTool') {
+                    event.selectedTool = replacementTool;
+                }
+            });
+            await agent.invoke('Test');
+            expect(originalExecuted).toBe(false);
+            expect(replacementExecuted).toBe(true);
+        });
+    });
+    describe('BeforeToolCallEvent toolUse mutation', () => {
+        it('passes mutated input to the tool', async () => {
+            const capturedInputs = [];
+            const tool = createMockTool('tool', () => {
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('ok')] });
+            });
+            // Wrap to capture input via the context the tool receives.
+            const capturingTool = {
+                ...tool,
+                async *stream(context) {
+                    capturedInputs.push(context.toolUse.input);
+                    return yield* tool.stream(context);
+                },
+            };
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'tool', toolUseId: 'tool-1', input: { a: 1 } })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [capturingTool] });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                event.toolUse.input = { a: 2, injected: true };
+            });
+            await agent.invoke('Test');
+            expect(capturedInputs).toEqual([{ a: 2, injected: true }]);
+        });
+        it('re-resolves the tool when hook renames toolUse.name', async () => {
+            let origExecuted = false;
+            let renamedExecuted = false;
+            const origTool = createMockTool('orig', () => {
+                origExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('orig')] });
+            });
+            const renamedTool = createMockTool('renamed', () => {
+                renamedExecuted = true;
+                return new ToolResultBlock({ toolUseId: 'tool-1', status: 'success', content: [new TextBlock('renamed')] });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'orig', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [origTool, renamedTool] });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                event.toolUse.name = 'renamed';
+            });
+            await agent.invoke('Test');
+            expect(origExecuted).toBe(false);
+            expect(renamedExecuted).toBe(true);
+        });
+        it('works with concurrent tool executor', async () => {
+            const capturedInputs = {};
+            const baseA = createMockTool('toolA', () => {
+                return new ToolResultBlock({ toolUseId: 'a', status: 'success', content: [new TextBlock('a done')] });
+            });
+            const baseB = createMockTool('toolB', () => {
+                return new ToolResultBlock({ toolUseId: 'b', status: 'success', content: [new TextBlock('b done')] });
+            });
+            const toolA = {
+                ...baseA,
+                async *stream(context) {
+                    capturedInputs[context.toolUse.name] = context.toolUse.input;
+                    return yield* baseA.stream(context);
+                },
+            };
+            const toolB = {
+                ...baseB,
+                async *stream(context) {
+                    capturedInputs[context.toolUse.name] = context.toolUse.input;
+                    return yield* baseB.stream(context);
+                },
+            };
+            const model = new MockMessageModel()
+                .addTurn([
+                { type: 'toolUseBlock', name: 'toolA', toolUseId: 'a', input: { original: 'a' } },
+                { type: 'toolUseBlock', name: 'toolB', toolUseId: 'b', input: { original: 'b' } },
+            ])
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [toolA, toolB], toolExecutor: 'concurrent' });
+            agent.addHook(BeforeToolCallEvent, (event) => {
+                event.toolUse.input = { mutated: event.toolUse.name };
+            });
+            await agent.invoke('Test');
+            expect(capturedInputs).toEqual({
+                toolA: { mutated: 'toolA' },
+                toolB: { mutated: 'toolB' },
+            });
+        });
+    });
+    describe('AfterToolCallEvent result mutation', () => {
+        it('propagates mutated result into the conversation message', async () => {
+            const tool = createMockTool('tool', () => {
+                return new ToolResultBlock({
+                    toolUseId: 'tool-1',
+                    status: 'success',
+                    content: [new TextBlock('SECRET_VALUE')],
+                });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'tool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [tool] });
+            agent.addHook(AfterToolCallEvent, (event) => {
+                event.result = new ToolResultBlock({
+                    toolUseId: 'tool-1',
+                    status: 'success',
+                    content: [new TextBlock('[REDACTED]')],
+                });
+            });
+            await agent.invoke('Test');
+            const toolResultMessage = agent.messages.find((m) => m.content.some((b) => b.type === 'toolResultBlock' && b.toolUseId === 'tool-1'));
+            expect(toolResultMessage).toBeDefined();
+            const block = toolResultMessage.content.find((b) => b.type === 'toolResultBlock' && b.toolUseId === 'tool-1');
+            expect(block.content).toEqual([new TextBlock('[REDACTED]')]);
+        });
+        it('propagates mutated result into AfterToolsEvent', async () => {
+            const tool = createMockTool('tool', () => {
+                return new ToolResultBlock({
+                    toolUseId: 'tool-1',
+                    status: 'success',
+                    content: [new TextBlock('SECRET_VALUE')],
+                });
+            });
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'tool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const agent = new Agent({ model, tools: [tool], plugins: [mockPlugin] });
+            agent.addHook(AfterToolCallEvent, (event) => {
+                event.result = new ToolResultBlock({
+                    toolUseId: 'tool-1',
+                    status: 'success',
+                    content: [new TextBlock('[REDACTED]')],
+                });
+            });
+            await agent.invoke('Test');
+            const afterToolsEvents = mockPlugin.invocations.filter((e) => e instanceof AfterToolsEvent);
+            expect(afterToolsEvents).toHaveLength(1);
+            const block = afterToolsEvents[0].message.content.find((b) => b.type === 'toolResultBlock' && b.toolUseId === 'tool-1');
+            expect(block.content).toEqual([new TextBlock('[REDACTED]')]);
+        });
+    });
+    describe('AfterInvocationEvent resume', () => {
+        it('re-invokes the agent with the resume args', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'textBlock', text: 'first' })
+                .addTurn({ type: 'textBlock', text: 'second' });
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                invocationCount++;
+                if (invocationCount === 1) {
+                    event.resume = 'follow-up';
+                }
+            });
+            const result = await agent.invoke('initial');
+            expect(invocationCount).toBe(2);
+            expect(result).toEqual(expectAgentResult({
+                stopReason: 'endTurn',
+                messageText: 'second',
+                // Meter cycleCount is cumulative across the resume chain (1 cycle per invocation x 2).
+                cycleCount: 2,
+            }));
+        });
+        it('chains multiple resumes', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'textBlock', text: 'a' })
+                .addTurn({ type: 'textBlock', text: 'b' })
+                .addTurn({ type: 'textBlock', text: 'c' });
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                invocationCount++;
+                if (invocationCount === 1)
+                    event.resume = 'second';
+                else if (invocationCount === 2)
+                    event.resume = 'third';
+            });
+            const result = await agent.invoke('first');
+            expect(invocationCount).toBe(3);
+            expect(result.lastMessage.content[0]).toEqual({ type: 'textBlock', text: 'c' });
+        });
+        it('does not resume when resume is left undefined', async () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'only' });
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, () => {
+                invocationCount++;
+            });
+            await agent.invoke('hi');
+            expect(invocationCount).toBe(1);
+        });
+        it('does not resume when the invocation errors', async () => {
+            const model = new MockMessageModel().addTurn(new Error('boom'));
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                invocationCount++;
+                event.resume = 'should-not-run';
+            });
+            await expect(agent.invoke('hi')).rejects.toThrow('boom');
+            expect(invocationCount).toBe(1);
+        });
+        it('first-registered hook wins when multiple hooks set resume', async () => {
+            // AfterInvocationEvent reverses callback order (_shouldReverseCallbacks=true),
+            // so the first-registered hook fires last and its resume value wins.
+            const model = new MockMessageModel()
+                .addTurn({ type: 'textBlock', text: 'first' })
+                .addTurn({ type: 'textBlock', text: 'second' });
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(BeforeInvocationEvent, () => {
+                invocationCount++;
+            });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                if (invocationCount === 1)
+                    event.resume = 'first-registered wins';
+            });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                if (invocationCount === 1)
+                    event.resume = 'second-registered loses';
+            });
+            await agent.invoke('initial');
+            const userTexts = agent.messages
+                .filter((m) => m.role === 'user')
+                .flatMap((m) => m.content.filter((b) => b.type === 'textBlock').map((b) => b.text));
+            expect(userTexts).toEqual(['initial', 'first-registered wins']);
+        });
+        it('ignores resume set during an erroring invocation', async () => {
+            // Resume should not fire when the invocation ends with an error, even if
+            // AfterInvocationEvent (which fires in _stream's finally) still runs.
+            const model = new MockMessageModel().addTurn(new Error('boom'));
+            let resumeFired = false;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                event.resume = 'should not run';
+            });
+            agent.addHook(BeforeInvocationEvent, () => {
+                // Track whether BeforeInvocationEvent fires a second time (would indicate resume ran).
+                if (resumeFired)
+                    throw new Error('unexpected second invocation');
+                resumeFired = true;
+            });
+            await expect(agent.invoke('hi')).rejects.toThrow('boom');
+        });
+        it('emits only one AgentResultEvent for a resumed chain', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'textBlock', text: 'first' })
+                .addTurn({ type: 'textBlock', text: 'second' });
+            let invocationCount = 0;
+            const agent = new Agent({ model });
+            agent.addHook(AfterInvocationEvent, (event) => {
+                invocationCount++;
+                if (invocationCount === 1) {
+                    event.resume = 'follow-up';
+                }
+            });
+            const items = await collectIterator(agent.stream('initial'));
+            const agentResults = items.filter((e) => e instanceof AgentResultEvent);
+            expect(agentResults).toHaveLength(1);
+            const afterInvocations = items.filter((e) => e instanceof AfterInvocationEvent);
+            expect(afterInvocations).toHaveLength(2);
+        });
+    });
+    describe('queue-based lifecycle plugin (WASM bridge pattern)', () => {
+        function createLifecycleBridgePlugin(queue) {
+            return {
+                name: 'strands:lifecycle-bridge',
+                initAgent(agent) {
+                    agent.addHook(InitializedEvent, () => {
+                        queue.push('initialized');
+                    });
+                    agent.addHook(BeforeInvocationEvent, () => {
+                        queue.push('before-invocation');
+                    });
+                    agent.addHook(AfterInvocationEvent, () => {
+                        queue.push('after-invocation');
+                    });
+                    agent.addHook(BeforeModelCallEvent, () => {
+                        queue.push('before-model-call');
+                    });
+                    agent.addHook(AfterModelCallEvent, () => {
+                        queue.push('after-model-call');
+                    });
+                    agent.addHook(MessageAddedEvent, () => {
+                        queue.push('message-added');
+                    });
+                    agent.addHook(BeforeToolCallEvent, () => {
+                        queue.push('before-tool-call');
+                    });
+                    agent.addHook(AfterToolCallEvent, () => {
+                        queue.push('after-tool-call');
+                    });
+                },
+            };
+        }
+        it('receives lifecycle events when registered via plugins config', async () => {
+            const queue = [];
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, plugins: [createLifecycleBridgePlugin(queue)] });
+            await agent.invoke('Hi');
+            expect(queue).toStrictEqual([
+                'initialized',
+                'before-invocation',
+                'message-added',
+                'before-model-call',
+                'after-model-call',
+                'message-added',
+                'after-invocation',
+            ]);
+        });
+        it('receives no events when passed via non-existent hooks config field', async () => {
+            const queue = [];
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'Hello' });
+            const agent = new Agent({ model, hooks: [createLifecycleBridgePlugin(queue)] });
+            await agent.invoke('Hi');
+            expect(queue).toHaveLength(0);
+        });
     });
 });
 //# sourceMappingURL=agent.hook.test.js.map