flowra 0.0.2.dev5__tar.gz → 0.0.3__tar.gz

{flowra-0.0.2.dev5 → flowra-0.0.3}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [0.0.3] - 2026-03-08
+
+### Changed
+- **Hook system redesign**: replaced `ToolLoopHooks`/`ChatHooks` (24 Protocol classes, 12 executor
+  functions, 5 result dataclasses) with generic `HookRegistry` + `Event[T]` pattern. Supports
+  multiple handlers per event, `HookProvider` for distributable hook sets, and `propagate_to()`
+  for parent/child isolation. Hook events are plain mutable dataclasses with result fields.
+- `ToolLoopSpec.meta` / `ChatSpec.meta` renamed to `metadata`.
+
+## [0.0.2] - 2026-03-08
+
 ### Added
 - **Streaming**: `LLMProvider.stream()` method returns `AsyncIterator[StreamEvent]` with `TextDelta`, `ThinkingDelta`, and `ContentComplete` events. All three built-in providers implement real-time streaming. Default fallback calls `call()` and yields `ContentComplete`.
 - **Anthropic thinking**: `AnthropicVertexAdditionalConfig` with `thinking_budget_tokens` enables extended thinking on Claude models. Thinking blocks are now parsed from Anthropic responses (`ThinkingBlock`).

