phronomy 0.30.1 → 0.32.0

data/lib/phronomy/context/context_policy_input_builder.rb

@@ -147,8 +147,9 @@ module Phronomy
         ordered = Array(items).sort_by { |item| [item.sequence || 0, item.id] }
         assistants = ordered.select { |item| item.kind == :assistant_message }
         tool_messages = ordered.select { |item| item.kind == :tool_message }
-        tool_messages_by_id = tool_messages.group_by(&:tool_call_id)
-        tool_messages_by_id.each do |tool_call_id, messages|
+        tool_messages_by_call = tool_messages.group_by { |item| tool_exchange_key(item, item.tool_call_id) }
+        tool_messages_by_call.each_value do |messages|
+          tool_call_id = messages.first.tool_call_id
           if tool_call_id.nil? || tool_call_id.empty?
             raise ArgumentError, "Tool message Context item requires tool_call_id"
           end
@@ -160,11 +161,12 @@ module Phronomy
         assistant_by_tool_call = {}
         assistants.each do |assistant|
           assistant.tool_call_ids.each do |tool_call_id|
-            if assistant_by_tool_call.key?(tool_call_id)
+            key = tool_exchange_key(assistant, tool_call_id)
+            if assistant_by_tool_call.key?(key)
               raise ArgumentError,
                 "duplicate assistant Tool Call id in Context Policy input: #{tool_call_id}"
             end
-            assistant_by_tool_call[tool_call_id] = assistant
+            assistant_by_tool_call[key] = assistant
           end
         end
 
@@ -173,26 +175,25 @@ module Phronomy
         ordered.each do |item|
           next if claimed[item.id]
 
-          if item.kind == :assistant_message && !item.tool_call_ids.empty?
-            messages = item.tool_call_ids.map do |tool_call_id|
-              tool_messages_by_id.fetch(tool_call_id) do
+          assistant = if item.kind == :assistant_message && !item.tool_call_ids.empty?
+            item
+          elsif item.kind == :tool_message
+            assistant_by_tool_call.fetch(tool_exchange_key(item, item.tool_call_id)) do
+              raise ArgumentError, "orphan Tool message in Context Policy input: #{item.tool_call_id}"
+            end
+          end
+
+          group = if assistant
+            messages = assistant.tool_call_ids.map do |tool_call_id|
+              key = tool_exchange_key(assistant, tool_call_id)
+              tool_messages_by_call.fetch(key) do
                 raise ArgumentError,
                   "assistant Tool Call has no Tool message in Context Policy input: #{tool_call_id}"
               end.first
             end
-            group = ([item] + messages).uniq.sort_by { |member| [member.sequence || 0, member.id] }
-          elsif item.kind == :tool_message
-            assistant = assistant_by_tool_call[item.tool_call_id]
-            unless assistant
-              raise ArgumentError,
-                "orphan Tool message in Context Policy input: #{item.tool_call_id}"
-            end
-            next if claimed[assistant.id]
-            group = ([assistant] + assistant.tool_call_ids.map do |tool_call_id|
-              tool_messages_by_id.fetch(tool_call_id).first
-            end).uniq.sort_by { |member| [member.sequence || 0, member.id] }
+            [assistant, *messages].sort_by { |member| [member.sequence || 0, member.id] }
           else
-            group = [item]
+            [item]
           end
 
           group.each { |member| claimed[member.id] = true }
@@ -202,6 +203,13 @@ module Phronomy
         mark_framework_required(groups, execution_id: execution_id, call_mode: call_mode)
       end
 
+      # Providers can number Tool calls afresh for each LLM response. Both native
+      # journal records carry the same durable LLM call ID, including after reload.
+      def tool_exchange_key(item, tool_call_id)
+        origin = item.provenance
+        [origin.agent_id, origin.execution_id, origin.llm_call_id, tool_call_id]
+      end
+
       def mark_framework_required(groups, execution_id:, call_mode:)
         return groups.map(&:freeze).freeze unless call_mode.to_sym == :complete
 

data/lib/phronomy/engine/fsm_session.rb

@@ -96,6 +96,7 @@ module Phronomy
       recursion_limit_scope: :session,
       resume_event: nil,
       resume_phase: nil,
