phronomy 0.14.0 → 0.15.1

data/lib/phronomy/agent/base.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require_relative "concerns/retryable"
 require_relative "concerns/filterable"
 require_relative "concerns/before_completion"
 require_relative "concerns/error_translation"
@@ -12,7 +11,7 @@ module Phronomy
     #
     # Subclass this to create a conversational agent powered by an LLM.
     # DSL class methods configure the model, instructions, tools, memory,
-    # and retry behaviour. Instance methods handle invocation.
+    # and execution hooks. Instance methods handle invocation.
     #
     # @example Minimal agent
     #   class GreetingAgent < Phronomy::Agent::Base
@@ -31,11 +30,13 @@ module Phronomy
     #   end
     class Base
       include Phronomy::Runnable
-      include Concerns::Retryable
       include Concerns::Filterable
       include Concerns::BeforeCompletion
       include Concerns::ErrorTranslation
 
+      APPROVAL_CONFIGURATION_INIT_MUTEX = Mutex.new
+      private_constant :APPROVAL_CONFIGURATION_INIT_MUTEX
+
       class << self
         # Sets or reads the LLM model identifier for this agent.
         # When called without an argument, returns the stored model or the
@@ -187,66 +188,6 @@ module Phronomy
           end
         end
 
-        # Sets or reads the maximum number of tool calls executed concurrently
-        # when the LLM returns multiple tool calls in a single response
-        # (ParallelToolChat mode, active inside an AgentFSM IO thread).
-        #
-        # Defaults to 10. Set to 1 to force sequential execution.
-        # Inherited by subclasses; the most-specific definition wins.
-        #
-        # @param val [Integer, nil]
-        # @return [Integer]
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     max_parallel_tools 4
-        #   end
-        # @api public
-        def max_parallel_tools(val = nil)
-          if val.nil?
-            @max_parallel_tools ||
-              (superclass.respond_to?(:max_parallel_tools) ? superclass.max_parallel_tools : 10)
-          else
-            unless val.is_a?(Integer) && val >= 1
-              raise ArgumentError,
-                "max_parallel_tools must be a positive Integer (>= 1), got #{val.inspect}"
-            end
-            @max_parallel_tools = val
-          end
-        end
-
-        # Sets or reads the per-invocation timeout (in seconds) for EventLoop-mode
-        # agent calls.  When set, +invoke+ raises {Phronomy::TimeoutError} if the
-        # agent does not finish within the given number of seconds.
-        #
-        # Has no effect when EventLoop mode is disabled (direct invoke path).
-        # Defaults to +nil+ (no timeout).
-        # Inherited by subclasses; the most-specific definition wins.
-        #
-        # When the timeout fires, a {Phronomy::Concurrency::CancellationScope} is cancelled
-        # and its token is propagated to the FSM config so that in-flight LLM,
-        # tool, and RAG calls observe cancellation via their +cancellation_token:+
-        # keyword argument.  +Phronomy::TimeoutError+ is raised to the caller.
-        #
-        # @param val [Numeric, nil]
-        # @return [Numeric, nil]
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     invoke_timeout 30
-        #   end
-        # @api public
-        def invoke_timeout(val = nil)
-          if val.nil?
-            return @invoke_timeout if defined?(@invoke_timeout)
-            superclass.respond_to?(:invoke_timeout) ? superclass.invoke_timeout : nil
-          else
-            unless val.is_a?(Numeric) && val > 0
-              raise ArgumentError,
-                "invoke_timeout must be a positive number, got #{val.inspect}"
-            end
-            @invoke_timeout = val
-          end
-        end
-
         # Registers one or more static knowledge sources on the agent class.
         # Static source content is fetched and memoized at the **class** level
         # the first time +invoke+ is called. The cache persists for the lifetime
@@ -373,21 +314,35 @@ module Phronomy
           end
         end
 
-        # Continues a suspended invocation identified by +session_id+.
-        #
-        # 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 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 no suspended session matches +session_id+
+        # Continues a suspended AgentInvocation.
+        # @param agent_invocation_id [String]
+        # @param approval_request_id [String]
+        # @param approved [Boolean]
+        # @param config [Hash]
+        # @api public
+        def approve(agent_invocation_id, approval_request_id:, approved: true, config: {})
+          new.approve(
+            agent_invocation_id,
+            approval_request_id: approval_request_id,
+            approved: approved,
+            config: config
+          )
+        end
+
+        # Continues a suspended AgentInvocation without blocking the caller.
+        # @param agent_invocation_id [String]
+        # @param approval_request_id [String]
+        # @param approved [Boolean]
+        # @param config [Hash]
+        # @return [Phronomy::Task]
         # @api public
