riffer 0.27.2 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22e4b5cd255cc4d66929a8696586b75a5f86d56728b930c50be48050972a5e60
-  data.tar.gz: c1a6a0a1f7200f2b9dceedbaccada8620ff39cf718d2cf7bbee6ee9954176441
+  metadata.gz: 65b1a78bcc2e6e26690176a167d4b8f5a28fdc83c95ac582fb980e1d52d0d89f
+  data.tar.gz: fa3f0633c56ca64a25f4026d48f7c8366344cacb76b2bdd7f4e9ce8642045b6c
 SHA512:
-  metadata.gz: 0cf4b811e2c89ab5d71ce64a5d701ea8582d87edb70062440974bba0ab4b0898db74d87b05fbd3b9042b47a2cd9af3ebe0c1efb89022a7a3a6cee34dcd66e9da
-  data.tar.gz: d94271b381b08a9bbfa57c372a9dcd3b404601aeaed6ef11e7f78af3a6e7667abc9a8488034fdc6e74b4c13dd6346002d4add9a20f30ac10a73569a62ab401f5
+  metadata.gz: e643b5a130b85f63bb37f51adf0fb43ea94f242af66ba379b98da8fbaf9e7389f17d9793cd2b1ff9a1b889ccce711632b02dfcd976cf323bf3c3b1300695635d
+  data.tar.gz: b01a4a3d4db8ca8ef72acf1e8c3e5b1ab01e5d47fdeca1a046c65daf8bde4e0160be8f10b2d94dc56c1dcd28e491cf6be44cf44fa12216fabe56956c327e9959

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.27.2"
+  ".": "0.28.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.28.0](https://github.com/janeapp/riffer/compare/riffer/v0.27.2...riffer/v0.28.0) (2026-05-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* Custom subclasses of Riffer::ToolRuntime that override around_tool_call or dispatch_tool_call must accept the new assistant_message: kwarg (or **kwargs). Existing overrides that omit it will raise ArgumentError: unknown keyword: :assistant_message.
+
+### Features
+
+* add history mutation API to Riffer::Agent ([#249](https://github.com/janeapp/riffer/issues/249)) ([d980daa](https://github.com/janeapp/riffer/commit/d980daa1526e476ce08b299be84e93257b746a1b))
+* forward assistant_message to ToolRuntime hooks ([#247](https://github.com/janeapp/riffer/issues/247)) ([3d5f935](https://github.com/janeapp/riffer/commit/3d5f935bf136a39e8fbef1b0a0728fcb87ef0de0))
+
 ## [0.27.2](https://github.com/janeapp/riffer/compare/riffer/v0.27.1...riffer/v0.27.2) (2026-05-04)
 
 

data/docs/04_AGENT_LIFECYCLE.md

@@ -235,6 +235,52 @@ agent.on_message do |msg|
 end
 ```
 
+#### Healing pending tool results on interrupt (experimental)
+
+When an interrupt fires while the assistant has a `tool_use` block that hasn't been answered yet, the LLM will reject the next request unless every `tool_use` has a matching `tool_result`. By default, the next `generate` call re-executes those pending tools (see "Resuming an Interrupted Loop" above).
+
+When the interrupt represents a course-change rather than a pause — e.g. a voice barge-in where the user has moved on — re-execution is the wrong behavior. Opt into history healing to have riffer fill any orphan `tool_use` with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted`, leaving history valid for the next turn:
+
+```ruby
+Riffer.configure { |c| c.experimental_history_healing = true }
+
+agent.on_message do |msg|
+  agent.interrupt!(:user_interrupt) if msg.is_a?(Riffer::Messages::Assistant) && barge_in?
+end
+
+response = agent.generate("Tell me a story")
+response.healed_tool_call_ids  # => ["call_abc123", ...]
+```
+
+The placeholder content is fixed: `"Tool call interrupted before completion."` with `error_type: :interrupted`. Each placeholder is inserted immediately after its parent assistant message. The list of filled `call_id`s is exposed on `response.healed_tool_call_ids` (and on `Riffer::StreamEvents::Interrupt#healed_tool_call_ids` when streaming).
+
+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.
+
+### 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.
+
+- **`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.
+
+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:
+
+```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)
+```
+
+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
 
 Access cumulative token usage across all LLM calls:
@@ -256,17 +302,18 @@ Returns `nil` if the provider doesn't report usage, or a `Riffer::TokenUsage` ob
 
 `Riffer::Agent::Response` is returned by `generate`:
 
-| Attribute           | Type                        | Description                                        |
-| ------------------- | --------------------------- | -------------------------------------------------- |
-| `content`           | `String`                    | The response text                                  |
-| `structured_output` | `Hash` / `nil`              | Parsed and validated structured output (see below) |
-| `blocked?`          | `Boolean`                   | `true` if a guardrail tripwire fired               |
-| `tripwire`          | `Tripwire` / `nil`          | The guardrail tripwire that blocked the request    |
-| `modified?`         | `Boolean`                   | `true` if a guardrail modified the content         |
-| `modifications`     | `Array`                     | List of guardrail modifications applied            |
-| `interrupted?`      | `Boolean`                   | `true` if the loop was interrupted                 |
-| `interrupt_reason`  | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`     |
-| `messages`          | `Array`                     | Full message history from the conversation         |
+| Attribute              | Type                        | Description                                                                          |
+| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------ |
+| `content`              | `String`                    | The response text                                                                    |
+| `structured_output`    | `Hash` / `nil`              | Parsed and validated structured output (see below)                                   |
+| `blocked?`             | `Boolean`                   | `true` if a guardrail tripwire fired                                                 |
+| `tripwire`             | `Tripwire` / `nil`          | The guardrail tripwire that blocked the request                                      |
+| `modified?`            | `Boolean`                   | `true` if a guardrail modified the content                                           |
+| `modifications`        | `Array`                     | List of guardrail modifications applied                                              |
+| `interrupted?`         | `Boolean`                   | `true` if the loop was interrupted                                                   |
+| `interrupt_reason`     | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`                                       |
+| `messages`             | `Array`                     | Full message history from the conversation                                           |
+| `healed_tool_call_ids` | `Array[String]`             | `tool_call` ids filled with placeholder results during interrupt healing (else `[]`) |
 
 ### response.structured_output
 

data/docs/07_TOOL_ADVANCED.md

@@ -215,7 +215,7 @@ Create a custom runtime by subclassing `Riffer::ToolRuntime` and overriding the
 class HttpToolRuntime < Riffer::ToolRuntime
   private
 
-  def dispatch_tool_call(tool_call, tools:, context:)
+  def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
     # Dispatch tool execution to an external service
     response = HttpClient.post("/tools/execute", {
       name: tool_call.name,
@@ -238,7 +238,7 @@ Each tool call is wrapped by the `around_tool_call` method, which yields by defa
 class InstrumentedRuntime < Riffer::ToolRuntime::Inline
   private
 
-  def around_tool_call(tool_call, context:)
+  def around_tool_call(tool_call, context:, assistant_message: nil)
     start = Time.now
     result = yield
     duration = Time.now - start
@@ -249,3 +249,7 @@ end
 ```
 
 Subclasses inherit the hook and can override it further.
+
+The `assistant_message:` kwarg is the `Riffer::Messages::Assistant` that produced the tool calls (the same object the agent appends to message history). It is `nil` when the runtime is invoked outside an agent loop. Use it when your hook or dispatcher needs context that lives on the assistant turn — for example, the accompanying assistant text, the model's reasoning content, or the full set of sibling tool calls from the same turn. The kwarg is **not** forwarded to `Tool#call`; tools that need it must read it via a custom `dispatch_tool_call` override.
+
+> **Note:** Custom runtimes that override `around_tool_call` or `dispatch_tool_call` must accept the `assistant_message:` kwarg (or `**kwargs`). Older overrides that omit it will raise `ArgumentError: unknown keyword: :assistant_message`.

data/docs/08_MESSAGES.md

@@ -327,3 +327,7 @@ end
 ```
 
 Subclasses implement `role` and optionally extend `to_h` with additional fields.
+
+## Editing history after the fact
+
+The agent's `messages` array is mutable, but the message value objects themselves are immutable. To edit recorded history — truncate an assistant message, replace a tool result, fill an orphan `tool_use` — use the mutators on `Riffer::Agent`. Each mutator enforces the `tool_use` ↔ `tool_result` invariant. See [Mutating history](04_AGENT_LIFECYCLE.md#mutating-history) for the full list.

data/docs/10_CONFIGURATION.md

@@ -65,11 +65,11 @@ Riffer.configure do |config|
 end
 ```
 
-| Value                           | Description                                                                                        |
-| ------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `Riffer::ToolRuntime` subclass  | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`)  |
-| `Riffer::ToolRuntime` instance  | Custom runtime with specific options                                                               |
-| `Proc`                          | Dynamic resolution                                                                                 |
+| Value                          | Description                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `Riffer::ToolRuntime` subclass | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`) |
+| `Riffer::ToolRuntime` instance | Custom runtime with specific options                                                              |
+| `Proc`                         | Dynamic resolution                                                                                |
 
 Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
@@ -134,6 +134,27 @@ Missing ids raise `Riffer::ArgumentError` with the offending index.
 
 See [Messages — IDs](08_MESSAGES.md#ids) for more details.
 
+### Experimental: History Healing
+
+> **Warning:** This feature is experimental and may change without notice.
+
+Opts the agent into keeping the `tool_use` ↔ `tool_result` invariant intact on its own:
+
+```ruby
+Riffer.configure do |config|
+  config.experimental_history_healing = true
+end
+```
+
+When enabled, two repairs run automatically:
+
+1. **Seeded history.** `agent.generate(messages_array)` silently drops orphaned `tool_use` exchanges (assistant `tool_call` with no matching `Tool` result) and parentless `Tool` messages from the seed before the run begins. Pending tool calls on the **resume boundary** — the last assistant whose tail is purely `Tool` results (or none) — are preserved; `execute_pending_tool_calls` runs them on the next LLM call.
+2. **Interrupts.** Any orphan `tool_use` left when the loop is interrupted (caller-issued `interrupt!` or the built-in `INTERRUPT_MAX_STEPS` ceiling) is filled with a placeholder `Riffer::Messages::Tool` carrying `error_type: :interrupted` and the content `"Tool call interrupted before completion."`. Filled `call_id`s are exposed on `Riffer::Agent::Response#healed_tool_call_ids` (and `Riffer::StreamEvents::Interrupt#healed_tool_call_ids` when streaming).
+
+Defaults to `false` — pre-healing behavior. Seeded arrays pass through untouched, and orphan `tool_use` left by an interrupt remain in history for `execute_pending_tool_calls` to re-run on the next call.
+
+There is no per-call override and no customizable placeholder. Callers needing finer control can call the `replace_tool_result` mutator after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](04_AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
+
 ## Agent-Level Configuration
 
 Override global configuration at the agent level:

data/lib/riffer/agent/response.rb

@@ -31,6 +31,12 @@ class Riffer::Agent::Response
   # The full message history from the agent conversation.
   attr_reader :messages #: Array[Riffer::Messages::Base]
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results during this turn — populated when an interrupt left them
+  # unanswered and +Riffer.config.experimental_history_healing+ is on.
+  # Empty otherwise.
+  attr_reader :healed_tool_call_ids #: Array[String]
+
   # Creates a new response.
   #
   # [content] the response content.
@@ -40,10 +46,12 @@ class Riffer::Agent::Response
   # [interrupt_reason] optional reason passed via <tt>throw :riffer_interrupt, reason</tt>.
   # [structured_output] parsed structured output when structured output is configured.
   # [messages] the full message history from the agent conversation.
+  # [healed_tool_call_ids] call ids filled with placeholder tool results
+  #   when history healing is enabled.
   #
   #--
-  #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base]) -> void
-  def initialize(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, messages: [])
+  #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
+  def initialize(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, messages: [], healed_tool_call_ids: [])
     @content = content
     @tripwire = tripwire
     @modifications = modifications
@@ -51,6 +59,7 @@ class Riffer::Agent::Response
     @interrupt_reason = interrupt_reason
     @structured_output = structured_output
     @messages = messages
+    @healed_tool_call_ids = healed_tool_call_ids
   end
 
   # Returns true if the response was blocked by a guardrail.

data/lib/riffer/agent.rb

@@ -26,6 +26,13 @@ class Riffer::Agent
   DEFAULT_MAX_STEPS = 16 #: Integer
   INTERRUPT_MAX_STEPS = :max_steps #: Symbol
 
+  # Placeholder used to fill orphan +tool_use+ blocks when
+  # +Riffer.config.experimental_history_healing+ is enabled and an
+  # interrupt fires mid-tool-use.
+  HEALING_PLACEHOLDER = ->(_tool_call) {
+    Riffer::Tools::Response.error("Tool call interrupted before completion.", type: :interrupted)
+  } #: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+
   # Gets or sets the agent identifier.
   #
   #--
@@ -345,6 +352,10 @@ class Riffer::Agent
 
   # Generates a response from the agent.
   #
+  # When +Riffer.config.experimental_history_healing+ is enabled, seeded
+  # message arrays that violate the +tool_use+ ↔ +tool_result+ invariant
+  # are silently repaired before the run begins.
+  #
   #--
   #: ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
   def generate(prompt_or_messages, files: nil, context: nil)
@@ -366,6 +377,9 @@ class Riffer::Agent
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
+  # See +#generate+ for the +experimental_history_healing+ behavior on
+  # seeded arrays.
+  #
   #--
   #: ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream(prompt_or_messages, files: nil, context: nil)
@@ -431,14 +445,197 @@ class Riffer::Agent
   # Call from an +on_message+ callback to cleanly interrupt the loop.
   # Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
   #
+  # When +Riffer.config.experimental_history_healing+ is enabled, riffer
+  # fills any orphaned +tool_use+ on the way out with a placeholder
+  # +Riffer::Messages::Tool+ carrying +error_type: :interrupted+. The
+  # filled call_ids are exposed on
+  # +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
+  # +Riffer::StreamEvents::Interrupt+ event).
+  #
   #--
   #: (?(String | Symbol)?) -> void
   def interrupt!(reason = nil)
     throw :riffer_interrupt, reason
   end
 
+  # Returns the message with the given id, or +nil+ when no message matches.
+  #
+  #--
+  #: (String) -> Riffer::Messages::Base?
+  def message_by_id(id)
+    @messages.find { |m| m.id == id }
+  end
+
+  # Returns the +Riffer::Messages::Tool+ message that satisfies +tool_call_id+,
+  # or +nil+ when no such tool result exists in history.
+  #
+  #--
+  #: (String) -> Riffer::Messages::Tool?
+  # TODO: Replace with rfind when minimum Ruby is 4.0+
+  # rubocop:disable Style/ReverseFind
+  def tool_message_for(tool_call_id)
+    @messages.reverse.find { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == tool_call_id } #: Riffer::Messages::Tool?
+  end
+  # rubocop:enable Style/ReverseFind
+
+  # Returns the most recent +Riffer::Messages::Assistant+ in history, or
+  # +nil+ when no assistant message has been recorded yet.
+  #
+  #--
+  #: () -> Riffer::Messages::Assistant?
+  # TODO: Replace with rfind when minimum Ruby is 4.0+
+  # rubocop:disable Style/ReverseFind
+  def last_assistant
+    @messages.reverse.find { |m| m.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
+  end
+  # rubocop:enable Style/ReverseFind
+
+  # Returns the call_ids of every +tool_call+ on any assistant message that
+  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
+  #
+  # Zero-cost validation hook for callers that want to check the
+  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
+  #
+  #--
+  #: () -> Array[String]
+  def orphaned_tool_call_ids
+    result_ids = @messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
+    @messages.flat_map { |m|
+      next [] unless m.is_a?(Riffer::Messages::Assistant)
+      m.tool_calls.reject { |tc| result_ids.include?(tc.call_id) }.map(&:call_id)
+    }
+  end
+
+  # Replaces the content of an assistant message in place. Preserves +id+,
+  # +tool_calls+, +token_usage+, and +structured_output+. Lookup is by id.
+  #
+  # When +content+ is empty, delegates to +remove_message+ — including the
+  # cascade that drops dependent +Riffer::Messages::Tool+ children.
+  #
+  # Raises Riffer::ArgumentError when no assistant message has the given id.
+  #
+  #--
+  #: (id: String, content: String) -> Riffer::Messages::Base?
+  def replace_assistant_content(id:, content:)
+    return remove_message(id: id) if content.empty?
+
+    idx = @messages.index { |m| m.is_a?(Riffer::Messages::Assistant) && m.id == id }
+    raise Riffer::ArgumentError, "no assistant message with id #{id.inspect}" unless idx
+
+    old = @messages[idx] #: Riffer::Messages::Assistant
+    replacement = Riffer::Messages::Assistant.new(
+      content,
+      id: old.id,
+      tool_calls: old.tool_calls,
+      token_usage: old.token_usage,
+      structured_output: old.structured_output
+    )
+    @messages[idx] = replacement
+    replacement
+  end
+
+  # Removes a message by id. When the target is an assistant message that
+  # carries +tool_calls+, every +Riffer::Messages::Tool+ result whose
+  # +tool_call_id+ matches one of those calls is removed atomically — keeping
+  # the +tool_use+ ↔ +tool_result+ invariant intact.
+  #
+  # Raises Riffer::ArgumentError when called on a +Riffer::Messages::Tool+
+  # message — that would orphan the parent's +tool_use+. Use
+  # +replace_tool_result+ instead.
+  #
+  # Returns the removed message, or +nil+ when no message has the given id
+  # (idempotent).
+  #
+  #--
+  #: (id: String) -> Riffer::Messages::Base?
+  def remove_message(id:)
+    idx = @messages.index { |m| m.id == id }
+    return nil unless idx
+
+    target = @messages[idx]
+    if target.is_a?(Riffer::Messages::Tool)
+      raise Riffer::ArgumentError,
+        "remove_message cannot drop a Tool message (would orphan the parent's tool_use); use replace_tool_result instead"
+    end
+
+    if target.is_a?(Riffer::Messages::Assistant) && !target.tool_calls.empty?
+      child_ids = target.tool_calls.map(&:call_id)
+      @messages.reject! { |m| m.is_a?(Riffer::Messages::Tool) && child_ids.include?(m.tool_call_id) }
+      @messages.delete(target)
+    else
+      @messages.delete_at(idx)
+    end
+    target
+  end
+
+  # Replaces a tool result's content (and optional error fields) in place.
+  # Lookup is by +tool_call_id+. Preserves the existing message's +name+ and
+  # +id+.
+  #
+  # Raises Riffer::ArgumentError when no Tool message exists for the given
+  # +tool_call_id+.
+  #
+  #--
+  #: (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
+  def replace_tool_result(tool_call_id:, content:, error: nil, error_type: nil)
+    idx = @messages.index { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == tool_call_id }
+    raise Riffer::ArgumentError, "no tool result for tool_call_id #{tool_call_id.inspect}" unless idx
+
+    old = @messages[idx] #: Riffer::Messages::Tool
+    replacement = Riffer::Messages::Tool.new(
+      content,
+      id: old.id,
+      tool_call_id: old.tool_call_id,
+      name: old.name,
+      error: error,
+      error_type: error_type
+    )
+    @messages[idx] = replacement
+    replacement
+  end
+
   private
 
+  # Fills any orphaned +tool_use+ in history with the +HEALING_PLACEHOLDER+
+  # response. Each placeholder Tool message is inserted immediately after
+  # its parent assistant message. Returns the array of call_ids that were
+  # filled, in order; +[]+ when there are no orphans.
+  #
+  # Bypasses +on_message+ — placeholders are not inference output.
+  # Consumers learn that healing happened via the structured
+  # +Riffer::Agent::Response#healed_tool_call_ids+ field (and the streaming
+  # +Interrupt+ event's matching field).
+  #
+  #--
+  #: () -> Array[String]
+  def heal_orphan_tool_calls
+    result_ids = @messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
+    healed = [] #: Array[String]
+    new_messages = [] #: Array[Riffer::Messages::Base]
+
+    @messages.each do |m|
+      new_messages << m
+      next unless m.is_a?(Riffer::Messages::Assistant) && !m.tool_calls.empty?
+
+      m.tool_calls.each do |tc|
+        next if result_ids.include?(tc.call_id)
+
+        response = HEALING_PLACEHOLDER.call(tc)
+        new_messages << Riffer::Messages::Tool.new(
+          response.content,
+          tool_call_id: tc.call_id,
+          name: tc.name,
+          error: response.error_message,
+          error_type: response.error_type
+        )
+        healed << tc.call_id
+      end
+    end
+
+    @messages = new_messages
+    healed
+  end
+
   #--
   #: (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
   def run_generate_loop(all_modifications = [])
@@ -475,9 +672,10 @@ class Riffer::Agent
     # catch returns the thrown value when throw :riffer_interrupt fires;
     # the return above exits on the successful (non-interrupted) path.
     @interrupted = true
+    healed = Riffer.config.experimental_history_healing ? heal_orphan_tool_calls : []
     response = extract_final_response
 
-    build_response(response&.content || "", modifications: all_modifications, interrupted: true, interrupt_reason: reason, structured_output: validate_structured_output(response))
+    build_response(response&.content || "", modifications: all_modifications, interrupted: true, interrupt_reason: reason, structured_output: validate_structured_output(response), healed_tool_call_ids: healed)
   end
 
   #--
@@ -502,7 +700,8 @@ class Riffer::Agent
       raise Riffer::ArgumentError, "cannot pass an array of messages on an agent with existing messages; use a string to continue the conversation or a new agent instance to start fresh" if @messages.any?
       raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead" if files && !files.empty?
       validate_seed_ids!(prompt_or_messages)
-      @messages = prompt_or_messages.map { |item| convert_to_message_object(item) }
+      converted = prompt_or_messages.map { |item| convert_to_message_object(item) }
+      @messages = Riffer.config.experimental_history_healing ? heal_seeded_history(converted) : converted
     elsif @messages.any?
       file_parts = (files || []).map { |f| convert_to_file_part(f) }
       @messages << Riffer::Messages::User.new(prompt_or_messages, files: file_parts)
@@ -535,6 +734,51 @@ class Riffer::Agent
     end
   end
 
+  # Repairs a seeded message array so the +tool_use+ ↔ +tool_result+
+  # invariant holds. Drops orphaned tool exchanges (assistant +tool_call+
+  # with no matching Tool result) and parentless Tool messages. Returns a
+  # new array; the input is not mutated.
+  #
+  # Pending tool_calls on the resume boundary — the last assistant whose
+  # tail is purely Tool results (or empty) — are preserved. They get swept
+  # up by +execute_pending_tool_calls+ at the start of the next
+  # generate/stream call.
+  #
+  # Only invoked when +Riffer.config.experimental_history_healing+ is on.
+  #
+  #--
+  #: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def heal_seeded_history(messages)
+    resume_boundary = (messages.length - 1).downto(0).find { |idx|
+      m = messages[idx]
+      m.is_a?(Riffer::Messages::Assistant) &&
+        messages[(idx + 1)..].all? { |later| later.is_a?(Riffer::Messages::Tool) }
+    }
+
+    result_ids = messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
+    parent_ids = messages.flat_map { |m|
+      m.is_a?(Riffer::Messages::Assistant) ? m.tool_calls.map(&:call_id) : []
+    }
+
+    strip_offenders = messages.each_with_index.flat_map { |m, idx|
+      next [] unless m.is_a?(Riffer::Messages::Assistant) && !m.tool_calls.empty?
+      next [] if idx == resume_boundary # preserve pending exchange
+      next [] if m.tool_calls.all? { |tc| result_ids.include?(tc.call_id) }
+      m.tool_calls.map(&:call_id)
+    }
+
+    messages.reject { |m|
+      case m
+      when Riffer::Messages::Assistant
+        !m.tool_calls.empty? && m.tool_calls.any? { |tc| strip_offenders.include?(tc.call_id) }
+      when Riffer::Messages::Tool
+        strip_offenders.include?(m.tool_call_id) || !parent_ids.include?(m.tool_call_id)
+      else
+        false
+      end
+    }
+  end
+
   #--
   #: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
   def build_instruction_message(context = @context)
@@ -629,7 +873,8 @@ class Riffer::Agent
 
     unless completed == :completed
       @interrupted = true
-      yielder << Riffer::StreamEvents::Interrupt.new(reason: completed)
+      healed = Riffer.config.experimental_history_healing ? heal_orphan_tool_calls : []
+      yielder << Riffer::StreamEvents::Interrupt.new(reason: completed, healed_tool_call_ids: healed)
     end
   end
 
@@ -671,7 +916,7 @@ class Riffer::Agent
   #: (Riffer::Messages::Assistant) -> void
   def execute_tool_calls(response)
     runtime = resolve_tool_runtime
-    results = runtime.execute(response.tool_calls, tools: resolved_tools, context: @context)
+    results = runtime.execute(response.tool_calls, tools: resolved_tools, context: @context, assistant_message: response)
 
     results.each do |tool_call, result|
       add_message(Riffer::Messages::Tool.new(
@@ -698,11 +943,11 @@ class Riffer::Agent
   # have a corresponding tool result. Safe to call unconditionally —
   # returns immediately when there is nothing pending.
   def execute_pending_tool_calls
-    pending = pending_tool_calls
+    assistant, pending = pending_tool_calls
     return if pending.empty?
 
     runtime = resolve_tool_runtime
-    results = runtime.execute(pending, tools: resolved_tools, context: @context)
+    results = runtime.execute(pending, tools: resolved_tools, context: @context, assistant_message: assistant)
 
     results.each do |tool_call, result|
       add_message(Riffer::Messages::Tool.new(
@@ -715,18 +960,24 @@ class Riffer::Agent
     end
   end
 
+  # Returns +[assistant, pending_tool_calls]+ for the last assistant message.
+  # When there is no assistant message or no pending calls, the second
+  # element is an empty array.
+  #
+  #--
+  #: () -> [untyped, Array[Riffer::Messages::Assistant::ToolCall]]
   def pending_tool_calls
     last_assistant_idx = @messages.rindex { |m| m.is_a?(Riffer::Messages::Assistant) }
-    return [] unless last_assistant_idx
+    return [nil, []] unless last_assistant_idx
 
     assistant = @messages[last_assistant_idx]
-    return [] if assistant.tool_calls.empty?
+    return [assistant, []] if assistant.tool_calls.empty?
 
     executed_ids = @messages[(last_assistant_idx + 1)..].select { |m|
       m.is_a?(Riffer::Messages::Tool)
     }.map(&:tool_call_id)
 
-    assistant.tool_calls.reject { |tc| executed_ids.include?(tc.call_id) }
+    [assistant, assistant.tool_calls.reject { |tc| executed_ids.include?(tc.call_id) }]
   end
 
   #--
@@ -978,8 +1229,8 @@ class Riffer::Agent
   end
 
   #--
-  #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def build_response(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil)
-    Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: @messages.frozen? ? @messages : @messages.dup.freeze)
+  #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
+  def build_response(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, healed_tool_call_ids: [])
+    Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: @messages.frozen? ? @messages : @messages.dup.freeze, healed_tool_call_ids: healed_tool_call_ids)
   end
 end

data/lib/riffer/config.rb

@@ -151,6 +151,47 @@ class Riffer::Config
     @message_id_strategy = value
   end
 
+  # Experimental: when +true+, riffer keeps the +tool_use+ ↔ +tool_result+
+  # invariant intact on its own.
+  #
+  # - On +Riffer::Agent#generate(messages_array)+, orphaned +tool_use+
+  #   exchanges and parentless +Riffer::Messages::Tool+ messages are
+  #   silently stripped from the seed. Pending tool calls on the resume
+  #   boundary (last assistant whose tail is purely Tool results) are
+  #   preserved for +execute_pending_tool_calls+.
+  # - On any interrupt (caller-issued +interrupt!+ or
+  #   +INTERRUPT_MAX_STEPS+), riffer fills any orphaned +tool_use+ with a
+  #   placeholder +Riffer::Messages::Tool+ carrying
+  #   +error_type: :interrupted+, leaving history valid for the next turn.
+  #   Filled call_ids are exposed on
+  #   +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
+  #   +Riffer::StreamEvents::Interrupt+ event).
+  #
+  # Defaults to +false+ — the pre-healing behavior. Experimental: the
+  # surface and default may change without notice.
+  attr_reader :experimental_history_healing #: bool
+
+  # Sets the +experimental_history_healing+ flag.
+  #
+  # Coerces common boolean representations so values pulled from
+  # environment variables don't silently enable healing — the string
+  # +"false"+ is truthy in Ruby and would otherwise flip the flag on.
+  # Accepts +true+/+false+, +"true"+/+"false"+, +1+/+0+, +"1"+/+"0"+, and
+  # +nil+ (treated as +false+, the default). Raises
+  # +Riffer::ArgumentError+ for any other value.
+  #
+  #--
+  #: (untyped) -> void
+  def experimental_history_healing=(value)
+    @experimental_history_healing = case value
+    when true, "true", 1, "1" then true
+    when false, "false", 0, "0", nil then false
+    else
+      raise Riffer::ArgumentError,
+        "experimental_history_healing must be a boolean (or 'true'/'false'/'1'/'0'/1/0), got #{value.inspect}"
+    end
+  end
+
   #--
   #: () -> void
   def initialize
@@ -164,5 +205,6 @@ class Riffer::Config
     @tool_runtime = Riffer::ToolRuntime::Inline.new
     @skills = Skills.new
     @message_id_strategy = :none
+    @experimental_history_healing = false
   end
 end

data/lib/riffer/stream_events/interrupt.rb

@@ -8,11 +8,17 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
   attr_reader :reason #: (String | Symbol)?
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results when the interrupt fired. Populated only when
+  # +Riffer.config.experimental_history_healing+ is on.
+  attr_reader :healed_tool_call_ids #: Array[String]
+
   #--
-  #: (?reason: (String | Symbol)?) -> void
-  def initialize(reason: nil)
+  #: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void
+  def initialize(reason: nil, healed_tool_call_ids: [])
     super(role: :system)
     @reason = reason
+    @healed_tool_call_ids = healed_tool_call_ids
   end
 
   # Converts the event to a hash.
@@ -22,6 +28,7 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   def to_h
     h = {role: @role, interrupt: true}
     h[:reason] = @reason if @reason
+    h[:healed_tool_call_ids] = @healed_tool_call_ids unless @healed_tool_call_ids.empty?
     h
   end
 end

data/lib/riffer/tool_runtime.rb

@@ -32,13 +32,17 @@ class Riffer::ToolRuntime
   # [tool_calls] the tool calls to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced these tool
+  #   calls, when known. Forwarded to +around_tool_call+ and
+  #   +dispatch_tool_call+ so subclasses can access it (e.g. for
+  #   instrumentation that needs the accompanying assistant text).
   #
   #--
-  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute(tool_calls, tools:, context:)
+  #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  def execute(tool_calls, tools:, context:, assistant_message: nil)
     @runner.map(tool_calls, context: context) do |tool_call|
-      result = around_tool_call(tool_call, context: context) do
-        dispatch_tool_call(tool_call, tools: tools, context: context)
+      result = around_tool_call(tool_call, context: context, assistant_message: assistant_message) do
+        dispatch_tool_call(tool_call, tools: tools, context: context, assistant_message: assistant_message)
       end
       [tool_call, result]
     end
@@ -52,7 +56,7 @@ class Riffer::ToolRuntime
   #   class InstrumentedRuntime < Riffer::ToolRuntime::Inline
   #     private
   #
-  #     def around_tool_call(tool_call, context:)
+  #     def around_tool_call(tool_call, context:, assistant_message: nil)
   #       start = Time.now
   #       result = yield
   #       Rails.logger.info("Tool #{tool_call.name} took #{Time.now - start}s")
@@ -61,8 +65,8 @@ class Riffer::ToolRuntime
   #   end
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
-  def around_tool_call(tool_call, context:)
+  #: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
+  def around_tool_call(tool_call, context:, assistant_message: nil)
     yield
   end
 
@@ -74,10 +78,12 @@ class Riffer::ToolRuntime
   # [tool_call] the tool call to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced this tool
+  #   call, when known.
   #
   #--
-  #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Riffer::Tools::Response
-  def dispatch_tool_call(tool_call, tools:, context:)
+  #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
+  def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)
     tool_class = tools.find { |tc| tc.name == tool_call.name }
 
     if tool_class.nil?

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.27.2" #: String
+  VERSION = "0.28.0" #: String
 end

data/sig/generated/riffer/agent/response.rbs

@@ -30,6 +30,12 @@ class Riffer::Agent::Response
   # The full message history from the agent conversation.
   attr_reader messages: Array[Riffer::Messages::Base]
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results during this turn — populated when an interrupt left them
+  # unanswered and +Riffer.config.experimental_history_healing+ is on.
+  # Empty otherwise.
+  attr_reader healed_tool_call_ids: Array[String]
+
   # Creates a new response.
   #
   # [content] the response content.
@@ -39,10 +45,12 @@ class Riffer::Agent::Response
   # [interrupt_reason] optional reason passed via <tt>throw :riffer_interrupt, reason</tt>.
   # [structured_output] parsed structured output when structured output is configured.
   # [messages] the full message history from the agent conversation.
+  # [healed_tool_call_ids] call ids filled with placeholder tool results
+  #   when history healing is enabled.
   #
   # --
-  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base]) -> void
-  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base]) -> void
+  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
+  def initialize: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?messages: Array[Riffer::Messages::Base], ?healed_tool_call_ids: Array[String]) -> void
 
   # Returns true if the response was blocked by a guardrail.
   #

