phronomy 0.31.0 → 0.33.0

data/lib/phronomy/agent/execution/execution_coordinator.rb

@@ -21,6 +21,36 @@ module Phronomy
         :approved, :config, :result_task
       )
 
+      # A resumed approval must never be adopted by the original start handle.
+      # Only a hosted decision owns the right to detach its next suspension.
+      class ApprovalOperation < OperationResult
+        attr_reader :parent_wait
+
+        def initialize(agent:, name:, parent_wait:)
+          super(agent: agent, name: name)
+          @parent_wait = parent_wait
+        end
+      end
+
+      # The recovery runner uses this task for replay of a framework Tool batch.
+      # @api private
+      class FrameworkRecoveryTask < Phronomy::TaskResult
+      end
+
+      # Recovery publishes a receipt only after its own coordination commit.
+      # The receipt belongs to this incarnation; a new local attempt invalidates it.
+      RecoveredCoordinationWait = Data.define(:coordinator, :execution_id, :revision) do
+        def current? = coordinator.current_coordination_wait?(self)
+      end
+      private_constant :ApprovalOperation, :RecoveredCoordinationWait
+      attr_reader :recovered_coordination_wait
+
+      def current_coordination_wait?(wait)
+        environment = @agent.__execution_environment
+        @recovered_coordination_wait.equal?(wait) && environment.ownership.owned?(@agent) &&
+          !environment.registry.agent_execution_admitted?(@agent.agent_id)
+      end
+
       # Recovery -> execution-owner commands. These stay on EventLoop and do
       # not carry persistence readers or arbitrary private method names.
       RecoverPreparationCommand = Data.define(
@@ -74,6 +104,8 @@ module Phronomy
       TerminalCommitReady = Data.define(
         :coordinator, :operation, :delivery, :outcome, :error
       )
+      DetachHostedWait = Data.define(:coordinator, :wait, :task, :parent, :completion)
+      private_constant :DetachHostedWait
       SuspensionCancelledCommand = Data.define(:coordinator, :execution_id)
 
       DeferredTerminalCommand = Data.define(
@@ -125,11 +157,11 @@ module Phronomy
         execution_id,
         approval_request_id:,
         approved:,
-        config: {}
+        config: {}, parent_wait: nil
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = OperationResult.new(agent: @agent,
+        result_task = ApprovalOperation.new(agent: @agent, parent_wait: parent_wait,
           name: "agent-approval-resume:#{execution_id}")
         command = ResumeCommand.new(
           coordinator: self,
@@ -148,6 +180,16 @@ module Phronomy
         result_task
       end
 
+      # Submit the committed wait for final ownership checks on the EventLoop.
+      # @api private
+      def request_hosted_detach(wait, task:, parent:)
+        completion = Phronomy::TaskResult.deferred(name: "detach-hosted-approval")
+        command = DetachHostedWait.new(coordinator: self, wait: wait, task: task, parent: parent, completion: completion)
+        accepted = @agent.__execution_environment.registry.post(command, completion: completion)
+        raise Phronomy::RuntimeShutdownError, "EventLoop rejected hosted detach" unless accepted
+        completion
+      end
+
       # Called only from an Agent FSMSession external-operation dispatch state on
       # EventLoop. Each method captures one operation-specific immutable snapshot
       # and sends only that snapshot to OffloadPool.
@@ -248,6 +290,8 @@ module Phronomy
           apply_provider_dispatch_preparation_on_event_loop(command)
         when ToolDispatchPreparationReady
           apply_tool_dispatch_preparation_on_event_loop(command)
+        when DetachHostedWait
+          detach_hosted_wait(command, environment)
         when ResumeCommand
           begin_resume_on_event_loop(command)
         when ResumeCommitReady
@@ -265,6 +309,47 @@ module Phronomy
 
       private
 
+      # Called on EventLoop after the host has read the committed wait outside it.
+      def detach_hosted_wait(command, environment)
+        wait = command.wait
+        registry = environment.registry
+        state = registry.agent_execution_state(wait.execution_id)
+        binding = @suspended_cancellation
+        task = command.task || binding&.fetch(2)
+        parent = command.parent
+        if task.is_a?(ApprovalOperation) && (!command.task.equal?(task) || !task.parent_wait&.current?)
+          raise Phronomy::AgentBusyError, "This handle does not own the resumed child wait"
+        end
+        if parent && registry.agent_execution_admitted?(parent.agent_id)
+          raise Phronomy::AgentBusyError, "Hosted parent has another local execution"
+        end
+        unless state && state.agent.equal?(@agent) && state.execution.status == :suspended &&
+            state.execution.execution_revision == wait.execution_revision && state.fsm_session_id.nil? &&
+            state.execution.approval_request&.fetch("id", nil) == wait.approval_request_id &&
+            binding && task.is_a?(OperationResult) && binding[1].equal?(state.invocation) && binding[2].equal?(task) &&
+            !state.invocation.config[:cancellation_token]&.cancelled? && registry.agent_execution_quiescent?(wait.execution_id)
+          raise Phronomy::AgentBusyError, "Hosted operation no longer owns this approval wait"
+        end
+        registry.mark_agent_execution_admission(@agent.agent_id, execution_id: wait.execution_id,
+          state: :suspended, expected_state: :suspended)
+        task.reserve_approval_detach!(command, parent: parent)
+        begin
+          # release_agent_execution validates all remaining physical work before mutation.
+          registry.release_agent_execution(wait.execution_id)
+        rescue
+          environment.ownership.finish_unload(@agent, command, success: false, parent: parent)
+          raise
+        end
+        clear_suspended_cancellation
+        registry.release_agent_execution_admission(@agent.agent_id, execution_id: wait.execution_id)
+        waiters = registry.take_agent_completion_waiters(wait.execution_id, fallback: task)
+        environment.ownership.finish_unload(@agent, command, success: true, parent: parent)
+        waiters.each { |waiter| @agent.send(:_complete_result_task, waiter, wait) }
+        command.completion.complete(wait)
+      rescue => error
+        command.completion.fail(error)
+      end
+
       # ----------------------------------------------------------------------
       # Initial preparation
       # ----------------------------------------------------------------------
@@ -296,6 +381,7 @@ module Phronomy
         # must abort instead of deleting the Agent underneath this start.
         @agent.send(:__assert_live_agent!)
 
+        @recovered_coordination_wait = nil
         operation = capture_initial_preparation(request, root)
         task = environment.submit(on_full: :raise) do
           @initial_preparation.prepare(operation)
@@ -901,6 +987,12 @@ module Phronomy
           return
         end
 
+        if request.result_task.is_a?(ApprovalOperation) && (parent_wait = request.result_task.parent_wait)
+          unless parent_wait.current? && !@suspended_cancellation
+            return fail_task(request.result_task, Phronomy::AgentBusyError.new("Hosted decision requires a restored child wait"))
+          end
+        end
+
         approval = state.execution.approval_request || {}
         current_request_id = approval["id"] || approval[:id]
         unless current_request_id.to_s == request.approval_request_id
@@ -1088,6 +1180,7 @@ module Phronomy
         environment = @agent.__execution_environment
         registry = environment.registry
         state = recovered_execution_state!(command)
+        @recovered_coordination_wait = nil
         validate_recovered_continuation!(state.execution, command.continuation)
         invocation = command.invocation
         unless invocation && invocation.agent.equal?(@agent) &&
@@ -1495,6 +1588,11 @@ module Phronomy
         delivery = ready.delivery
         outcome = ready.outcome
         release_terminal_ownership(environment, operation.execution_id, state)
+        if delivery.result_task.is_a?(OperationResult)
+          delivery.result_task.coordination_wait_execution_id = operation.execution_id
+        elsif delivery.result_task.is_a?(FrameworkRecoveryTask)
+          @recovered_coordination_wait = RecoveredCoordinationWait.new(self, operation.execution_id, outcome.execution.execution_revision)
+        end
         environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| fail_task(task, outcome.error) }
       end
 

data/lib/phronomy/agent/journal/journal_projection.rb

@@ -37,7 +37,12 @@ module Phronomy
       # clear_transcript! does not remove Knowledge, while knowledge_cleared and
       # context_reset invalidate earlier Knowledge records by Journal position.
       def context_records
-        (transcript_records + active_knowledge_records)
+        rejected_batches = rejected_tool_batches
+        messages = transcript_records.reject do |record|
+          %i[assistant_message tool_message].include?(record.kind) &&
+            record.llm_call_id && rejected_batches[record.execution_id] == record.llm_call_id
+        end
+        (messages + active_knowledge_records)
           .sort_by { |record| [record.sequence || 0, record.record_id] }
           .freeze
       end
@@ -52,6 +57,24 @@ module Phronomy
 
       private
 
+      # Rejection ends the execution at its final provider Tool batch. That
+      # exchange has no complete set of Tool replies to send to a provider.
+      # Identify it from existing journal facts, including pre-upgrade histories.
+      def rejected_tool_batches
+        rejected = {}
+        batches = {}
+        records.reverse_each do |record|
+          if record.kind == :execution_rejected
+            rejected[record.execution_id] = true
+          elsif record.kind == :assistant_message && rejected.delete(record.execution_id)
+            if Array(record.metadata["tool_call_ids"]).any? && record.llm_call_id
+              batches[record.execution_id] = record.llm_call_id
+            end
+          end
+        end
+        batches
+      end
+
       def active_knowledge_records
         reset_sequence = records.filter_map do |record|
           record.sequence if KNOWLEDGE_RESET_KINDS.include?(record.kind)

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

@@ -0,0 +1,67 @@
+# 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
+        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
+        completion = owner.coordinator.request_hosted_detach(wait,
+          task: (child && !@resumed_from) ? nil : @task, parent: child ? @agent : nil)
+        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/agent/tool_execution/tool_approval_request.rb

@@ -101,12 +101,13 @@ module Phronomy
       end
 
       def self.build_item(invocation)
+        display = invocation.approval_display
         Item.new(
           tool_invocation_id: invocation.id,
           tool_call_id: invocation.tool_call_id,
           tool_name: invocation.tool_name,
-          arguments: invocation.display_arguments,
-          facts: invocation.display_facts,
+          arguments: display.fetch(:arguments),
+          facts: display.fetch(:facts),
           reason: invocation.authorization_reason,
           origin: invocation.origin,
           metadata: invocation.metadata

data/lib/phronomy/agent/tool_execution/tool_invocation.rb

@@ -333,14 +333,21 @@ module Phronomy
         @tool&.respond_to?(:parameters_schema) ? @tool.parameters_schema : {}
       end
 
-      def display_arguments
-        redact_for_display(@arguments || @raw_arguments)
-      end
+      # The approval Item snapshots these fields at its own construction boundary.
+      # @api private
+      def approval_display
+        return {arguments: {}.freeze, facts: {}.freeze}.freeze unless @tool&.respond_to?(:approval_display)
 
-      def display_facts
-        redact_value(@facts, sensitive_argument_values)
+        display = @tool.approval_display(arguments: @arguments || @raw_arguments, facts: @facts)
+        unless Hash === display && Hash === display.fetch(:arguments, nil) && Hash === display.fetch(:facts, nil)
+          raise Phronomy::ConfigurationError, "Tool approval_display must return :arguments and :facts Hashes"
+        end
+        display
       end
 
+      def display_arguments = immutable_copy(approval_display.fetch(:arguments))
+      def display_facts = immutable_copy(approval_display.fetch(:facts))
+
       private
 
       def restore_saved_state!(status, result)
@@ -544,37 +551,6 @@ module Phronomy
       def immutable_copy(value)
         Phronomy::Values::Immutable.copy(value)
       end
-
-      def redact_for_display(value)
-        if @tool&.respond_to?(:redacted_args, true)
-          immutable_copy(@tool.send(:redacted_args, value || {}))
-        else
-          immutable_copy(value || {})
-        end
-      end
-
-      def sensitive_argument_values
-        return [] unless @tool&.class&.respond_to?(:redact_params)
-        normalized = (@arguments || @raw_arguments || {}).transform_keys(&:to_sym)
-        @tool.class.redact_params.filter_map { |name| normalized[name] }
-      end
-
-      def redact_value(value, sensitive_values)
-        return "[REDACTED]" if sensitive_values.any? { |sensitive| sensitive == value }
-
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[key] = redact_value(item, sensitive_values)
-          end.freeze
-        when Array
-          value.map { |item| redact_value(item, sensitive_values) }.freeze
-        when String
-          "[REDACTED]"
-        else
-          value
-        end
-      end
     end
   end
 end

data/lib/phronomy/context/context_policy.rb

@@ -11,6 +11,16 @@ module Phronomy
 
       protected
 
+      # Uses the same canonical representation and estimator as generated Policy
+      # items. Estimates are planning values, not a model tokenizer guarantee.
+      # @param content [Object] text or JSON-serializable content
+      # @return [Integer] estimated token count
+      # @api public
+      def estimate_tokens(content)
+        bytes = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
+        Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+      end
+
       def instruction_item(
         content:,
         role: :system,
@@ -113,8 +123,7 @@ module Phronomy
       end
 
       def estimate_content(content)
-        bytes = content.is_a?(String) ? content : Phronomy::CanonicalJSON.dump(content)
-        Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
+        estimate_tokens(content)
       end
     end
   end