-        def approve(session_id, approved: true, config: {})
-          new.approve(session_id, approved: approved, config: config)
+        def approve_async(agent_invocation_id, approval_request_id:, approved: true, config: {})
+          new.approve_async(
+            agent_invocation_id,
+            approval_request_id: approval_request_id,
+            approved: approved,
+            config: config
+          )
         end
       end
 
@@ -409,172 +364,26 @@ 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) }
+      # Registers the final Agent/Application authorization policy.
+      # The block runs on the Runtime authorization pool and must return
+      # :allow, :require_approval, or :reject.
       # @return [self]
       # @api public
-      def on_approval_required(&block)
-        @approval_handler = block
-        self
-      end
+      def tool_approval_policy(&block)
+        raise ArgumentError, "tool_approval_policy requires a block" unless block
 
-      # 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::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
-      #   variables consumed by the configured instructions template.
-      # @param messages  [Array<RubyLLM::Message>] conversation history from a
-      #   previous invocation. The application owns and persists this array;
-      #   pass it on every turn to maintain multi-turn context.
-      # @param thread_id [String, nil] conversation thread identifier, forwarded
-      #   to the compaction context when on_compact is configured.
-      # @param config    [Hash] additional runtime options:
-      #   +:user_id+    (+String+, optional) — caller identity forwarded to the tracer
-      #   +:session_id+ (+String+, optional) — session identity forwarded to the tracer
-      # @param invocation_context [Phronomy::InvocationContext, nil] optional first-class context
-      #   object.  When present, +thread_id+, +cancellation_token+, and +deadline+ are
-      #   derived from it (existing +config:+ keys take precedence as backward-compat
-      #   aliases).  The object is also stored in +config[:invocation_context]+ so that
-      #   +task_id+ / +parent_task_id+ appear in trace spans automatically.
-      # @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::FilterBlockError] when an input or output filter rejects the value
-      # @example Normal invocation
-      #   result = MyAgent.new.invoke("What is Ruby?")
-      #   puts result[:output]
-      # @example Multi-turn conversation
-      #   result1 = agent.invoke("Hi, I'm Alice.")
-      #   result2 = agent.invoke("What's my name?", messages: result1[:messages])
-      # @example Suspend / resume flow
-      #   result = agent.invoke("Perform task X")
-      #   if result[:suspended]
-      #     result = agent.resume(result[:checkpoint], approved: true)
-      #   end
-      #   puts result[:output]
-      # @example With InvocationContext (deadline-based timeout)
-      #   ctx = Phronomy::InvocationContext.new(
-      #     thread_id: "conv-123",
-      #     deadline: Phronomy::Concurrency::Deadline.in(30),
-      #     task_id: SecureRandom.uuid
-      #   )
-      #   result = MyAgent.new.invoke("Hello", invocation_context: ctx)
-      # @api public
-      def invoke(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        _check_scheduler_reentrancy
-
-        timeout_sec = self.class.invoke_timeout
-        unless timeout_sec
-          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
-        # to the async invocation, and use scope.pop_queue so the calling thread
-        # unblocks as soon as either the result arrives or the deadline fires.
-        scope = Phronomy::Concurrency::CancellationScope.new(parent_token: config[:cancellation_token])
-        scope.deadline_in(timeout_sec)
-        effective_config = config.merge(cancellation_token: scope.token)
-        task = invoke_async(input, messages: messages, thread_id: thread_id, config: effective_config)
-
-        # 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.wait_result)
-        rescue => e
-          completion_queue.push(e)
-        end
-
-        result = scope.pop_queue(completion_queue) do
-          raise Phronomy::TimeoutError,
-            "Agent #{self.class.name} invoke timed out after #{timeout_sec}s"
-        end
-        raise result if result.is_a?(Exception)
-        result
-      end
-
-      # Invokes this agent asynchronously and returns a {Phronomy::Task}.
-      #
-      # This is the primary async entry point.  {#invoke} is a synchronous wrapper
-      # that calls this method and blocks the caller until the task completes.
-      # Calling {#invoke} from inside an active scheduler task raises
-      # {Phronomy::SchedulerReentrancyError}; use +invoke_async+ directly in that
-      # context.
-      #
-      # The task is registered with the Runtime task registry so {Runtime#shutdown}
-      # drains in-flight invocations before process exit.
-      #
-      # @example
-      #   task = agent.invoke_async("Hello!")
-      #   result = task.wait_result   # => { output: "...", messages: [...], usage: ... }
-      #
-      # @param input    [String, Hash]
-      # @param messages [Array]
-      # @param thread_id [String, nil]
-      # @param config   [Hash]
-      # @param invocation_context [Phronomy::InvocationContext, nil]
-      # @return [Phronomy::Task]
-      # @api public
-      def invoke_async(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
-        _start_invoke_attempt(result_task, input, messages: messages, thread_id: thread_id, config: config, attempt: 0)
-        result_task
+        _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
+        self
       end
 
-      # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
-      # as they are produced by the underlying LLM.
-      #
-      # Events emitted (in order):
-      #   :token       — each content delta from the LLM
-      #   :tool_call   — when the LLM requests a tool
-      #   :tool_result — after a tool completes
-      #   :done        — final event carrying output, messages, and usage
-      #   :error       — if an unrecoverable error occurs
-      #
-      # @param input     [String, Hash] same as #invoke
-      # @param messages  [Array<RubyLLM::Message>] same as #invoke
-      # @param thread_id [String, nil] same as #invoke
-      # @param config    [Hash]        same as #invoke
-      # @yield [Phronomy::Agent::StreamEvent]
-      # @return [Hash] { output:, messages:, usage: } — same as #invoke
+      # Registers a non-blocking Application notification listener.
+      # @return [self]
       # @api public
-      def stream(input, messages: [], thread_id: nil, config: {}, &block)
-        return invoke(input, messages: messages, thread_id: thread_id, config: config) unless block
+      def on_tool_approval_required(&block)
+        raise ArgumentError, "on_tool_approval_required requires a block" unless block
 
-        _stream_impl(input, messages: messages, thread_id: thread_id, config: config, &block)
-      rescue => e
-        block&.call(StreamEvent.new(type: :error, payload: {error: e}))
-        raise
+        _approval_configuration_mutex.synchronize { @tool_approval_listener = block }
+        self
       end
 
       # @deprecated The context version cache has been removed. Returns nil.
@@ -604,12 +413,18 @@ module Phronomy
         [effective_thread_id, effective_config]
       end
 
-      def _check_scheduler_reentrancy
+      def _check_scheduler_reentrancy(sync_method, async_method)
+        if Phronomy::Runtime.instance.event_loop.current?
+          raise Phronomy::SchedulerReentrancyError,
+            "#{self.class.name}##{sync_method} cannot run on the EventLoop thread. " \
+            "Use #{async_method} and return immediately."
+        end
+
         return unless Phronomy::Task.current
 
-        msg = "#{self.class.name}#invoke called from inside a scheduler task. " \
+        msg = "#{self.class.name}##{sync_method} called from inside a scheduler task. " \
           "This blocks the scheduler until the inner invocation completes, preventing " \
-          "other tasks from making progress. Use invoke_async + await instead."
+          "other tasks from making progress. Use #{async_method} + await instead."
         if Phronomy.configuration.strict_runtime_guards
           raise Phronomy::SchedulerReentrancyError, msg
         elsif Phronomy.configuration.logger
@@ -619,48 +434,6 @@ module Phronomy
         end
       end
 
-      # 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|
-          input = run_input_filters!(input)
-
-          chat = build_chat
-          user_message = extract_message(input)
-          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
-          )
-          _apply_context_to_chat(chat, context)
-
-          current_tool_call = nil
-          chat.on_tool_call do |tool_call|
-            current_tool_call = tool_call
-            block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tool_call}))
-          end
-          chat.on_tool_result do |tool_result|
-            block.call(StreamEvent.new(type: :tool_result, payload: {
-              tool_call_id: current_tool_call&.id,
-              tool_name: current_tool_call&.name,
-              tool_result: tool_result
-            }))
-          end
-
-          run_before_completion_hooks!(chat, config)
-
-          output, usage = _drain_stream(chat, user_message, config, &block)
-          output = run_output_filters!(output)
-
-          result = {output: output, messages: chat.messages, usage: usage}
-          block.call(StreamEvent.new(type: :done, payload: result))
-          [result, usage]
-        end
-      end
-
       # Assembles the LLM context (system prompt + conversation messages)
       # for a single invocation. Subclasses may override this method to
       # inject custom context editing logic without having to override
