phronomy 0.27.0 → 0.28.0

data/lib/phronomy/llm_adapter/token_usage.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Immutable usage counts. An omitted count remains nil; zero is a reported
+    # measurement. SDK field translation belongs to the backend.
+    # @api public
+    class TokenUsage
+      attr_reader :input, :output, :cached, :cache_creation
+
+      def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
+        [input, output, cached, cache_creation].each do |value|
+          if !(value.nil? || (value.is_a?(Integer) && value >= 0))
+            raise ArgumentError, "token usage must be non-negative Integers or nil"
+          end
+        end
+        @input = input
+        @output = output
+        @cached = cached
+        @cache_creation = cache_creation
+        freeze
+      end
+
+      # Returns a zero-valued TokenUsage suitable as an accumulator seed.
+      def self.zero
+        new(input: 0, output: 0, cached: 0, cache_creation: 0)
+      end
+
+      # Adds two TokenUsage instances. nil fields are treated as 0 so that
+      # partially-reported usage accumulates correctly.
+      # When other is nil, returns self unchanged.
+      def +(other)
+        return self if other.nil?
+
+        self.class.new(
+          input: _add(input, other.input),
+          output: _add(output, other.output),
+          cached: _add(cached, other.cached),
+          cache_creation: _add(cache_creation, other.cache_creation)
+        )
+      end
+
+      def ==(other)
+        other.is_a?(TokenUsage) &&
+          input == other.input &&
+          output == other.output &&
+          cached == other.cached &&
+          cache_creation == other.cache_creation
+      end
+
+      def to_h
+        {input: input, output: output, cached: cached, cache_creation: cache_creation}
+      end
+
+      private
+
+      def _add(a, b)
+        return nil if a.nil? && b.nil?
+
+        (a || 0) + (b || 0)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/transport_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module LLMAdapter
+    class TransportError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/llm_adapter.rb

@@ -1,22 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Namespace for LLM call adapters.
-  #
-  # The public extension boundary is {LLMAdapter::Base#complete} and
-  # {LLMAdapter::Base#stream}. Those methods receive Phronomy's currently
-  # materialized chat/runtime object and perform the provider call. Phronomy owns
-  # the async/offload bridge around that synchronous contract.
-  #
-  # This SPI does not by itself make the complete input-materialization pipeline
-  # provider-neutral: the current Agent pipeline still materializes the canonical
-  # LLM input through RubyLLM-specific runtime objects before invoking the adapter.
-  #
-  # @example Configuring a custom adapter
-  #   Phronomy.configure do |c|
-  #     c.llm_adapter = MyCustomAdapter.new
-  #   end
-  #
+  # LLM domain operations and public request, response, usage and failure values.
+  # A backend implements Base's protected hooks. SDK objects remain inside the
+  # backend; AsyncClient executes the entire synchronous operation on a worker.
   # @api public
   module LLMAdapter
   end

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -2,18 +2,11 @@
 
 module Phronomy
   module MultiAgent
-    # Runtime-local admission for one synchronous coordination call per owner
+    # Environment-local admission for one synchronous coordination call per owner
     # (a Handoff main Agent or TeamCoordinator). This does not own durable runs
     # or active-agent mutation; those remain in their existing domains.
     # @api private
     class AdmissionRegistry
-      # Construction has no side effects. Runtime returns the registered instance
-      # when callers concurrently supply candidates for the same key.
-      # @api private
-      def self.for(runtime)
-        runtime.__register_shutdown_participant(key: self, participant: new)
-      end
-
       def initialize
         @mutex = Mutex.new
         @cond = ConditionVariable.new

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -1,127 +1,151 @@
 # frozen_string_literal: true
 
-require "securerandom"
+require "digest"
 
 module Phronomy
   module MultiAgent
-    # Agent-owned transactions reserve child work; TaskResult callbacks only wake observers.
+    # Owns slot reservations and import progress. The Agent participant stores
+    # only this binding's opaque state reference alongside its own transition.
     # @api private
     class DurableSubagentCoordinator
