riffer 0.28.0 → 0.29.0

data/docs/04_AGENT_LIFECYCLE.md

@@ -1,69 +1,64 @@
 # Agent Lifecycle
 
-## Instance Methods
+## Construction
 
-### generate
+### Agent.new
 
-Generates a response synchronously. Returns a `Riffer::Agent::Response` object.
+```ruby
+Agent.new(session: nil, context: nil)
+```
+
+- **`session:`** — an existing `Riffer::Agent::Session`. When given, the agent uses it as-is (no system/skills seeding). Typical use case: cross-process resume from persisted history. With `Riffer.config.experimental_history_healing` on, a provided session is healed at construction time so the `tool_use` ↔ `tool_result` invariant holds before the next inference call.
+- **`context:`** — a `Hash` carried for the lifetime of the agent. Used to evaluate Proc-based `instructions`, `model`, `uses_tools`, and skill activation at construction time, and threaded through tool execution and guardrails on every `generate`/`stream` call.
 
-The behavior depends on what you pass and the agent's current state:
+When `session:` is omitted, the agent constructs a fresh session and seeds it with `[instruction_message, skills_message].compact` eagerly. To swap context, construct a new agent — context is fixed for the lifetime of an agent instance.
+
+## Instance Methods
 
-| Input      | Agent state                    | Behavior                                                                                                                                                              |
-| ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **String** | No prior messages              | **New conversation.** Builds system messages (instructions + skills), adds user message, calls the LLM.                                                               |
-| **String** | Has messages from a prior call | **Continue conversation.** Appends the user message to the existing history and re-enters the LLM loop. Pending tool calls from a prior interrupt are executed first. |
-| **Array**  | No prior messages              | **Restore from persisted data.** Uses the array as-is (no system messages added). Pending tool calls are executed. This is for cross-process resume.                  |
-| **Array**  | Has messages from a prior call | **Raises `Riffer::ArgumentError`.** Use a string to continue, or a new agent instance to start from a persisted array.                                                |
+### generate
 
-**State reset per call:** Each call to `generate` or `stream` resets `context`, tools, tool runtime, model, skills state, and the interrupted flag. This means `context:` must be passed on every call — it is not carried over from a previous call. The only state that persists across calls is the message history and cumulative `token_usage`.
+Generates a response synchronously. Returns a `Riffer::Agent::Response` object.
 
 ```ruby
-agent.generate('Hello', context: {user_id: 123})
-agent.generate('Follow up')  # context is nil here — pass it again if needed
-agent.generate('More', context: {user_id: 123})  # context is restored
+agent.generate(prompt = nil, files: nil)
 ```
 
+- **`prompt`** — when given, a new `Riffer::Messages::User` is silently appended to the session (no `on_message` callbacks fire for user inputs) and the inference loop runs.
+- **`prompt` omitted** — the loop runs against the current session. Useful when the seeded session's last turn is already a user message, or when picking up pending tool calls from a prior interrupt.
+- **`files:`** — requires `prompt`. Attached to the new user message.
+
 ```ruby
 # New conversation (class method — recommended for simple calls)
-response = MyAgent.generate('Hello')
+response = MyAgent.generate('Hello', context: {user_id: 123})
 puts response.content       # Access the response text
 puts response.blocked?      # Check if guardrail blocked (always false without guardrails)
 puts response.interrupted?  # Check if a callback interrupted the loop
 
 # New conversation (instance method — when you need message history or callbacks)
-agent = MyAgent.new
-agent.on_message { |msg| log(msg) }
+agent = MyAgent.new(context: {user_id: 123})
+agent.session.on_message { |msg| log(msg) }
 response = agent.generate('Hello')
-agent.messages  # Access message history
+agent.session.messages  # Access message history
 
 # Multi-turn conversation
 agent = MyAgent.new
 agent.generate('Hello')
 agent.generate('Tell me more')   # continues with full history
 
-# Restore from persisted messages (cross-process resume)
-agent = MyAgent.new
-response = agent.generate(persisted_messages, context: {user_id: 123})
-
-# With context
-response = MyAgent.generate('Look up my orders', context: {user_id: 123})
+# Resume from persisted messages (cross-process)
+session = Riffer::Agent::Session.new(messages: persisted_messages)
+agent = MyAgent.new(session: session, context: {user_id: 123})
+response = agent.generate  # no prompt — session already has the last user message
 
-# With files (string prompt + files shorthand)
+# With files
 response = MyAgent.generate('What is in this image?', files: [
   {data: base64_data, media_type: 'image/jpeg'}
 ])
-
-# With files in messages array (per-message)
-response = MyAgent.generate([
-  {role: 'user', content: 'Describe this document', files: [
-    {url: 'https://example.com/report.pdf', media_type: 'application/pdf'}
-  ]}
-])
 ```
 
 ### stream
 
