phronomy 0.31.0 → 0.32.0

data/lib/phronomy/agent/lifecycle/hosted_invocation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # An opt-in host handle. wait_result yields the ordinary terminal result or
+    # an ApprovalWait when the hosted operation itself is detached.
+    class HostedInvocation
+      def initialize(agent, execution_id, task, resumed_from: nil, &child_approval_wait)
+        @agent, @execution_id, @task = agent, execution_id, task
+        @environment = agent.__execution_environment
+        @resumed_from = resumed_from
+        @child_approval_wait = child_approval_wait
+      end
+
+      def wait_result(timeout: nil) = @task.wait_result(timeout: timeout)
+
+      # Supports racing normal completion or failure with an approval event.
+      def on_complete(&callback)
+        @task.on_complete(&callback)
+        self
+      end
+
+      def detach!(approval_request_id:, execution_id: @resumed_from&.execution_id || @execution_id)
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "detach! requires a host thread"
+        end
+        child = execution_id != @execution_id
+        wait = if @resumed_from
+          if execution_id == @resumed_from.execution_id && approval_request_id != @resumed_from.approval_request_id
+            @child_approval_wait.call(execution_id, approval_request_id)
+          end
+        elsif child
+          matching_child_wait(execution_id, approval_request_id)
+        else
+          @agent.persistence.standalone_approval_wait(agent_id: @agent.agent_id, execution_id: @execution_id)
+        end
+        unless wait && wait.approval_request_id == approval_request_id
+          raise Phronomy::AgentBusyError, "No matching hosted approval wait"
+        end
+        completion = Phronomy::TaskResult.deferred(name: "detach-hosted-approval")
+        owner = @environment.registry.agent_execution_owner(execution_id)
+        unless owner && (child ? owner.agent.persistence.equal?(@agent.persistence) : owner.agent.equal?(@agent))
+          raise Phronomy::AgentBusyError, "Hosted execution has no matching local owner"
+        end
+        command = ExecutionCoordinator::DetachHostedWait.new(coordinator: owner.coordinator, wait: wait,
+          task: (child && !@resumed_from) ? nil : @task, parent: child ? @agent : nil, completion: completion)
+        accepted = @environment.registry.post(command, completion: completion)
+        raise Phronomy::RuntimeShutdownError, "EventLoop rejected hosted detach" unless accepted
+        completion.wait_result
+      end
+
+      private
+
+      def matching_child_wait(execution_id, approval_request_id)
+        settled = @task.done?
+        wait = @child_approval_wait&.call(execution_id, approval_request_id)
+        return unless wait
+
+        # The child's event can precede the parent's committed coordination
+        # wait. Physical completion and that exact outcome authorize release.
+        @task.join
+        unless @task.coordination_wait_execution_id == @execution_id && @task.physical_complete?
+          @task.wait_result # Propagate a parent failure other than a committed wait.
+          raise Phronomy::AgentBusyError, "Hosted parent did not reach its coordination wait"
+        end
+        wait if settled || @child_approval_wait.call(execution_id, approval_request_id) == wait
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/lifetime_api.rb

@@ -29,6 +29,36 @@ module Phronomy
 
       private
 
+      # The participant proves which durable retentions are finished history;
+      # Agent controls admission, idleness and release of the local owners.
+      def __unload_with_peer_execution!(execution_id, reserved_by:)
+        if Phronomy::WaitPolicy.blocking_forbidden?
+          raise Phronomy::EventLoopReentrancyError, "Unloading coordinated Agents requires a host thread"
+        end
+        return false if @_phronomy_runtime_owner_state == :unloaded
+        __assert_live_agent!
+        peer = persistence.execution_identity(execution_id)
+        unless peer.correlation&.slice(*reserved_by.keys) == reserved_by
+          raise Phronomy::AgentBusyError, "Execution does not belong to this coordination owner"
+        end
+        environment = __execution_environment
+        environment.ownership.unload_idle_pair(self, peer.agent_id) do |live_peer|
+          ids = [agent_id, peer.agent_id].sort
+          if ids.any? { |id| environment.existing_registry&.agent_execution_admitted?(id) }
+            raise Phronomy::AgentBusyError, "A coordinated Agent has a local execution"
+          end
+          persistence.transaction do |records, scope|
+            unless scope.outermost?
+              raise Phronomy::Persistence::TransactionError, "Releasing local owners requires an outermost transaction"
+            end
+            ids.each { |id| records.executions.assert_idle!(id) }
+            unless yield(peer, live_peer, scope)
+              raise Phronomy::AgentBusyError, "No matching completed coordination history"
+            end
+          end
+        end
+      end
+
       def __with_operation(async: false, read_only: false)
         lease = __acquire_operation!(read_only: read_only)
         followed = false

data/lib/phronomy/agent/lifecycle/operation_lease.rb