-      KEY = "multi_agent_coordination_ref"
+      BINDING_KEY = "phronomy.subagent"
+      attr_reader :persistence
 
-      def self.prepare(parent, execution, tx:)
-        ref = execution.metadata[KEY]
-        snapshot = ref ? tx.contents.fetch_json(ref) : {"kind" => "static_subagent", "children" => []}
-        children = snapshot.fetch("children").map(&:dup)
-        children.each do |child|
-          begin
-            exact = tx.executions.load(child.fetch("execution_id"))
-          rescue Phronomy::Storage::NotFoundError
-            next
-          end
-          raise Phronomy::Storage::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
-          child.merge!("state" => exact.status.to_s, "result_ref" => exact.result_ref, "error_ref" => exact.error_ref)
+      def initialize(agent_class:, persistence:)
+        @agent_class, @persistence = agent_class, persistence
+        @definitions = agent_class.registered_subagents
+      end
+
+      def binding
+        Phronomy::Agent::ExecutionExtensionState.new(binding_key: BINDING_KEY, binding_version: 1)
+      end
+
+      def guard_change(change, scope)
+        snapshot = state_for(change.extension)
+        ids = [change.agent_id] + snapshot.fetch("children").filter_map do |child|
+          child.fetch("agent_id") if persistence.agent_store.exist?(child.fetch("agent_id"))
         end
-        Array(execution.metadata[Phronomy::Agent::ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).each do |tool|
-          registration = parent.class.registered_subagents.find { |name, _| "dispatch_to_#{name}" == tool.fetch("tool_name") }
-          next unless registration
-          next if children.any? { |child| child.fetch("slot") == tool.fetch("tool_invocation_id") }
-          name, settings = registration
-          definition = settings.fetch(:agent_class).agent_definition
-          knowledge = settings.fetch(:inherit_knowledge) ? parent.send(:active_knowledge_snapshot) : []
-          children << {
-            "slot" => tool.fetch("tool_invocation_id"), "name" => name.to_s,
-            "definition" => definition.transform_keys(&:to_s),
-            "agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid,
-            "input_ref" => tx.contents.put_text(tool.fetch("arguments").fetch("input")),
-            "durable_context_ref" => execution.metadata["durable_context_ref"],
-            "knowledge_ref" => tx.contents.put_json(Phronomy::Agent::RecoverySupport.canonical_copy(knowledge)),
-            "state" => "reserved", "result_ref" => nil, "error_ref" => nil,
-            "on_error" => settings.fetch(:on_error).to_s
-          }
+        persistence.agent_store.guard_agents(scope, agent_ids: ids)
+      end
+
+      # The referenced content is immutable and is part of Agent's commit proof.
+      def change_evidence(change, scope)
+        persistence.agent_store.retained_references(agent_id: change.agent_id, scope: scope).map(&:to_h)
+      end
+
+      def commit(change)
+        persistence.coordinator.atomic do |scope|
+          guard_change(change, scope)
+          change.prepare_in(scope)
+          snapshot = state_for(change.extension)
+          children = snapshot.fetch("children").map(&:dup)
+          cancelled = snapshot["cancel_requested"] || change.cancel_requested ||
+            persistence.agent_store.cancellation_requested?(agent_id: change.agent_id, execution_id: change.execution_id, scope: scope)
+          children.each do |child|
+            observed = persistence.agent_store.observe_execution(agent_id: child.fetch("agent_id"), execution_id: child.fetch("execution_id"), scope: scope)
+            # This is import progress, not a replicated child execution state.
+            child["imported"] = true if observed.terminal? && change.kind == :dispatch && change.operations.empty?
+          end
+          change.operations.each do |operation|
+            entry = @definitions.find { |name, _| "dispatch_to_#{name}" == operation.name }
+            next unless entry
+            next if children.any? { |child| child.fetch("slot") == operation.invocation_id }
+            name, settings = entry
+            digest = Digest::SHA256.hexdigest(Phronomy::CanonicalJSON.dump(
+              ["phronomy-subagent-v1", change.agent_id, change.execution_id, operation.invocation_id]
+            ))
+            knowledge = settings.fetch(:inherit_knowledge) ? persistence.agent_store.knowledge_snapshot(agent_id: change.agent_id, scope: scope) : []
+            children << {"slot" => operation.invocation_id, "name" => name.to_s,
+                         "definition" => settings.fetch(:agent_class).agent_definition.transform_keys(&:to_s),
+                         "agent_id" => "subagent-#{digest}", "execution_id" => "subagent-execution-#{digest}",
+                         "input" => operation.arguments.fetch("input"), "durable_context" => change.durable_context,
+                         "knowledge" => knowledge.map { |item| {"content" => item.content, "metadata" => item.metadata} },
+                         "on_error" => settings.fetch(:on_error).to_s, "imported" => false}
+          end
+          unless children.empty?
+            persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: change.agent_id,
+              execution_id: change.execution_id, owner_key: "subagent:#{change.execution_id}"), scope: scope)
+          end
+          unresolved = children.any? do |child|
+            observed = persistence.agent_store.observe_execution(agent_id: child.fetch("agent_id"), execution_id: child.fetch("execution_id"), scope: scope)
+            observed.active? || (observed.absent? && !cancelled)
+          end
+          persistence.participate(scope) do |records|
+            ref = records.contents.put_json(snapshot.merge("children" => children, "cancel_requested" => !!cancelled))
+            state = Phronomy::Agent::ExecutionExtensionState.new(binding_key: BINDING_KEY, binding_version: 1, state_ref: ref)
+            change.commit_in(scope, state: state,
+              pending: change.kind == :terminal && unresolved && (change.cancel_requested || change.recovery_required))
+          end
         end