-Streams a response as an Enumerator. Follows the same input rules as `generate` — a string starts a new conversation or continues an existing one, an array restores from persisted data.
+Streams a response as an Enumerator. Same prompt/files semantics as `generate`.
 
 ```ruby
 # New conversation (class method — recommended for simple calls)
@@ -80,9 +75,9 @@ end
 
 # New conversation (instance method — when you need message history or callbacks)
 agent = MyAgent.new
-agent.on_message { |msg| persist_message(msg) }
+agent.session.on_message { |msg| persist_message(msg) }
 agent.stream('Tell me a story').each { |event| handle(event) }
-agent.messages  # Access message history
+agent.session.messages  # Access message history
 
 # Multi-turn conversation
 agent = MyAgent.new
@@ -95,7 +90,9 @@ MyAgent.stream('What is in this image?', files: [{data: base64_data, media_type:
 end
 ```
 
-### messages
+### session
+
+Conversation state lives on `agent.session` — a `Riffer::Agent::Session` instance that owns the message array, the `on_message` callback list, and the `tool_use` ↔ `tool_result` invariant. The methods below are all on the session, not on the agent itself.
 
 Access the message history after a generate/stream call:
 
@@ -103,17 +100,24 @@ Access the message history after a generate/stream call:
 agent = MyAgent.new
 agent.generate('Hello')
 
-agent.messages.each do |msg|
+agent.session.messages.each do |msg|
   puts "#{msg.role}: #{msg.content}"
 end
 ```
 
+`Riffer::Agent::Session` includes `Enumerable`, so `find`, `select`, `count`, `reverse_each` all work directly on the session:
+
+```ruby
+agent.session.find { |m| m.id == 'a_1' }
+agent.session.count { |m| m.is_a?(Riffer::Messages::Assistant) }
+```
+
 ### on_message
 
 Registers a callback to receive messages as they're added during generation:
 
 ```ruby
-agent.on_message do |message|
+agent.session.on_message do |message|
   case message.role
   when :assistant
     puts "[Assistant] #{message.content}"
@@ -126,10 +130,10 @@ end
 Multiple callbacks can be registered. Returns `self` for method chaining:
 
 ```ruby
-agent
+agent.session
   .on_message { |msg| persist_message(msg) }
   .on_message { |msg| log_message(msg) }
-  .generate('Hello')
+agent.generate('Hello')
 ```
 
 Works with both `generate` and `stream`. Only emits agent-generated messages (Assistant, Tool), not inputs (System, User).
@@ -144,7 +148,7 @@ An optional reason can be passed to `interrupt!`. It is available via `interrupt
 
 ```ruby
 agent = MyAgent.new
-agent.on_message do |msg|
+agent.session.on_message do |msg|
   if msg.is_a?(Riffer::Messages::Tool)
     agent.interrupt!("needs human approval")
   end
