phronomy 0.31.0 → 0.33.0

data/lib/phronomy/context/context_policy_input.rb

@@ -56,6 +56,32 @@ module Phronomy
         freeze
       end
 
+      # Reports the input limit supplied to this Policy without exposing the
+      # framework's budget representation. Unknown capability remains nil.
+      # @return [Integer, nil]
+      # @api public
+      def input_token_limit
+        token_budget&.effective_input_limit
+      end
+
+      # Returns a selection input with an application limit. A known limit may
+      # only be retained or reduced. An unknown limit accepts an explicit cap
+      # without asserting that the model can accept that many tokens.
+      # @param limit [Integer] positive selection limit
+      # @return [ContextPolicyInput]
+      # @raise [ArgumentError] for an invalid limit or a known-limit increase
+      # @api public
+      def with_input_token_limit(limit)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "input token limit must be a positive Integer"
+        end
+        if input_token_limit && limit > input_token_limit
+          raise ArgumentError, "input token limit must not exceed the current limit"
+        end
+
+        with(token_budget: Phronomy::LlmContextWindow::TokenBudget.new(max_input_tokens: limit))
+      end
+
       private
 
       def validate_items!(items, expected_class, label)

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

data/lib/phronomy/multi_agent/shared_state/binding.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class SharedState
+      # Connects one application's shared data to the Tools offered to members.
+      # The application owns the store's shape, operations and resource lifetime.
+      # @api public
+      class Binding
+        # @param store [Object] opaque application data passed to coordination callbacks
+        # @param tools [#call] builder accepting member: (Agent class) and cycle:
+        # @api public
+        def initialize(store:, tools:)
+          raise ArgumentError, "sharing tools must respond to call" unless tools.respond_to?(:call)
+
+          @store = store
+          @tools = tools
+          freeze
+        end
+
+        # @api public
+        attr_reader :store
+
+        # Build invocation-bound Tools using the existing Agent.tools declaration shape.
+        # The builder receives the registered Agent class, not an Agent instance.
+        # @return [Hash<Class, String, nil>] Tool classes mapped to aliases or nil
+        # @api public
+        def tool_definitions(member:, cycle:)
+          definitions = @tools.call(member: member, cycle: cycle)
+          unless definitions.is_a?(Hash)
+            raise ArgumentError, "sharing tools must return a Hash of ToolClass => alias_or_nil"
+          end
+
+          definitions.to_h do |tool_class, alias_name|
+            unless tool_class.is_a?(Class) && tool_class <= Phronomy::Tool::Base
+              raise ArgumentError, "sharing tools must contain Phronomy::Tool::Base classes"
+            end
+            [tool_class, alias_name&.to_s&.dup&.freeze]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/shared_state/member_lifecycle_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class SharedState
+      # Keeps the member handle when invocation-scoped sharing cannot finish safely.
+      # Callers choose approval, cancellation or release through existing Agent APIs.
+      # @api public
+      class MemberLifecycleError < Phronomy::Error
+        # @api public
+        attr_reader :agent, :result, :reason, :primary_error, :release_error
+
+        # The live Agent and application resources are process-local, not a
+        # durable recipe for rebuilding the sharing provider or its Tools.
+        # @api public
+        def initialize(agent:, result:, reason:, primary_error: nil, release_error: nil)
+          @agent = agent
+          @result = result
+          @reason = reason
+          @primary_error = primary_error
+          @release_error = release_error
+          message = if reason == :suspended
+            "SharedState sharing cannot complete while a member is suspended"
+          else
+            "SharedState sharing could not release a member: #{release_error&.message}"
+          end
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/shared_state.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Phronomy
   module MultiAgent
-    # Implements peer coordination through an invocation-local KnowledgeStore.
+    # Coordinates members through default findings or application-defined shared data.
     # @api public
     class SharedState
       # Semantic revision of the framework-owned SharedState instrumentation
@@ -70,6 +72,29 @@ module Phronomy
           block ? @aggregator = block : @aggregator
         end
 
+        # Declare application-owned sharing for each invocation. The provider's
+        # open(input:, config:) method must synchronously yield one Binding.
+        # Its block scope owns any connection or other application resource.
+        # Increment version when the shared Tool schemas or meanings change.
+        # @param provider [#open]
+        # @param id [String] stable application sharing definition identity
+        # @param version [Integer] positive sharing definition revision
+        # @api public
+        def sharing(provider, id:, version:)
+          raise ArgumentError, "sharing provider must respond to open" unless provider.respond_to?(:open)
+          unless id.is_a?(String) && !id.strip.empty?
+            raise ArgumentError, "sharing id must be a nonempty String"
+          end
+          unless version.is_a?(Integer) && version.positive?
+            raise ArgumentError, "sharing version must be a positive Integer"
+          end
+
+          @sharing = {provider: provider, id: id.dup.freeze, version: version}.freeze
+        end
+
+        # @api private
+        def _sharing = @sharing
+
         def _members = Array(@members)
         def _coordination = @coordination
         def _max_cycles = @max_cycles