-        return execution if children.empty?
-        value = tx.contents.put_json(snapshot.merge("children" => children))
-        execution.with(execution_revision: execution.execution_revision, metadata: execution.metadata.merge(KEY => value))
+      end
+
+      def state_for(extension)
+        extension&.state_ref ? persistence.contents.fetch_json(extension.state_ref) : {"children" => [], "cancel_requested" => false}
       end
 
       def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
-        runtime = Phronomy::Runtime.instance
         completion = Phronomy::TaskResult.deferred(name: "durable-subagent:#{tool_invocation_id}")
-        preparation = runtime.offload.submit(on_full: :raise) do
-          current = parent.persistence.executions.load(parent_execution_id)
-          raise Phronomy::Storage::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
-          snapshot = parent.persistence.contents.fetch_json(current.metadata.fetch(KEY))
+        preparation = Phronomy::Execution.submit(on_full: :raise) do
+          store = parent.coordination_store
+          extension = parent.persistence.execution_extension(agent_id: parent.agent_id, execution_id: parent_execution_id, binding_key: BINDING_KEY)
+          raise Phronomy::ExecutionRehydrationRequiredError, "Missing subagent reservation state" unless extension&.state_ref
+          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
-          definition = parent.class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
-          unless definition && definition.fetch(:agent_class).agent_definition.transform_keys(&:to_s) == child.fetch("definition")
-            raise Phronomy::ConfigurationError, "Registered child definition changed: #{child.fetch("name")}"
+          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 = definition.fetch(:agent_class)
+          klass = settings.fetch(:agent_class)
           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)
           unless agent
-            begin
-              parent.persistence.agents.load(id)
-              exists = true
-            rescue Phronomy::Storage::NotFoundError
-              exists = false
-            end
-            listener = parent.send(:_phronomy_event_listener)
-            agent = if exists
-              klass.load(id, persistence: parent.persistence, on_event: listener)
+            if parent.persistence.exist?(id)
+              agent = klass.load(id, persistence: parent.persistence, on_event: parent.event_listener)
             else