+      require_resume_transition: false,
       stable_observer: nil,
       context_metadata: {},
       event_sink: nil,
@@ -132,6 +133,7 @@ module Phronomy
       @event_loop = event_loop
       @resume_event = resume_event
       @resume_phase = resume_phase
+      @require_resume_transition = require_resume_transition
       @stable_observer = stable_observer
       @terminal_policy = terminal_policy
       @terminal_lifecycle_state = :running
@@ -153,7 +155,8 @@ module Phronomy
             type: @resume_event,
             target_id: @id,
             payload: nil
-          )
+          ),
+          require_transition: @require_resume_transition
         )
       else
         @current_state = @entry_point
@@ -165,6 +168,10 @@ module Phronomy
       end
     rescue => error
       finish_with_error(error)
+    ensure
+      # The session owns its context between events. A tracker retained by the
+      # state-machine library or VM must not retain that live context as well.
+      @tracker.context = nil if @tracker
     end
 
     def handle(event)
@@ -190,6 +197,9 @@ module Phronomy
       fire_and_advance!(event)
     rescue => error
       finish_with_error(error)
+    ensure
+      # fire_and_advance! rebinds the context for the next accepted transition.
+      @tracker.context = nil if @tracker
     end
 
     private
@@ -235,7 +245,7 @@ module Phronomy
       end
     end
 
-    def fire_and_advance!(event)
+    def fire_and_advance!(event, require_transition: false)
       automatic = event.type == :state_completed
       exhausted = if @recursion_limit_scope == :automatic_chain
         automatic && @automatic_steps >= @recursion_limit
@@ -251,7 +261,10 @@ module Phronomy
       clear_selected_transition!
       @tracker.current_event = event if @tracker.respond_to?(:current_event=)
       transitioned = fire_event!(@tracker, event.type, @current_state)
-      return unless transitioned
+      unless transitioned
+        raise ArgumentError, "Event #{event.type.inspect} was rejected at #{@current_state.inspect}" if require_transition
+        return
+      end
 
       @ctx = @tracker.context
       @context = @ctx

data/lib/phronomy/execution/async_operation.rb

@@ -25,6 +25,22 @@ module Phronomy
       map(source, name: name, on_error: on_error, &transform)
     end
 
+    # Finalize owned work after its logical and physical boundaries. Cleanup is
+    # asynchronous too. The owner supplies cleanup and combined-error meaning;
+    # neither observer cancellation nor an Execution scope can skip cleanup.
+    # @api private
+    def self.finalize(name:, cleanup:, on_cleanup_error:)
+      source = begin
+        value = yield
+        raise TypeError, "finalized operation must return a TaskResult" unless value.is_a?(TaskResult)
+        value
+      rescue => error
+        TaskResult.failed(error, name: name)
+      end
+      Concurrency::ResultFinalization.new(source, name: name,
+        cleanup: cleanup, on_cleanup_error: on_cleanup_error).start
+    end
+
     # Short synchronous fallback/validation only; never offloads or awaits work.
     def self.capture(name:, on_error: nil)
       value = yield

