phronomy 0.26.0 → 0.27.0

data/docs/runtime-and-concurrency.md

@@ -23,37 +23,38 @@ are defined by
 
 ## Runtime model
 
-```text
-Runtime
-├─ Agent ownership registry
-│  └─ agent_id -> one mutable live Agent instance
-├─ EventLoop (one control-plane operating-system Thread)
-│  ├─ FSMSession
-│  │  ├─ Agent
-│  │  ├─ Workflow
-│  │  ├─ ToolInvocation
-│  │  └─ MultiAgent fan-out
-│  ├─ Agent top-level admission
-│  │  └─ agent_id -> one nonterminal logical Execution admission
-│  └─ Agent execution directory
-│     └─ execution_id -> immutable live-state record
-├─ OffloadPool (bounded operating-system Threads)
-│  ├─ private Operation records
-│  ├─ blocking input/output (I/O)
-│  ├─ central-processing-unit (CPU)-bound synchronous work
-│  └─ operation-specific durable Agent/Workflow work
-├─ named OffloadPools
-└─ EventLoop-driven timers
-
-EventLoop / FSMSession ─┐
-                       ├─> TaskResult = completion handle
-OffloadPool ────────────┘
-```
+| Runtime-retained component | Implementation owner and responsibility |
+|---|---|
+| Shutdown participants | Feature-owned registries: Agent identity, Team identity, and MultiAgent synchronous-call admission |
+| EventLoop | Engine dispatcher thread, FSMSessions and registered feature receivers |
+| Execution receivers | Agent/Workflow own execution admission, state and idle policies; mutations run on EventLoop |
+| OffloadPool and named pools | Engine bounded workers and private physical-operation records |
+| Timers | Engine EventLoop-driven scheduling |
+
+Runtime retains participants through a generic lifecycle protocol; it does not
+construct Agent or Team identity registries. Each feature registers its own
+instance. See [ADR-041](decisions/041-feature-owned-identity-registries.md).
 
 The framework does not allocate one operating-system Thread per logical
 Agent/Workflow/Tool lifecycle. Logical waits remain explicit states plus later
 EventLoop events.
 
+## Feature execution receivers
+
+[ADR-042](decisions/042-feature-owned-execution-state.md) separates implementation
+ownership from the single-writer execution context. Agent and Workflow create
+`Agent::ExecutionRegistry` and `WorkflowExecutionRegistry` respectively; Engine
+retains registered receivers without selecting concrete feature types.
+
+Receiver registration and new request admission close before idle checks.
+Already queued requests, pending durable operations and supervised physical
+work are counted until their feature continuation settles. Worker callbacks
+only enqueue results. Workflow instance routing and generic FSM enqueue share
+one lock. After a clean join, receiver cleanup invalidates retained state;
+a failing receiver makes Runtime cleanup incomplete. Dispatcher failure instead
+notifies receivers on the failing loop thread with the original error.
+
+
 ## Live state and durable state
 
 A live Agent or Workflow owns its current logical state. `Persistence` is the
@@ -61,7 +62,7 @@ last committed durable representation and recovery source; it is not reloaded at
 every semantic boundary.
 
 For active Agents, **EventLoop is the single writer of Phronomy-managed live
-execution state**. EventLoop owns a process-local execution directory keyed by
+execution state**. `Agent::ExecutionRegistry` owns the process-local directory keyed by
 canonical `execution_id`. Each directory value is immutable and is replaced on
 EventLoop when the current AgentExecution, RuntimeProjection, AgentInvocation, or
 owning FSMSession changes. The former mutex-protected
@@ -75,7 +76,7 @@ handling; workers do not receive AgentInvocation as a mutable state authority.
 Mutable Agent/Execution/Journal state is not automatically reloaded before every
 LLM or Tool step. Durable writes use optimistic revision/position guardrails; an
 external writer that advances the durable base causes