@@ -828,160 +601,202 @@ module Phronomy
       end
       protected :instance_knowledge_chunks
 
-      # 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")
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        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,
-            runtime: runtime
+      def _complete_result_task(task, result)
+        task.backend.unblock(result, nil)
+        task.transition!(:completed, value: result)
+      end
+
+      def _fail_result_task(task, error)
+        task.backend.unblock(nil, error)
+        task.transition!(:failed, error: error)
+      end
+
+      def _translated_error(error)
+        translate_and_reraise!(error)
+      rescue => translated
+        translated
+      end
+
+      def _build_stream_terminal_event(result)
+        if result[:suspended]
+          StreamEvent.new(
+            type: :approval_required,
+            payload: {request: result[:approval_request]}
           )
-          completion_queue = event_loop.register(session)
-          ctx = completion_queue.pop
-          raise ctx if ctx.is_a?(Exception)
-          result = _extract_invoke_result(ctx, session.id)
-          [result, result[:usage]]
+        else
+          StreamEvent.new(type: :done, payload: result)
         end
       end
 
-      # 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")
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        session = Agent::InvocationSession.build(
-          agent: self,
-          input: input,
-          messages: messages,
-          config: effective_config,
-          runtime: runtime
+      # Returns the Application exception instead of allowing it to escape the
+      # shared EventLoop. A nil return means delivery succeeded or no listener
+      # was registered.
+      def _deliver_stream_event(listener, event)
+        return unless listener
+
+        listener.call(event)
+        nil
+      rescue => callback_error
+        callback_error
+      end
+
+      def _build_stream_callback_error(event_type:, callback_error:, result:)
+        wrapped = Phronomy::StreamCallbackError.new(
+          event_type: event_type,
+          original_error: callback_error,
+          result: result
         )
-        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-attempt-#{attempt}")
-        event_loop.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
+
+        begin
+          raise wrapped, cause: callback_error
+        rescue Phronomy::StreamCallbackError => error
+          error.set_backtrace(callback_error.backtrace)
+          error
+        end
+      end
+
+      def _report_stream_callback_error(callback_error, event:, invocation_id:,
+        callback_error_policy:)
+        lines = [
+          "[Phronomy] Stream callback failed",
+          "event=#{event.type.inspect}",
+          "agent_invocation_id=#{invocation_id || "unknown"}",
+          "policy=#{callback_error_policy.inspect}",
+          "error=#{callback_error.class}: #{callback_error.message}"
+        ]
+        Array(callback_error.backtrace).each { |line| lines << "  #{line}" }
+        _warn_stream_callback_error(lines.join("\n"))
+      rescue => reporting_error
+        _kernel_warn_safely(
+          "[Phronomy] Failed to report stream callback error: " \
+            "#{reporting_error.class}: #{reporting_error.message}"
+        )
+      end
+
+      def _warn_stream_callback_error(message)
+        logger = Phronomy.configuration.logger
+        unless logger
+          _kernel_warn_safely(message)
+          return
         end
-      rescue => e
-        result_task.backend.unblock(nil, e)
-        result_task.transition!(:failed, error: e)
+
+        logger.warn(message)
+      rescue => logger_error
+        _kernel_warn_safely(
+          "#{message}\n" \
+            "[Phronomy] Logger failed while reporting a stream callback error: " \
+            "#{logger_error.class}: #{logger_error.message}"
+        )
       end
 
-      # 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]
+      def _kernel_warn_safely(message)
+        Kernel.warn(message)
+      rescue
+        nil
+      end
+
+      # Continues a suspended AgentInvocation. The parent session is registered
+      # asynchronously; this method is only the synchronous wrapper.
       # @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
+      def approve(agent_invocation_id, approval_request_id:, approved: true, config: {})
+        _check_scheduler_reentrancy(:approve, :approve_async)
+        approve_async(
+          agent_invocation_id,
+          approval_request_id: approval_request_id,
+          approved: approved,
+          config: config
+        ).wait_result
       end
       public :approve
 
-      # Builds and runs a resume FSMSession for the given context and event.
-      # @api private
-      def _resume_fsm(ctx, event)
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        session = Agent::InvocationSession.build_for_resume(
-          agent: self,
-          context: ctx,
-          resume_event: event,
-          resume_phase: :awaiting_approval,
-          runtime: runtime
+      # Continues a suspended AgentInvocation without blocking the caller.
+      #
+      # This method is safe to call from an EventLoop stream callback. The
+      # returned Task completes when the resumed AgentInvocation finishes,
+      # suspends again, or fails.
+      # @return [Phronomy::Task]
+      # @api public
+      def approve_async(agent_invocation_id, approval_request_id:, approved: true, config: {})
+        result_task = Phronomy::Task.deferred(
+          name: "agent-approval-resume:#{agent_invocation_id}"
         )
-        completion_queue = event_loop.register(session)
-        resumed_ctx = completion_queue.pop
-        raise resumed_ctx if resumed_ctx.is_a?(Exception)
-        _extract_invoke_result(resumed_ctx, session.id)
+
+        begin
+          entry = Agent::AgentInvocationRegistry.consume_approval(
+            agent_invocation_id, approval_request_id
+          )
+          unless entry
+            raise ArgumentError,
+              "No pending approval found for AgentInvocation #{agent_invocation_id}"
+          end
+
+          _start_approval_resume(
+            result_task,
+            entry.invocation,
+            approved: approved,
+            config: config
+          )
+        rescue => e
+          _fail_result_task(result_task, e)
+        end
+
+        result_task
+      end
+      public :approve_async
+
+      def _extract_invoke_result(invocation)
+        if invocation.phase == :suspended
+          request = invocation.approval_request
+          Agent::AgentInvocationRegistry.store_suspended(invocation, request)
+          _dispatch_tool_approval_notification(invocation, request)
+          {
+            suspended: true,
+            agent_invocation_id: invocation.id,
+            approval_request: request,
+            messages: invocation.messages
+          }
+        elsif invocation.input_blocked? || invocation.output_blocked?
+          raise invocation.block_error
+        elsif invocation.error
+          raise invocation.error
+        elsif invocation.rejected
+          {rejected: true, messages: invocation.messages}
+        else
+          {output: invocation.output, messages: invocation.messages, usage: invocation.usage}
+        end
       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}
+      def _dispatch_tool_approval_notification(invocation, request)
+        listener = invocation.approval_listener
+        return unless listener
+
+        Phronomy::Runtime.instance.blocking_io.submit(on_full: :raise) do
+          listener.call(request)
+        end
+      rescue => e
+        message = "[Phronomy] Tool approval notification failed: #{e.class}: #{e.message}"
+        if Phronomy.configuration.logger
+          Phronomy.configuration.logger.warn(message)
         else
-          {output: ctx.output, messages: ctx.messages, usage: ctx.usage}
+          Kernel.warn(message)
+        end
+      end
+
+      def _approval_configuration_mutex
+        return @approval_configuration_mutex if @approval_configuration_mutex
+
+        APPROVAL_CONFIGURATION_INIT_MUTEX.synchronize do
+          @approval_configuration_mutex ||= Mutex.new
+        end
+      end
+
+      def _approval_configuration_snapshot(invocation_listener = nil)
+        _approval_configuration_mutex.synchronize do
+          {
+            policy: @tool_approval_policy,
+            listener: invocation_listener || @tool_approval_listener
+          }.freeze
         end
       end
 
@@ -1002,22 +817,6 @@ module Phronomy
         context[:messages].each { |msg| chat.messages << msg }
       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)