data/lib/phronomy/execution/concurrency/result_finalization.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Completion composition for an owner-supplied asynchronous finalizer.
+    # This has no cancellation authority and no domain release policy.
+    # @api private
+    class ResultFinalization
+      def initialize(source, name:, cleanup:, on_cleanup_error:)
+        @source = source
+        @cleanup = cleanup
+        @on_cleanup_error = on_cleanup_error
+        @result = PhysicalCompletionTask.deferred(name: name)
+        @mutex = Mutex.new
+        @phase = :source
+        @outcomes = {}
+        @physical = {}
+      end
+
+      def start
+        observe(@source, :source)
+        @result
+      end
+
+      private
+
+      def observe(task, phase)
+        physical = task.respond_to?(:on_physical_complete)
+        @mutex.synchronize { @physical[phase] = !physical }
+        if physical
+          task.on_physical_complete do
+            @mutex.synchronize { @physical[phase] = true unless @phase == :finished }
+            advance
+          end
+        end
+        task.on_complete do |value, error|
+          @mutex.synchronize do
+            if @phase == phase && !@outcomes.key?(phase)
+              status = if error
+                (task.status == :cancelled) ? :cancelled : :failed
+              else
+                :completed
+              end
+              @outcomes[phase] = [status, value, error]
+            end
+          end
+          advance
+        end
+      end
+
+      def advance
+        action = @mutex.synchronize do
+          phase = @phase
+          next unless @outcomes.key?(phase) && @physical[phase]
+          @phase = (phase == :source) ? :cleanup : :finished
+          phase
+        end
+        case action
+        when :source then start_cleanup
+        when :cleanup then finish
+        end
+      end
+
+      def start_cleanup
+        task = begin
+          value = @cleanup.call
+          raise TypeError, "asynchronous cleanup must return a TaskResult" unless value.is_a?(TaskResult)
+          value
+        rescue => error
+          TaskResult.failed(error)
+        end
+        observe(task, :cleanup)
+      end
+
+      def finish
+        status, value, error = @outcomes.fetch(:source)
+        cleanup_error = @outcomes.fetch(:cleanup).last
+        if cleanup_error
+          begin
+            error = @on_cleanup_error.call(value, error, cleanup_error)
+            raise TypeError, "cleanup error policy must return or raise an Exception" unless error.is_a?(Exception)
+          rescue => policy_error
+            error = policy_error
+          end
+          status = :failed
+        end
+        # Completed handles must not keep the owner or its source/cleanup
+        # closures alive. A domain cleanup error may deliberately retain them.
+        @source = @cleanup = @on_cleanup_error = nil
+        @mutex.synchronize do
+          @outcomes.clear
+          @physical.clear
+        end
+        begin
+          @result.mark_physical_complete!
+        ensure
+          case status
+          when :completed then @result.complete(value)
+          when :cancelled then @result.cancel!(error)
+          else @result.fail(error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier/agent_operation.rb

@@ -8,8 +8,8 @@ module Phronomy
     # still pending. Generation owns the request-to-Workflow correlation.
     # @api private
     class AgentOperation
-      def initialize(agent_class, output_schema:)
-        @output_schema = output_schema
+      def initialize(agent_class, output_schema:, schema_delivery:)
+        @output_schema, @schema_delivery = output_schema, schema_delivery
         @mutex = Mutex.new
         @pending = []
         @agent = agent_class.new(on_event: method(:receive_event))
@@ -21,7 +21,7 @@ module Phronomy
         # own result settles: Agent admission itself may run after an earlier
         # request completes, so a pending submission is not necessarily busy.
         @mutex.synchronize { @pending << [request, listener] }
-        task = @agent.invoke_async(input, config: config, output_schema: @output_schema)
+        task = @agent.invoke_async(input, config: config, output_schema: @output_schema, schema_delivery: @schema_delivery)
         task.on_complete do |result, error|
           release(request)
           remember_execution(result[:execution_id]) if result.is_a?(Hash)

data/lib/phronomy/generation/generator_verifier.rb

@@ -34,10 +34,13 @@ module Phronomy
     end
 
     def initialize(draft_agent:, review_agent:, draft_prompt_builder:, review_prompt_builder:,
-      citation_schema: Protocol::DEFAULT_CITATION,
+      citation_schema: Protocol::DEFAULT_CITATION, schema_delivery: :native,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
       max_iterations: DEFAULT_MAX_ITERATIONS, raise_if_unaccepted: false, on_approval: nil)
       ensure_blocking_allowed!(:new)
+      unless %i[native none].include?(schema_delivery)
+        raise ArgumentError, "schema_delivery must be :native or :none"
+      end
       unless confidence_threshold.is_a?(Numeric) && confidence_threshold.real? && confidence_threshold.to_f.finite? &&
           (0.0..1.0).cover?(confidence_threshold)
         raise ArgumentError, "confidence_threshold must be a finite number in 0..1"
@@ -62,8 +65,8 @@ module Phronomy
       @draft_prompt_builder, @review_prompt_builder = draft_prompt_builder, review_prompt_builder
       draft_schema = Protocol.draft(citation_schema)
       begin
-        @operations[:draft] = AgentOperation.new(draft_agent, output_schema: draft_schema)
-        @operations[:review] = AgentOperation.new(review_agent, output_schema: Protocol::REVIEW)
+        @operations[:draft] = AgentOperation.new(draft_agent, output_schema: draft_schema, schema_delivery: schema_delivery)
+        @operations[:review] = AgentOperation.new(review_agent, output_schema: Protocol::REVIEW, schema_delivery: schema_delivery)
       rescue Exception => primary # rubocop:disable Lint/RescueException -- release partially acquired resources
         begin
           release!

data/lib/phronomy/llm_adapter/backends/ruby_llm.rb

@@ -63,7 +63,7 @@ module Phronomy
         callback_error = nil
         chat = build_chat(request)
         capture = StructuredResponseCapture.new
-        capture.bind(chat) if request.response_schema && block_given?
+        capture.bind(chat) if block_given?
         token&.raise_if_cancelled!
         chat.after_message do |message|
           raise ToolsRequested.new(message) if message.tool_call?

data/lib/phronomy/llm_adapter/backends/structured_response_capture.rb

@@ -24,7 +24,9 @@ module Phronomy
 
       def record(data)
         choice = data.dig("choices", 0) || {}
-        @raw_finish_reason = choice["finish_reason"] || data.dig("delta", "stop_reason") ||
+        provider_delta = data["delta"]
+        stop_reason = provider_delta["stop_reason"] if provider_delta.is_a?(Hash)
+        @raw_finish_reason = choice["finish_reason"] || stop_reason ||
           data.dig("candidates", 0, "finishReason") || @raw_finish_reason
         delta = choice.dig("delta", "refusal")
         delta ||= data["delta"] if data["type"] == "response.refusal.delta"

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -83,6 +83,91 @@ module Phronomy
         extension&.state_ref ? persistence.contents.fetch_json(extension.state_ref) : {"children" => [], "cancel_requested" => false}
       end
 
+      # Validate both ends of the reservation in one durable snapshot. Only
+      # one direct, unfinished child belongs to this hosted handoff.
+      def child_approval_wait(parent_id, parent_execution_id, execution_id, approval_id, parent_revision: nil, live_child: nil)
+        store = persistence.agent_store
+        persistence.coordinator.atomic do |scope|
+          extension = store.execution_extension(agent_id: parent_id, execution_id: parent_execution_id,
+            binding_key: BINDING_KEY, scope: scope)
+          next unless extension&.state_ref && extension.binding_version == 1
+          snapshot = state_for(extension)
+          children = snapshot.fetch("children")
+          next unless !snapshot["cancel_requested"] && children.size == 1
+          child = children.first
+          next unless !child.fetch("imported") && child.fetch("execution_id") == execution_id
+          next unless matching_child_class?(child, live_child)
+          next unless store.single_dispatch_wait?(agent_id: parent_id, execution_id: parent_execution_id,
+            invocation_id: child.fetch("slot"), name: "dispatch_to_#{child.fetch("name")}", expected_revision: parent_revision, scope: scope)
+          next unless hosted_retentions?(parent_id, parent_execution_id, scope)
+
+          child_id = child.fetch("agent_id")
+          owner = {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
+                   "parent_agent_id" => parent_id, "slot" => child.fetch("slot")}
+          retention = Phronomy::Agent::Retention.new(agent_id: child_id, execution_id: execution_id,
+            owner_key: "subagent:#{parent_execution_id}")
+          wait = store.approval_wait_for(agent_id: child_id, execution_id: execution_id,
+            correlation: owner, retentions: [retention], scope: scope)
+          wait if wait&.approval_request_id == approval_id
+        end
+      end
+
+      # A terminal record alone does not show that its result reached the
+      # parent. Check the native slot, exact reservation and holds together.
+      def completed_child_pair?(parent_id, parent_execution_id, child, live_child:, scope:)
+        store = persistence.agent_store
+        return false unless store.terminal_execution?(agent_id: parent_id, execution_id: parent_execution_id, scope: scope)
+        children = stored_children(parent_id, parent_execution_id, scope)
+        return false unless children&.size == 1
+        slot = children.first
+        return false unless slot.fetch("imported") == true && slot.fetch("agent_id") == child.agent_id &&
+          slot.fetch("execution_id") == child.execution_id && matching_child_class?(slot, live_child)
+
+        owner = {"kind" => "subagent", "parent_agent_id" => parent_id, "parent_execution_id" => parent_execution_id,
+                 "slot" => slot.fetch("slot")}
+        return false unless store.terminal_execution?(agent_id: child.agent_id, execution_id: child.execution_id,
+          reservation: owner, scope: scope)
+        hold = Phronomy::Agent::Retention.new(agent_id: child.agent_id, execution_id: child.execution_id,
+          owner_key: "subagent:#{parent_execution_id}")
+        return false unless store.retained_references(agent_id: child.agent_id, scope: scope) == [hold]
+
+        hosted_retentions?(parent_id, parent_execution_id, scope) do |prior_id|
+          prior = stored_children(parent_id, prior_id, scope)
+          prior && !prior.empty? && prior.all? { |entry| entry.fetch("imported") == true }
+        end
+      end
+
+      private def stored_children(parent_id, execution_id, scope)
+        extension = persistence.agent_store.execution_extension(agent_id: parent_id, execution_id: execution_id,
+          binding_key: BINDING_KEY, scope: scope)
+        state_for(extension).fetch("children") if extension&.state_ref && extension.binding_version == 1
+      end
+
+      private def matching_child_class?(slot, live_child)
+        klass = self.class.registered_child_class(@agent_class, slot)
+        klass && (!live_child || (live_child.agent_id == slot.fetch("agent_id") && live_child.is_a?(klass) &&
+          live_child.class.agent_definition == klass.agent_definition && live_child.persistence.equal?(persistence.agent_store)))
+      end
+
+      # Retaining the history of an earlier completed native dispatch on this
+      # same Agent does not give anyone a live interest in the current run.
+      private def hosted_retentions?(agent_id, execution_id, scope)
+        store = persistence.agent_store
+        current = Phronomy::Agent::Retention.new(agent_id: agent_id, execution_id: execution_id, owner_key: "subagent:#{execution_id}")
+        retentions = store.retained_references(agent_id: agent_id, scope: scope)
+        retentions.include?(current) && (retentions - [current]).all? do |retention|
+          retention.execution_id && retention.owner_key == "subagent:#{retention.execution_id}" &&
+            store.terminal_execution?(agent_id: agent_id, execution_id: retention.execution_id, scope: scope) &&
+            (!block_given? || yield(retention.execution_id))
+        end
+      end
+
+      def self.registered_child_class(parent_class, child)
+        settings = parent_class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
+        klass = settings&.fetch(:agent_class)
+        klass if klass && klass.agent_definition.transform_keys(&:to_s) == child.fetch("definition")
+      end
+
       def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
         completion = Phronomy::TaskResult.deferred(name: "durable-subagent:#{tool_invocation_id}")
         preparation = Phronomy::Execution.submit(on_full: :raise) do
@@ -92,11 +177,8 @@ module Phronomy
           snapshot = store.contents.fetch_json(extension.state_ref)
           child = snapshot.fetch("children").find { |entry| entry.fetch("slot") == tool_invocation_id }
           raise Phronomy::ExecutionRehydrationRequiredError, "Missing reserved child slot" unless child
-          settings = parent.class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
-          unless settings && settings.fetch(:agent_class).agent_definition.transform_keys(&:to_s) == child.fetch("definition")
-            raise Phronomy::ConfigurationError, "Registered child definition changed"
-          end
-          klass = settings.fetch(:agent_class)
+          klass = registered_child_class(parent.class, child)
+          raise Phronomy::ConfigurationError, "Registered child definition changed" unless klass
           id = child.fetch("agent_id")
           retention = Phronomy::Agent::Retention.new(agent_id: id, execution_id: child.fetch("execution_id"), owner_key: "subagent:#{parent_execution_id}")
           agent = klass.get(id)

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -29,6 +29,16 @@ module Phronomy
         @participant = @coordination_store && DurableSubagentCoordinator.new(agent_class: self.class, persistence: @coordination_store)
       end
 
+      # Release the local parent and its directly dispatched child after the
+      # child's outcome has been imported. The stored history remains intact.
+      # @api public
+      def unload_with_completed_child!(parent_execution_id, execution_id:)
+        owner = {"kind" => "subagent", "parent_agent_id" => agent_id, "parent_execution_id" => parent_execution_id}
+        __unload_with_peer_execution!(execution_id, reserved_by: owner) do |child, live_child, scope|
+          @participant&.completed_child_pair?(agent_id, parent_execution_id, child, live_child: live_child, scope: scope)
+        end
+      end
+
       # Current composition, never serialized in an execution record.
       def __invocation_config(config)
         if !self.class.registered_subagents.empty? && !@participant
@@ -38,6 +48,14 @@ module Phronomy
           phronomy_execution_participant: @participant).compact
       end
 