@@ -20,6 +20,13 @@ module Phronomy
         ownership&.first&.release_operation(ownership[1], ownership[2])
       end
 
+      def reserve_approval_detach!(transition, parent: nil)
+        @mutex.synchronize do
+          raise Phronomy::AgentBusyError, "Hosted operation has ended" unless @registry
+          @registry.reserve_approval_detach!(@agent, @token, transition, parent: parent)
+        end
+      end
+
       def follow(task)
         if task.respond_to?(:on_physical_complete)
           task.on_physical_complete { release }

data/lib/phronomy/agent/lifecycle/operation_result.rb

@@ -6,6 +6,9 @@ module Phronomy
     # Only the domain runner acknowledges the end of its accepted operation.
     # @api private
     class OperationResult < Phronomy::Concurrency::PhysicalCompletionTask
+      # Published on the EventLoop before the task signals a committed coordination wait.
+      attr_accessor :coordination_wait_execution_id
+
       def initialize(agent:, name:)
         super(name: name)
         @operation_lease = agent.send(:__acquire_operation!)
@@ -20,6 +23,15 @@ module Phronomy
         release_if_quiet
       end
 
+      def reserve_approval_detach!(transition, parent: nil)
+        @lifetime_mutex.synchronize do
+          if @finished || @released || !@work.zero?
+            raise Phronomy::AgentBusyError, "Hosted operation is still busy or has finished"
+          end
+          @operation_lease.reserve_approval_detach!(transition, parent: parent)
+        end
+      end
+
       def track(task)
         @lifetime_mutex.synchronize { @work += 1 }
         task.on_physical_complete do

data/lib/phronomy/agent/lifecycle/ownership_registry.rb

@@ -165,12 +165,38 @@ module Phronomy
         true
       end
 
+      # Transfer only the single outstanding hosting operation, atomically with
+      # the same admission gate used by all other Agent operations.
+      def reserve_approval_detach!(agent, operation_token, transition, parent: nil)
+        @mutex.synchronize do
+          ensure_running!
+          entry = @entries[agent.agent_id]
+          operations = @operations[agent]
+          unless entry&.state == :live && entry.agent.equal?(agent) && !@scope_owners[agent.agent_id] &&
+              operations&.size == 1 && operations.key?(operation_token)
+            raise Phronomy::AgentBusyError, "Agent has another owner or accepted operation"
+          end
+          if parent
+            entry = @entries[parent.agent_id]
+            unless entry&.state == :live && entry.agent.equal?(parent) && !@scope_owners[parent.agent_id]
+              raise Phronomy::AgentBusyError, "Hosted parent no longer owns the local Agent"
+            end
+            assert_no_operations!(parent)
+            @entries[parent.agent_id] = Entry.new(state: :unloading, agent: parent, token: transition)
+          end
+          @entries[agent.agent_id] = Entry.new(state: :unloading, agent: agent, token: transition)
+        end
+      end
+
       # Returns the already accepted transition for duplicate callers.
       def reserve_unload(agent)
         @mutex.synchronize do
           ensure_running!
           entry = @entries[agent.agent_id]
           if entry&.state == :unloading && entry.agent.equal?(agent)
+            unless entry.token.is_a?(UnloadTransition)
+              raise Phronomy::AgentBusyError, "Agent has a coordinated release in progress"
+            end
             return [entry.token, false]
           end
           unless entry&.state == :live && entry.agent.equal?(agent)
@@ -183,22 +209,28 @@ module Phronomy
         end
       end
 
-      def finish_unload(agent, transition, success:)
-        @mutex.synchronize do
-          entry = @entries[agent.agent_id]
-          unless entry&.state == :unloading && entry.agent.equal?(agent) && entry.token.equal?(transition)
-            raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
-          end
-          if success
-            agent.send(:__mark_unloaded!)
-            @entries.delete(agent.agent_id)
-            @scope_owners.delete(agent.agent_id)
-          else
-            @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: nil)
+      def finish_unload(agent, transition, success:, parent: nil)
+        owners = {agent.agent_id => agent}
+        owners[parent.agent_id] = parent if parent
+        finish_unload_entries(owners, transition, success: success)
+      end
+
+      # Reserve the peer identity even when no instance is loaded. Its absence
+      # is then stable until the caller's durable checks commit or roll back.
+      def unload_idle_pair(parent, peer_id)
+        raise Phronomy::AgentBusyError, "Expected distinct Agent identities" if parent.agent_id == peer_id
+        transition = Object.new.freeze
+        # A host thread may exit during verification. Keep the short two-owner
+        # registry changes indivisible even in the presence of an async interrupt.
+        Thread.handle_interrupt(Object => :never) do
+          owners = reserve_idle_pair!(parent, peer_id, transition)
+          begin
+            Thread.handle_interrupt(Object => :immediate) { yield owners[peer_id] }
+            success = true
+          ensure
+            finish_unload_entries(owners, transition, success: success)
           end