-              knowledge = parent.persistence.contents.fetch_json(child.fetch("knowledge_ref"))
-              context = Phronomy::Agent::ContextImporter::ImportedContext.new(records: knowledge.map do |item|
-                Phronomy::Agent::ContextImporter::ImportedRecord.new(kind: :knowledge,
-                  channel: :context, role: :user, content: item.fetch("content"),
-                  content_format: :text, metadata: item.fetch("metadata"))
-              end)
-              klass.create(agent_id: id, persistence: parent.persistence,
-                context: context, on_event: listener)
+              raise Phronomy::CancellationError, "Parent reservation was cancelled" if snapshot["cancel_requested"]
+              knowledge = child.fetch("knowledge").map { |item| Phronomy::Agent::KnowledgeItem.new(content: item.fetch("content"), metadata: item.fetch("metadata")) }
+              agent = klass.create(agent_id: id, persistence: parent.persistence, knowledge: knowledge,
+                retention: retention, on_event: parent.event_listener)
             end
           end
-          unless agent.persistence.equal?(parent.persistence)
-            raise Phronomy::ConfigurationError, "Child Persistence instance mismatch"
-          end
-          durable_context = child["durable_context_ref"] && parent.persistence.contents.fetch_json(child["durable_context_ref"])
-          [child, agent, parent.persistence.contents.fetch_text(child.fetch("input_ref")), durable_context]
+          raise Phronomy::ConfigurationError, "Child Persistence mismatch" unless agent.persistence.equal?(parent.persistence)
+          [child, agent, store]
         end
         preparation.on_complete do |prepared, failure|
           if failure
-            completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
+            completion.fail(failure.is_a?(Phronomy::CancellationError) ? failure : Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
             next
           end
-          child, agent, input, durable_context = prepared
+          child, agent, store = prepared
+          owner = {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
+                   "parent_agent_id" => parent.agent_id, "slot" => tool_invocation_id}
           child_config = {cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new,
                           invocation_context: config[:invocation_context],
-                          phronomy_coordination: {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
-                                                  "parent_agent_id" => parent.agent_id, "slot" => tool_invocation_id}}.compact
-          child_config = child_config.merge(durable_context: durable_context) if child["durable_context_ref"]
-          source = Phronomy::Agent::ExactExecution.start(agent: agent,
-            execution_id: child.fetch("execution_id"), input: input, config: child_config)
-          source.on_complete do |result, error|
+                          phronomy_admission: ReservedChildAdmission.new(persistence: store, owner: owner)}.compact
+          child_config[:durable_context] = child["durable_context"] if child["durable_context"]
+          reservation = Phronomy::Agent::ReservedExecution.new(agent_id: agent.agent_id, execution_id: child.fetch("execution_id"), correlation: owner)
+          agent.start_reserved_async(reservation: reservation, input: child.fetch("input"), config: child_config).on_complete do |result, error|
             if error
-              if error.is_a?(Phronomy::CancellationError)
-                completion.fail(error)
-              else
-                completion.fail(Phronomy::ExecutionRehydrationRequiredError.new(
-                  "Child #{child.fetch("execution_id")} is unfinished: #{error.message}"
-                ))
-              end
+              completion.fail(error.is_a?(Phronomy::CancellationError) ? error : Phronomy::ExecutionRehydrationRequiredError.new("Child #{reservation.execution_id} is unfinished: #{error.message}"))
             elsif result[:error]
-              if child.fetch("on_error") == "skip"
+              if child.fetch("on_error") == "skip" && result[:status] != :cancelled
                 completion.complete(nil)
               else
-                completion.fail(Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]))
+                observed = Phronomy::Agent::ExecutionObservation.from_result(result)
+                begin
+                  observed.value!
+                rescue => failure
+                  completion.fail(failure)
+                end
               end
             else
               completion.complete(result[:output])
             end
           end
         rescue => error