-`Persistence::ConflictError` rather than automatic reload or merge.
+`Storage::ConflictError` rather than automatic reload or merge.
 
 For Workflows, the current `WorkflowContext` and FSMSession own the active
 logical state. A durable Workflow hydrates once at invocation/resume and saves at
@@ -88,8 +89,9 @@ content reference is value materialization rather than mutable state refresh.
 
 `agent_id` identifies one logical Agent, not a reusable lookup key for independent
 mutable objects. One Runtime therefore publishes at most one mutable live Agent
-instance for a given `agent_id`. The Runtime-owned registry is an authority, not a
-cache, and reserves the identity before create/load materialization.
+instance for a given `agent_id`. The Agent-owned registry, strongly retained by
+Runtime, is an authority, not a cache, and reserves the identity before
+create/load materialization.
 
 The application-facing identity operations are distinct:
 
@@ -100,7 +102,7 @@ new / create
 load(agent_id, persistence:)
   live -> exact same Ruby object, with no Persistence reload
   durable-only -> hydrate and publish once
-  missing -> Persistence::NotFoundError
+  missing -> Storage::NotFoundError
 
 get(agent_id)
   live Runtime lookup only; missing -> nil
@@ -114,7 +116,8 @@ invalidates the old object, deletes durable state, releases the process-local
 identity, and allows a later new Agent to reuse the textual ID.
 
 Live Agent ownership and top-level Execution admission are separate lifetimes.