data/sig/generated/riffer/agent.rbs

@@ -25,6 +25,11 @@ class Riffer::Agent
 
   INTERRUPT_MAX_STEPS: Symbol
 
+  # Placeholder used to fill orphan +tool_use+ blocks when
+  # +Riffer.config.experimental_history_healing+ is enabled and an
+  # interrupt fires mid-tool-use.
+  HEALING_PLACEHOLDER: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+
   # Gets or sets the agent identifier.
   #
   # --
@@ -220,6 +225,10 @@ class Riffer::Agent
 
   # Generates a response from the agent.
   #
+  # When +Riffer.config.experimental_history_healing+ is enabled, seeded
+  # message arrays that violate the +tool_use+ ↔ +tool_result+ invariant
+  # are silently repaired before the run begins.
+  #
   # --
   # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
   def generate: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
@@ -228,6 +237,9 @@ class Riffer::Agent
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
+  # See +#generate+ for the +experimental_history_healing+ behavior on
+  # seeded arrays.
+  #
   # --
   # : ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream: (String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base], ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
@@ -267,12 +279,106 @@ class Riffer::Agent
   # Call from an +on_message+ callback to cleanly interrupt the loop.
   # Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
   #
+  # When +Riffer.config.experimental_history_healing+ is enabled, riffer
+  # fills any orphaned +tool_use+ on the way out with a placeholder
+  # +Riffer::Messages::Tool+ carrying +error_type: :interrupted+. The
+  # filled call_ids are exposed on
+  # +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
+  # +Riffer::StreamEvents::Interrupt+ event).
+  #
   # --
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
 
