phronomy 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8bcaf54fe256791053b04c22df3b58595d267b2c0ee16b67369fe2ecb36f19d
-  data.tar.gz: 9be01ec03a79ec5d557a3c51fc442992cd012a07e682a43cfa4c9e0358110fc8
+  metadata.gz: 2a6262c12bc063819c0e1656699f47666b06b182747d6ce85843d2a74988c358
+  data.tar.gz: 6529858071913e61a6a840fe03e36620322bfddd50e415b054314124f9b7fcd1
 SHA512:
-  metadata.gz: 44de75b5cc59ddf380aeb0be3abcf2a2c566cb8a1db6c35540525b86c74e7e0c06e75a3581e30276a25eea7f5f0334226e05b54d7d9694ed8f2b881d04a54e60
-  data.tar.gz: 76821f0cad1a918b762bb1d5737f902cc67b726f8dafb0dcf646b5cfc8dd4173527733a8a04e92e71ebea9a152fdb6ebaea20d9ccde3037f32d7fc32f5b05497
+  metadata.gz: 6b1441aab8f7197c23bd84fea750388280ee00036e729f47de13b0113249261f72fb10f01b5e9a78fb2464fcb0ebac5fd07d91eef7d4b5e83fb973b463c0630e
+  data.tar.gz: d9c0401177c9d59900543c7ff5bbae698401fa0dc5ca7e33272458f41eddff2fa61caa501a5735b273f59b44de96e1fc70b0c5a648bb159066f7facd18b5aa82

data/CHANGELOG.md