+      # Answers the current wait of a recovered direct child. If the same
+      # execution suspends again the host can release the pair with this handle.
+      # @api public
+      def approve_hosted_child(parent_execution_id, execution_id:, approval_request_id:, approved: true, config: {})
+        resume_hosted_child_approval(parent_execution_id, execution_id: execution_id,
+          approval_request_id: approval_request_id, approved: approved, config: config)
+      end
+
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         # A subagent Tool is logically asynchronous: ToolInvocation starts the
         # child Agent and resumes when its completion TaskResult settles. It must not
@@ -224,6 +242,8 @@ module Phronomy
 
       private
 
+      def hosted_child_approval_reader = @participant&.method(:child_approval_wait)
+
       def prepare_tool_class(tool_class, invocation: nil)
         prepared = super
         return prepared unless self.class._subagent_tool_classes.include?(tool_class)
@@ -234,28 +254,20 @@ module Phronomy
         end&.last
         inherits_knowledge = registration ? registration.fetch(:inherit_knowledge, true) : true
 
-        captured_context = {parent: self}
+        context = {parent: self}
         # Invocation-owned Tools inherit the durable child slot's knowledge,
         # captured by the existing preparation transaction off EventLoop.
-        captured_context[:knowledge] = active_knowledge_snapshot if inherits_knowledge && !invocation
+        context[:knowledge] = active_knowledge_snapshot if inherits_knowledge && !invocation
         if invocation