+  # Returns the message with the given id, or +nil+ when no message matches.
+  #
+  # --
+  # : (String) -> Riffer::Messages::Base?
+  def message_by_id: (String) -> Riffer::Messages::Base?
+
+  # Returns the +Riffer::Messages::Tool+ message that satisfies +tool_call_id+,
+  # or +nil+ when no such tool result exists in history.
+  #
+  # --
+  # : (String) -> Riffer::Messages::Tool?
+  # TODO: Replace with rfind when minimum Ruby is 4.0+
+  # rubocop:disable Style/ReverseFind
+  def tool_message_for: (String) -> Riffer::Messages::Tool?
+
+  # Returns the most recent +Riffer::Messages::Assistant+ in history, or
+  # +nil+ when no assistant message has been recorded yet.
+  #
+  # --
+  # : () -> Riffer::Messages::Assistant?
+  # TODO: Replace with rfind when minimum Ruby is 4.0+
+  # rubocop:disable Style/ReverseFind
+  def last_assistant: () -> Riffer::Messages::Assistant?
+
+  # Returns the call_ids of every +tool_call+ on any assistant message that
+  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
+  #
+  # Zero-cost validation hook for callers that want to check the
+  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
+  #
+  # --
+  # : () -> Array[String]
+  def orphaned_tool_call_ids: () -> Array[String]
+
+  # Replaces the content of an assistant message in place. Preserves +id+,
+  # +tool_calls+, +token_usage+, and +structured_output+. Lookup is by id.
+  #
+  # When +content+ is empty, delegates to +remove_message+ — including the
+  # cascade that drops dependent +Riffer::Messages::Tool+ children.
+  #
+  # Raises Riffer::ArgumentError when no assistant message has the given id.
+  #
+  # --
+  # : (id: String, content: String) -> Riffer::Messages::Base?
+  def replace_assistant_content: (id: String, content: String) -> Riffer::Messages::Base?
+
+  # Removes a message by id. When the target is an assistant message that
+  # carries +tool_calls+, every +Riffer::Messages::Tool+ result whose
+  # +tool_call_id+ matches one of those calls is removed atomically — keeping
+  # the +tool_use+ ↔ +tool_result+ invariant intact.
+  #
+  # Raises Riffer::ArgumentError when called on a +Riffer::Messages::Tool+
+  # message — that would orphan the parent's +tool_use+. Use
+  # +replace_tool_result+ instead.
+  #
+  # Returns the removed message, or +nil+ when no message has the given id
+  # (idempotent).
+  #
+  # --
+  # : (id: String) -> Riffer::Messages::Base?
+  def remove_message: (id: String) -> Riffer::Messages::Base?
+
+  # Replaces a tool result's content (and optional error fields) in place.
+  # Lookup is by +tool_call_id+. Preserves the existing message's +name+ and
+  # +id+.
+  #
+  # Raises Riffer::ArgumentError when no Tool message exists for the given
+  # +tool_call_id+.
+  #
+  # --
+  # : (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
+  def replace_tool_result: (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
+
   private
 
+  # Fills any orphaned +tool_use+ in history with the +HEALING_PLACEHOLDER+
+  # response. Each placeholder Tool message is inserted immediately after
+  # its parent assistant message. Returns the array of call_ids that were
+  # filled, in order; +[]+ when there are no orphans.
+  #
+  # Bypasses +on_message+ — placeholders are not inference output.
+  # Consumers learn that healing happened via the structured
+  # +Riffer::Agent::Response#healed_tool_call_ids+ field (and the streaming
+  # +Interrupt+ event's matching field).
+  #
+  # --
+  # : () -> Array[String]
+  def heal_orphan_tool_calls: () -> Array[String]
+
   # --
   # : (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
   def run_generate_loop: (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
@@ -293,6 +399,22 @@ class Riffer::Agent
   # : (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
   def validate_seed_ids!: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
 
+  # Repairs a seeded message array so the +tool_use+ ↔ +tool_result+
+  # invariant holds. Drops orphaned tool exchanges (assistant +tool_call+
+  # with no matching Tool result) and parentless Tool messages. Returns a
+  # new array; the input is not mutated.
+  #
+  # Pending tool_calls on the resume boundary — the last assistant whose
+  # tail is purely Tool results (or empty) — are preserved. They get swept
+  # up by +execute_pending_tool_calls+ at the start of the next
+  # generate/stream call.
+  #
+  # Only invoked when +Riffer.config.experimental_history_healing+ is on.
+  #
+  # --
+  # : (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def heal_seeded_history: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+
   # --
   # : (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
   def build_instruction_message: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
@@ -344,7 +466,13 @@ class Riffer::Agent
   # returns immediately when there is nothing pending.
   def execute_pending_tool_calls: () -> void
 
-  def pending_tool_calls: () -> untyped
+  # Returns +[assistant, pending_tool_calls]+ for the last assistant message.
+  # When there is no assistant message or no pending calls, the second
+  # element is an empty array.
+  #
+  # --
+  # : () -> [untyped, Array[Riffer::Messages::Assistant::ToolCall]]
+  def pending_tool_calls: () -> [ untyped, Array[Riffer::Messages::Assistant::ToolCall] ]
 
   # --
   # : () -> void
@@ -435,6 +563,6 @@ class Riffer::Agent
   def merged_model_options: () -> Hash[Symbol, untyped]
 
   # --
-  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def build_response: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
+  # : (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
+  def build_response: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
 end

data/sig/generated/riffer/config.rbs

@@ -180,6 +180,39 @@ class Riffer::Config
   # : (Symbol) -> void
   def message_id_strategy=: (Symbol) -> void
 
+  # Experimental: when +true+, riffer keeps the +tool_use+ ↔ +tool_result+
+  # invariant intact on its own.
+  #
+  # - On +Riffer::Agent#generate(messages_array)+, orphaned +tool_use+
+  #   exchanges and parentless +Riffer::Messages::Tool+ messages are
+  #   silently stripped from the seed. Pending tool calls on the resume
+  #   boundary (last assistant whose tail is purely Tool results) are
+  #   preserved for +execute_pending_tool_calls+.
+  # - On any interrupt (caller-issued +interrupt!+ or
+  #   +INTERRUPT_MAX_STEPS+), riffer fills any orphaned +tool_use+ with a
+  #   placeholder +Riffer::Messages::Tool+ carrying
+  #   +error_type: :interrupted+, leaving history valid for the next turn.
+  #   Filled call_ids are exposed on
+  #   +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
+  #   +Riffer::StreamEvents::Interrupt+ event).
+  #
+  # Defaults to +false+ — the pre-healing behavior. Experimental: the
+  # surface and default may change without notice.
+  attr_reader experimental_history_healing: bool
+
+  # Sets the +experimental_history_healing+ flag.
+  #
+  # Coerces common boolean representations so values pulled from
+  # environment variables don't silently enable healing — the string
+  # +"false"+ is truthy in Ruby and would otherwise flip the flag on.
+  # Accepts +true+/+false+, +"true"+/+"false"+, +1+/+0+, +"1"+/+"0"+, and
+  # +nil+ (treated as +false+, the default). Raises
+  # +Riffer::ArgumentError+ for any other value.
+  #
+  # --
+  # : (untyped) -> void
+  def experimental_history_healing=: (untyped) -> void
+
   # --
   # : () -> void
   def initialize: () -> void

data/sig/generated/riffer/stream_events/interrupt.rbs

@@ -7,9 +7,14 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
   attr_reader reason: (String | Symbol)?
 
+  # Call ids of tool_use blocks that riffer filled with placeholder
+  # results when the interrupt fired. Populated only when
+  # +Riffer.config.experimental_history_healing+ is on.
+  attr_reader healed_tool_call_ids: Array[String]
+
   # --
-  # : (?reason: (String | Symbol)?) -> void
-  def initialize: (?reason: (String | Symbol)?) -> void
+  # : (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void
+  def initialize: (?reason: (String | Symbol)?, ?healed_tool_call_ids: Array[String]) -> void
 
   # Converts the event to a hash.
   #

data/sig/generated/riffer/tool_runtime.rbs

@@ -25,10 +25,14 @@ class Riffer::ToolRuntime
   # [tool_calls] the tool calls to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced these tool
+  #   calls, when known. Forwarded to +around_tool_call+ and
+  #   +dispatch_tool_call+ so subclasses can access it (e.g. for
+  #   instrumentation that needs the accompanying assistant text).
   #
   # --
-  # : (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
-  def execute: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]
+  # : (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
+  def execute: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[ Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response ]]
 
   # Hook that wraps each tool call execution. Override in subclasses
   # to customize. Must +yield+ to continue execution.