@@ -160,7 +164,7 @@ response.content           # => last assistant content before interrupt
 
 ```ruby
 agent = MyAgent.new
-agent.on_message { |msg| throw :riffer_interrupt, "budget exceeded" }
+agent.session.on_message { |msg| throw :riffer_interrupt, "budget exceeded" }
 
 agent.stream('Hello').each do |event|
   case event
@@ -176,53 +180,51 @@ end
 
 There are two ways to resume after an interrupt, depending on whether the agent is still in memory or you're restoring from persisted data.
 
-**In-memory resume** — call `generate` (or `stream`) again with a string. The agent keeps its message history, so a new string appends a user message and continues the loop. Pending tool calls from the interrupt are automatically executed first.
+**In-memory resume** — call `generate` (or `stream`) again. With a prompt, the new user message is appended and the loop runs. Without a prompt, the loop runs against the current session — useful for picking up pending tool calls after the user has approved.
 
 ```ruby
-agent = MyAgent.new
-agent.on_message { |msg| throw :riffer_interrupt if needs_approval?(msg) }
+agent = MyAgent.new(context: {user_id: 123})
+agent.session.on_message { |msg| throw :riffer_interrupt if needs_approval?(msg) }
 
 response = agent.generate('Do something risky')
 
 if response.interrupted?
-  approve_action(agent.messages)
+  approve_action(agent.session.messages)
   response = agent.generate('Approved, go ahead')  # executes pending tools, then calls the LLM
+  # or: agent.generate                              # resume without a new turn
 end
 ```
 
-You can also resume without adding a new user message by passing a continuation like `'Continue'` — the LLM will pick up from the existing context.
-
-**Cross-process resume** — when the agent is gone (process restart, async approval, etc.), create a new agent and pass the persisted messages as an array. Array input uses messages as-is (no system messages added) and executes any pending tool calls.
+**Cross-process resume** — when the agent is gone (process restart, async approval, etc.), construct a `Riffer::Agent::Session` from the persisted messages and pass it to a new agent. The agent uses the session as-is (no system messages added). Pending tool calls on the resume boundary are executed on the next `generate`/`stream`.
 
 ```ruby
-# During generation, persist messages via on_message callback
+# During generation, persist each new message via on_message
 # Later, in a new process:
-agent = MyAgent.new
-response = agent.generate(persisted_messages, context: {user_id: 123})
+session = Riffer::Agent::Session.new(messages: persisted_messages)
+agent = MyAgent.new(session: session, context: {user_id: 123})
+response = agent.generate  # session already has the last user turn
 
 # Or resume in streaming mode:
-agent = MyAgent.new
-agent.stream(persisted_messages).each do |event|
+agent = MyAgent.new(session: session, context: {user_id: 123})
+agent.stream.each do |event|
   # handle stream events
 end
 ```
 
-**Important:** You cannot pass an array to an agent that already has messages. This raises `Riffer::ArgumentError` because it would silently discard the existing history. Use a string to continue, or create a new agent instance for cross-process resume.
-
-### Building System Messages for Persistence
+### Reading System Messages for Persistence
 
-Use `generate_instruction_message` and `generate_skills_message` to generate system messages independently. This is useful for database persistence workflows where you need to store and later reconstruct message histories.
+Read the agent's instruction and skills system messages from `agent.instruction_message` and `agent.skills_message`. Both are built once at `Agent.new` time using the constructor `context:` and cached — they reflect the agent's configured `instructions` and `skills` DSL output. Useful for database persistence workflows where you need to store and later reconstruct message histories.
 
-Both methods return a `Riffer::Messages::System` or `nil` (when unconfigured). They accept an optional `context:` keyword, just like `generate`.
+Both return `Riffer::Messages::System` or `nil` (when unconfigured / empty).
 
 ```ruby
-agent = MyAgent.new
-sys = agent.generate_instruction_message(context: ctx)     # => Riffer::Messages::System or nil
-skills = agent.generate_skills_message(context: ctx)        # => Riffer::Messages::System or nil
+agent = MyAgent.new(context: ctx)
+sys = agent.instruction_message     # => Riffer::Messages::System or nil
+skills = agent.skills_message       # => Riffer::Messages::System or nil
 
 # Store in DB, then later resume in a new process:
