robot_lab 0.2.6 → 0.2.7

data/docs/api/errors.md

@@ -16,9 +16,13 @@ StandardError
     ├── RobotLab::BusError
     ├── RobotLab::RactorBoundaryError
     ├── RobotLab::ToolError
-    └── RobotLab::BudgetExceeded
+    ├── RobotLab::BudgetExceeded
+    └── RobotLab::AwaitTimeout
 ```
 
+`AwaitTimeout` is defined in `lib/robot_lab/memory.rb` and raised by
+[`Memory#get`](core/memory.md#get) when a blocking read expires.
+
 Additionally, `DelegationFuture` defines its own scoped error:
 
 ```
@@ -49,6 +53,8 @@ Raised when configuration is invalid or missing required values.
 
 ```ruby
 # Example: missing API key, invalid template path
+begin
+  robot.run("hello")
 rescue RobotLab::ConfigurationError => e
   puts "Bad config: #{e.message}"
 end
@@ -58,15 +64,27 @@ end
 
 ## RobotLab::DependencyError < ConfigurationError
 
-Raised when a required optional gem dependency is not installed.
+Raised when a required optional gem dependency is not installed. There are three
+distinct raise sites in core, each with its own message:
+
+| Raised by | Missing dependency | Message |
+|-----------|--------------------|---------|
+| `TextAnalysis.require_classifier!` — reached from `Convergence`, `HistoryCompressor`, `Robot#compress_history`, `Robot#search_history` | `classifier` gem | `The 'classifier' gem is required for text analysis features. Add it to your Gemfile: gem 'classifier', '~> 2.3'` |
+| `Memory`'s document-store methods (`store_document`, `search_documents`, `document_keys`, `delete_document`) | `robot_lab-document_store` gem | `document storage requires the robot_lab-document_store gem. Add \`gem 'robot_lab-document_store'\` to your Gemfile.` |
+| `Network#run` under `parallel_mode: :ractor` | `robot_lab-ractor` gem | `parallel_mode: :ractor requires the robot_lab-ractor gem. Add \`gem 'robot_lab-ractor'\` to your Gemfile.` |
 
 ```ruby
-# Triggered by: Convergence, HistoryCompressor when 'classifier' gem is absent
+begin
+  robot.compress_history
 rescue RobotLab::DependencyError => e
-  puts e.message  # "Add gem 'classifier', '~> 2.3' to your Gemfile"
+  warn e.message
 end
 ```
 
+Two places swallow it rather than propagate: `auto_compact: :context_window`
+logs the message at `:warn` and skips compaction, and
+`MCP::ServerDiscovery` rescues it and falls back.
+
 ---
 
 ## RobotLab::InferenceError
@@ -74,6 +92,8 @@ end
 Raised when LLM inference fails (API errors, timeouts, rate limits).
 
 ```ruby
+begin
+  robot.run("hello")
 rescue RobotLab::InferenceError => e
   puts "LLM call failed: #{e.message}"
 end
@@ -94,13 +114,22 @@ robot = RobotLab.build(
 )
 
 begin
-  robot.run("Run all steps.")
+  robot.run("Run all steps.", tools: :inherit)
 rescue RobotLab::ToolLoopError => e
-  puts e.message  # "Tool call limit of 10 exceeded"
+  puts e.message
+  # "Circuit breaker triggered: 11 tool calls exceeded max_tool_rounds (10)"
   robot.clear_messages  # required before reuse
 end
 ```
 
+The message format is:
+
+```
+Circuit breaker triggered: <N> tool calls exceeded max_tool_rounds (<M>)
+```
+
+`N` is the call count that tripped the breaker (always `M + 1`); `M` is the configured limit.
+
 ---
 
 ## RobotLab::ToolNotFoundError
@@ -114,6 +143,8 @@ Raised when a tool name is referenced but cannot be found in the `ToolManifest`.
 Raised when MCP server communication fails (connection refused, timeout, protocol error).
 
 ```ruby
+begin
+  robot.run("hello", mcp: :inherit, tools: :inherit)
 rescue RobotLab::MCPError => e
   puts "MCP failed: #{e.message}"
 end
@@ -128,6 +159,8 @@ end
 Raised when message bus communication fails (no bus configured, channel not found).
 
 ```ruby