@@ -38,7 +42,7 @@ class Riffer::ToolRuntime
   #   class InstrumentedRuntime < Riffer::ToolRuntime::Inline
   #     private
   #
-  #     def around_tool_call(tool_call, context:)
+  #     def around_tool_call(tool_call, context:, assistant_message: nil)
   #       start = Time.now
   #       result = yield
   #       Rails.logger.info("Tool #{tool_call.name} took #{Time.now - start}s")
@@ -47,8 +51,8 @@ class Riffer::ToolRuntime
   #   end
   #
   # --
-  # : (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
-  def around_tool_call: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
+  # : (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
+  def around_tool_call: (Riffer::Messages::Assistant::ToolCall, context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) { () -> Riffer::Tools::Response } -> Riffer::Tools::Response
 
   private
 
@@ -58,10 +62,12 @@ class Riffer::ToolRuntime
   # [tool_call] the tool call to execute.
   # [tools] the resolved tool classes.
   # [context] the context hash.
+  # [assistant_message] the assistant message that produced this tool
+  #   call, when known.
   #
   # --
-  # : (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Riffer::Tools::Response
-  def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?) -> Riffer::Tools::Response
+  # : (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
+  def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Hash[Symbol, untyped]?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
 
   # --
   # : (String?) -> Hash[Symbol, untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.27.2
+  version: 0.28.0
 platform: ruby
 authors:
 - Jake Bottrall