-          completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child coordination requires recovery: #{error.message}"))
+          completion.fail(error)
         end
         completion
       rescue => error

data/lib/phronomy/multi_agent/execution_environment.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # Process-local connection selected by composition. MultiAgent owns the
+    # admission and Team identity rules; the environment connects their
+    # registries to shutdown and submits work to the originating executor.
+    # Environments and registries are never durable execution authority.
+    # @api private
+    class ExecutionEnvironment
+      class << self
+        def install_provider(provider)
+          raise ArgumentError, "MultiAgent execution provider must be callable" unless provider.respond_to?(:call)
+          @provider = provider
+        end
+
+        def current
+          @provider&.call || raise(Phronomy::ConfigurationError, "MultiAgent execution environment has not been configured")
+        end
+      end
+
+      def admissions = raise(NotImplementedError)
+      def ownership = raise(NotImplementedError)
+      def existing_ownership = raise(NotImplementedError)
+      def current? = raise(NotImplementedError)
+      def submit(**options, &operation) = raise(NotImplementedError)
+    end
+  end
+end

data/lib/phronomy/{agent/handoff → multi_agent}/handoff.rb

@@ -3,7 +3,7 @@
 require "digest"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Application-defined semantic edge for transferring active responsibility
     # from one live Agent instance to another.
     class Handoff
@@ -19,7 +19,7 @@ module Phronomy
           raise ArgumentError, "Handoff source_agent and target_agent must be different instances"
         end
         unless policy.is_a?(HandoffPolicy)
-          raise ArgumentError, "policy must be a Phronomy::Agent::HandoffPolicy"
+          raise ArgumentError, "policy must be a Phronomy::MultiAgent::HandoffPolicy"
         end
 
         @source_agent = source_agent

data/lib/phronomy/{agent/handoff → multi_agent}/handoff_capability_factory.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     class HandoffCapabilityFactory
       Binding = Data.define(:handoff, :tool_class, :tool_name) do
+        def source_agent_id = handoff.source_agent.agent_id
+
+        def request(arguments:, llm_call_id:, tool_call_id:)
+          args = arguments.transform_keys(&:to_sym)
+          allowed = [:responsibility] + handoff.policy.selectable_categories.map { |category| :"include_#{category}" }
+          raise ArgumentError, "Unknown Handoff argument" unless (args.keys - allowed).empty?
+          selection = HandoffPolicy::CATEGORIES.to_h do |category|
+            value = if handoff.policy.selectable?(category)
+              args.fetch(:"include_#{category}") { handoff.policy.default_include?(category) }
+            else
+              handoff.policy.required?(category)
+            end
+            [category, value]
+          end
+          Phronomy::Agent::ControlRequest.new(target_agent_id: handoff.target_agent.agent_id,
+            responsibility: args.fetch(:responsibility), selection: selection,
+            llm_call_id: llm_call_id, tool_call_id: tool_call_id)
+        end
+
         def initialize(handoff:, tool_class:, tool_name:)
           super(handoff: handoff, tool_class: tool_class, tool_name: tool_name.to_s.freeze)
           freeze
@@ -16,7 +35,7 @@ module Phronomy
         description = handoff.description
         policy = handoff.policy
 
-        klass = Class.new(Phronomy::Agent::Context::Capability::Base) do
+        klass = Class.new(Phronomy::Tool::Base) do
           self.tool_name(tool_name)
           self.description(description)
           execution_mode :cooperative