-For one live Agent, EventLoop admits at most one nonterminal top-level Execution.
+For one live Agent, `Agent::ExecutionRegistry` admits at most one nonterminal
+top-level Execution on EventLoop.
 Admission is acquired **before** the initial Offload/Persistence operation:
 
 ```text
@@ -195,6 +198,15 @@ Phronomy-managed live domain objects are rejected from that value data. A comple
 value-type/serialization contract for arbitrary Application-owned opaque objects is
 deferred; such objects remain Application-owned and must be worker-safe.
 
+The existing restricted types declare the internal methodless
+`Concurrency::WorkerInputRestricted` marker at their own definitions.
+ToolInvocation checks that execution-boundary contract instead of enumerating
+Agent/Workflow/Runtime classes. Frozen marked values and subclasses remain
+restricted; Hash keys and values, nested Arrays and behavior handles are all
+checked. The marker does not inspect opaque application fields or closure
+captures and is not a general restriction on every OffloadPool command.
+See [ADR-045](decisions/045-worker-input-restriction-ownership.md).
+
 Worker authorization/execution outcomes return as values carrying
 `tool_invocation_id`; the Tool FSMSession consumes a mismatched semantic result
 without advancing its current state.
@@ -279,6 +291,32 @@ remain durable conflict defense rather than distributed ownership.
 
 ## Tool execution modes
 
+The default dispatch helper is the private
+`Phronomy::Agent::Context::Capability::ToolExecutor`, colocated with Capability
+Base. Agent ToolInvocation supplies Runtime and admission policy for the
+standard path, and owns authorization and logical result handling. Custom
+`call_async` implementations keep the public Tool protocol. This ownership is
+defined by [ADR-035](decisions/035-tool-executor-capability-ownership.md); the
+public `Phronomy::Tool::Base` facade and its Class identity remain unchanged.
+
+Agent uses ordinary `RubyLLM::Chat` for both complete and streaming Provider
+calls. The `before_tool_call` callback takes the complete assistant Tool-call
+batch before RubyLLM executes the first Tool body. `AgentInvocation` then owns
+authorization, dispatch, approval suspension and result collection. Offloaded
+Tools can overlap within Runtime capacity; short cooperative Tools run according
+to their existing execution contract.
+
+On successful batch completion, Agent records one Tool result per call ID in
+request order and includes the whole exchange in the next Provider request.
+Worker completion order does not split the conversation or trigger a partial
+Provider continuation. Failure, cancellation and approval keep their existing
+Agent lifecycle semantics.
+
+There is no separate Chat execution path or `parallel_tool_execution` switch.
+The removed internal `MultiAgent::ParallelToolChat` class is not replaced by an
+alias. See the [Chat migration guide](migrations/parallel-tool-chat-removal.md)
+for application configuration and existing stored model-config records.
+
 Phronomy exposes two execution modes for capabilities:
 
 - `:cooperative` — short EventLoop-safe work, or specialized asynchronous work
@@ -547,6 +585,53 @@ Use these to distinguish worker saturation from EventLoop backlog/latency.
 Runtime-owned EventLoop, then closes pools and timers according to the Runtime
 shutdown contract.
 
+Internal subsystems can register one shutdown participant per Runtime-local key
+through `Runtime#__register_shutdown_participant`. This is an internal lifecycle
+contract, not a public extension API or an execution registry. Runtime does not
+construct participants or interpret their admission rules.
+
+Each participant implements two required operations:
+
+- `begin_draining` closes admission under the participant's admission lock. It
+  must be idempotent, short and nonblocking, and must not call back into Runtime.
+  Runtime invokes it under its lifecycle lock when shutdown starts or EventLoop
+  fails, so no participant can be registered after closure begins.
+- `wait_until_idle(deadline)` returns whether admitted calls have finished before
+  the shared absolute monotonic deadline. Runtime closes every participant before
+  waiting, and waits without holding its lifecycle lock. A timeout or failed hook
+  makes cleanup incomplete; other participants, pools and timers still receive
+  their shutdown calls. Incomplete cleanup prevents default Runtime replacement.
+
+Participants may also implement `after_runtime_shutdown`. Runtime calls it
+outside its lifecycle lock after every wait succeeds, EventLoop has stopped,
+and pools/timers have shut down successfully. The hook must be idempotent,
+short, and perform no I/O; its return value is ignored. A hook exception marks
+cleanup incomplete, retains the first failure, and does not skip later hooks.
+Completed releases are not rolled back; repeated shutdown returns its cached
+result without retrying hooks. A prior closure/wait failure, timeout, or worker
+shutdown failure skips finalization entirely.
+
+`Runtime#__shutdown_participant(key:)` only retrieves an existing participant,
+including during/after shutdown. Registration still requires a running Runtime,
+even for an existing key. Agent/Team `get` uses lookup without registration;
+feature gates reject new ownership changes through retained registries after
+closure. Already admitted transitions may finish. Identity registries wait only
+for active construction/purge, then detach Agent references or clear Team
+owners at finalization; live idle objects do not themselves prolong shutdown.
+
+`MultiAgent::AdmissionRegistry.for(runtime)` constructs and registers the shared
+coordination admission registry. MultiAgent::HandoffRunner and TeamCoordinator retain that
+registry, admit each synchronous call directly and release it in `ensure` after
+successful admission. The registry closes admission atomically with respect to
+`admit!`; a call admitted before closure is included in the wait, and a call after
+closure raises `RuntimeShutdownError`, including after EventLoop failure. The
+existing `HandoffError` for duplicate admission remains unchanged.
+
+This tracks the current synchronous Handoff/Team call, not the lifetime or
+completion of a durable AgentExecution or TeamExecution. Multi-Agent policy stays
+in `multi_agent`; Runtime depends only on the shutdown operations. Application
+authors do not register these participants themselves.
+
 Workflow durable admission participates in EventLoop idleness: a Workflow whose
 FSMSession has ended but whose durable save is still in flight remains owned until
 that save completes and owner-aware admission is released.

data/lib/phronomy/agent/api/agent.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    StreamEvent = Data.define(:type, :payload)
+  end
+end
+
+require_relative "../async_event_api"
+
+unless Phronomy::Agent::Base < Phronomy::Agent::AsyncEventApi
+  Phronomy::Agent::Base.prepend(Phronomy::Agent::AsyncEventApi)
+end
+
+# Durable Agent Recovery and Agent-incarnation event binding.
+require_relative "../recovery/recovery_support"
+require_relative "../recovery/recovery_coordinator"