@@ -81,6 +106,8 @@ module Phronomy
       # @api public
       def invoke(input, config: {})
         validate_termination!
+        return invoke_with_sharing(input, config, self.class._sharing) if self.class._sharing
+
         store = KnowledgeStore.new
         cycles, terminated_by = coordinate_members(input, store)
 
@@ -97,7 +124,11 @@ module Phronomy
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
-          invoke_members(input, store, cycle)
+          if block_given?
+            yield cycle
+          else
+            invoke_members(input, store, cycle)
+          end
           completed_cycles = cycle
 
           if self.class._terminate_when&.call(store)
@@ -137,6 +168,120 @@ module Phronomy
           "max_cycles or timeout must be configured before invoking SharedState"
       end
 
+      def invoke_with_sharing(input, config, sharing)
+        unless self.class._aggregator
+          raise ArgumentError, "aggregate must be configured when sharing is configured"
+        end
+
+        open_sharing(sharing, input, config) do |binding|
+          cycles, terminated_by = coordinate_members(input, binding.store) do |cycle|
+            invoke_shared_members(input, binding, cycle, sharing)
+          end
+          {output: aggregate_findings(binding.store), cycles: cycles, terminated_by: terminated_by}
+        end
+      end
+
+      def open_sharing(sharing, input, config)
+        opening_thread = Thread.current
+        active = true
+        entered = completed = false
+        result = callback_error = nil
+
+        sharing.fetch(:provider).open(input: input, config: config) do |binding|
+          unless active && Thread.current.equal?(opening_thread)
+            raise ArgumentError, "sharing provider must yield synchronously within open"
+          end
+          raise ArgumentError, "sharing provider must yield exactly once" if entered
+
+          entered = true
+          unless binding.is_a?(Binding)
+            raise ArgumentError, "sharing provider must yield a SharedState::Binding"
+          end
+
+          result = yield binding
+          completed = true
+        rescue => error
+          callback_error = error
+          raise
+        end
+
+        raise callback_error if callback_error
+        unless entered && completed
+          raise ArgumentError, "sharing provider must yield exactly once and complete the block"
+        end
+
+        result
+      ensure
+        active = false
+      end
+
+      def invoke_shared_members(input, binding, cycle, sharing)
+        self.class._members.each do |member_config|
+          member = member_config.fetch(:klass)
+          definitions = shared_tool_definitions(member, binding, cycle)
+          instrumented = build_shared_researcher(member, definitions, sharing)
+          prompt = shared_prompt(input, member_config[:instruction])
+          invoke_shared_researcher(instrumented, prompt)
+        end
+      end
+
+      def invoke_shared_researcher(instrumented, prompt)
+        agent = instrumented.new
+        suspended = false
+        result = agent.invoke(prompt)
+        if result.is_a?(Hash) && result[:suspended]
+          suspended = true
+          raise MemberLifecycleError.new(agent: agent, result: result, reason: :suspended)
+        end
+        result
+      ensure
+        release_shared_member(agent, result, $!) if agent && !suspended
+      end
+
+      def release_shared_member(agent, result, primary_error)
+        agent.unload!
+      rescue => release_error
+        error = MemberLifecycleError.new(agent: agent, result: result, reason: :release_failed,
+          primary_error: primary_error, release_error: release_error)
+        raise error, cause: primary_error || release_error
+      end
+
+      def shared_tool_definitions(member, binding, cycle)
+        definitions = member.tools.to_h { |tool| [tool, member.tool_aliases[tool]] }
+        added = binding.tool_definitions(member: member, cycle: cycle)
+        unless (definitions.keys & added.keys).empty?
+          raise ArgumentError, "sharing Tool classes must not replace member Tools"
+        end
+
+        definitions = definitions.merge(added)
+        names = definitions.map { |tool, alias_name| (alias_name || tool.tool_name).to_s }
+        if names.any?(&:empty?) || names.uniq.length != names.length
+          raise ArgumentError, "sharing and member Tools must have distinct nonempty names or aliases"
+        end
+        definitions
+      end
+
+      def build_shared_researcher(member, definitions, sharing)
+        definition = shared_definition_for(member, sharing)
+        member.with_tools(definitions, id: definition.fetch(:id), version: definition.fetch(:version))
+      end
+
+      def shared_definition_for(member, sharing)
+        parent = member.agent_definition
+        identity = [parent.fetch(:id), parent.fetch(:version), sharing.fetch(:id), sharing.fetch(:version)]
+        digest = Digest::SHA256.hexdigest(Phronomy::CanonicalJSON.dump(identity))
+        {id: "Phronomy::MultiAgent::SharedState::Application/#{digest}", version: 1}
+      end
+
+      def shared_prompt(input, instruction)
+        guide = self.class._coordination ||
+          "Use the provided Tools to collaborate through the application's shared data."
+        parts = [guide]
+        parts << "\nYour specific focus for this session: #{instruction}" if instruction
+        parts << "\n\nTask: #{input}"
+        parts.join
+      end
+
       def invoke_researcher(
         researcher_class,
         store,