phronomy 0.14.0 → 0.15.0

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(session_id, approved: true, config: {})
-          new.approve(session_id, approved: approved, config: config)
+        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_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,38 +364,31 @@ 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
+      def tool_approval_policy(&block)
+        raise ArgumentError, "tool_approval_policy requires a block" unless block
+
+        _approval_configuration_mutex.synchronize { @tool_approval_policy = 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]
+      # Registers a non-blocking Application notification listener.
+      # @return [self]
       # @api public
-      attr_writer :scope_policy
+      def on_tool_approval_required(&block)
+        raise ArgumentError, "on_tool_approval_required requires a block" unless block
+
+        _approval_configuration_mutex.synchronize { @tool_approval_listener = block }
+        self
+      end
 
       # 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.
+      # Provider errors are translated after the configured LLM adapter returns
+      # its final result. Phronomy does not replay the Agent invocation.
       #
       # @param input     [String, Hash] the user message; a Hash may supply
       #   +:message+, +:query+, or +:user+ as the text key, plus any template
@@ -486,38 +434,17 @@ module Phronomy
         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
+        _check_scheduler_reentrancy(:invoke, :invoke_async)
 
-        result = scope.pop_queue(completion_queue) do
-          raise Phronomy::TimeoutError,
-            "Agent #{self.class.name} invoke timed out after #{timeout_sec}s"
+        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
-        raise result if result.is_a?(Exception)
-        result
       end
 
       # Invokes this agent asynchronously and returns a {Phronomy::Task}.
@@ -542,39 +469,81 @@ module Phronomy
       # @param invocation_context [Phronomy::InvocationContext, nil]
       # @return [Phronomy::Task]
       # @api public
-      def invoke_async(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
+      def invoke_async(input, messages: [], thread_id: nil, config: {},
+        invocation_context: nil, on_tool_approval_required: 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)
+        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
+        _start_invocation(
+          result_task, input,
+          messages: messages, thread_id: thread_id, config: config,
+          approval_snapshot: approval_snapshot
+        )
         result_task
       end
 
-      # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
-      # as they are produced by the underlying LLM.
+      # Invokes this agent asynchronously and delivers stream events from the
+      # Runtime-owned EventLoop thread.
       #
-      # 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
+      # The callback must return quickly. Blocking I/O, synchronous Agent calls,
+      # sleep, and heavy CPU work must be delegated by the Application.
       #
-      # @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
+      # @return [Phronomy::Task] final invocation result
+      # @api public
+      def stream_async(input, messages: [], thread_id: nil, config: {},
+        invocation_context: nil, on_tool_approval_required: nil, &block)
+        raise ArgumentError, "stream_async requires a block" unless block
+
+        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}-stream-async"
+        )
+        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
+        _start_invocation(
+          result_task,
+          input,
+          messages: messages,
+          thread_id: thread_id,
+          config: config,
+          approval_snapshot: approval_snapshot,
+          mode: :stream,
+          on_event: block
+        )
+        result_task
+      end
+
+      # Synchronous wrapper around {#stream_async}.
+      #
+      # Stream callbacks execute on the EventLoop thread, not on the thread that
+      # calls this method. This method only blocks while waiting for the final Task.
       # @yield [Phronomy::Agent::StreamEvent]
-      # @return [Hash] { output:, messages:, usage: } — same as #invoke
+      # @return [Hash] same result shape as #invoke
       # @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 stream(input, messages: [], thread_id: nil, config: {},
+        invocation_context: nil, on_tool_approval_required: nil, &block)
+        raise ArgumentError, "stream 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
+        if invocation_context
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
+        end
+        _check_scheduler_reentrancy(:stream, :stream_async)
+
+        trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
+          result = stream_async(
+            input,
+            messages: messages,
+            thread_id: thread_id,
+            config: config,
+            on_tool_approval_required: on_tool_approval_required,
+            &block
+          ).wait_result
+          [result, result[:usage]]
+        end
       end
 
       # @deprecated The context version cache has been removed. Returns nil.
@@ -604,12 +573,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 +594,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 +761,398 @@ 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.
+      # Starts one AgentInvocation and resolves +result_task+ from that session.
+      # Phronomy translates the adapter's final error but never starts another
+      # AgentInvocation automatically.
       # @api private
-      def _invoke_via_fsm(input, messages: [], thread_id: nil, config: {})
+      def _start_invocation(result_task, input, messages:, thread_id:, config:,
+        approval_snapshot:, mode: :invoke, on_event: nil)
         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
