@strands-agents/sdk 0.3.0 → 0.4.0

package/dist/src/hooks/events.d.ts

@@ -1,13 +1,70 @@
-import type { AgentData } from '../types/agent.js';
+import type { AgentData, AgentResult } from '../types/agent.js';
 import type { ContentBlock, Message, StopReason, ToolResultBlock } from '../types/messages.js';
-import type { Tool } from '../tools/tool.js';
+import { type Tool, ToolStreamEvent } from '../tools/tool.js';
 import type { JSONValue } from '../types/json.js';
 import type { ModelStreamEvent } from '../models/streaming.js';
 /**
- * Base class for all hook events.
- * Hook events are emitted at specific points in the agent lifecycle.
+ * Agent hook events.
+ *
+ * All events extend {@link StreamEvent} and carry `readonly agent: AgentData` with a
+ * `readonly type` discriminator (camelCase of the class name) for switch-based narrowing.
+ * Constructor takes a single data-object parameter. All properties are readonly except
+ * explicit mutable flags (`retry`).
+ *
+ * All current events extend {@link HookableEvent} (which itself extends {@link StreamEvent}),
+ * making them both streamable and subscribable via hook callbacks. {@link StreamEvent} exists
+ * as the base class for potential future events that should be stream-only without hookability.
+ *
+ * ## Event categories
+ *
+ * **Lifecycle events** — Before/After pairs that bracket agent operations.
+ * - Naming: `Before<Noun>Event` / `After<Noun>Event`
+ * - `After*` events override `_shouldReverseCallbacks()` → `true` for cleanup ordering.
+ * - Examples: {@link BeforeInvocationEvent}/{@link AfterInvocationEvent},
+ *   {@link BeforeModelCallEvent}/{@link AfterModelCallEvent},
+ *   {@link BeforeToolsEvent}/{@link AfterToolsEvent},
+ *   {@link BeforeToolCallEvent}/{@link AfterToolCallEvent}
+ *
+ * **State-change events** — Signal that agent state was mutated.
+ * - Naming: `<Noun><PastTense>Event`
+ * - Examples: {@link InitializedEvent}, {@link MessageAddedEvent}
+ *
+ * **Data events** — Wrap data objects produced during agent execution.
+ * Two sub-categories:
+ *
+ *   *Update events* — wrap transient streaming data from lower layers.
+ *   - Naming: `<Source>StreamUpdateEvent`, payload field: `.event`
+ *   - Examples: {@link ModelStreamUpdateEvent}, {@link ToolStreamUpdateEvent}
+ *
+ *   *Completion events* — wrap finished data after processing completes.
+ *   - Naming: descriptive `<Noun>Event`, payload field matches data type
+ *     (`.result` for results, `.message` for messages, `.contentBlock` for content blocks).
+ *   - Examples: {@link ContentBlockEvent}, {@link ModelMessageEvent},
+ *     {@link ToolResultEvent}, {@link AgentResultEvent}
+ *
+ * ## Field naming conventions
+ *
+ * | Field          | Usage                                       |
+ * |----------------|---------------------------------------------|
+ * | `agent`        | Present on every event (`AgentData`)         |
+ * | `.event`       | Inner event in update wrappers               |
+ * | `.result`      | Finished result object                       |
+ * | `.message`     | Message object                               |
+ * | `.contentBlock`| Content block object                         |
+ */
+/**
+ * Base class for all events yielded by `agent.stream()`.
+ * Carries no hookability — subclasses that should be hookable extend {@link HookableEvent} instead.
+ */
+export declare abstract class StreamEvent {
+}
+/**
+ * Base class for events that can be subscribed to via the hook system.
+ * Only events extending this class are dispatched to {@link HookRegistry} callbacks.
+ * All current events extend this class. {@link StreamEvent} exists as the base for
+ * potential future stream-only events that should not be hookable.
  */