-          captured_context[:config] = invocation.config
-          captured_context[:invocation_context] = invocation.config[:invocation_context]
-        end
-        captured_context.freeze
-
-        effective_name = prepared.new.name
-        Class.new(prepared) do
-          tool_name effective_name
-          define_method(:call) do |args, **kwargs|
-            self._orchestrator_context = captured_context
-            super(args, **kwargs)
-          end
-          define_method(:call_async) do |args, **kwargs|
-            self._orchestrator_context = captured_context
-            super(args, **kwargs)
-          end
+          context[:config] = invocation.config
+          context[:invocation_context] = invocation.config[:invocation_context]
         end
+
+        # Cached Tool methods can outlive an execution. Only the instance used
+        # for this dispatch should hold its parent and invocation configuration.
+        tool = prepared.new
+        tool._orchestrator_context = context.freeze
+        tool
       end
 
       def active_knowledge_snapshot = knowledge_snapshot

data/lib/phronomy/tools/agent.rb

@@ -7,13 +7,30 @@ module Phronomy
     # Agent-backed Tools are logically asynchronous rather than offloaded
     # synchronous operations. Their ToolInvocation starts the child Agent and then
     # returns to EventLoop immediately; the Tool completion handle settles when the
-    # child Agent FSMSession finishes. An OffloadPool worker is therefore never
-    # consumed merely to wait for another Agent.
+    # child Agent's physical work and release finish. An OffloadPool worker is
+    # therefore never consumed merely to wait for another Agent.
     class Agent < Phronomy::Tool::Base
       execution_mode :cooperative
       description "Wraps a Phronomy::Agent as a Tool"
       param :input, type: :string, desc: "The input to forward to the wrapped Agent"
 