{flowra-0.0.2.dev5 → flowra-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowra
-Version: 0.0.2.dev5
+Version: 0.0.3
 Summary: Flowra — flow infrastructure for building stateful LLM agents
 Project-URL: Repository, https://github.com/anna-money/flowra
 Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md

{flowra-0.0.2.dev5 → flowra-0.0.3}/context7.json

@@ -62,15 +62,15 @@
     "ChatAgent usage: runtime.run(agent=ChatAgent, step=ChatAgent.process_message, spec=ChatSpec(user_message=text))",
     "ChatSpec(user_message: str) is the input, ChatResult(response: str | None, usage: Usage | None) is the output",
     "ChatConfig configures ChatAgent: ChatConfig(llm_config=LLMConfig(model='...'), system_messages=[SystemMessage(...)])",
-    "ChatHooks provides chat-level lifecycle hooks (DI service, same pattern as ToolLoopHooks): ChatHooks(on_save_turn_messages=filter_fn)",
-    "on_save_turn_messages hook filters turn messages before saving to session history — useful for excluding transient messages injected by hooks",
-    "Transient message pattern: mark messages with metadata={'transient': True}, then filter in on_save_turn_messages hook",
+    "HookRegistry from flowra.agent provides generic Event[T] + handler pattern for lifecycle hooks. Register handlers via hooks.on(EventType, handler). Supports multiple handlers, sync/async transparency, HookProvider composition, and propagate_to() for isolation",
+    "SaveTurnMessagesEvent filters turn messages before saving to session history — mutate event.data.messages in place to control what gets persisted. Useful for excluding transient messages injected by hooks",
+    "Transient message pattern: mark messages with metadata={'transient': True}, then filter in SaveTurnMessagesEvent handler",
 
     "PRE-BUILT AGENTS — ToolLoopAgent: single-turn LLM tool loop with hooks and caching",
     "ToolLoopAgent sends messages to LLM, executes tool calls, feeds results back, repeats until done",
     "ToolLoopConfig configures ToolLoopAgent: ToolLoopConfig(llm_config=LLMConfig(model='...'), cache_config=CacheConfig(...))",
-    "ToolLoopHooks provides lifecycle callbacks: on_user_message, on_message_accepted, on_start_iteration, on_before_llm_call, on_text_delta, on_thinking_delta, on_after_llm_call, on_text_reasoning, on_thinking, on_result_message, on_before_tool_call, on_after_tool_call",
-    "When on_text_delta or on_thinking_delta hooks are set, ToolLoopAgent automatically uses provider.stream() instead of provider.call()",
+    "ToolLoopAgent hook events: UserMessageEvent, MessageAcceptedEvent, StartIterationEvent, BeforeLLMCallEvent, TextDeltaEvent, ThinkingDeltaEvent, AfterLLMCallEvent, TextReasoningEvent, ThinkingEvent, ResultMessageEvent, BeforeToolCallEvent, AfterToolCallEvent",
+    "When TextDeltaEvent or ThinkingDeltaEvent handlers are registered, ToolLoopAgent automatically uses provider.stream() instead of provider.call()",
 
     "CACHING: CacheConfig(system_prompt, tools, messages) controls prompt caching strategies",
     "Predefined configs: CACHE_ALL, CACHE_SESSION, CACHE_MANUAL, NO_CACHE",
@@ -80,7 +80,7 @@
     "ConfigValue[T] wraps static or dynamic (callable) config values: ConfigValue[str] | ConfigValue[Callable[[], str]]",
 
     "QUICK START: Create provider -> create ToolRegistry -> create Config -> create AgentRuntime -> runtime.run()",
-    "Import ChatAgent: from flowra.lib.chat import ChatAgent, ChatConfig, ChatHooks, ChatResult, ChatSpec",
+    "Import ChatAgent: from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec, SaveTurnMessagesEvent",
     "Import LLMConfig: from flowra.lib import LLMConfig",
     "Import LLM types: from flowra.llm import LLMProvider, SystemMessage, TextBlock, Usage, TextDelta, ThinkingDelta, ContentComplete",
     "Import runtime: from flowra.runtime import AgentRuntime, FileSessionStorage",

{flowra-0.0.2.dev5 → flowra-0.0.3}/docs/architecture.md

@@ -56,7 +56,8 @@ Pre-built agents for common patterns:
 - **`ToolLoopAgent`** — single-turn LLM tool loop. Sends messages to the LLM,
   executes tool calls, feeds results back, repeats until done.
 
-Also provides lifecycle hooks, prompt caching strategies, and dynamic config. → [docs/lib.md](lib.md)
+Also provides a generic `HookRegistry` + `Event[T]` hook system, prompt caching strategies,
+and dynamic config. → [docs/lib.md](lib.md)
 
 ## Data flow
 

{flowra-0.0.2.dev5 → flowra-0.0.3}/docs/lib.md

@@ -11,14 +11,12 @@ flowra/lib/
 ├── chat/
 │   ├── agent.py             # ChatAgent — multi-turn chat with session history
 │   ├── config.py            # ChatConfig — chat-level configuration
-│   ├── hooks.py             # ChatHooks — chat-level lifecycle hooks
-│   ├── hook_executor.py     # Internal: async/sync hook dispatch
+│   ├── hook_events.py       # SaveTurnMessagesEvent
 │   └── spec.py              # ChatSpec, ChatResult
 └── tool_loop/
     ├── agent.py             # ToolLoopAgent — single-turn LLM tool loop
     ├── config.py            # ToolLoopConfig
-    ├── hooks.py             # ToolLoopHooks, hook protocols and result types
-    ├── hook_executor.py     # Internal: async/sync hook dispatch
+    ├── hook_events.py       # 12 event dataclasses for hook system
     ├── spec.py              # ToolLoopSpec, ToolLoopResult, ToolLoopStatus
     ├── context.py           # ToolLoopAgentContext — tool-accessible loop context
     ├── cache.py             # CacheConfig, cache strategies and presets
@@ -114,10 +112,10 @@ Input for `ChatAgent.process_message`.
 | Field          | Type                     | Default |
 |----------------|--------------------------|---------|
 | `user_message` | `str`                    | —       |
-| `meta`         | `dict[str, Any] \| None` | `None`  |
+| `metadata`     | `dict[str, Any] \| None` | `None`  |
 
-`meta` is passed through to `ToolLoopSpec` and delivered to the `on_message_accepted`
-hook — useful for tracking message IDs in interrupt scenarios.
+`metadata` is passed through to `ToolLoopSpec` and delivered to `MessageAcceptedEvent`
+— useful for tracking message IDs in interrupt scenarios.
 
 ### `ChatResult`
 
@@ -151,31 +149,32 @@ sync callable, or async callable (see [ConfigValue](#configvalue) below).
 instead of `session_messages`. The chat agent builds `session_messages` automatically
 by prepending `system_messages` to the accumulated conversation history.
 
-### `ChatHooks`
+### Chat hooks
 
-Chat-level lifecycle hooks, injected via DI as a service (same pattern as `ToolLoopHooks`).
+Chat-level hook events, registered on the same `HookRegistry` instance as tool loop hooks.
 
-| Field                    | Type                                                           | Default |
-|--------------------------|----------------------------------------------------------------|---------|
-| `on_save_turn_messages`  | `OnSaveTurnMessages \| OnSaveTurnMessagesAsync \| None`        | `None`  |
+**`SaveTurnMessagesEvent`** — emitted before turn messages are saved into session history.
+Handlers mutate `messages` in place to control what gets persisted. Useful for excluding
+transient messages (e.g. dynamic context injected by hooks) from long-term session history.
 
-**`on_save_turn_messages`** — called before turn messages are saved into session history.
-Receives the full list of turn messages and returns the filtered list to persist.
-Useful for excluding transient messages (e.g. dynamic context injected by hooks)
-from long-term session history.
+| Field               | Type                      | Default |
+|---------------------|---------------------------|---------|
+| `messages`          | `list[Message]`           | —       |
 
 ```python
-from flowra.lib.chat import ChatAgent, ChatConfig, ChatHooks
+from flowra.agent import HookRegistry
+from flowra.lib.chat import ChatAgent, ChatConfig, SaveTurnMessagesEvent
 from flowra.llm import Message
 
-def filter_transient(messages: list[Message]) -> list[Message]:
-    return [m for m in messages if not m.metadata.get("transient")]
+def filter_transient(event):
+    event.data.messages = [m for m in event.data.messages if not m.metadata.get("transient")]
 
-hooks = ChatHooks(on_save_turn_messages=filter_transient)
+hooks = HookRegistry()
+hooks.on(SaveTurnMessagesEvent, filter_transient)
 
 runtime = AgentRuntime(
     agents={"chat": ChatAgent},
-    services={..., ChatConfig: config, ChatHooks: hooks},
+    services={..., ChatConfig: config, HookRegistry: hooks},
 )
 ```
 
@@ -217,7 +216,7 @@ Input for `ToolLoopAgent.start`.
 | Field          | Type                     | Default |
 |----------------|--------------------------|---------|
 | `user_message` | `str`                    | —       |
-| `meta`         | `dict[str, Any] \| None` | `None`  |
+| `metadata`     | `dict[str, Any] \| None` | `None`  |
 
 ### `ToolLoopResult`
 
@@ -278,99 +277,78 @@ the agent tells the LLM to try a different approach.
 
 ## Hooks
 
-All lifecycle hooks are grouped into the `ToolLoopHooks` dataclass, injected via DI as
-a service. Every hook is optional, and each accepts either a sync or async callable.
+Lifecycle hooks use a generic `HookRegistry` + `Event[T]` pattern from `flowra.agent`.
+Register handlers for typed event dataclasses. Supports multiple handlers per event,
+sync/async transparency, and composition via `HookProvider`.
 
 ```python
-from flowra.lib.tool_loop import ToolLoopHooks
+from flowra.agent import HookRegistry
+from flowra.lib.tool_loop import BeforeLLMCallEvent, AfterLLMCallEvent
 
-hooks = ToolLoopHooks(
-    on_before_llm_call=lambda req, ctx: print(f"Calling LLM with {len(req.messages)} messages"),
-    on_after_llm_call=lambda req, res, ctx: print(f"LLM returned {res.stop_reason}"),
-)
+hooks = HookRegistry()
+hooks.on(BeforeLLMCallEvent, lambda e: print(f"Calling LLM with {len(e.data.request.messages)} messages"))
+hooks.on(AfterLLMCallEvent, lambda e: print(f"LLM returned {e.data.response.stop_reason}"))
 
 runtime = AgentRuntime(
     agents={"chat": ChatAgent},
-    services={..., ToolLoopHooks: hooks},
+    services={..., HookRegistry: hooks},
 )
 ```
 
-### `ToolLoopHooks`
-
-| Field                  | Type                                                           | Default |
-|------------------------|----------------------------------------------------------------|---------|
-| `on_user_message`      | `OnUserMessage \| OnUserMessageAsync \| None`                  | `None`  |
-| `on_message_accepted`  | `OnMessageAccepted \| OnMessageAcceptedAsync \| None`          | `None`  |
-| `on_start_iteration`   | `OnStartIteration \| OnStartIterationAsync \| None`            | `None`  |
-| `on_before_llm_call`   | `OnBeforeLLMCall \| OnBeforeLLMCallAsync \| None`              | `None`  |
-| `on_after_llm_call`    | `OnAfterLLMCall \| OnAfterLLMCallAsync \| None`                | `None`  |
-| `on_result_message`    | `OnResultMessage \| OnResultMessageAsync \| None`              | `None`  |
-| `on_text_delta`        | `OnTextDelta \| OnTextDeltaAsync \| None`                      | `None`  |
-| `on_thinking_delta`    | `OnThinkingDelta \| OnThinkingDeltaAsync \| None`              | `None`  |
-| `on_text_reasoning`    | `OnTextReasoning \| OnTextReasoningAsync \| None`              | `None`  |
-| `on_thinking`          | `OnThinking \| OnThinkingAsync \| None`                        | `None`  |
-| `on_before_tool_call`  | `OnBeforeToolCall \| OnBeforeToolCallAsync \| None`            | `None`  |
-| `on_after_tool_call`   | `OnAfterToolCall \| OnAfterToolCallAsync \| None`              | `None`  |
+### `HookRegistry`
+
+| Method                                      | Description                                      |
+|---------------------------------------------|--------------------------------------------------|
+| `on(event_type, handler, *, prepend=False)` | Register a handler for an event type             |
+| `has_handlers(event_type) -> bool`          | Check if any handlers are registered             |
+| `add(provider: HookProvider)`               | Register all hooks from a HookProvider           |
+| `async emit(data: T) -> T`                  | Wrap data in `Event`, call handlers, return data |
+| `propagate_to(target, *, only, exclude)`    | Forward events to another registry               |
+
+Handlers receive `Event[T]` where `T` is the event dataclass. `Event` has two fields:
+`data: T` (the event payload) and `context: HookContext | None` (metadata stamped by emit).
+`HookContext` carries `agent_type: type[AbstractAgent] | None` and `agent_path: str`.
+Handlers can mutate `event.data` fields to communicate results back.
+
+### Hook events
+
+| Event                  | Mutable fields                                   | Description                                                               |
+|------------------------|--------------------------------------------------|---------------------------------------------------------------------------|
+| `UserMessageEvent`     | `messages: list[UserMessage]`                    | Once at loop start. Mutate to replace or augment the initial messages.    |
+| `MessageAcceptedEvent` | —                                                | After messages accepted (incl. on resume). Has `messages: list[Message]`. |
+| `StartIterationEvent`  | `additional_messages: list[UserMessage]`         | At start of each iteration. Append to inject context before LLM call.     |
+| `BeforeLLMCallEvent`   | —                                                | Before each LLM request. Has `request`, `context`.                        |
+| `TextDeltaEvent`       | —                                                | During streaming. Has `text` (str), `context`.                            |
+| `ThinkingDeltaEvent`   | —                                                | During streaming. Has `text` (str), `context`.                            |
+| `AfterLLMCallEvent`    | —                                                | After each LLM response. Has `request`, `response`, `context`.            |
+| `TextReasoningEvent`   | —                                                | For each `TextBlock` in response. Has `text` (TextBlock), `context`.      |
+| `ThinkingEvent`        | —                                                | For each `ThinkingBlock` in response. Has `thinking`, `context`.          |
+| `BeforeToolCallEvent`  | `tool_use: ToolUseBlock`                         | Before tool execution. Replace to modify tool parameters.                 |
+| `AfterToolCallEvent`   | `result: ToolResultBlock`, `additional_messages` | After tool execution. Replace result or inject messages.                  |
+| `ResultMessageEvent`   | `continue_messages: list[UserMessage]`           | On END_TURN. Set to continue loop instead of finishing.                   |
 
 ### Hook lifecycle
 
-Hooks fire in this order during a single tool loop iteration:
-
-1. **`on_user_message`** — once at loop start, before the first iteration. Receives the
-   `UserMessage` built from the spec. Return `UserMessageResult(messages=[...])` to
-   replace the initial messages (include the original in the list to keep it).
-
-2. **`on_message_accepted`** — once after the user message is persisted via `flush()`.
-   Receives `meta` from the spec. Useful for tracking accepted message IDs.
-
-3. **`on_start_iteration`** — at the start of each iteration. Receives 1-indexed
-   iteration number and `ToolLoopAgentContext`. Return `StartIterationResult` with
-   `additional_messages` to inject context before the LLM call.
-
-4. **`on_before_llm_call`** — before each LLM request. Receives `LLMRequest` and context.
-   Observational only (no return value).
+Events fire in this order during a single tool loop iteration:
 
-5. **`on_text_delta`** / **`on_thinking_delta`** — when either hook is set, the agent
-   uses `provider.stream()` instead of `provider.call()`. `on_text_delta` fires for
-   each incremental text chunk; `on_thinking_delta` fires for each thinking chunk.
-   These fire **during** the LLM call, before `on_after_llm_call`. The stream is
-   wrapped with `with_interrupt`, so an `InterruptToken` signal exits immediately —
-   even if the LLM is slow to produce the next token.
-
-6. **`on_after_llm_call`** — after each LLM response. Receives `LLMRequest`, `LLMResponse`,
-   and context. Observational only.
-
-7. **`on_text_reasoning`** — for each `TextBlock` in the assistant response. Fires
-   regardless of stop reason — useful for observing text output even when tool calls
-   are also present.
-
-8. **`on_thinking`** — for each `ThinkingBlock` in the assistant response. Fires
-   for models with thinking/reasoning enabled (e.g. extended thinking).
+1. **`UserMessageEvent`** — once at loop start, before the first iteration.
+2. **`MessageAcceptedEvent`** — once after messages are accepted (including on resume).
+3. **`StartIterationEvent`** — at the start of each iteration.
+4. **`BeforeLLMCallEvent`** — before each LLM request.
+5. **`TextDeltaEvent`** / **`ThinkingDeltaEvent`** — when handlers are registered for either,
+   the agent uses `provider.stream()` instead of `provider.call()`. These fire **during**
+   the LLM call, before `AfterLLMCallEvent`.
+6. **`AfterLLMCallEvent`** — after each LLM response.
+7. **`TextReasoningEvent`** — for each `TextBlock` in the assistant response.
+8. **`ThinkingEvent`** — for each `ThinkingBlock` in the assistant response.
 
 Then the flow branches based on stop reason:
 
 - **If `TOOL_USE`:**
-
-  9. **`on_before_tool_call`** — before each tool execution. Return `BeforeToolCallResult`
-     with `amended_tool_use` to modify tool parameters.
-
-  10. **`on_after_tool_call`** — after each tool execution. Return `AfterToolCallResult`
-      with `amended_result` and/or `additional_messages`.
-
+  9. **`BeforeToolCallEvent`** — before each tool execution.
+  10. **`AfterToolCallEvent`** — after each tool execution.
 - **If `END_TURN`:**
-
-  11. **`on_result_message`** — return `ResultMessageResult` with `continue_messages`
-      to force the loop to continue instead of finishing.
-
-### Hook result types
-
-| Type                     | Fields                                                                              |
-|--------------------------|-------------------------------------------------------------------------------------|
-| `UserMessageResult`      | `messages: list[UserMessage]`                                                       |
-| `StartIterationResult`   | `additional_messages: list[UserMessage]` (default `[]`)                             |
-| `BeforeToolCallResult`   | `amended_tool_use: ToolUseBlock \| None` (default `None`)                           |
-| `AfterToolCallResult`    | `amended_result: ToolResultBlock \| None`, `additional_messages: list[UserMessage]` |
-| `ResultMessageResult`    | `continue_messages: list[UserMessage]` (default `[]`)                               |
+  11. **`ResultMessageEvent`** — set `continue_messages` to force the loop to continue.
 
 ## Prompt caching
 
@@ -515,23 +493,6 @@ value = await resolve_config_value(config.max_iterations)  # always returns T
 ## Type aliases
 
 ```python
-# Chat hook protocols (each has sync and async variant)
-OnSaveTurnMessages / OnSaveTurnMessagesAsync
-
-# Tool loop hook protocols (each has sync and async variant)
-OnUserMessage / OnUserMessageAsync
-OnMessageAccepted / OnMessageAcceptedAsync
-OnStartIteration / OnStartIterationAsync
-OnBeforeLLMCall / OnBeforeLLMCallAsync
-OnAfterLLMCall / OnAfterLLMCallAsync
-OnTextDelta / OnTextDeltaAsync
-OnThinkingDelta / OnThinkingDeltaAsync
-OnTextReasoning / OnTextReasoningAsync
-OnThinking / OnThinkingAsync
-OnResultMessage / OnResultMessageAsync
-OnBeforeToolCall / OnBeforeToolCallAsync
-OnAfterToolCall / OnAfterToolCallAsync
-
 # Cache strategy protocols
 SystemPromptCacheStrategy   # (messages: list[SystemMessage]) -> list[SystemMessage]
 ToolsCacheStrategy          # (tools: list[Tool]) -> list[Tool]
@@ -554,23 +515,16 @@ ChatAgent
 
 ### Tool loop flow
 
-1. `start` — accepts user message, runs `on_user_message` hook, appends to
-   `turn_messages`, flushes, fires `on_message_accepted`, then gotos `call_llm`.
-2. `call_llm` — checks interrupt/finish/max_iterations, runs `on_start_iteration`,
-   builds `LLMRequest`, runs `on_before_llm_call`, calls LLM (streaming deltas via
-   `on_text_delta`/`on_thinking_delta` if set), runs `on_after_llm_call`,
-   `on_text_reasoning`, and `on_thinking`, then:
-   - `END_TURN` → runs `on_result_message`, returns `ToolLoopResult` (or continues
+1. `start` — accepts user message, emits `UserMessageEvent`, appends to
+   `turn_messages`, flushes, emits `MessageAcceptedEvent`, then gotos `call_llm`.
+2. `call_llm` — checks interrupt/finish/max_iterations, emits `StartIterationEvent`,
+   builds `LLMRequest`, emits `BeforeLLMCallEvent`, calls LLM (streaming deltas via
+   `TextDeltaEvent`/`ThinkingDeltaEvent` if handlers registered), emits `AfterLLMCallEvent`,
+   `TextReasoningEvent`, and `ThinkingEvent`, then:
+   - `END_TURN` → emits `ResultMessageEvent`, returns `ToolLoopResult` (or continues
      if `continue_messages` is non-empty)
-   - `TOOL_USE` → runs `on_before_tool_call` for each tool, spawns `ToolCallAgent`
+   - `TOOL_USE` → emits `BeforeToolCallEvent` for each tool, spawns `ToolCallAgent`
      children in parallel
-3. `collect_results` — gathers results from `ToolCallAgent` children, runs
-   `on_after_tool_call` for each, applies `max_consecutive_errors` logic,
+3. `collect_results` — gathers results from `ToolCallAgent` children, emits
+   `AfterToolCallEvent` for each, applies `max_consecutive_errors` logic,
    appends tool results to `turn_messages`, gotos `call_llm`.
-
-### Hook executor
-
-`hook_executor.py` provides `execute_*_hook()` functions that handle the sync/async
-dispatch transparently — each function calls the hook, checks `inspect.isawaitable()`,
-and awaits if needed. This allows hooks to be plain functions or async functions
-interchangeably.

flowra-0.0.3/docs/research/hooks_redesign.md

@@ -0,0 +1,273 @@
+# Hook System Redesign — Research
+
+Research date: 2026-03-08
+
+## Problem
+
+Current hook system in `flowra/lib/tool_loop/hooks.py`:
+
+1. **24 Protocol classes** (12 hooks × sync/async variants) — massive boilerplate
+2. **12 executor functions** in `hook_executor.py` — nearly identical code
+3. **5 result dataclasses** — separate types for hook results
+4. **Single handler per hook** — no composition (can't have OTel + logging + guardrails)
+5. No isolation — parent agents can't intercept/filter child agent events
+
+
+## Design decisions
+
+### Event[T] — generic envelope
+
+Handler always receives `Event[T]` — one generic type, no signature inspection magic,
+works naturally with lambdas:
+
+```python
+@dataclass
+class Event[T]:
+    data: T
+    context: HookContext | None = None
+
+
+@dataclass
+class HookContext:
+    agent: str                    # "ResearchAgent"
+    agent_path: str               # "coordinator.research"
+    execution_path: str | None    # "run_123.step_5.spawn_2"
+```
+
+HookRegistry stamps context automatically on emit. Emitting code doesn't know about context.
+
+
+### Event data — plain dataclasses with mutable result fields
+
+Each hook point is a dataclass. Contains input args and mutable fields for results.
+No Protocol classes, no separate result types:
+
+```python
+@dataclass
+class BeforeLLMCall:
+    request: LLMRequest
+    context: ToolLoopAgentContext
+
+@dataclass
+class BeforeToolCall:
+    tool_use: ToolUseBlock
+    context: ToolLoopAgentContext
+    amended_tool_use: ToolUseBlock | None = None  # handler can set this
+
+@dataclass
+class UserMessageEvent:
+    user_message: UserMessage
+    replacement_messages: list[UserMessage] | None = None  # handler can set this
+
+@dataclass
+class TextDeltaEvent:
+    text: str
+    context: ToolLoopAgentContext
+```
+
+
+### HookRegistry — flat, no hierarchy
+
+No parent/child relationship inside HookRegistry. No bubbling. No propagate flag.
+Isolation is handled explicitly by creating separate registries and wiring them manually.
+
+```python
+class HookRegistry:
+    def __init__(self, context: HookContext | None = None):
+        self._context = context
+        self._handlers: dict[type, list[Callable]] = {}
+
+    def on[E](self, event_type: type[E], handler: Callable[[Event[E]], Any], *,
+              prepend: bool = False) -> None:
+        """Add handler. Append by default, prepend=True to go first."""
+        handlers = self._handlers.setdefault(event_type, [])
+        if prepend:
+            handlers.insert(0, handler)
+        else:
+            handlers.append(handler)
+
+    def has_handlers(self, event_type: type) -> bool:
+        """Check if any handlers registered (used for streaming decision)."""
+        return bool(self._handlers.get(event_type))
+
+    def add(self, provider: HookProvider) -> None:
+        """Register all hooks from a provider."""
+        provider.register_hooks(self)
+
+    async def emit[T](self, data: T) -> T:
+        """Emit event: wrap in Event[T], call all handlers in order."""
+        event = Event(data=data, context=self._context)
+        for handler in self._handlers.get(type(data), []):
+            result = handler(event)
+            if inspect.isawaitable(result):
+                await result
+        return data
+
+    def propagate_to(self, target: HookRegistry, *,
+                     only: list[type] | None = None,
+                     exclude: list[type] | None = None) -> None:
+        """Subscribe to events and re-emit them to target registry."""
+        event_types = only or ALL_EVENT_TYPES
+        if exclude:
+            event_types = [t for t in event_types if t not in exclude]
+        for event_type in event_types:
+            self.on(event_type, lambda e, _t=target: _t.emit(e.data))
+```
+
+
+### HookProvider — protocol for grouping related hooks
+
+Distributable hook sets (OTel, logging, guardrails):
+
+```python
+class HookProvider(Protocol):
+    def register_hooks(self, registry: HookRegistry) -> None: ...
+```
+
+```python
+class OtelHooks(HookProvider):
+    def __init__(self, tracer: Tracer):
+        self._tracer = tracer
+
+    def register_hooks(self, registry: HookRegistry) -> None:
+        registry.on(BeforeLLMCall, self._start_span)
+        registry.on(AfterLLMCall, self._end_span)
+
+    async def _start_span(self, event: Event[BeforeLLMCall]) -> None:
+        self._span = self._tracer.start("llm_call", model=event.data.request.model)
+
+    async def _end_span(self, event: Event[AfterLLMCall]) -> None:
+        if self._span:
+            self._span.end(tokens=event.data.response.usage)
+```
+
+
+### Handler styles — all work
+
+```python
+# Lambda
+hooks.on(BeforeLLMCall, lambda e: print(e.data.request.model))
+
+# Function
+def on_llm(e: Event[BeforeLLMCall]) -> None:
+    print(f"{e.context.agent_path}: {e.data.request.model}")
+
+# Async function
+async def on_llm(e: Event[BeforeLLMCall]) -> None:
+    await tracer.start_span(e.data.request.model)
+
+# Method in HookProvider
+class MyHooks(HookProvider):
+    def register_hooks(self, registry: HookRegistry) -> None:
+        registry.on(BeforeLLMCall, self._on_llm)
+    def _on_llm(self, event: Event[BeforeLLMCall]) -> None: ...
+```
+
+
+### Ordering
+
+- `on(EventType, handler)` — appends (default)
+- `on(EventType, handler, prepend=True)` — inserts at beginning
+- All events — same order (registration order). No reverse for "after" events.
+- No wrapping semantics. Hooks are observers, not middleware.
+
+
+### Child agent isolation — explicit, no magic
+
+No hierarchy inside HookRegistry. Parent creates a separate registry for children
+and wires it explicitly:
+
+```python
+def __init__(self, hooks: HookRegistry, services: ServiceLocator, ...):
+    self._hooks = hooks
+
+    # Children get a separate registry
+    child_hooks = HookRegistry()
+
+    # Subscribe to what I care about
+    child_hooks.on(BeforeLLMCall, self._on_child_llm)
+
+    # Propagate selected events to my registry
+    child_hooks.propagate_to(hooks, exclude=[ThinkingDelta])
+
+    # Provide to children via DI
+    services.provide(HookRegistry, child_hooks)
+```
+
+Three modes:
+- **No isolation**: provide same registry to children — they emit into it directly
+- **Full isolation**: `HookRegistry()` without propagation — nothing escapes
+- **Selective**: `propagate_to(hooks, exclude=[...])` — filter what goes up
+
+
+### HookContext — stamped by registry, not by emitting code
+
+HookRegistry is created with a HookContext. The runtime/execution engine sets it
+when creating registries for agent execution nodes:
+
+```python
+hooks = HookRegistry(context=HookContext(
+    agent="ResearchAgent",
+    agent_path="coordinator.research",
+    execution_path="run_42.step_3.spawn_1",
+))
+services.provide(HookRegistry, hooks)
+```
+
+Agent code just emits data:
+```python
+await self._hooks.emit(BeforeLLMCall(request=request))
+```
+
+Handler sees context:
+```python
+hooks.on(BeforeLLMCall, lambda e: print(f"[{e.context.agent_path}] LLM call"))
+```
+
+HookContext is orthogonal to hook routing — it's informational metadata for
+observability, not a mechanism for controlling event flow.
+
+
+### Error handling
+
+Exceptions from handlers propagate as-is. No catching, no logging, no suppression.
+If a handler raises — it's a bug, let it surface. Users can add their own try/except
+in handlers if they want resilience.
+
+
+### Agent usage — in ToolLoopAgent
+
+```python
+# Before (current):
+await execute_before_llm_call_hook(self.__hooks.on_before_llm_call, request, self.__context)
+
+# After (new):
+await self.__hooks.emit(BeforeLLMCall(request=request, context=self.__context))
+
+# Streaming decision (current):
+if self.__hooks.on_text_delta is not None or self.__hooks.on_thinking_delta is not None:
+
+# After (new):
+if self.__hooks.has_handlers(TextDeltaEvent) or self.__hooks.has_handlers(ThinkingDeltaEvent):
+```
+
+
+## What gets eliminated
+
+| Before | After |
+|---|---|
+| 24 Protocol classes (sync + async) | 0 |
+| 12 executor functions | 1 generic `emit()` |
+| 5 Result dataclasses | 0 — mutable fields on event data |
+| `ToolLoopHooks` with 12 fields | `HookRegistry` with one dict |
+| Single handler per hook | Multiple handlers, ordered |
+| No composition | `HookProvider`, `propagate_to()` |
+| No isolation | Separate registries, explicit wiring |
+
+
+## Future ideas (not for initial implementation)
+
+- **Filters on registration**: `hooks.on(BeforeLLMCall, handler, filter=lambda e: ...)`
+  to skip handler based on event/context without running the handler.
+- **Typed propagate_to**: auto-discover all event types instead of maintaining
+  `ALL_EVENT_TYPES` list.