-        pending = adapter.stream_async(chat, user_message, config: config, enqueue_to: chunk_queue)
-
-        loop do
-          chunk = chunk_queue.pop
-          break if chunk.nil?
-          block.call(StreamEvent.new(type: :token, payload: {content: chunk.content}))
-          check_cancellation!(config, "invocation cancelled during streaming")
-        end
-
-        response = pending.blocking_wait
-        [response.content, Phronomy::TokenUsage.from_tokens(response.tokens)]
-      end
-
       # Builds a TokenBudget for this agent's model if possible.
       # When context_window is set at the class level, that value is used directly
       # (bypassing the RubyLLM catalogue) — useful for locally-hosted models where
@@ -1065,7 +864,7 @@ module Phronomy
         t = self.class.temperature
         parallel_class = build_chat_class
         chat = if parallel_class
-          parallel_class.new(max_parallel_tools: self.class.max_parallel_tools, **opts)
+          parallel_class.new(**opts)
         else
           RubyLLM.chat(**opts)
         end
@@ -1126,33 +925,12 @@ module Phronomy
         raise Phronomy::CancellationError, message if ct&.cancelled?
       end
 
-      # Builds the final tool class to register with the chat.
-      #
-      # When an already-instantiated tool object is passed (e.g. a
-      # {Phronomy::Tools::Mcp} returned by +Phronomy::Tools::Mcp.from_server+), it is
-      # returned as-is.  RubyLLM's +with_tool+ accepts both classes and
-      # instances, so no wrapping is needed.
-      #
-      # For tool classes, three transformations are applied in order:
-      #   1. Alias override — when the Hash form of .tools maps this class to an
-      #      explicit name, an anonymous subclass with that tool_name is returned.
-      #   2. Scope policy   — when a scope is declared on the tool, the configured
-      #      {Phronomy::Agent::Context::Capability::ScopePolicy} (or the default) is evaluated.
-      #      +:reject+ wraps the tool to return a denial message without executing.
-      #      +:approve+ behaves like requiring approval (same as step 3 when the
-      #      tool does not already have +requires_approval+).
-      #   3. Approval gate  — when the tool class has +requires_approval+ set AND
-      #      an approval handler has been registered via #on_approval_required,
-      #      the tool's #call method is wrapped: the handler is invoked with
-      #      (tool_name, args) and, if it returns falsy, the tool returns a denial
-      #      message instead of executing.
+      # Builds the final Tool class to register with RubyLLM. Alias and Tool
+      # result filters remain wrappers; authorization is handled only by
+      # ToolInvocation before Tool#call begins.
       def prepare_tool_class(tool_class)