+      # A private child's operation ended, but its safe release failed. The live
+      # reference supports retrying unload_async without repeating business work.
+      # This error and its child reference are process-local, not durable state.
+      # @api public
+      class CleanupError < Phronomy::ToolError
+        attr_reader :child_agent, :agent_id, :result, :primary_error, :cleanup_error
+
+        def initialize(child_agent:, result:, primary_error:, cleanup_error:)
+          @child_agent = child_agent
+          @agent_id = child_agent.agent_id
+          @result = result
+          @primary_error = primary_error
+          @cleanup_error = cleanup_error
+          super("Agent Tool cleanup failed for #{@agent_id.inspect}", code: "tool.agent_cleanup_failed")
+        end
+      end
+
       class << self
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)
@@ -35,36 +52,34 @@ module Phronomy
           # Preserve the synchronous Tool API for top-level callers. ToolInvocation
           # never uses this path for Agent-backed Tools; it calls #call_async.
           klass.define_method(:execute) do |input:, cancellation_token: nil|
-            invoke_options = {}
-            if cancellation_token
-              invoke_options[:config] = {cancellation_token: cancellation_token}
+            if Phronomy::WaitPolicy.blocking_forbidden?
+              raise Phronomy::EventLoopReentrancyError,
+                "Agent Tool execute cannot block EventLoop; use call_async"
             end