-          @condition.broadcast
         end
-        true
       end
 
       def owned?(agent)
@@ -319,6 +351,46 @@ module Phronomy
 
       private
 
+      def reserve_idle_pair!(parent, peer_id, transition)
+        @mutex.synchronize do
+          ensure_running!
+          owners = {parent.agent_id => parent, peer_id => @entries[peer_id]&.agent}
+          owners.each do |id, agent|
+            entry = @entries[id]
+            raise Phronomy::AgentBusyError, "Agent belongs to a scope" if @scope_owners[id]
+            next if entry.nil? && agent.nil?
+            unless entry&.state == :live && entry.agent.equal?(agent)
+              raise Phronomy::AgentBusyError, "Local Agent owner changed"
+            end
+            assert_no_operations!(agent)
+          end
+          owners.each { |id, agent| @entries[id] = Entry.new(state: :unloading, agent: agent, token: transition) }
+          owners
+        end
+      end
+
+      def finish_unload_entries(owners, transition, success:)
+        @mutex.synchronize do
+          owners.each do |id, owner|
+            entry = @entries[id]
+            unless entry&.state == :unloading && entry.agent.equal?(owner) && entry.token.equal?(transition)
+              raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
+            end
+          end
+          owners.each do |id, owner|
+            if success || owner.nil?
+              owner&.send(:__mark_unloaded!)
+              @entries.delete(id)
+              @scope_owners.delete(id)
+            else
+              @entries[id] = Entry.new(state: :live, agent: owner, token: nil)
+            end
+          end
+          @condition.broadcast
+        end
+        true
+      end
+
       def reserve_create!(key, scope_owner: nil)
         token = Object.new.freeze
         @mutex.synchronize do

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -316,7 +316,7 @@ module Phronomy
           main = agent.send(:execution_coordinator_for, agent.__execution_wiring)
 
           if framework_batch?(execution)
-            internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
+            internal = ExecutionCoordinator::FrameworkRecoveryTask.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
             agent.send(:_complete_result_task, completion, agent)
             return

data/lib/phronomy/agent/store.rb

@@ -108,6 +108,58 @@ module Phronomy
         end
       end
 
+      # Read without loading a live Agent. Missing or ineligible waits return nil.
+      def standalone_approval_wait(agent_id:, execution_id:, scope: nil)
+        approval_wait_for(agent_id: agent_id, execution_id: execution_id, correlation: nil, retentions: [], scope: scope)
+      end
+
+      # Participant observation. An active coordinated wait must match both its
+      # exact reservation and every durable retention owned by the participant.
+      # @api private
+      def approval_wait_for(agent_id:, execution_id:, correlation:, retentions:, scope:)
+        with_scope(scope) do |records|
+          begin
+            execution = records.executions.load(execution_id)
+          rescue Phronomy::Persistence::NotFoundError
+            next
+          end
+          assert_execution_owner!(execution, agent_id)
+          next unless execution.status == :suspended && (id = execution.approval_request&.fetch("id", nil))
+          next unless execution.metadata["reservation"] == correlation && !execution.metadata["execution_extension"]
+          next if execution.metadata["cancellation_requested"] || records.cancellations.requested?(agent_id, execution_id)
+          next unless records.retentions.list(agent_id) == retentions
+
+          ApprovalWait.new(execution_id: execution.execution_id.dup.freeze, approval_request_id: id.dup.freeze,
+            execution_revision: execution.execution_revision)
+        end
+      end
+
+      # A native participant can release a root only at a single replayable
+      # Tool dispatch. A mixed batch may still require external Tool evidence.
+      # @api private
+      def single_dispatch_wait?(agent_id:, execution_id:, invocation_id:, name:, scope:, expected_revision: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          next false if expected_revision && execution.execution_revision != expected_revision
+          batch = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
+          execution.status == :active && execution.phase.to_sym == :dispatching_tools &&
+            !execution.metadata["reservation"] && !execution.metadata["cancellation_requested"] &&
+            !records.cancellations.requested?(agent_id, execution_id) &&
+            batch.size == 1 && batch.first.values_at("tool_invocation_id", "tool_name", "status") == [invocation_id, name, "authorized"]
+        end
+      end
+
+      # Check a historical reference without reading its output or error content.
+      # @api private
+      def terminal_execution?(agent_id:, execution_id:, scope:, reservation: nil)
+        with_scope(scope) do |records|
+          execution = records.executions.load(execution_id)
+          assert_execution_owner!(execution, agent_id)
+          execution.terminal? && (reservation.nil? || execution.metadata["reservation"] == reservation)
+        end
+      end
+
       def active_executions(agent_id:, scope: nil)
         with_scope(scope) do |records|
           records.executions.list_active(agent_id).map do |execution|

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
@@ -242,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
@@ -258,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/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