data/lib/phronomy/agent/async_event_api.rb

@@ -96,7 +96,7 @@ module Phronomy
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
         _reject_removed_generic_identity_keys!(config)
-        owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+        owner = Phronomy::Agent::ExecutionRegistry.existing_for(Phronomy::Runtime.instance)&.agent_execution_owner(execution_id)
         coordinator = if owner&.agent&.equal?(self)
           owner.coordinator
         else
@@ -190,7 +190,7 @@ module Phronomy
         end
 
         bytes = Phronomy::CanonicalJSON.dump(value)
-        snapshot = Phronomy::Agent::Immutable.copy(
+        snapshot = Phronomy::Values::Immutable.copy(
           Phronomy::CanonicalJSON.load(bytes)
         )
         config.merge(durable_context: snapshot)

data/lib/phronomy/agent/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../engine/concurrency/worker_input_restricted"
+
 require "securerandom"
 require_relative "concerns/filterable"
 require_relative "concerns/before_llm_input"
@@ -31,6 +33,8 @@ module Phronomy
     #     max_iterations 15
     #   end
     class Base
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       include Phronomy::Runnable
       include Concerns::Filterable
       include Concerns::BeforeLLMInput
@@ -119,15 +123,9 @@ module Phronomy
           if val.nil?
             @max_output_tokens
           else
-            @max_output_tokens = val.to_i
-          end
-        end
-
-        def context_window(val = nil)
-          if val.nil?
-            @context_window
-          else
-            @context_window = val.to_i
+            value = Integer(val)
+            raise ArgumentError, "max_output_tokens must be positive" unless value.positive?
+            @max_output_tokens = value
           end
         end
 
@@ -204,7 +202,7 @@ module Phronomy
           runtime = Phronomy::Runtime.instance
           materialized = false
 
-          agent = runtime.__load_agent(key, expected_class: self) do |owner_runtime|
+          agent = OwnershipRegistry.for(runtime).load(key, expected_class: self) do |owner_runtime|
             materialized = true
             instance = __construct_owned_agent(
               owner_runtime,
@@ -235,14 +233,17 @@ module Phronomy
         # Returns only the process-local live Agent owner. Does not access
         # Persistence and returns nil when this Runtime has no live owner.
         def get(agent_id)
-          Phronomy::Runtime.instance.__get_agent(agent_id, expected_class: self)
+          key = agent_id.to_s
+          raise ArgumentError, "agent_id must not be empty" if key.empty?
+
+          OwnershipRegistry.existing_for(Phronomy::Runtime.instance)&.get(key, expected_class: self)
         end
 
         # Resolves the live Agent instance that currently owns execution_id in
         # this process. The Runtime returns only a read-only ownership view;
         # mutable Agent execution state remains EventLoop-owned.
         def live_for_execution(execution_id)
-          owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+          owner = Phronomy::Agent::ExecutionRegistry.existing_for(Phronomy::Runtime.instance)&.agent_execution_owner(execution_id)
           unless owner
             raise Phronomy::ExecutionRehydrationRequiredError,
               "no live execution owner for #{execution_id}; durable rehydration is required"
@@ -338,7 +339,7 @@ module Phronomy
 
         runtime = Phronomy::Runtime.instance
         begin
-          runtime.__create_agent(effective_agent_id, expected_class: self.class) do |owner_runtime|
+          OwnershipRegistry.for(runtime).create(effective_agent_id, expected_class: self.class) do |owner_runtime|
             __prepare_runtime_owner!(owner_runtime, effective_agent_id)
             initialize_owned_state(
               agent_id: effective_agent_id,
@@ -350,7 +351,7 @@ module Phronomy
             )
             self
           end
-        rescue Phronomy::Persistence::ConflictError => error
+        rescue Phronomy::Storage::ConflictError => error
           raise Phronomy::AgentAlreadyExistsError,
             "Agent #{effective_agent_id.inspect} already exists durably: #{error.message}"
         end
@@ -395,34 +396,8 @@ module Phronomy
       def add_knowledge(content, metadata: {})
         __assert_live_agent!
         current = agent_root
-        next_root = nil
-        appended = nil
-        persistence.transaction do |tx|
-          tx.executions.assert_idle!(agent_id)
-          record = build_knowledge_record(
-            tx: tx,
-            root: current,
-            content: content,
-            metadata: metadata
-          )
-          appended = tx.journals.append(
-            agent_id,
-            expected_position: current.journal_position,
-            records: [record]
-          )
-          next_root = current.with(
-            agent_revision: current.agent_revision + 1,
-            context_revision: current.context_revision + 1,
-            journal_position: current.journal_position + appended.length
-          )
-          tx.agents.save(
-            agent_id,
-            expected_revision: current.agent_revision,
-            root: next_root
-          )
-        end
-        _append_journal_records(appended)
-        @root = next_root
+        update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
+        apply_state_update(update)
         self
       end
 
@@ -450,9 +425,10 @@ module Phronomy
 
         __assert_live_agent!
         runtime = @_phronomy_runtime_owner
-        token = runtime.__begin_agent_purge(self)
-        if runtime.__agent_execution_admitted?(agent_id)
-          runtime.__abort_agent_purge(self, token)
+        registry = OwnershipRegistry.for(runtime)
+        token = registry.begin_purge(self)
+        if Phronomy::Agent::ExecutionRegistry.existing_for(runtime)&.agent_execution_admitted?(agent_id)
+          registry.abort_purge(self, token)
           raise Phronomy::AgentBusyError,
             "Agent #{agent_id.inspect} has a nonterminal top-level execution"
         end
@@ -471,20 +447,20 @@ module Phronomy
             tx.agents.delete(agent_id)
           end
         rescue Phronomy::AgentBusyError,
-          Phronomy::Persistence::ConflictError,
-          Phronomy::Persistence::NotFoundError,
-          Phronomy::Persistence::SerializationError,
+          Phronomy::Storage::ConflictError,
+          Phronomy::Storage::NotFoundError,
+          Phronomy::Storage::SerializationError,
           ArgumentError
-          runtime.__abort_agent_purge(self, token)
+          registry.abort_purge(self, token)
           raise
         rescue
           # Without F1 reconciliation support we cannot infer that a failed
           # durable delete did not commit. Keep the identity fail-closed.
-          runtime.__leave_agent_purge_uncertain(self, token)
+          registry.leave_purge_uncertain(self, token)
           raise
         end
 
-        runtime.__complete_agent_purge(self, token)
+        registry.complete_purge(self, token)
         true
       end
 
@@ -585,7 +561,7 @@ module Phronomy
       )
         @persistence = persistence ||
           Phronomy.configuration.persistence ||
-          Phronomy::Persistence::InMemory.new
+          DefaultPersistence.build
         @agent_id = agent_id.to_s.freeze
 
         if load_existing
@@ -630,117 +606,27 @@ module Phronomy
 
       def create_agent_root!(context:, knowledge:, metadata:)
         definition = self.class.agent_definition
-        root = Agent::AgentRoot.create(
-          agent_id: agent_id,
-          agent_definition_id: definition.fetch(:id),
-          agent_definition_version: definition.fetch(:version),
-          metadata: metadata
-        )
-        persistence.transaction do |tx|
-          tx.agents.create(root)
-          records = initial_context_records(tx: tx, root: root, context: context)
-          records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
-          unless records.empty?
-            appended = tx.journals.append(agent_id, expected_position: 0, records: records)
-            root = root.with(
-              agent_revision: 1,
-              context_revision: 1,
-              journal_position: appended.length
-            )
-            tx.agents.save(agent_id, expected_revision: 0, root: root)
-          end
-        end
-        root
-      end
-
-      def initial_context_records(tx:, root:, context:)
-        return [] unless context
-
-        imported = context.respond_to?(:records) ? context :
-          Agent::ContextImporter.import_messages(context)
-        imported.records.map do |record|
-          content_ref = case record.content_format
-          when :text then tx.contents.put_text(record.content)
-          when :json then tx.contents.put_json(record.content)
-          else
-            raise ArgumentError,
-              "unsupported imported content format: #{record.content_format.inspect}"
-          end
-          Agent::JournalRecord.new(
-            agent_id: agent_id,
-            kind: record.kind,
-            channel: record.channel,
-            role: record.role,
-            content_ref: content_ref,
-            context_generation: root.transcript_generation,
-            context_candidate: true,
-            metadata: record.metadata
-          )
-        end
-      end
-
-      def initial_knowledge_records(tx:, root:, knowledge:)
-        Array(knowledge).map do |content|
-          build_knowledge_record(
-            tx: tx,
-            root: root,
-            content: content,
-            metadata: {}
-          )
-        end
-      end
-
-      def build_knowledge_record(tx:, root:, content:, metadata:)
-        Agent::JournalRecord.new(
-          agent_id: agent_id,
-          kind: :knowledge,
-          channel: :context,
-          role: :user,
-          content_ref: tx.contents.put_text(String(content)),
-          context_generation: root.transcript_generation,
-          context_candidate: true,
-          metadata: metadata || {}
+        state_writer.create_root(
+          definition: definition, context: context, knowledge: knowledge, metadata: metadata
         )
       end
 
       def mutate_context!(kind, context_affecting: true)
         __assert_live_agent!
         current = agent_root
-        next_root = nil
-        appended = nil
-        persistence.transaction do |tx|
-          tx.executions.assert_idle!(agent_id)
-          record = Agent::JournalRecord.new(
-            agent_id: agent_id,
-            kind: kind,
-            channel: :state,
-            context_generation: current.transcript_generation,
-            context_candidate: false
-          )
-          appended = tx.journals.append(
-            agent_id,
-            expected_position: current.journal_position,
-            records: [record]
-          )
-          proposed = yield(current)
-          next_root = proposed.with(
-            journal_position: current.journal_position + appended.length,
-            context_revision: context_affecting ?
-              yield_context_revision(current, proposed) : current.context_revision
-          )
-          tx.agents.save(
-            agent_id,
-            expected_revision: current.agent_revision,
-            root: next_root
-          )
-        end
-        _append_journal_records(appended)
-        @root = next_root
+        update = state_writer.mutate_context(
+          root: current, kind: kind, context_affecting: context_affecting
+        ) { |root| yield(root) }
+        apply_state_update(update)
       end
 
-      def yield_context_revision(current, proposed)
-        (proposed.context_revision == current.context_revision) ?
-          current.context_revision + 1 : proposed.context_revision
+      def state_writer
+        StateWriter.new(persistence: persistence, agent_id: agent_id)
+      end
+
+      def apply_state_update(update)
+        _append_journal_records(update.records)
+        @root = update.root
       end
 
       def _journal_records_snapshot
@@ -789,7 +675,8 @@ module Phronomy
         return true if @_phronomy_runtime_owner_state == :constructing
 
         runtime = @_phronomy_runtime_owner
-        unless runtime&.__agent_owned?(self)
+        registry = OwnershipRegistry.existing_for(runtime) if runtime
+        unless registry&.owned?(self)
           raise Phronomy::RuntimeShutdownError,
             "Agent #{agent_id.inspect} is no longer the live owner in its Runtime"
         end
@@ -943,7 +830,7 @@ module Phronomy
           )
         end
         projection.tool_classes.each do |tool_class|
-          chat.with_tool(prepare_tool_class(tool_class, invocation: invocation))
+          chat.with_tools(prepare_tool_class(tool_class, invocation: invocation))
         end
         projection.messages.each { |message| chat.messages << message }
         chat
@@ -954,25 +841,9 @@ module Phronomy
           "model" => self.class.model,
           "provider" => self.class.provider,
           "temperature" => self.class.temperature,
-          "max_output_tokens" => self.class.max_output_tokens,
-          "parallel_tool_execution" => Phronomy.configuration.parallel_tool_execution
+          "max_output_tokens" => self.class.max_output_tokens
         }