-messages = [sys, skills, user_msg].compact
-MyAgent.new.generate(messages, context: ctx)
+session = Riffer::Agent::Session.new(messages: [sys, skills, user_msg].compact)
+MyAgent.new(session: session, context: ctx).generate
 ```
 
 ### interrupt!
@@ -230,7 +232,7 @@ MyAgent.new.generate(messages, context: ctx)
 Interrupts the agent loop from an `on_message` callback. Equivalent to `throw :riffer_interrupt, reason`:
 
 ```ruby
-agent.on_message do |msg|
+agent.session.on_message do |msg|
   agent.interrupt!(:needs_approval) if requires_approval?(msg)
 end
 ```
@@ -244,7 +246,7 @@ When the interrupt represents a course-change rather than a pause — e.g. a voi
 ```ruby
 Riffer.configure { |c| c.experimental_history_healing = true }
 
-agent.on_message do |msg|
+agent.session.on_message do |msg|
   agent.interrupt!(:user_interrupt) if msg.is_a?(Riffer::Messages::Assistant) && barge_in?
 end
 
@@ -256,48 +258,47 @@ The placeholder content is fixed: `"Tool call interrupted before completion."` w
 
 Healing covers all interrupts uniformly — caller-issued `interrupt!` and the built-in `INTERRUPT_MAX_STEPS` ceiling alike. When the flag is off (the default), orphans remain in history and `execute_pending_tool_calls` re-runs them on the next `generate` call.
 
-If you need finer control over placeholder content (per-call shape, structured metadata, etc.), use the `replace_tool_result` mutator below to upgrade a placeholder after the interrupt returns.
+If you need finer control over placeholder content (per-call shape, structured metadata, etc.), use the `update` mutator below to upgrade a placeholder after the interrupt returns.
 
 ### Mutating history
 