-        # When an instantiated tool object is passed (e.g. Phronomy::Tools::Mcp.from_server
-        # returns an instance, not a class), skip class-level processing and
-        # return it directly. RubyLLM#with_tool handles both forms.
         return tool_class unless tool_class.is_a?(Class)
 
-        # Step 1: apply alias if needed.
         resolved = if (alias_name = self.class.tool_aliases[tool_class])
           parent_description = tool_class.description
           Class.new(tool_class) do
@@ -1163,62 +941,17 @@ module Phronomy
           tool_class
         end
 
-        # Step 2: evaluate scope policy.
-        scope = resolved.scope
-        if scope
-          policy = @scope_policy || Phronomy::Agent::Context::Capability::ScopePolicy::DEFAULT
-          decision = policy.call(resolved, scope, self)
-          case decision
-          when :reject
-            effective_name = resolved.new.name
-            rejected_class = Class.new(resolved) do
-              tool_name effective_name
-              define_method(:call) do |_args, **_kwargs|
-                "Tool execution denied: scope :#{scope} is not permitted."
-              end
-            end
-            return rejected_class
-          when :approve
-            # Treat as requires_approval unless the tool already has that flag.
-            unless resolved.requires_approval
-              effective_name = resolved.new.name
-              resolved = Class.new(resolved) do
-                tool_name effective_name
-                requires_approval true
-              end
-            end
-          end
-        end
-
-        # Step 3: wrap with approval gate when handler is registered.
-        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, **kwargs|
-              if handler.call(name, args)
-                super(args, **kwargs)
-              else
-                "Tool execution denied."
-              end
-            end
-          end
-        end
-
-        # 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
+        effective_name = resolved.new.name
         Class.new(resolved) do
-          tool_name effective_name4
+          tool_name effective_name
           define_method(:call) do |args, **kwargs|
             result = super(args, **kwargs)
-            result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
+            result_filters.inject(result) { |val, filter|
+              filter.call(val, tool_name: name, args: args)
+            }
           end
         end
       end