-          )
-          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]]
-        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(
+        session = Agent::AgentInvocationSessionBuilder.build(
           agent: self,
           input: input,
           messages: messages,
           config: effective_config,
+          approval_policy: approval_snapshot[:policy],
+          approval_listener: approval_snapshot[:listener],
+          mode: mode,
+          on_event: on_event,
           runtime: runtime
         )
-        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-attempt-#{attempt}")
+        callback_error_policy =
+          Phronomy.configuration.stream_callback_error_policy
+        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-source")
+        source_task.on_complete do |invocation, error|
+          _handle_agent_completion(
+            result_task: result_task,
+            invocation: invocation,
+            error: error,
+            mode: mode,
+            listener: on_event,
+            event_loop: event_loop,
+            callback_error_policy: callback_error_policy
+          )
+        end
+
+        # Register completion handling before EventLoop admission. Otherwise an
+        # immediately finishing session can complete source_task before the
+        # callback is installed, causing Task#on_complete to run on this thread.
         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
+      rescue => e
+        _fail_result_task(result_task, e)
+      end
+
+      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
+
+      # Completes one Agent execution interval. Execution failures and
+      # Application callback failures are deliberately handled in separate
+      # exception domains.
+      def _handle_agent_completion(result_task:, invocation:, error:, mode:, listener:,
+        event_loop:, callback_error_policy:)
+        if mode == :stream && !event_loop.current?
+          completion_error = error || Phronomy::Error.new(
+            "Stream completion occurred outside the EventLoop"
+          )
+          _fail_result_task(result_task, _translated_error(completion_error))
+          return
+        end
+
+        result = nil
+        execution_error = nil
+        begin
+          raise error if error
+
+          result = _extract_invoke_result(invocation)
+        rescue => e
+          execution_error = _translated_error(e)
+        end
+
+        if execution_error
+          if mode == :stream
+            event = StreamEvent.new(
+              type: :error,
+              payload: {error: execution_error}
+            )
+            callback_error = _deliver_stream_event(listener, event)
+            if callback_error
+              _report_stream_callback_error(
+                callback_error,
+                event: event,
+                invocation_id: invocation&.id,
+                callback_error_policy: callback_error_policy
               )
-            }
-            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
+
+          # An Application failure while consuming :error never replaces the
+          # original Agent/LLM/Tool/Runtime failure.
+          _fail_result_task(result_task, execution_error)
+          return
+        end
+
+        unless mode == :stream
+          _complete_result_task(result_task, result)
+          return
+        end
+
+        event = _build_stream_terminal_event(result)
+        callback_error = _deliver_stream_event(listener, event)
+        unless callback_error
+          _complete_result_task(result_task, result)
+          return
+        end
+
+        _report_stream_callback_error(
+          callback_error,
+          event: event,
+          invocation_id: invocation&.id,
+          callback_error_policy: callback_error_policy
+        )
+
+        if callback_error_policy == :fail_task
+          wrapped = _build_stream_callback_error(
+            event_type: event.type,
+            callback_error: callback_error,
+            result: result
+          )
+          _fail_result_task(result_task, wrapped)
+        else
+          _complete_result_task(result_task, result)
         end
-      rescue => e
-        result_task.backend.unblock(nil, e)
-        result_task.transition!(:failed, error: e)
       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]
-      # @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)
+      def _build_stream_terminal_event(result)
+        if result[:suspended]
+          StreamEvent.new(
+            type: :approval_required,
+            payload: {request: result[:approval_request]}
+          )
         else
-          _resume_fsm(ctx, :reject)
+          StreamEvent.new(type: :done, payload: result)
         end
       end
+
+      # 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
+        )
+
+        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
+
+        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
+
+      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(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.
+      # 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}"
+        )
+
+        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
+
+      # Parent completion handling is installed before EventLoop registration,
+      # and the parent session is registered before child sessions so immediate
+      # child events cannot be lost.
       # @api private
-      def _resume_fsm(ctx, event)
+      def _start_approval_resume(result_task, invocation, approved:, config:)
+        invocation.merge_config!(config)
+        invocation.begin_approval_resume!(approved: approved)
         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,
+        source_task = Phronomy::Task.deferred(
+          name: "#{result_task.name}-source"
+        )
+        parent_session = Agent::AgentInvocationSessionBuilder.build_for_resume(
+          agent_invocation: invocation,
+          resume_event: :resume,
+          resume_phase: :suspended,
           runtime: runtime
         )
-        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)
+        stream_listener = invocation.stream_listener
+        mode = stream_listener ? :stream : :invoke
+        callback_error_policy =
+          Phronomy.configuration.stream_callback_error_policy
+
+        source_task.on_complete do |completed_invocation, error|
+          _handle_agent_completion(
+            result_task: result_task,
+            invocation: completed_invocation,
+            error: error,
+            mode: mode,
+            listener: stream_listener,
+            event_loop: event_loop,
+            callback_error_policy: callback_error_policy
+          )
+        end
+
+        # The parent must exist before any child can post an immediate result.
+        event_loop.register(parent_session, completion: source_task)
+
+        invocation.tool_invocations.each do |child|
+          child_session = if child.awaiting_approval?
+            Agent::ToolInvocationSessionBuilder.build_for_resume(
+              tool_invocation: child,
+              resume_event: approved ? :approve : :reject,
+              resume_phase: :awaiting_approval,
+              runtime: runtime
+            )
+          elsif !approved && child.authorized?
+            Agent::ToolInvocationSessionBuilder.build_for_resume(
+              tool_invocation: child,
+              resume_event: :cancel,
+              resume_phase: :authorized,
+              runtime: runtime
+            )
+          end
+          _register_tool_invocation_session(event_loop, runtime, child, child_session) if child_session
+        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 _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
+
+      def _register_tool_invocation_session(event_loop, runtime, child, session)
+        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
+        completion.on_complete do |_result, error|
+          next unless error
+
+          child.mark_framework_failed!(error)
+          runtime.event_loop.post(
+            Phronomy::Event.new(
+              type: :tool_failed,
+              target_id: child.parent_agent_invocation_id,
+              payload: {tool_invocation_id: child.id}
+            )
+          )
+        end
+        event_loop.register(session, completion: completion)
+      end
+
+      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 +1173,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 +1220,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 +1281,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 +1297,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