-The agent exposes a small set of in-place mutators that enforce the `tool_use` ↔ `tool_result` invariant on every operation. Use these to align the agent's history with external state (persisted transcript, partial output that wasn't actually delivered, etc.) without rebuilding the agent.
+The session exposes a small set of in-place mutators that enforce the `tool_use` ↔ `tool_result` invariant on every operation. Use these to align history with external state (persisted transcript, partial output that wasn't actually delivered, etc.) without rebuilding the agent.
 
-- **`agent.replace_assistant_content(id:, content:)`** — In-place truncation/edit. Preserves `tool_calls`, `token_usage`, and `id`. Empty `content` delegates to `remove_message`.
-- **`agent.remove_message(id:)`** — Removes a message; cascades to its `Tool` children when the target carries `tool_calls`. Raises if called on a `Tool` (use `replace_tool_result`).
-- **`agent.replace_tool_result(tool_call_id:, content:, error:, error_type:)`** — Replace a tool result in place, preserving `name` and `id`. Use this to upgrade an interrupt-time placeholder once the real result is available.
+- **`agent.session.update(id:, **attrs)`** — In-place partial update. Looks up by message `id:`; builds a replacement of the same type with `attrs` overlaid on the existing fields. Use this to edit assistant content (`update(id:, content:)`), restate a system message, etc. When the target is an assistant and the update drops entries from `tool_calls`, matching `Tool` children are removed atomically.
+- **`agent.session.update(tool_call_id:, **attrs)`** — Same as above but looks up the tool result by `tool_call_id:`. Preserves `name` and `id`. Use this to upgrade an interrupt-time placeholder once the real result is available (`update(tool_call_id:, content:, error: nil, error_type: nil)`).
+- **`agent.session.remove(id:)`** — Removes a message; cascades to its `Tool` children when the target carries `tool_calls`. Raises if called on a `Tool` message (use `update(tool_call_id:, ...)` to rewrite a tool result instead).
 
 Bulk filling of orphan `tool_use` blocks is handled by `Riffer.config.experimental_history_healing` (see "Healing pending tool results on interrupt" above) — there is no public synthesizer hook.
 
-Read accessors that pair with the mutators:
+Lookup patterns that pair with the mutators (via `Enumerable`):
 
 ```ruby
-agent.message_by_id(id)           # => Riffer::Messages::Base or nil
-agent.tool_message_for(call_id)   # => Riffer::Messages::Tool or nil
-agent.last_assistant              # => Riffer::Messages::Assistant or nil
-agent.orphaned_tool_call_ids      # => Array[String]   (zero-cost validation)
+agent.session.find { |m| m.id == id }                                           # message by id
+agent.session.reverse_each.find { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == call_id }
+agent.session.reverse_each.find { |m| m.is_a?(Riffer::Messages::Assistant) }    # last assistant
+agent.session.orphaned_tool_call_ids                                            # Array[String], zero-cost validation
 ```
 
 Mutating history while a `stream` enumerator is being consumed is undefined; mutators are intended for use between turns.
 
 Mutators do **not** fire `on_message` — that callback is reserved for messages produced by inference (LLM responses, tool execution results). Healing placeholders bypass `on_message` for the same reason; consumers learn that healing happened via `Response#healed_tool_call_ids` (and `StreamEvents::Interrupt#healed_tool_call_ids`).
 
-### token_usage
+### context
+
+The mutable runtime context. A `Hash` threaded into every Proc-based DSL setting, guardrail, tool runtime, and skills resolution, and shared with every `Riffer::Agent::Run` this agent executes. Carries:
 
-Access cumulative token usage across all LLM calls:
+- `context[:skills]` — the resolved `Riffer::Skills::Context` when skills are configured.
+- `context[:token_usage]` — the cumulative `Riffer::Providers::TokenUsage`, mutated by each Run as the loop progresses.
+- any caller-provided keys passed via `Agent.new(context: ...)`.
 
 ```ruby
 agent = MyAgent.new
 agent.generate("Hello!")
 
-if agent.token_usage
-  puts "Total tokens: #{agent.token_usage.total_tokens}"
-  puts "Input: #{agent.token_usage.input_tokens}"
-  puts "Output: #{agent.token_usage.output_tokens}"
-end
+agent.context[:token_usage]   # cumulative TokenUsage across all calls
+agent.context[:skills]        # the Skills::Context, if skills configured
 ```
 
-Returns `nil` if the provider doesn't report usage, or a `Riffer::TokenUsage` object with accumulated totals.
-
 ## Response Attributes
 
 `Riffer::Agent::Response` is returned by `generate`:
@@ -333,7 +334,7 @@ The assistant message in the message history stores the parsed hash, so you can
 agent = SentimentAgent.new
 agent.generate('Analyze: "I love this!"')
 
-msg = agent.messages.last
+msg = agent.session.messages.last
 msg.structured_output?    # => true
 msg.structured_output     # => {sentiment: "positive", score: 0.95}
 ```

data/docs/05_AGENT_LOOP.md

@@ -5,7 +5,7 @@
 When an agent receives a response with tool calls:
 
 1. Agent detects `tool_calls` in the assistant message
-2. The configured tool runtime executes the tool calls (sequentially by default, or concurrently with `Riffer::ToolRuntime::Threaded`):
+2. The configured tool runtime executes the tool calls (sequentially by default, or concurrently with `Riffer::Tools::Runtime::Threaded`):
    - Finds the matching tool class
    - Validates arguments against the tool's parameter schema
    - Calls the tool's `call` method with `context` and arguments
@@ -58,7 +58,7 @@ Callbacks registered with `on_message` can call `agent.interrupt!` (or `throw :r
 
 ```ruby
 agent = MyAgent.new
-agent.on_message do |msg|
+agent.session.on_message do |msg|
   agent.interrupt!("approval needed") if requires_approval?(msg)
 end
 

data/docs/06_TOOLS.md

@@ -108,12 +108,12 @@ Options:
 | `String`                   | `string`         |
 | `Integer`                  | `integer`        |
 | `Float`                    | `number`         |
-| `Riffer::Boolean`          | `boolean`        |
+| `Riffer::Params::Boolean`          | `boolean`        |
 | `TrueClass` / `FalseClass` | `boolean`        |
 | `Array`                    | `array`          |
 | `Hash`                     | `object`         |
 
-`Riffer::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
+`Riffer::Params::Boolean` is the preferred way to declare boolean parameters. `TrueClass` and `FalseClass` continue to work for backwards compatibility.
 
 ### Nested Parameters
 
@@ -158,7 +158,7 @@ end
 
 ### Accessing Context
 
-The `context` argument receives whatever was passed as `context:` to `generate`:
+The `context` argument is a `Riffer::Agent::Context` — a typed value object wrapping the Hash passed as `context:` to `Agent.new`. Caller-provided keys are read with `context[:key]` or `context&.dig(:key)`:
 
 ```ruby
 class UserOrdersTool < Riffer::Tool
@@ -176,9 +176,14 @@ class UserOrdersTool < Riffer::Tool
 end
 
 # Usage
-agent.generate("Show my orders", context: {user_id: 123})
+MyAgent.new(context: {user_id: 123}).generate("Show my orders")
 ```
 
+Two keys are framework-managed and exposed as typed accessors:
+
+- `context.skills` — the resolved `Riffer::Skills::Context` when the agent has skills configured, otherwise `nil`.
+- `context.token_usage` — the cumulative `Riffer::Providers::TokenUsage` across every run on the agent, or `nil` before the first response.
+
 ## Response Objects
 
 All tools must return a `Riffer::Tools::Response` object from their `call` method. Riffer::Tool provides shorthand methods for creating responses.

data/docs/07_TOOL_ADVANCED.md

@@ -103,15 +103,15 @@ The LLM receives the error message and can decide how to respond (retry, apologi
 
 > **Warning:** This feature is experimental and may be removed or changed without warning in a future release.
 
-By default, tool calls are executed sequentially in the current thread using `Riffer::ToolRuntime::Inline`. You can change how tool calls are executed by configuring a different tool runtime.
+By default, tool calls are executed sequentially in the current thread using `Riffer::Tools::Runtime::Inline`. You can change how tool calls are executed by configuring a different tool runtime.
 
 ### Built-in Runtimes
 
 | Runtime                         | Description                                    |
 | ------------------------------- | ---------------------------------------------- |
-| `Riffer::ToolRuntime::Inline`   | Executes tool calls sequentially (default)     |
-| `Riffer::ToolRuntime::Threaded` | Executes tool calls concurrently using threads |
-| `Riffer::ToolRuntime::Fibers`   | Executes tool calls concurrently using fibers  |
+| `Riffer::Tools::Runtime::Inline`   | Executes tool calls sequentially (default)     |
+| `Riffer::Tools::Runtime::Threaded` | Executes tool calls concurrently using threads |
+| `Riffer::Tools::Runtime::Fibers`   | Executes tool calls concurrently using fibers  |
 
 ### Per-Agent Configuration
 
@@ -121,14 +121,14 @@ Use the `tool_runtime` class method on your agent:
 class MyAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
-  tool_runtime Riffer::ToolRuntime::Threaded
+  tool_runtime Riffer::Tools::Runtime::Threaded
 end
 ```
 
 Accepted values:
 
-- A `Riffer::ToolRuntime` subclass — instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`)
-- A `Riffer::ToolRuntime` instance — for custom runtimes with specific options
+- A `Riffer::Tools::Runtime` subclass — instantiated automatically (e.g., `Riffer::Tools::Runtime::Inline`, `Riffer::Tools::Runtime::Threaded`)
+- A `Riffer::Tools::Runtime` instance — for custom runtimes with specific options
 - A `Proc` — evaluated at runtime (see below)
 
 ### Dynamic Resolution
@@ -141,11 +141,11 @@ class MyAgent < Riffer::Agent
   uses_tools [WeatherTool, SearchTool]
 
   tool_runtime ->(context) {
-    context&.dig(:parallel) ? Riffer::ToolRuntime::Threaded.new : Riffer::ToolRuntime::Inline.new
+    context&.dig(:parallel) ? Riffer::Tools::Runtime::Threaded.new : Riffer::Tools::Runtime::Inline.new
   }
 end
 
-agent.generate("Do work", context: {parallel: true})
+MyAgent.new(context: {parallel: true}).generate("Do work")
 ```
 
 When the lambda accepts a parameter, it receives the `context`. Zero-arity lambdas are also supported.
@@ -156,7 +156,7 @@ Set a default tool runtime for all agents:
 
 ```ruby
 Riffer.configure do |config|
-  config.tool_runtime = Riffer::ToolRuntime::Threaded
+  config.tool_runtime = Riffer::Tools::Runtime::Threaded
 end
 ```
 
@@ -164,7 +164,7 @@ Per-agent configuration overrides the global default.
 
 ### Threaded Runtime Considerations
 
-When using `Riffer::ToolRuntime::Threaded`, each tool call runs in its own thread. The `around_tool_call` hook also runs inside that thread. Be mindful of thread-local state — for example, `ActiveRecord::Base.connection`, `RequestStore`, or any `Thread.current[]` values may not be available or may behave differently across threads. Ensure your tools and hooks are thread-safe.
+When using `Riffer::Tools::Runtime::Threaded`, each tool call runs in its own thread. The `around_tool_call` hook also runs inside that thread. Be mindful of thread-local state — for example, `ActiveRecord::Base.connection`, `RequestStore`, or any `Thread.current[]` values may not be available or may behave differently across threads. Ensure your tools and hooks are thread-safe.
 
 ### Threaded Runtime Options
 
@@ -174,7 +174,7 @@ The threaded runtime accepts a `max_concurrency` option (default: 5):
 class MyAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
-  tool_runtime Riffer::ToolRuntime::Threaded.new(max_concurrency: 3)
+  tool_runtime Riffer::Tools::Runtime::Threaded.new(max_concurrency: 3)
 end
 ```
 
@@ -191,7 +191,7 @@ gem "async"
 class MyAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
-  tool_runtime Riffer::ToolRuntime::Fibers
+  tool_runtime Riffer::Tools::Runtime::Fibers
 end
 ```
 
@@ -201,7 +201,7 @@ By default, all tool calls run as fibers without a concurrency limit. You can op
 class MyAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
-  tool_runtime Riffer::ToolRuntime::Fibers.new(max_concurrency: 10)
+  tool_runtime Riffer::Tools::Runtime::Fibers.new(max_concurrency: 10)
 end
 ```
 
@@ -209,10 +209,10 @@ Fibers use cooperative scheduling — they yield control at I/O boundaries (netw
 
 ### Custom Runtimes
 
-Create a custom runtime by subclassing `Riffer::ToolRuntime` and overriding the private `dispatch_tool_call` method:
+Create a custom runtime by subclassing `Riffer::Tools::Runtime` and overriding the private `dispatch_tool_call` method:
 
 ```ruby
-class HttpToolRuntime < Riffer::ToolRuntime
+class HttpToolRuntime < Riffer::Tools::Runtime
   private
 
   def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
@@ -235,7 +235,7 @@ end
 Each tool call is wrapped by the `around_tool_call` method, which yields by default. Override it in a subclass to add instrumentation, logging, or other cross-cutting concerns:
 
 ```ruby
-class InstrumentedRuntime < Riffer::ToolRuntime::Inline
+class InstrumentedRuntime < Riffer::Tools::Runtime::Inline
   private
 
   def around_tool_call(tool_call, context:, assistant_message: nil)