@@ -9,7 +9,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
----
+### Added
+
+- **`Phronomy::Filter::Base` — unified value filter interface** (#389):
+  A single abstract base class `Filter::Base` with one method `call(value, **context)`
+  covers all three agent boundaries — user input, LLM output, and tool return values.
+  Subclasses return the (possibly transformed) value to continue, or call `block!` /
+  `raise Phronomy::FilterBlockError` to reject.  The same filter instance can be
+  registered at multiple sites.  Guardrails registered via `add_input_guardrail` /
+  `add_output_guardrail` are automatically included at the front of the filter chain.
+
+  ```ruby
+  class PiiMaskFilter < Phronomy::Filter::Base
+    def call(value, **_context)
+      value.to_s.gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    end
+  end
+
+  f = PiiMaskFilter.new
+  agent.add_input_filter(f)
+  agent.add_output_filter(f)
+  agent.add_tool_result_filter(CustomerDataTool, f)
+  ```
+
+  Class-level DSL counterparts: `input_filter`, `output_filter`, `tool_result_filter`.
+  The `tools(Hash)` DSL also accepts a `:result_filter` key for per-tool scoping.
+
+- **`Guardrail::Base#call` — Filter::Base-compatible interface**:
+  `Guardrail::Base` now implements `call(value, **_context)`, which calls `check(value)`
+  and returns the value unchanged (or raises `GuardrailError`).  Existing guardrail
+  subclasses require no changes.
+
+### Changed
+
+- **Guardrail execution unified into the filter chain**:
+  Guardrails registered via `add_input_guardrail` / `add_output_guardrail` now run
+  as the first entries in `run_input_filters!` / `run_output_filters!`.  The separate
+  `run_input_guardrails!` / `run_output_guardrails!` call sites in `invoke_once`,
+  `_stream_impl`, and `Suspendable#resume` have been removed.  Behaviour is unchanged
+  — guardrails still run before any filters and `GuardrailError` still propagates.
+
+
 
 ## [0.10.0] - 2026-06-08
 

data/README.md

@@ -7,7 +7,7 @@
 > We apologise for the instability this may cause.
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Workflows, Agents, Tools, Guardrails, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, Tools, Filters, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
@@ -31,8 +31,8 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
 | **Context Management** — Token budget calculation, estimation, and pruning; `Agent::Base` protected hooks: `build_context` (overridable), `trim_messages`, `trim_to_budget`, `compact_messages`, `budget_exceeded?`, `drop_messages_over` | Stable |
-| **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
-| **`PromptInjectionGuardrail`** — Built-in `InputGuardrail` subclass that detects prompt-injection patterns; usable standalone or as part of a guardrail chain | Beta |
+| **Filters** — Input/output transformation and blocking via `Filter::Base`; call `block!(reason)` to reject and raise `FilterBlockError` | Beta |
+| **`PromptInjectionFilter`** — Built-in `Filter::Base` subclass that detects prompt-injection patterns; usable standalone or as part of a filter chain | Beta |
 | **`Agent::Context::Capability::Base.redact_params` / `.max_result_size`** — Class-level DSL: `redact_params` masks parameter values in log/trace output; `max_result_size` truncates oversized tool results before they reach the LLM | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
@@ -78,6 +78,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **`ScopePolicy`** — Configurable policy callable that maps (tool, scope, agent) to `:allow`/`:approve`/`:reject`; default policy auto-routes high-risk scopes through the approval gate | Experimental |
 | **HITL Checkpoint/Resume** — `Agent::Base#invoke` returns `{ suspended: true, checkpoint: Checkpoint }` when an approval-required tool is encountered without a synchronous handler; `Agent::Base#resume(checkpoint, approved:)` resumes execution; `Agent::Base.resume(checkpoint, approved:)` (class-level) resolves the agent class automatically; `Checkpoint#to_h` / `Checkpoint.from_h` for serialization; `Agent::Base#checkpoint_store=` for custom idempotency backends; `CheckpointAlreadyResumedError` raised on duplicate resume | Experimental |
+| **`Filter::Base` — unified value filter interface** — `Phronomy::Filter::Base` with a single abstract method `call(value, **context)`; apply to user input (`add_input_filter` / `input_filter` DSL), final LLM output (`add_output_filter` / `output_filter` DSL), or individual tool return values (`add_tool_result_filter(tool_class?, filter)` / `tool_result_filter` DSL); filters transform values and return the result, or raise `Phronomy::FilterBlockError` to reject; filter chains are composable; the same filter instance can be reused across all three sites | Beta |
 
 > **Public API boundary**: The tables above are the complete list of classes, modules, and features
 > intended for gem consumers. Every entry has an associated stability label.
@@ -252,30 +253,31 @@ result = OrchestratorAgent.new.invoke("Write a blog post about Ruby 3.4 features
 puts result[:output]
 ```
 
-### Guardrails — Input/output validation
+### Filters — Input/output transformation and blocking
 
-Call `fail!(reason)` inside `check` to reject — it raises `Phronomy::GuardrailError`.
-When a guardrail rejects, `invoke` raises instead of returning an output.
+Filters sit between user input and the LLM (input filters) or between the LLM response and the caller (output filters).
+A filter may **transform** the value (return the modified value) or **block** it (call `block!(reason)`, which raises `Phronomy::FilterBlockError`).
 
 ```ruby
-class NoSensitiveDataGuardrail < Phronomy::Guardrail::InputGuardrail
-  def check(input)
-    fail!("Credit card numbers are not allowed") if input.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+class NoCreditCardFilter < Phronomy::Filter::Base
+  def call(value, **_context)
+    block!("Credit card numbers are not allowed") if value.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+    value
   end
 end
 
 agent = ResearchAgent.new
-agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
+agent.add_input_filter(NoCreditCardFilter.new)
 
 begin
   agent.invoke("Charge 4111-1111-1111-1111")
-rescue Phronomy::GuardrailError => e
+rescue Phronomy::FilterBlockError => e
   puts e.message   # => "Credit card numbers are not allowed"
 end
 ```
 
-> **Note:** Phronomy includes `PromptInjectionGuardrail`, a built-in pattern-based
-> input guardrail that detects common injection patterns (see the feature table above).
+> **Note:** Phronomy includes `PromptInjectionFilter`, a built-in pattern-based
+> input filter that detects common injection patterns (see the feature table above).
 > PII scanning and content classification are **not** provided by the framework;
 > that logic must be implemented by the application. Reference implementations for
 > common patterns are available in `phronomy-examples` (example 06).
@@ -601,14 +603,16 @@ Understanding when to use each prevents scheduler stalls and hidden deadlocks.
 | Context | Recommended API |
 |---------|----------------|
 | Top-level application code, Rails controller, background job | `agent.invoke(input)` — blocks the calling thread until done |
-| Inside a `Runtime#spawn` block, `TaskGroup`, Workflow action, Tool `execute` | `agent.invoke_async(input).await` — non-blocking within the scheduler |
+| Workflow action / EventLoop callback | `agent.invoke_async(input).map { |r| ctx.merge(output: r[:output]) }` — returns a Task and resumes by state transition |
+| Top-level code that wants explicit async | `agent.invoke_async(input).wait_result` — blocks the calling thread until the Task completes |
 
 ### Why this matters
 
 `invoke` is a synchronous wrapper that calls `invoke_async` and then _blocks_ the calling
-thread until the task completes. When called from **inside** an active scheduler task, the
-calling task blocks the scheduler thread, preventing other tasks from making progress — a
-hidden deadlock when all scheduler threads are occupied.
+thread until the task completes.  It is intended for top-level application threads such as
+Rails controller actions, CLI scripts, or background jobs.  Inside EventLoop-driven
+workflow actions, return a Task and let `Task#map` / `Task#on_complete` drive the next
+state transition instead of waiting inside the EventLoop thread.
 
 ### Runtime guard
 
@@ -628,14 +632,21 @@ You can also query the current context directly:
 Phronomy::Runtime.in_scheduler_context?  # => true if called from inside a task
 ```
 
-### Migration: invoke → invoke_async
+### Migration: blocking wait → Task mapping
 
 ```ruby
-# Before (blocks scheduler if called from inside a task)
+# Top-level synchronous use
 result = my_agent.invoke("Hello")
 
-# After (safe inside tasks and TaskGroups)
-result = my_agent.invoke_async("Hello").await
+# Explicit async from top-level code
+result = my_agent.invoke_async("Hello").wait_result
+
+# Workflow action / EventLoop-safe use
+NODE = ->(ctx) {
+  my_agent.invoke_async("Hello").map { |result|
+    ctx.merge(answer: result[:output])
+  }
+}
 ```
 
 ### :immediate backend (synchronous / test mode)
@@ -851,11 +862,11 @@ span attributes by default (`trace_pii: false`). To include full content in trac
 Phronomy configuration. Evaluate whether your tracing backend (OTLP collector, Jaeger,
 Honeycomb, etc.) meets your data-retention and privacy requirements.
 
-**Prompt injection** — Phronomy provides `PromptInjectionGuardrail`, a built-in
-pattern-based input guardrail that detects common injection patterns (ignore/override
+**Prompt injection** — Phronomy provides `PromptInjectionFilter`, a built-in
+pattern-based input filter that detects common injection patterns (ignore/override
 instructions, role-switching phrases, etc.). It is a useful starting point, not a
 comprehensive defence; applications processing untrusted input should layer additional
-custom guardrails as needed (see the Guardrails section above).
+custom filters as needed (see the Filters section above).
 
 **Tool and MCP security** — Tools can perform real-world side effects (database
 writes, API calls, file deletion). Treat tool execution as a privileged operation:

data/benchmark/bench_agent_invoke.rb

@@ -39,6 +39,7 @@ class BenchStubChat
   def with_temperature(_) = self
   def with_cache_instructions(_) = self
   def with_output_schema(_) = self
+  def on_tool_call(&) = self
   def last_message = @response
 
   def ask(_)

data/lib/phronomy/agent/base.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require_relative "checkpoint_store"
 require_relative "concerns/retryable"
-require_relative "concerns/guardrailable"
+require_relative "concerns/filterable"
 require_relative "concerns/before_completion"
-require_relative "concerns/suspendable"
 require_relative "concerns/error_translation"
 
 module Phronomy
@@ -34,9 +32,8 @@ module Phronomy
     class Base
       include Phronomy::Runnable
       include Concerns::Retryable
-      include Concerns::Guardrailable
+      include Concerns::Filterable
       include Concerns::BeforeCompletion
-      include Concerns::Suspendable
       include Concerns::ErrorTranslation
 
       class << self
@@ -376,25 +373,21 @@ module Phronomy
           end
         end
 
-        # Resumes a suspended invocation identified by +checkpoint+ without
-        # requiring the original agent instance to be kept in memory.
+        # Continues a suspended invocation identified by +session_id+.
         #
-        # Validates that the checkpoint was created by this agent class, then
-        # instantiates a fresh agent and delegates to {Suspendable#resume}.
+        # Instantiates a fresh agent and delegates to the instance-level #approve.
+        # When +approved: false+, the agent rejects the pending tool call and ends
+        # the invocation.
         #
-        # @param checkpoint [Phronomy::Agent::Checkpoint]
+        # @param session_id [String] the session_id from the suspended result hash
         # @param approved   [Boolean] +true+ to execute the pending tool; +false+ to deny
         # @param config     [Hash] same runtime options as {#invoke}
         # @return [Hash] same shape as {#invoke} — may contain +suspended: true+ if
         #   another approval-required tool is encountered during continuation
-        # @raise [ArgumentError] when +checkpoint.agent_class+ does not match this class
+        # @raise [ArgumentError] when no suspended session matches +session_id+
         # @api public
-        def resume(checkpoint, approved:, config: {})
-          if checkpoint.agent_class && checkpoint.agent_class != name
-            raise ArgumentError,
-              "checkpoint belongs to #{checkpoint.agent_class}, cannot resume with #{name}"
-          end
-          new.resume(checkpoint, approved: approved, config: config)
+        def approve(session_id, approved: true, config: {})
+          new.approve(session_id, approved: approved, config: config)
         end
       end
 
@@ -416,9 +409,38 @@ module Phronomy
         @_handoff_tools || []
       end
 
+      # Registers a synchronous approval callback that is invoked before
+      # executing any tool that has +requires_approval true+ set.
+      # The block receives the tool name (String) and the arguments Hash, and
+      # must return a truthy value to allow execution.
+      # Returning a falsy value causes the tool to return a denial message.
+      #
+      # When no handler is registered and a tool with +requires_approval+ is
+      # called, #invoke returns a suspended result hash containing a
+      # +session_id+. Call #approve to continue execution.
+      #
+      # @example
+      #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
+      # @return [self]
+      # @api public
+      def on_approval_required(&block)
+        @approval_handler = block
+        self
+      end
+
+      # Registers a scope policy callable for this agent instance.
+      #
+      # The callable receives +(tool_class, scope, agent)+ and must return
+      # +:allow+, +:reject+, or +:approve+.
+      #
+      # @param policy [#call]
+      # @return [void]
+      # @api public
+      attr_writer :scope_policy
+
       # Invokes the agent with the given input and returns a result Hash.
       # Applies the retry policy configured via {.retry_policy} when transient
-      # errors occur. {Phronomy::GuardrailError} is never retried.
+      # errors occur. {Phronomy::FilterBlockError} is never retried.
       #
       # @param input     [String, Hash] the user message; a Hash may supply
       #   +:message+, +:query+, or +:user+ as the text key, plus any template
@@ -439,7 +461,7 @@ module Phronomy
       # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
       #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
       #   messages: Array }+ when the invocation was suspended awaiting tool approval.
-      # @raise [Phronomy::GuardrailError] when an input or output guardrail rejects the value
+      # @raise [Phronomy::FilterBlockError] when an input or output filter rejects the value
       # @example Normal invocation
       #   result = MyAgent.new.invoke("What is Ruby?")
       #   puts result[:output]
@@ -468,7 +490,10 @@ module Phronomy
 
         timeout_sec = self.class.invoke_timeout
         unless timeout_sec
-          return invoke_async(input, messages: messages, thread_id: thread_id, config: config).await
+          return trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
+            result = invoke_async(input, messages: messages, thread_id: thread_id, config: config).wait_result
+            [result, result[:usage]]
+          end
         end
 
         # invoke_timeout: create a CancellationScope with deadline, pass its token
@@ -482,7 +507,7 @@ module Phronomy
         # Bridge the task result to an AsyncQueue so scope.pop_queue can observe the deadline.
         completion_queue = Phronomy::Concurrency::AsyncQueue.new
         Phronomy::Runtime.instance.spawn(name: "invoke-timeout-bridge:#{(self.class.name || "agent").downcase}") do
-          completion_queue.push(task.await)
+          completion_queue.push(task.wait_result)
         rescue => e
           completion_queue.push(e)
         end
@@ -508,7 +533,7 @@ module Phronomy
       #
       # @example
       #   task = agent.invoke_async("Hello!")
-      #   result = task.await   # => { output: "...", messages: [...], usage: ... }
+      #   result = task.wait_result   # => { output: "...", messages: [...], usage: ... }
       #
       # @param input    [String, Hash]
       # @param messages [Array]
@@ -524,11 +549,11 @@ module Phronomy
         bp = Phronomy.configuration.backpressure
         on_full = (bp == :raise) ? :reject : (bp || :wait)
         bp_timeout = Phronomy.configuration.backpressure_timeout
+        result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
         gate = Phronomy::Runtime.instance.gate(:agent)
-        Phronomy::Runtime.instance.spawn(name: "agent-#{(self.class.name || "anonymous").downcase}-async") do
-          gate.acquire(on_full: on_full, timeout: bp_timeout) do
-            _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
-          end
+        gate.acquire(on_full: on_full, timeout: bp_timeout) do
+          _start_invoke_attempt(result_task, input, messages: messages, thread_id: thread_id, config: config, attempt: 0)
+          return result_task
         end
       end
 
@@ -603,7 +628,7 @@ module Phronomy
       # Streaming implementation for #stream.
       def _stream_impl(input, messages: [], thread_id: nil, config: {}, &block)
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
+          input = run_input_filters!(input)
 
           chat = build_chat
           user_message = extract_message(input)
@@ -634,7 +659,7 @@ module Phronomy
           run_before_completion_hooks!(chat, config)
 
           output, usage = _drain_stream(chat, user_message, config, &block)
-          run_output_guardrails!(output)
+          output = run_output_filters!(output)
 
           result = {output: output, messages: chat.messages, usage: usage}
           block.call(StreamEvent.new(type: :done, payload: result))
@@ -809,34 +834,154 @@ module Phronomy
       end
       protected :instance_knowledge_chunks
 
-      # Performs a single (non-retried) invocation. Extracted so that #invoke can
-      # wrap it in a retry loop without duplicating the LLM interaction logic.
-      def invoke_once(input, messages: [], thread_id: nil, config: {})
-        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
-
-          user_message = extract_message(input)
-          chat = build_chat
-          context = build_context(
-            input,
-            messages: messages, thread_id: thread_id, config: config,
-            budget: build_token_budget, instruction: build_instructions(input),
-            tools: self.class.tools + _handoff_tools
+      # Runs the agent invocation through the FSM-based execution engine.
+      # Called by Retryable#_invoke_impl (which wraps it in a retry loop).
+      # Returns the result hash: { output:, messages:, usage: } on success,
+      # or { suspended: true, session_id:, messages: } when awaiting approval.
+      # @api private
+      def _invoke_via_fsm(input, messages: [], thread_id: nil, config: {})
+        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
+        # Fail fast when the token is already cancelled before any LLM call.
+        check_cancellation!(effective_config, "invocation cancelled")
+        # Ensure EventLoop is running. start is idempotent when already alive.
+        Phronomy::EventLoop.instance.start
+        trace("agent.invoke", input: input, **_build_caller_meta(effective_config)) do |_span|
+          session = Agent::InvocationSession.build(
+            agent: self,
+            input: input,
+            messages: messages,
+            config: effective_config
           )
-          _apply_context_to_chat(chat, context)
+          completion_queue = Phronomy::EventLoop.instance.register(session)
+          ctx = completion_queue.pop
+          raise ctx if ctx.is_a?(Exception)
+          result = _extract_invoke_result(ctx, session.id)
+          [result, result[:usage]]
+        end
+      end
 
-          run_before_completion_hooks!(chat, config)
-          _register_suspension_hook!(chat)
-          check_cancellation!(config, "invocation cancelled before LLM call")
+      # Starts a single invocation attempt and wires retry/translation onto result_task.
+      # Non-blocking: registers with EventLoop and returns immediately.
+      # On error, retries via timer_queue when policy allows; otherwise translates
+      # and resolves result_task as failed.
+      # @api private
+      def _start_invoke_attempt(result_task, input, messages:, thread_id:, config:, attempt:)
+        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
+        check_cancellation!(effective_config, "invocation cancelled")
+        Phronomy::EventLoop.instance.start
+        session = Agent::InvocationSession.build(
+          agent: self,
+          input: input,
+          messages: messages,
+          config: effective_config
+        )
+        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-attempt-#{attempt}")
+        Phronomy::EventLoop.instance.register(session, completion: source_task)
+        session_id = session.id
+        policy = self.class._retry_policy
+
+        source_task.on_complete do |ctx, error|
+          retriable = error &&
+            !error.is_a?(Phronomy::FilterBlockError) &&
+            !error.is_a?(Phronomy::CancellationError) &&
+            policy && attempt < policy[:times]
+
+          if retriable
+            wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
+            # Call _sleep_proc for instrumentation (test spy records the duration;
+            # in production this is a no-op since timer_queue handles the actual delay).
+            self.class._sleep_proc.call(wait) if wait > 0
+            do_retry = -> {
+              _start_invoke_attempt(
+                result_task, input,
+                messages: messages, thread_id: thread_id, config: config,
+                attempt: attempt + 1
+              )
+            }
+            if wait > 0
+              Phronomy::Runtime.instance.timer_queue.schedule(seconds: wait, &do_retry)
+            else
+              do_retry.call
+            end
+          elsif error
+            begin
+              translate_and_reraise!(error)
+            rescue => translated
+              result_task.backend.unblock(nil, translated)
+              result_task.transition!(:failed, error: translated)
+            end
+          else
+            begin
+              result = _extract_invoke_result(ctx, session_id)
+              result_task.backend.unblock(result, nil)
+              result_task.transition!(:completed, value: result)
+            rescue => e
+              result_task.backend.unblock(nil, e)
+              result_task.transition!(:failed, error: e)
+            end
+          end
+        end
+      rescue => e
+        result_task.backend.unblock(nil, e)
+        result_task.transition!(:failed, error: e)
+      end
 
-          result, usage = _complete_with_suspension_guard(
-            chat, user_message, config,
-            thread_id: thread_id, original_input: input
-          )
-          next [result, usage] if result[:suspended]
+      # Continues a suspended invocation identified by +session_id+.
+      # When +approved: true+, executes the pending tool and continues.
+      # When +approved: false+, rejects the tool call and ends the invocation.
+      #
+      # @param session_id [String]
+      # @param approved   [Boolean]
+      # @param config     [Hash]
+      # @return [Hash]
+      # @api public
+      def approve(session_id, approved: true, config: {})
+        ctx = Agent::SuspendedSessionRegistry.fetch(session_id)
+        raise ArgumentError, "No suspended session found: #{session_id}" unless ctx
+
+        # Reset approval_required so executing_tool_action proceeds instead of
+        # re-suspending when called after the :approve FSM transition.
+        ctx.approval_required = false
+        ctx.approved = true if approved  # signals executing_tool to run the tool
+        ctx.rejected = !approved  # signals _extract_invoke_result for rejection
+
+        if approved
+          _resume_fsm(ctx, :approve)
+        else
+          _resume_fsm(ctx, :reject)
+        end
+      end
+      public :approve
 
-          run_output_guardrails!(result[:output])
-          [result, usage]
+      # Builds and runs a resume FSMSession for the given context and event.
+      # @api private
+      def _resume_fsm(ctx, event)
+        session = Agent::InvocationSession.build_for_resume(
+          agent: self,
+          context: ctx,
+          resume_event: event,
+          resume_phase: :awaiting_approval
+        )
+        completion_queue = Phronomy::EventLoop.instance.register(session)
+        resumed_ctx = completion_queue.pop
+        raise resumed_ctx if resumed_ctx.is_a?(Exception)
+        _extract_invoke_result(resumed_ctx, session.id)
+      end
+
+      # Interprets the InvocationContext after FSM completion/halt and returns
+      # the appropriate result hash or raises the block error.
+      # @api private
+      def _extract_invoke_result(ctx, session_id)
+        if ctx.phase == :awaiting_approval
+          Agent::SuspendedSessionRegistry.store(session_id, ctx)
+          {suspended: true, session_id: session_id, messages: ctx.messages}
+        elsif ctx.input_blocked? || ctx.output_blocked?
+          raise ctx.block_error
+        elsif ctx.rejected
+          # Rejected path: :reject event → :blocked terminal
+          {rejected: true, messages: ctx.messages}
+        else
+          {output: ctx.output, messages: ctx.messages, usage: ctx.usage}
         end
       end
 
@@ -857,36 +1002,6 @@ module Phronomy
         context[:messages].each { |msg| chat.messages << msg }
       end
 
-      # Submits the LLM call via LLMAdapter and handles SuspendSignal.
-      # Sets/clears the chat cancellation token around the call so that
-      # ParallelToolChat can observe cancellation without Thread.current.
-      # Returns [result_hash, usage_or_nil].
-      def _complete_with_suspension_guard(chat, user_message, config, thread_id:, original_input:)
-        chat.cancellation_token = config[:cancellation_token] if chat.respond_to?(:cancellation_token=)
-        begin
-          adapter = Phronomy.configuration.llm_adapter
-          response = adapter.complete_async(chat, user_message, config: config).await
-        rescue SuspendSignal => signal
-          checkpoint = Checkpoint.new(
-            checkpoint_id: SecureRandom.uuid,
-            agent_class: self.class.name,
-            requested_at: Time.now.utc,
-            thread_id: thread_id,
-            original_input: original_input,
-            messages: chat.messages.dup,
-            pending_tool_name: signal.tool_name,
-            pending_tool_args: signal.args,
-            pending_tool_call_id: signal.tool_call_id
-          )
-          return [{output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}, nil]
-        ensure
-          chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
-        end
-        output = response.content
-        usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-        [{output: output, messages: chat.messages, usage: usage}, usage]
-      end
-
       def _drain_stream(chat, user_message, config, &block)
         adapter = Phronomy.configuration.llm_adapter
         chunk_queue = Phronomy::Concurrency::AsyncQueue.new(max_size: Phronomy.configuration.stream_queue_max_size)
@@ -899,7 +1014,7 @@ module Phronomy
           check_cancellation!(config, "invocation cancelled during streaming")
         end
 
-        response = pending.await
+        response = pending.blocking_wait
         [response.content, Phronomy::TokenUsage.from_tokens(response.tokens)]
       end
 
@@ -1076,21 +1191,34 @@ module Phronomy
         end
 
         # Step 3: wrap with approval gate when handler is registered.
-        return resolved unless resolved.requires_approval && @approval_handler
+        if resolved.requires_approval && @approval_handler
+          handler = @approval_handler
+          # Capture the effective tool name before building the anonymous subclass.
+          # Class-level instance variables (@tool_name) are not inherited through
+          # subclassing, so the wrapper must set it explicitly.
+          effective_name = resolved.new.name
+          resolved = Class.new(resolved) do
+            tool_name effective_name
+            define_method(:call) do |args|
+              if handler.call(name, args)
+                super(args)
+              else
+                "Tool execution denied."
+              end
+            end
+          end
+        end
 
-        handler = @approval_handler
-        # Capture the effective tool name before building the anonymous subclass.
-        # Class-level instance variables (@tool_name) are not inherited through
-        # subclassing, so the wrapper must set it explicitly.
-        effective_name = resolved.new.name
+        # Step 4: wrap with tool result filters when registered.
+        result_filters = _tool_result_filters_for(tool_class)
+        return resolved if result_filters.empty?
+
+        effective_name4 = resolved.new.name
         Class.new(resolved) do
-          tool_name effective_name
+          tool_name effective_name4
           define_method(:call) do |args|
-            if handler.call(name, args)
-              super(args)
-            else
-              "Tool execution denied."
-            end
+            result = super(args)
+            result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
           end
         end
       end

data/lib/phronomy/agent/concerns/error_translation.rb

@@ -36,7 +36,7 @@ module Phronomy
           when RubyLLM::Error
             raise Phronomy::TransportError, error.message
           else
-            raise # bare re-raise preserves $! and its backtrace unchanged
+            raise error # preserve original class, message, and backtrace
           end
         end
       end