-        opts = {}
-        model = config["model"]
-        opts[:model] = model if model
-        provider = config["provider"]
-        if provider
-          opts[:provider] = provider.to_sym
-          opts[:assume_model_exists] = true
-        end
-        parallel_class = config["parallel_tool_execution"] ?
-          Phronomy::MultiAgent::ParallelToolChat : nil
-        chat = parallel_class ? parallel_class.new(**opts) : RubyLLM.chat(**opts)
-        chat.with_temperature(config["temperature"]) if config["temperature"]
-        if config["max_output_tokens"] && chat.respond_to?(:with_max_output_tokens)
-          chat.with_max_output_tokens(config["max_output_tokens"])
-        end
-        chat
+        RuntimeChatBuilder.build(config)
       end
 
       def build_instructions(input)
@@ -988,12 +859,7 @@ module Phronomy
       end
 
       def apply_instructions(chat, text, cache: false, provider: nil)
-        if cache && provider.to_s == "anthropic"
-          content = RubyLLM::Providers::Anthropic::Content.new(text, cache: true)
-          chat.with_instructions(content)
-        else
-          chat.with_instructions(text)
-        end
+        RuntimeChatBuilder.apply_instructions(chat, text, cache: cache, provider: provider)
       end
 
       def extract_message(input)