+begin
+  robot.send_message(to: :bob, content: "hi")
 rescue RobotLab::BusError => e
   puts "Bus error: #{e.message}"
 end
@@ -139,37 +172,65 @@ end
 
 Raised when a value cannot be made Ractor-shareable before crossing a Ractor boundary (e.g., a live `IO` object, a `Proc`, or an object with mutable state).
 
+!!! note "The error class is core; the machinery that raises it is not"
+    `RobotLab::RactorBoundaryError` is defined in core
+    (`lib/robot_lab/error.rb`) so hosts can rescue it without loading anything
+    extra. But `RactorBoundary`, `RactorWorkerPool`, and `RactorMemoryProxy` are
+    **not defined in core** — they ship in the separate **`robot_lab-ractor`**
+    gem. Core only *references* `RactorBoundary.freeze_deep` from
+    `Network#build_robot_spec`, which is reachable only under
+    `parallel_mode: :ractor`, which itself raises `DependencyError` unless that
+    gem is loaded.
+
 ```ruby
+require "robot_lab"
+require "robot_lab/ractor"   # provides RactorBoundary and the worker pool
+
 begin
   RobotLab::RactorBoundary.freeze_deep({ io: StringIO.new })
 rescue RobotLab::RactorBoundaryError => e
-  puts e.message  # "Cannot make value Ractor-shareable: ..."
+  puts e.message
 end
 ```
 
-Raised proactively by `RactorWorkerPool#submit` and `RactorMemoryProxy#set` before any Ractor is involved.
-
 ---
 
 ## RobotLab::ToolError
 
-Raised when a tool fails during execution inside a Ractor worker (the pool unwraps `RactorJobError` and re-raises as `ToolError`).
+An opt-in error type for tool failures. Core raises it nowhere itself — you raise
+it from your own `execute`, and the `robot_lab-ractor` worker pool raises it when
+unwrapping a failure that happened inside a Ractor.
+
+`ToolError.new(message, retryable: true)` marks a specific instance as retryable.
+
+When a tool raises inside `Tool#call`, the error is caught and returned to the
+LLM as text rather than propagating (unless the class sets
+`self.raise_on_error = true`). RobotLab appends `" (retryable)"` whenever
+`RobotLab::Errors.retryable?(error)` is true, so the model itself can see that
+another attempt is worth trying:
 
 ```ruby
-begin
-  pool.submit("MyTool", { input: "bad" })
-rescue RobotLab::ToolError => e
-  puts e.message  # "Tool 'MyTool' failed in Ractor: ..."
+class Fetch < RobotLab::Tool
+  description "Fetch a record"
+  param :id, type: "string", desc: "record id"
+
+  def execute(id:)
+    raise RobotLab::ToolError.new("upstream unavailable", retryable: true)
+  end
 end
+
+Fetch.new.call({ "id" => "1" })
+# => "Error (fetch): upstream unavailable (retryable)"
 ```
 