data/lib/phronomy/multi_agent/handoff_participant.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module MultiAgent
+    # Routing and Agent terminal state share the same outer transaction. This
+    # participant sees public semantic values only, never Agent records.
+    # @api private
+    class HandoffParticipant
+      def initialize(persistence:, main_agent_id:, expected_revision:)
+        @persistence, @main_agent_id, @expected_revision = persistence, main_agent_id, expected_revision
+      end
+
+      def binding
+        Phronomy::Agent::ExecutionExtensionState.new(binding_key: "phronomy.handoff", binding_version: 1)
+      end
+
+      def guard_change(change, scope)
+        @persistence.participate(scope) { |records| records.handoff_states.load_locked(@main_agent_id) }
+        ids = [@main_agent_id, change.agent_id, change.control_request&.target_agent_id].compact
+        @persistence.agent_store.guard_agents(scope, agent_ids: ids)
+      end
+
+      def change_evidence(change, scope)
+        state = @persistence.participate(scope) { |records| records.handoff_states.load(@main_agent_id) }
+        ids = [@main_agent_id, change.agent_id, change.control_request&.target_agent_id].compact.uniq.sort
+        [state&.to_h, ids.map { |id| @persistence.agent_store.retained_references(agent_id: id, scope: scope).map(&:to_h) }]
+      end
+
+      def commit(change)
+        @persistence.coordinator.atomic do |scope|
+          guard_change(change, scope)
+          change.prepare_in(scope)
+          @persistence.participate(scope) do |records|
+            routing = records.handoff_states.load(@main_agent_id)
+            unless routing && routing.active_agent_id == change.agent_id
+              raise Phronomy::Persistence::StateConflictError, "Handoff no longer owns this execution"
+            end
+            receipt = nil
+            if change.kind == :terminal && change.control_request
+              if Array(routing.metadata["cancelled_execution_ids"]).include?(change.execution_id) || change.cancel_requested
+                raise Phronomy::CancellationError, "Handoff Source turn was cancelled"
+              end
+              unless routing.handoff_revision == @expected_revision
+                raise Phronomy::Persistence::StateConflictError, "Handoff routing changed before Source transfer"
+              end
+              request = change.control_request
+              context = change.transfer_context(scope)
+              ref = records.contents.put_json(context.to_h)
+              target_id = "handoff-target-#{Digest::SHA256.hexdigest([change.execution_id, request.target_agent_id].join("\0"))}"
+              definition = @persistence.agent_store.definition(agent_id: request.target_agent_id, scope: scope)
+              retain(scope, change.agent_id, change.execution_id)
+              retain(scope, request.target_agent_id, target_id)
+              receipt = {"target_agent_id" => request.target_agent_id, "target_execution_id" => target_id,
+                         "context_ref" => ref, "owner_key" => "handoff:#{@main_agent_id}"}.freeze
+              ids = (Array(routing.metadata["retained_agent_ids"]) + [change.agent_id, request.target_agent_id]).uniq.sort
+              transfer = routing.with(active_agent_id: request.target_agent_id, active_handoff_context_ref: ref,
+                phase: "target_pending", pending_source_execution_id: change.execution_id, pending_target_execution_id: target_id,
+                metadata: routing.metadata.merge("target_definition" => definition.transform_keys(&:to_s),
+                  "source_agent_id" => change.agent_id, "retained_agent_ids" => ids))
+              records.handoff_states.save(@main_agent_id, expected_revision: routing.handoff_revision, state: transfer)
+            elsif change.finishing? && routing.phase != "stable" && routing.pending_target_execution_id == change.execution_id
+              records.handoff_states.save(@main_agent_id, expected_revision: routing.handoff_revision, state: routing.with(phase: "stable"))
+            end
+            change.commit_in(scope, transfer_receipt: receipt)
+          end
+        end
+      end
+
+      private
+
+      def retain(scope, id, execution_id)
+        @persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: id, execution_id: execution_id,
+          owner_key: "handoff:#{@main_agent_id}"), scope: scope)
+      end
+    end
+  end
+end

data/lib/phronomy/{agent/handoff → multi_agent}/handoff_policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     class HandoffPolicy
       CATEGORIES = %i[current_request history knowledge tool_exchanges].freeze
       MODES = %i[required forbidden selectable].freeze