@@ -1021,66 +887,10 @@ module Phronomy
       def prepare_tool_class(tool_class, invocation: nil)
         return tool_class unless tool_class.is_a?(Class)
 
-        resolved = if (alias_name = self.class.tool_aliases[tool_class])
-          Class.new(tool_class) do
-            tool_name alias_name
-          end
-        else
-          tool_class
-        end
-
-        result_filters = _tool_result_filters_for(tool_class)
-        return resolved if result_filters.empty?
-
-        effective_name = resolved.new.name
-        custom_async_call =
-          resolved.instance_method(:call_async).owner !=
-          Phronomy::Agent::Context::Capability::Base
-
-        Class.new(resolved) do
-          tool_name effective_name
-          define_method(:call) do |args, **kwargs|
-            result = super(args, **kwargs)
-            result_filters.inject(result) { |val, filter|
-              filter.call(val, tool_name: name, args: args)
-            }
-          end
-
-          if custom_async_call
-            define_method(:call_async) do |args, **kwargs|
-              source = super(args, **kwargs)
-              filtered = Phronomy::Concurrency::PhysicalCompletionTask.deferred(
-                name: "tool-filter-#{name}"
-              )
-              source_has_physical_signal = source.respond_to?(:on_physical_complete)
-              source.on_physical_complete { filtered.mark_physical_complete! } if
-                source_has_physical_signal
-              source.on_complete do |value, error|
-                if error
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  if source.respond_to?(:status) && source.status == :cancelled
-                    filtered.cancel!(error)
-                  else
-                    filtered.fail(error)
-                  end
-                  next
-                end
-
-                begin
-                  result = result_filters.inject(value) { |val, filter|
-                    filter.call(val, tool_name: name, args: args)
-                  }
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  filtered.complete(result)
-                rescue => filter_error
-                  filtered.mark_physical_complete! unless source_has_physical_signal
-                  filtered.fail(filter_error)
-                end
-              end
-              filtered
-            end
-          end
-        end
+        binding = ToolBinding.new(
+          tool_class, alias_name: self.class.tool_aliases[tool_class]
+        )
+        binding.prepare(result_filters: _tool_result_filters_for(tool_class))
       end
     end
   end