-            # Use the same supplied store factory as the asynchronous path.
-            # Preserve the creation arguments previously supplied by run_once.
-            persistence = Phronomy::Agent::DefaultPersistence.build
-            agent = agent_class.create(
-              context: nil,
-              knowledge: [],
-              persistence: persistence,
-              on_event: nil
-            )
-            result = agent.invoke(input, **invoke_options)
-            result[:output].to_s
+            execute_async(input: input, cancellation_token: cancellation_token).wait_result
           end
 
           # Internal asynchronous execution protocol used by Agent#call_async.
-          # The child Agent owns its own FSMSession/EventLoop lifecycle; this
-          # method only returns its completion handle and performs a short map.
+          # C04 decides whether release is safe; C13 composes completion. The
+          # concrete Tool supplies only creation, output and cleanup policies.
           klass.define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
-            persistence = Phronomy::Agent::DefaultPersistence.build
-            agent = agent_class.create(persistence: persistence)
+            unless config.nil? || config.is_a?(Hash)
+              raise ArgumentError, "Agent Tool config must be a Hash"
+            end
             task_config = (config || {}).dup
             if cancellation_token && !task_config[:cancellation_token]
               task_config[:cancellation_token] = cancellation_token
             end
 
-            agent.invoke_async(input, config: task_config).map do |result|
-              result[:output].to_s
+            persistence = Phronomy::Agent::DefaultPersistence.build
+            agent = agent_class.create(persistence: persistence)
+            Phronomy::AsyncOperation.finalize(name: "agent-tool-#{name}-release",
+              cleanup: -> { agent.unload_async },
+              on_cleanup_error: ->(value, primary, cleanup) { child_cleanup_failed(agent, value, primary, cleanup) }) do
+              Phronomy::AsyncOperation.call(name: "agent-tool-#{name}-invoke",
+                transform: ->(result) { result[:output].to_s }) do
+                agent.invoke_async(input, config: task_config)
+              end
             end
           end
           klass.send(:private, :execute_async)
@@ -102,6 +117,27 @@ module Phronomy
 
       private
 
+      def child_cleanup_failed(agent, result, primary_error, cleanup_error)
+        failure = CleanupError.new(child_agent: agent, result: result,
+          primary_error: primary_error, cleanup_error: cleanup_error)
+        # Always report cleanup failures: an outer observer may already have
+        # cancelled its handle, so returning an error alone is not sufficient.
+        report_child_cleanup_failure(failure)
+        raise failure, cause: primary_error || cleanup_error
+      end
+
+      def report_child_cleanup_failure(failure)
+        details = {"agent_id" => failure.agent_id, "code" => failure.code,
+                   "cleanup_error" => Phronomy::Error.diagnostic(failure.cleanup_error)}
+        details["primary_error"] = Phronomy::Error.diagnostic(failure.primary_error) if failure.primary_error
+        message = "[Phronomy] Agent Tool cleanup failed: #{details.inspect}"
+        logger = Phronomy::RuntimeSettings.current.logger
+        logger ? logger.error(message) : warn(message)
+      rescue
+        # Diagnostics cannot change the combined error or repeat the operation.
+        nil
+      end
+
       # Subclasses created by .from_agent override this method.
       # It deliberately remains private so it is not part of the public Tool API.
       def execute_async(input:, cancellation_token: nil, config: {})

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.30.1"
+  VERSION = "0.32.0"
 end