-export declare abstract class HookEvent {
+export declare abstract class HookableEvent extends StreamEvent {
     /**
      * @internal
      * Check if callbacks should be reversed for this event.
@@ -19,7 +76,7 @@ export declare abstract class HookEvent {
  * Event triggered when an agent has finished initialization.
  * Fired after the agent has been fully constructed and all built-in components have been initialized.
  */
-export declare class InitializedEvent extends HookEvent {
+export declare class InitializedEvent extends HookableEvent {
     readonly type: "initializedEvent";
     readonly agent: AgentData;
     constructor(data: {
@@ -30,7 +87,7 @@ export declare class InitializedEvent extends HookEvent {
  * Event triggered at the beginning of a new agent request.
  * Fired before any model inference or tool execution occurs.
  */
-export declare class BeforeInvocationEvent extends HookEvent {
+export declare class BeforeInvocationEvent extends HookableEvent {
     readonly type: "beforeInvocationEvent";
     readonly agent: AgentData;
     constructor(data: {
@@ -42,7 +99,7 @@ export declare class BeforeInvocationEvent extends HookEvent {
  * Fired after all processing completes, regardless of success or error.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export declare class AfterInvocationEvent extends HookEvent {
+export declare class AfterInvocationEvent extends HookableEvent {
     readonly type: "afterInvocationEvent";
     readonly agent: AgentData;
     constructor(data: {
@@ -55,7 +112,7 @@ export declare class AfterInvocationEvent extends HookEvent {
  * Fired during the agent loop execution for framework-generated messages.
  * Does not fire for initial messages from AgentConfig or user input messages.
  */
-export declare class MessageAddedEvent extends HookEvent {
+export declare class MessageAddedEvent extends HookableEvent {
     readonly type: "messageAddedEvent";
     readonly agent: AgentData;
     readonly message: Message;
@@ -68,7 +125,7 @@ export declare class MessageAddedEvent extends HookEvent {
  * Event triggered just before a tool is executed.
  * Fired after tool lookup but before execution begins.
  */
-export declare class BeforeToolCallEvent extends HookEvent {
+export declare class BeforeToolCallEvent extends HookableEvent {
     readonly type: "beforeToolCallEvent";
     readonly agent: AgentData;
     readonly toolUse: {
@@ -92,7 +149,7 @@ export declare class BeforeToolCallEvent extends HookEvent {
  * Fired after tool execution finishes, whether successful or failed.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export declare class AfterToolCallEvent extends HookEvent {
+export declare class AfterToolCallEvent extends HookableEvent {
     readonly type: "afterToolCallEvent";
     readonly agent: AgentData;
     readonly toolUse: {
@@ -125,7 +182,7 @@ export declare class AfterToolCallEvent extends HookEvent {
  * Event triggered just before the model is invoked.
  * Fired before sending messages to the model for inference.
  */
-export declare class BeforeModelCallEvent extends HookEvent {
+export declare class BeforeModelCallEvent extends HookableEvent {
     readonly type: "beforeModelCallEvent";
     readonly agent: AgentData;
     constructor(data: {
@@ -152,7 +209,7 @@ export interface ModelStopData {
  *
  * Note: stopData may be undefined if an error occurs before the model completes.
  */
-export declare class AfterModelCallEvent extends HookEvent {
+export declare class AfterModelCallEvent extends HookableEvent {
     readonly type: "afterModelCallEvent";
     readonly agent: AgentData;
     readonly stopData?: ModelStopData;
@@ -171,25 +228,102 @@ export declare class AfterModelCallEvent extends HookEvent {
 }
 /**
  * Event triggered for each streaming event from the model.
- * Allows hooks to observe individual streaming events during model inference.
- * Provides read-only access to streaming events.
+ * Wraps a {@link ModelStreamEvent} (transient streaming delta) during model inference.
+ * Completed content blocks are handled separately by {@link ContentBlockEvent}
+ * because they represent different granularities: partial deltas vs fully assembled results.
+ */
+export declare class ModelStreamUpdateEvent extends HookableEvent {
+    readonly type: "modelStreamUpdateEvent";
+    readonly agent: AgentData;
+    readonly event: ModelStreamEvent;
+    constructor(data: {
+        agent: AgentData;
+        event: ModelStreamEvent;
+    });
+}
+/**
+ * Event triggered when a content block completes during model inference.
+ * Wraps completed content blocks (TextBlock, ToolUseBlock, ReasoningBlock) from model streaming.
+ * This is intentionally separate from {@link ModelStreamUpdateEvent}. The model's
+ * `streamAggregated()` yields two kinds of output: {@link ModelStreamEvent} (transient
+ * streaming deltas — partial data arriving while the model generates) and
+ * {@link ContentBlock} (fully assembled results after all deltas accumulate).
+ * These represent different granularities with different semantics, so they are
+ * wrapped in distinct event classes rather than combined into a single event.
+ */
+export declare class ContentBlockEvent extends HookableEvent {
+    readonly type: "contentBlockEvent";
+    readonly agent: AgentData;
+    readonly contentBlock: ContentBlock;
+    constructor(data: {
+        agent: AgentData;
+        contentBlock: ContentBlock;
+    });
+}
+/**
+ * Event triggered when the model completes a full message.
+ * Wraps the assembled message and stop reason after model streaming finishes.
+ */
+export declare class ModelMessageEvent extends HookableEvent {
+    readonly type: "modelMessageEvent";
+    readonly agent: AgentData;
+    readonly message: Message;
+    readonly stopReason: StopReason;
+    constructor(data: {
+        agent: AgentData;
+        message: Message;
+        stopReason: StopReason;
+    });
+}
+/**
+ * Event triggered when a tool execution completes.
+ * Wraps the tool result block after a tool finishes execution.
+ */
+export declare class ToolResultEvent extends HookableEvent {
+    readonly type: "toolResultEvent";
+    readonly agent: AgentData;
+    readonly result: ToolResultBlock;
+    constructor(data: {
+        agent: AgentData;
+        result: ToolResultBlock;
+    });
+}
+/**
+ * Event triggered for each streaming progress event from a tool during execution.
+ * Wraps a {@link ToolStreamEvent} with agent context, keeping the tool authoring
+ * interface unchanged — tools construct `ToolStreamEvent` without knowledge of agents
+ * or hooks, and the agent layer wraps them at the boundary.
  *
- * Currently private pending https://github.com/strands-agents/sdk-typescript/issues/288
+ * Consistent with {@link ModelStreamUpdateEvent} which wraps model streaming events
+ * the same way.
+ */
+export declare class ToolStreamUpdateEvent extends HookableEvent {
+    readonly type: "toolStreamUpdateEvent";
+    readonly agent: AgentData;
+    readonly event: ToolStreamEvent;
+    constructor(data: {
+        agent: AgentData;
+        event: ToolStreamEvent;
+    });
+}
+/**
+ * Event triggered as the final event in the agent stream.
+ * Wraps the agent result containing the stop reason and last message.
  */
-export declare class ModelStreamEventHook extends HookEvent {
-    readonly type: "modelStreamEventHook";
+export declare class AgentResultEvent extends HookableEvent {
+    readonly type: "agentResultEvent";
     readonly agent: AgentData;
-    readonly event: ModelStreamEvent | ContentBlock;
+    readonly result: AgentResult;
     constructor(data: {
         agent: AgentData;
-        event: ModelStreamEvent | ContentBlock;
+        result: AgentResult;
     });
 }
 /**
  * Event triggered before executing tools.
  * Fired when the model returns tool use blocks that need to be executed.
  */
-export declare class BeforeToolsEvent extends HookEvent {
+export declare class BeforeToolsEvent extends HookableEvent {
     readonly type: "beforeToolsEvent";
     readonly agent: AgentData;
     readonly message: Message;
@@ -203,7 +337,7 @@ export declare class BeforeToolsEvent extends HookEvent {
  * Fired after tool results are collected and ready to be added to conversation.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export declare class AfterToolsEvent extends HookEvent {
+export declare class AfterToolsEvent extends HookableEvent {
     readonly type: "afterToolsEvent";
     readonly agent: AgentData;
     readonly message: Message;

package/dist/src/hooks/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/hooks/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D;;;GAGG;AACH,8BAAsB,SAAS;IAC7B;;;;OAIG;IACH,uBAAuB,IAAI,OAAO;CAGnC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IAClD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAS;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;IAK7B,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAS;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;CAKzD;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,SAAS,CAAA;KACjB,CAAA;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;gBAEnB,IAAI,EAAE;QAChB,KAAK,EAAE,SAAS,CAAA;QAChB,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAA;QAC9D,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;KACvB;CAMF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAS;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,SAAS,CAAA;KACjB,CAAA;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEH,IAAI,EAAE;QAChB,KAAK,EAAE,SAAS,CAAA;QAChB,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAA;QAC9D,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;QACtB,MAAM,EAAE,eAAe,CAAA;QACvB,KAAK,CAAC,EAAE,KAAK,CAAA;KACd;IAWQ,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEH,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;IAWtE,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,CAAA;gBAEnC,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,CAAA;KAAE;CAK/E;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;CAKzD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;IAM/C,uBAAuB,IAAI,OAAO;CAG5C"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/hooks/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,KAAK,IAAI,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;GAGG;AACH,8BAAsB,WAAW;CAAG;AAEpC;;;;;GAKG;AACH,8BAAsB,aAAc,SAAQ,WAAW;IACrD;;;;OAIG;IACH,uBAAuB,IAAI,OAAO;CAGnC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAS;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;IAK7B,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAS;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;CAKzD;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,SAAS,CAAA;KACjB,CAAA;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;gBAEnB,IAAI,EAAE;QAChB,KAAK,EAAE,SAAS,CAAA;QAChB,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAA;QAC9D,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;KACvB;CAMF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAS;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,SAAS,CAAA;KACjB,CAAA;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEH,IAAI,EAAE;QAChB,KAAK,EAAE,SAAS,CAAA;QAChB,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAA;QAC9D,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;QACtB,MAAM,EAAE,eAAe,CAAA;QACvB,KAAK,CAAC,EAAE,KAAK,CAAA;KACd;IAWQ,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAA;KAAE;CAIvC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAS;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;gBAEH,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;IAWtE,uBAAuB,IAAI,OAAO;CAG5C;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAS;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;gBAEpB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE;CAKhE;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAS;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;gBAEvB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,YAAY,EAAE,YAAY,CAAA;KAAE;CAKnE;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAS;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;gBAEnB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE;CAMjF;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;gBAEpB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE;CAKhE;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAS;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;gBAEnB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,eAAe,CAAA;KAAE;CAK/D;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;gBAEhB,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE;CAK5D;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;CAKzD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;gBAEb,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;IAM/C,uBAAuB,IAAI,OAAO;CAG5C"}

package/dist/src/hooks/events.js

@@ -1,8 +1,66 @@
+import { ToolStreamEvent } from '../tools/tool.js';
 /**
- * Base class for all hook events.
- * Hook events are emitted at specific points in the agent lifecycle.
+ * Agent hook events.
+ *
+ * All events extend {@link StreamEvent} and carry `readonly agent: AgentData` with a
+ * `readonly type` discriminator (camelCase of the class name) for switch-based narrowing.
+ * Constructor takes a single data-object parameter. All properties are readonly except
+ * explicit mutable flags (`retry`).
+ *
+ * All current events extend {@link HookableEvent} (which itself extends {@link StreamEvent}),
+ * making them both streamable and subscribable via hook callbacks. {@link StreamEvent} exists
+ * as the base class for potential future events that should be stream-only without hookability.
+ *
+ * ## Event categories
+ *
+ * **Lifecycle events** — Before/After pairs that bracket agent operations.
+ * - Naming: `Before<Noun>Event` / `After<Noun>Event`
+ * - `After*` events override `_shouldReverseCallbacks()` → `true` for cleanup ordering.
+ * - Examples: {@link BeforeInvocationEvent}/{@link AfterInvocationEvent},
+ *   {@link BeforeModelCallEvent}/{@link AfterModelCallEvent},
+ *   {@link BeforeToolsEvent}/{@link AfterToolsEvent},
+ *   {@link BeforeToolCallEvent}/{@link AfterToolCallEvent}
+ *
+ * **State-change events** — Signal that agent state was mutated.
+ * - Naming: `<Noun><PastTense>Event`
+ * - Examples: {@link InitializedEvent}, {@link MessageAddedEvent}
+ *
+ * **Data events** — Wrap data objects produced during agent execution.
+ * Two sub-categories:
+ *
+ *   *Update events* — wrap transient streaming data from lower layers.
+ *   - Naming: `<Source>StreamUpdateEvent`, payload field: `.event`
+ *   - Examples: {@link ModelStreamUpdateEvent}, {@link ToolStreamUpdateEvent}
+ *
+ *   *Completion events* — wrap finished data after processing completes.
+ *   - Naming: descriptive `<Noun>Event`, payload field matches data type
+ *     (`.result` for results, `.message` for messages, `.contentBlock` for content blocks).
+ *   - Examples: {@link ContentBlockEvent}, {@link ModelMessageEvent},
+ *     {@link ToolResultEvent}, {@link AgentResultEvent}
+ *
+ * ## Field naming conventions
+ *
+ * | Field          | Usage                                       |
+ * |----------------|---------------------------------------------|
+ * | `agent`        | Present on every event (`AgentData`)         |
+ * | `.event`       | Inner event in update wrappers               |
+ * | `.result`      | Finished result object                       |
+ * | `.message`     | Message object                               |
+ * | `.contentBlock`| Content block object                         |
+ */
+/**
+ * Base class for all events yielded by `agent.stream()`.
+ * Carries no hookability — subclasses that should be hookable extend {@link HookableEvent} instead.
  */
-export class HookEvent {
+export class StreamEvent {
+}
+/**
+ * Base class for events that can be subscribed to via the hook system.
+ * Only events extending this class are dispatched to {@link HookRegistry} callbacks.
+ * All current events extend this class. {@link StreamEvent} exists as the base for
+ * potential future stream-only events that should not be hookable.
+ */
+export class HookableEvent extends StreamEvent {
     /**
      * @internal
      * Check if callbacks should be reversed for this event.
@@ -16,7 +74,7 @@ export class HookEvent {
  * Event triggered when an agent has finished initialization.
  * Fired after the agent has been fully constructed and all built-in components have been initialized.
  */
-export class InitializedEvent extends HookEvent {
+export class InitializedEvent extends HookableEvent {
     type = 'initializedEvent';
     agent;
     constructor(data) {
@@ -28,7 +86,7 @@ export class InitializedEvent extends HookEvent {
  * Event triggered at the beginning of a new agent request.
  * Fired before any model inference or tool execution occurs.
  */
-export class BeforeInvocationEvent extends HookEvent {
+export class BeforeInvocationEvent extends HookableEvent {
     type = 'beforeInvocationEvent';
     agent;
     constructor(data) {
@@ -41,7 +99,7 @@ export class BeforeInvocationEvent extends HookEvent {
  * Fired after all processing completes, regardless of success or error.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export class AfterInvocationEvent extends HookEvent {
+export class AfterInvocationEvent extends HookableEvent {
     type = 'afterInvocationEvent';
     agent;
     constructor(data) {
@@ -57,7 +115,7 @@ export class AfterInvocationEvent extends HookEvent {
  * Fired during the agent loop execution for framework-generated messages.
  * Does not fire for initial messages from AgentConfig or user input messages.
  */
-export class MessageAddedEvent extends HookEvent {
+export class MessageAddedEvent extends HookableEvent {
     type = 'messageAddedEvent';
     agent;
     message;
@@ -71,7 +129,7 @@ export class MessageAddedEvent extends HookEvent {
  * Event triggered just before a tool is executed.
  * Fired after tool lookup but before execution begins.
  */
-export class BeforeToolCallEvent extends HookEvent {
+export class BeforeToolCallEvent extends HookableEvent {
     type = 'beforeToolCallEvent';
     agent;
     toolUse;
@@ -88,7 +146,7 @@ export class BeforeToolCallEvent extends HookEvent {
  * Fired after tool execution finishes, whether successful or failed.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export class AfterToolCallEvent extends HookEvent {
+export class AfterToolCallEvent extends HookableEvent {
     type = 'afterToolCallEvent';
     agent;
     toolUse;
@@ -118,7 +176,7 @@ export class AfterToolCallEvent extends HookEvent {
  * Event triggered just before the model is invoked.
  * Fired before sending messages to the model for inference.
  */
-export class BeforeModelCallEvent extends HookEvent {
+export class BeforeModelCallEvent extends HookableEvent {
     type = 'beforeModelCallEvent';
     agent;
     constructor(data) {
@@ -133,7 +191,7 @@ export class BeforeModelCallEvent extends HookEvent {
  *
  * Note: stopData may be undefined if an error occurs before the model completes.
  */
-export class AfterModelCallEvent extends HookEvent {
+export class AfterModelCallEvent extends HookableEvent {
     type = 'afterModelCallEvent';
     agent;
     stopData;
@@ -159,13 +217,81 @@ export class AfterModelCallEvent extends HookEvent {
 }
 /**
  * Event triggered for each streaming event from the model.
- * Allows hooks to observe individual streaming events during model inference.
- * Provides read-only access to streaming events.
+ * Wraps a {@link ModelStreamEvent} (transient streaming delta) during model inference.
+ * Completed content blocks are handled separately by {@link ContentBlockEvent}
+ * because they represent different granularities: partial deltas vs fully assembled results.
+ */
+export class ModelStreamUpdateEvent extends HookableEvent {
+    type = 'modelStreamUpdateEvent';
+    agent;
+    event;
+    constructor(data) {
+        super();
+        this.agent = data.agent;
+        this.event = data.event;
+    }
+}
+/**
+ * Event triggered when a content block completes during model inference.
+ * Wraps completed content blocks (TextBlock, ToolUseBlock, ReasoningBlock) from model streaming.
+ * This is intentionally separate from {@link ModelStreamUpdateEvent}. The model's
+ * `streamAggregated()` yields two kinds of output: {@link ModelStreamEvent} (transient
+ * streaming deltas — partial data arriving while the model generates) and
+ * {@link ContentBlock} (fully assembled results after all deltas accumulate).
+ * These represent different granularities with different semantics, so they are
+ * wrapped in distinct event classes rather than combined into a single event.
+ */
+export class ContentBlockEvent extends HookableEvent {
+    type = 'contentBlockEvent';
+    agent;
+    contentBlock;
+    constructor(data) {
+        super();
+        this.agent = data.agent;
+        this.contentBlock = data.contentBlock;
+    }
+}
+/**
+ * Event triggered when the model completes a full message.
+ * Wraps the assembled message and stop reason after model streaming finishes.
+ */
+export class ModelMessageEvent extends HookableEvent {
+    type = 'modelMessageEvent';
+    agent;
+    message;
+    stopReason;
+    constructor(data) {
+        super();
+        this.agent = data.agent;
+        this.message = data.message;
+        this.stopReason = data.stopReason;
+    }
+}
+/**
+ * Event triggered when a tool execution completes.
+ * Wraps the tool result block after a tool finishes execution.
+ */
+export class ToolResultEvent extends HookableEvent {
+    type = 'toolResultEvent';
+    agent;
+    result;
+    constructor(data) {
+        super();
+        this.agent = data.agent;
+        this.result = data.result;
+    }
+}
+/**
+ * Event triggered for each streaming progress event from a tool during execution.
+ * Wraps a {@link ToolStreamEvent} with agent context, keeping the tool authoring
+ * interface unchanged — tools construct `ToolStreamEvent` without knowledge of agents
+ * or hooks, and the agent layer wraps them at the boundary.
  *
- * Currently private pending https://github.com/strands-agents/sdk-typescript/issues/288
+ * Consistent with {@link ModelStreamUpdateEvent} which wraps model streaming events
+ * the same way.
  */
-export class ModelStreamEventHook extends HookEvent {
-    type = 'modelStreamEventHook';
+export class ToolStreamUpdateEvent extends HookableEvent {
+    type = 'toolStreamUpdateEvent';
     agent;
     event;
     constructor(data) {
@@ -174,11 +300,25 @@ export class ModelStreamEventHook extends HookEvent {
         this.event = data.event;
     }
 }
+/**
+ * Event triggered as the final event in the agent stream.
+ * Wraps the agent result containing the stop reason and last message.
+ */
+export class AgentResultEvent extends HookableEvent {
+    type = 'agentResultEvent';
+    agent;
+    result;
+    constructor(data) {
+        super();
+        this.agent = data.agent;
+        this.result = data.result;
+    }
+}
 /**
  * Event triggered before executing tools.
  * Fired when the model returns tool use blocks that need to be executed.
  */
-export class BeforeToolsEvent extends HookEvent {
+export class BeforeToolsEvent extends HookableEvent {
     type = 'beforeToolsEvent';
     agent;
     message;
@@ -193,7 +333,7 @@ export class BeforeToolsEvent extends HookEvent {
  * Fired after tool results are collected and ready to be added to conversation.
  * Uses reverse callback ordering for proper cleanup semantics.
  */
-export class AfterToolsEvent extends HookEvent {
+export class AfterToolsEvent extends HookableEvent {
     type = 'afterToolsEvent';
     agent;
     message;

package/dist/src/hooks/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/hooks/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/hooks/events.ts"],"names":[],"mappings":"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"}

package/dist/src/hooks/index.d.ts

@@ -1,11 +1,19 @@
 /**
  * Hooks module for event-driven extensibility.
  *
- * Hooks provide a composable mechanism for extending agent functionality
- * by subscribing to events throughout the agent lifecycle.
+ * This module has two concerns with distinct naming:
+ *
+ * - **Events** (`StreamEvent` and subclasses) — the data objects yielded by `agent.stream()`.
+ *   Named `Stream*` because they are members of the agent stream.
+ *   All current events extend {@link HookableEvent}, making them subscribable via hook callbacks.
+ *   See {@link StreamEvent} and `events.ts` for the full taxonomy.
+ *
+ * - **Hook infrastructure** (`HookProvider`, `HookCallback`, `HookRegistry`, `HookCleanup`) —
+ *   the subscription mechanism that lets providers register callbacks for {@link HookableEvent} types.
+ *   Named `Hook*` because they describe the hooking/subscription pattern, not the events themselves.
  */
-export { HookEvent, InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, MessageAddedEvent, BeforeToolCallEvent, AfterToolCallEvent, BeforeModelCallEvent, AfterModelCallEvent, ModelStreamEventHook, BeforeToolsEvent, AfterToolsEvent, } from './events.js';
+export { StreamEvent, HookableEvent, InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, MessageAddedEvent, BeforeToolCallEvent, AfterToolCallEvent, BeforeModelCallEvent, AfterModelCallEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, ToolStreamUpdateEvent, AgentResultEvent, BeforeToolsEvent, AfterToolsEvent, } from './events.js';
 export type { ModelStopData as ModelStopResponse } from './events.js';
 export { HookRegistryImplementation as HookRegistry } from './registry.js';
-export type { HookCallback, HookProvider, HookEventConstructor, HookCleanup } from './types.js';
+export type { HookCallback, HookProvider, HookableEventConstructor, HookCleanup } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGrE,OAAO,EAAE,0BAA0B,IAAI,YAAY,EAAE,MAAM,eAAe,CAAA;AAG1E,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGrE,OAAO,EAAE,0BAA0B,IAAI,YAAY,EAAE,MAAM,eAAe,CAAA;AAG1E,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/hooks/index.js

@@ -1,11 +1,19 @@
 /**
  * Hooks module for event-driven extensibility.
  *
- * Hooks provide a composable mechanism for extending agent functionality
- * by subscribing to events throughout the agent lifecycle.
+ * This module has two concerns with distinct naming:
+ *
+ * - **Events** (`StreamEvent` and subclasses) — the data objects yielded by `agent.stream()`.
+ *   Named `Stream*` because they are members of the agent stream.
+ *   All current events extend {@link HookableEvent}, making them subscribable via hook callbacks.
+ *   See {@link StreamEvent} and `events.ts` for the full taxonomy.
+ *
+ * - **Hook infrastructure** (`HookProvider`, `HookCallback`, `HookRegistry`, `HookCleanup`) —
+ *   the subscription mechanism that lets providers register callbacks for {@link HookableEvent} types.
+ *   Named `Hook*` because they describe the hooking/subscription pattern, not the events themselves.
  */
 // Event classes
-export { HookEvent, InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, MessageAddedEvent, BeforeToolCallEvent, AfterToolCallEvent, BeforeModelCallEvent, AfterModelCallEvent, ModelStreamEventHook, BeforeToolsEvent, AfterToolsEvent, } from './events.js';
+export { StreamEvent, HookableEvent, InitializedEvent, BeforeInvocationEvent, AfterInvocationEvent, MessageAddedEvent, BeforeToolCallEvent, AfterToolCallEvent, BeforeModelCallEvent, AfterModelCallEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, ToolStreamUpdateEvent, AgentResultEvent, BeforeToolsEvent, AfterToolsEvent, } from './events.js';
 // Registry
 export { HookRegistryImplementation as HookRegistry } from './registry.js';
 //# sourceMappingURL=index.js.map

package/dist/src/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gBAAgB;AAChB,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAA;AAKpB,WAAW;AACX,OAAO,EAAE,0BAA0B,IAAI,YAAY,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,gBAAgB;AAChB,OAAO,EACL,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAA;AAKpB,WAAW;AACX,OAAO,EAAE,0BAA0B,IAAI,YAAY,EAAE,MAAM,eAAe,CAAA"}