-Like `MCPError`, `ToolError.new(message, retryable: true)` marks a specific instance as retryable. When a tool raises inside `Tool#call`, RobotLab appends `" (retryable)"` to the formatted error text returned to the LLM whenever `RobotLab::Errors.retryable?(error)` is true, so the model itself can see that another attempt is worth trying.
+Unlike the generic `StandardError` path, the `ToolError` path writes **nothing**
+to the logger. See [Tool#call](core/tool.md#call).
 
 ---
 
 ## RobotLab::BudgetExceeded
 
-Raised when a Robot's configured `token_budget` or `cost_budget` is already exhausted **before** an LLM call is attempted (see [Budgets](../guides/observability.md#budgets-token--cost) and `RobotLab::Budget::Ledger`). This is distinct from the pre-existing `InferenceError` "Token budget exceeded" message, which covers a call that *completed* but pushed cumulative usage over budget — `BudgetExceeded` means the call was refused outright, before any tokens were spent.
+Raised when a Robot's configured `token_budget` or `cost_budget` is already exhausted **before** an LLM call is attempted (see [Budgets](../guides/observability.md#budgets-token-cost) and `RobotLab::Budget::Ledger`). This is distinct from the pre-existing `InferenceError` "Token budget exceeded" message, which covers a call that *completed* but pushed cumulative usage over budget — `BudgetExceeded` means the call was refused outright, before any tokens were spent.
 
 ```ruby
 robot = RobotLab.build(name: "capped", system_prompt: "...", cost_budget: 0.50)
@@ -181,6 +242,38 @@ rescue RobotLab::BudgetExceeded => e
 end
 ```
 
+Raised by `Budget::Ledger#reserve!`; the message format is
+`"budget exceeded for <dimension>: <committed + amount> > <limit>"` where
+`<dimension>` is `tokens` or `cost`.
+
+The post-call `InferenceError` messages are formatted differently:
+
+| Dimension | Message |
+|-----------|---------|
+| `token_budget` | `Token budget exceeded: <N> tokens used, budget is <M>` |
+| `cost_budget` | `Cost budget exceeded: $0.523100 used, budget is $0.500000` (both values via `%.6f`) |
+
+---
+
+## RobotLab::AwaitTimeout
+
+Raised by [`Memory#get`](core/memory.md#get) when a blocking read
+(`wait: true` or `wait: <seconds>`) expires before the key is written.
+
+```ruby
+begin
+  memory.get(:sentiment, wait: 30)
+rescue RobotLab::AwaitTimeout => e
+  puts e.message  # "Timeout waiting for :sentiment after 30 seconds"
+end
+```
+
+With multiple keys the timeout is applied **per missing key**, so
+`get(:a, :b, wait: 30)` can block for up to 60 seconds before raising.
+
+Not retryable per `RobotLab::Errors.retryable?` — it falls into the
+"everything else" bucket.
+
 ---
 
 ## Retryable Errors
@@ -192,7 +285,7 @@ end
 | `InferenceError` (and subclasses, except `ToolLoopError`) | Always |
 | `ToolLoopError` | Never — it's a circuit breaker; retrying immediately re-triggers the same loop |
 | `MCPError` / `ToolError` | Only when raised with `retryable: true` at the raise site |
-| Everything else (`ConfigurationError`, `ToolNotFoundError`, `DependencyError`, `RactorBoundaryError`, `BusError`, `BudgetExceeded`, non-RobotLab errors) | Never |
+| Everything else (`ConfigurationError`, `ToolNotFoundError`, `DependencyError`, `RactorBoundaryError`, `BusError`, `BudgetExceeded`, `AwaitTimeout`, `DelegationTimeout`, non-RobotLab errors) | Never |
 
 ```ruby
 begin

data/docs/api/hooks.md

@@ -0,0 +1,469 @@
+# Hooks API
+
+Class-level reference for the hook system. For the conceptual walkthrough —
+families, firing order, registration levels, and worked examples — see the
+[Hook System guide](../guides/hooks.md). This page documents the public methods
+of the classes that implement it.
+
+```mermaid
+classDiagram
+    class Hook {
+        <<abstract>>
+        +namespace() Symbol
+        +call(hook_name, ctx, block) Object
+    }
+
+    class HookRegistry {
+        +on(handler_class, context) Registration
+        +registrations_for(hook_name) Array
+        +registrations() Array
+        +clear() Array
+    }
+
+    class Registration {
+        <<Data>>
+        +handler_class Class
+        +context Hash
+        +namespace() Symbol
+    }
+
+    class Hooks {
+        <<module>>
+        +run(family, ctx, registries, per_run_hooks) Object
+        +call(hook_name, ctx, registries, per_run_hooks) void
+        +around(hook_name, ctx, registries, per_run_hooks) Object
+    }
+
+    class HookContext {
+        +event Symbol
+        +metadata ExtensionState
+        +ext(name) DotState
+        +local() DotState
+        +with_namespace(ns) Object
+        +to_h() Hash
+    }
+
+    HookContext <|-- RunHookContext
+    RunHookContext <|-- LlmGenerationHookContext
+    HookContext <|-- ToolCallHookContext
+    HookContext <|-- NetworkRunHookContext
+    HookContext <|-- TaskHookContext
+    HookContext <|-- LearnHookContext
+    HookContext <|-- CompactionHookContext
+
+    HookRegistry --> Registration : builds
+    Hooks --> HookRegistry : reads
+    Hooks --> HookContext : namespaces
+    Hook <|-- Narrator
+```
+
+---
+
+## RobotLab::Hook
+
+Base class for hook handlers. Subclasses implement hook methods as **class**
+methods; any method a subclass does not define is silently skipped when that hook
+fires.
+
+### namespace / namespace=
+
+```ruby
+class TimerHook < RobotLab::Hook; end
+TimerHook.namespace          # => :timer_hook
+
+class Tracer < RobotLab::Hook
+  self.namespace = :trace
+end
+Tracer.namespace             # => :trace
+
+RobotLab::Hook.namespace     # => nil (the base class has none)
+```
+
+The namespace isolates a handler's `ctx.local` scratchpad from every other
+handler. It defaults to the snake_case form of the **last** segment of the class
+name, so `MyExt::Tracer` becomes `:tracer`. `HookRegistry#on` raises
+`ArgumentError` when `namespace` is `nil`, which is why the base `Hook` class
+itself can never be registered.
+
+`inherited` resets `@namespace` to `nil` on each subclass, so a namespace set on
+a parent handler is **not** inherited by its subclasses — each re-derives its own.
+
+### call
+
+```ruby
+HandlerClass.call(hook_name, context)            # point / before / after hook
+HandlerClass.call(hook_name, context) { ... }    # around hook
+```
+
+Dispatch one hook to this handler. This is the method `Hooks.call_registration`
+invokes; you rarely call it directly.
+
+| Case | Behavior |
+|------|----------|
+| Handler defines `hook_name` | Called with `context` (and the block, for around hooks) |
+| Handler does not define it, block given | The block is called directly — **around passthrough**, so the chain never breaks |
+| Handler does not define it, no block | Silent no-op |
+
+The check is `singleton_class.public_method_defined?(hook_name)`, so a hook
+defined as a *private* class method never fires.
+
+---
+
+## RobotLab::HookRegistry
+
+The store behind `RobotLab.hooks`, `network.hooks`, and `robot.hooks`. Each of
+those three is a separate instance; a run consults all three.
+
+### on
+
+```ruby
+registration = registry.on(HandlerClass, context: nil)
+# => RobotLab::HookRegistry::Registration
+```
+
+Register a handler class.
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `handler_class` | `Class` | **required** | Must be a subclass of `RobotLab::Hook` |
+| `context` | `Hash`, `nil` | `nil` | Defaults merged into the handler's `ctx.local` before each callback (via `DotState#merge_defaults`, so an already-set key is not overwritten) |
+
+**Raises `ArgumentError`** when `handler_class` is not a `RobotLab::Hook`
+subclass, or when its `namespace` is `nil`.
+
+`RobotLab.on`, `network.on`, and `robot.on` are thin delegators to this method.
+
+### registrations_for
+
+```ruby
+registry.registrations_for(:before_run)  # => Array<Registration>
+```
+
+Only the registrations whose handler class actually implements `hook_name`. This
+is the filter that makes an unimplemented hook a no-op rather than an error, and
+it is what `Hooks.registrations` calls on each registry.
+
+### registrations
+
+```ruby
+registry.registrations  # => Array<Registration>
+```
+
+Every registration, as a defensive copy (`@registrations.dup`) — mutating the
+returned array does not affect the registry.
+
+Used by `Network#ractor_hook_classes_for` to collect the handler classes that
+must cross a Ractor boundary under `parallel_mode: :ractor`.
+
+### clear
+
+```ruby
+registry.clear  # => the emptied internal array
+```
+
+Remove every registration **in place**. Note the difference from
+`RobotLab.clear_hooks!`, which replaces the global registry object entirely
+rather than emptying it.
+
+### HookRegistry::Registration
+
+A `Data` value object pairing a handler with its optional context.
+
+| Member / method | Type | Description |
+|-----------------|------|-------------|
+| `handler_class` | `Class` | The `RobotLab::Hook` subclass |
+| `context` | `Hash`, `nil` | Per-registration defaults (defaults to `nil`) |
+| `namespace` | `Symbol` | Delegates to `handler_class.namespace` |
+
+---
+
+## RobotLab::Hooks
+
+The dispatcher (`module_function`, so every method is called as
+`RobotLab::Hooks.foo`). Core calls into it; extension authors normally write
+handler classes instead. It is documented here because a host that drives
+RobotLab objects directly — or an extension that adds its own hook family — needs
+the contract.
+
+### run
+
+```ruby
+RobotLab::Hooks.run(family, context, registries:, per_run_hooks: nil) { core_work }
+# => the block's return value
+```
+
+Execute a full hook family around a block. In order: every `before_<family>`,
+then the `around_<family>` chain wrapping the block, then
+[`set_result`](#set_result), then every `after_<family>`.
+
+| Name | Type | Description |
+|------|------|-------------|
+| `family` | `Symbol` | `:run`, `:llm_generation`, `:tool_call`, `:network_run`, `:task`, `:compaction`, `:learn` |
+| `context` | `HookContext` | The family's context object |
+| `registries` | `Array<HookRegistry, nil>` | Consulted in order; `nil` entries are compacted away |
+| `per_run_hooks` | `Class`, `Array<Class>`, `nil` | Handler classes active only for this call (`robot.run(..., hooks:)`) |
+
+**Error path:** `run` rescues `Exception` (not just `StandardError`, so
+`Timeout::Error` and `SignalException` are covered), assigns it to
+`context.error` when the context has an `error=` writer, fires `on_error`, and
+**re-raises**. Hooks never swallow an exception.
+
+### call
+
+```ruby
+RobotLab::Hooks.call(hook_name, context, registries:, per_run_hooks: nil)
+```
+
+Fire one non-around hook across all matching registrations. This is how the point
+hooks `:on_compaction` and `:on_learn` are dispatched from inside the core block
+of their family — which is why they do not compose with `around_*` handlers and
+have no chainable result.
+
+### around
+
+```ruby
+RobotLab::Hooks.around(hook_name, context, registries:, per_run_hooks: nil) { ... }
+```
+
+Build and invoke just the around chain for one hook name, without the
+before/after phases.
+
+### registrations
+
+```ruby
+RobotLab::Hooks.registrations(hook_name, registries, per_run_hooks)
+# => Array<Registration>
+```
+
+The complete ordered list for one hook name: each registry's
+`registrations_for(hook_name)` concatenated in registry order, followed by the
+per-run entries. This ordering is what produces **global → network → robot →
+per-run** execution.
+
+### error_registrations
+
+```ruby
+RobotLab::Hooks.error_registrations(family, registries, per_run_hooks)
+# => Array<Registration>
+```
+
+`on_error` registrations, but **only** for the `:run`, `:network_run`, and
+`:task` families — every other family returns `[]`. This is the mechanism behind
+the guide's statement that `:llm_generation`, `:tool_call`, `:compaction`, and
+`:learn` have no `on_error` variant.
+
+### call_all
+
+```ruby
+RobotLab::Hooks.call_all(registrations, hook_name, context)
+```
+
+Invoke each registration in order for a non-around hook.
+
+### call_around
+
+```ruby
+RobotLab::Hooks.call_around(registrations, hook_name, context) { core_work }
+```
+
+Fold the registrations into a nested chain and call it. The list is `reverse`d
+before folding, so the **first** registration ends up outermost — a global
+`around_run` wraps a robot-level one, not the other way round. A handler that
+does not implement the hook passes the block straight through.
+
+### call_registration
+
+```ruby
+RobotLab::Hooks.call_registration(registration, hook_name, context, &block)
+```
+
+Invoke one registration with its namespace active. It wraps the call in
+`context.with_namespace(registration.namespace)` and, when the registration
+carries a `context:` hash, merges those values into
+`context.ext(namespace)` as defaults first. This is what makes `ctx.local`
+resolve to the *calling handler's* private `DotState`.
+
+### per_run_entries
+
+```ruby
+RobotLab::Hooks.per_run_entries(hook_name, hooks)
+# => Array<Registration>
+```
+
+Turn `robot.run(msg, hooks: HandlerClass)` or `hooks: [A, B]` into
+`Registration`s, skipping any class that does not implement `hook_name`. Per-run
+registrations carry no `context:`.
+
+### set_result
+
+```ruby
+RobotLab::Hooks.set_result(context, family, result)
+```
+
+Publish a family's return value onto its context so `after_*` handlers can read
+it. The mapping is fixed:
+
+| Family | Assigned to |
+|--------|-------------|
+| `:run` | `context.response` |
+| `:network_run`, `:task` | `context.result` |
+| `:llm_generation` | `context.generation_response` |
+| `:tool_call`, `:compaction`, `:learn` | *(nothing — those contexts carry their result in a family-specific accessor set by the core block)* |
+
+Each assignment is guarded by `respond_to?`, so a custom context lacking the
+writer is simply skipped.
+
+---
+
+## RobotLab::HookContext
+
+Base class for every hook context. The family-specific subclasses below add the
+accessors a handler actually reads.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `event` | `Symbol` | The family (`:run`, `:tool_call`, …), symbolized at construction |
+| `metadata` | `ExtensionState` | The per-run namespace store; defaults to a fresh `ExtensionState` |
+| `ext(name)` | `DotState` | Another handler's namespaced state — `ctx.ext(:timer).start_time` |
+| `local` | `DotState` | **This** handler's state. Raises `ArgumentError: No hook namespace active` outside a `with_namespace` block |
+| `with_namespace(ns) { \|ctx\| }` | block's value | Sets the active namespace for the duration of the block and restores the previous one in an `ensure`. Called by `Hooks.call_registration` |
+| `to_h` | `Hash` | Snapshot of every public reader (excluding `to_h` and `local`) plus `metadata: metadata.to_h` |
+
+!!! warning "`ctx.local` lives for exactly one run"
+    `metadata` is a fresh `ExtensionState` per `HookContext`, and a new context is
+    built per run. Use a class-level accessor on the handler for cross-run state.
+
+### Context subclasses
+
+Readers are read-only unless marked **rw**.
+
+#### RunHookContext (`event: :run`)
+
+| Accessor | | Description |
+|----------|--|-------------|
+| `robot` | | The robot being run |
+| `network` | | Owning `Network`, or `nil` when standalone |
+| `task` | | The `Task` wrapper, when run from a pipeline |
+| `memory` | | The resolved run memory |
+| `config` | | The robot's effective `RunConfig` |
+| `request` | rw | The user message. **Writable** — assign in `before_run` to rewrite the prompt |
+| `response` | rw | The `RobotResult`; set by `Hooks.set_result` before `after_run` |
+| `error` | rw | Set by `Hooks.run` before `on_error` |
+
+#### LlmGenerationHookContext (`event: :run`) — subclass of `RunHookContext`
+
+Adds `iteration` (Integer, defaults to `0`) and `generation_response` (**rw**,
+set by `set_result`). Note it inherits `event: :run` from its parent; the family
+name comes from the hook method names, not from `event`.
+
+#### ToolCallHookContext (`event: :tool_call`)
+
+| Accessor | | Description |
+|----------|--|-------------|
+| `tool` | | The tool instance |
+| `tool_name` | | `tool.name`, falling back to `tool.class.name` |
+| `tool_args` | | Arguments the LLM supplied |
+| `robot` | | Owning robot, or `nil` |
+| `tool_result` | rw | The result. Assign it in `around_tool_call` **without** calling the block to block a tool |
+| `tool_error` | rw | Set by `Tool#call` when `execute` raised |
+
+#### NetworkRunHookContext (`event: :network_run`)
+
+`network`, `memory`, `config`; **rw**: `context` (the run params hash), `result`, `error`.
+
+#### TaskHookContext (`event: :task`)
+
+`network`, `task`, `task_name` (`task.name`), `robot` (falls back to
+`task.robot`), `memory`, `config`; **rw**: `result`, `error`.
+
+#### LearnHookContext (`event: :learn`)
+
+| Accessor | | Description |
+|----------|--|-------------|
+| `robot` | | The robot learning |
+| `text` | | The stripped learning text |
+| `learnings_before` | | Frozen copy of `robot.learnings` prior to the write |
+| `stored` | rw | Set `true` by core when the learning was actually appended (i.e. not deduplicated away) |
+| `error` | rw | |
+
+#### CompactionHookContext (`event: :compaction`)
+
+| Accessor | | Description |
+|----------|--|-------------|
+| `robot` | | |
+| `messages_before` | | Frozen copy of `chat.messages` before compaction |
+| `config` | | The effective `RunConfig` |
+| `strategy` | | `:context_window`, or `:custom` when `auto_compact` is a `Proc` |
+| `compacted_messages` | rw | Assign in `on_compaction` to **replace** the core algorithm |
+| `error` | rw | |
+| `handled?` | | `!compacted_messages.nil?` — core skips its own compaction when true |
+
+---
+
+## ExtensionState and DotState
+
+The two-level store behind `ctx.local` / `ctx.ext`.
+
+### ExtensionState
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `ext(name)` | `DotState` | The `DotState` for a namespace, auto-created on first access |
+| `to_h` | `Hash` | `{ namespace => state_hash }` for every namespace touched |
+
+### DotState
+
+A schemaless dot-access bag.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `method_missing` | value / assigned value | `state.foo` reads, `state.foo = 1` writes. Any key is allowed |
+| `merge_defaults(hash)` | `self` | Writes each pair **only when the key is absent** — this is how a registration's `context:` becomes defaults rather than an override |
+| `to_h` | `Hash` | A `dup` of the backing hash |
+
+!!! warning "`DotState#respond_to_missing?` always returns true"
+    `state.respond_to?(:anything)` is `true`, and reading a key that was never
+    set returns `nil` instead of raising `NoMethodError`. A typo in a `ctx.local`
+    reader fails silently.
+
+---
+
+## Module-level hook methods
+
+```ruby
+RobotLab.hooks                     # => the global HookRegistry (memoized)
+RobotLab.on(HandlerClass, context: nil)
+RobotLab.clear_hooks!              # => replaces the global registry with a new one
+```
+
+`clear_hooks!` swaps in a brand-new `HookRegistry`; any `Registration` object you
+held from before is orphaned. Use it in test teardown to avoid leaking handlers
+between examples.
+
+### with_hook_scope / current_hook_scope
+
+```ruby
+RobotLab.with_hook_scope(registries, per_run_hooks) { ... }
+RobotLab.current_hook_scope   # => { registries: [...], per_run_hooks: ... } or nil
+```
+
+Publishes the active run's registries and per-run handlers in a
+`Thread.current` slot for the duration of the block, restoring the previous value
+in an `ensure`. `Robot::Hooking#run` opens the scope; `Tool#call` reads it so a
+tool invoked deep inside RubyLLM's tool loop still resolves the same registries
+(including the network's and any `hooks:` passed to that one `run`) instead of
+falling back to `[RobotLab.hooks, robot.hooks]`.
+
+!!! note "Thread-local, so it does not cross a thread boundary"
+    A tool that executes on another thread — or a `delegate(async: true)` target —
+    sees `current_hook_scope == nil` and falls back to the global + robot
+    registries. Network-scoped and per-run hooks will not fire for it.
+
+---
+
+## See Also
+
+- [Hook System guide](../guides/hooks.md) — families, ordering, and applied patterns
+- [Observability & Safety](../guides/observability.md) — `Narrator`, budgets, doom-loop detection
+- [Support API](support.md) — `Narrator`, the one `Hook` subclass shipped in core
+- [Robot: on](core/robot.md#on) · [Network: on](core/network.md#on)