phronomy 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7eb1f72acaa35f02d5f848dac344ea971e6ef190544d2b200fe367409e48e92
-  data.tar.gz: 26b2de048b30845bdbf973a5e26a6d5fa4b734295d31b81cec2530e9dd896dc8
+  metadata.gz: 8eeef6dddca310da11fcdcaf7ffc2490191151cfa070384be8d04f84366efb08
+  data.tar.gz: 2b43c66ff8c5484360b2a953bcdd4aa754ef99c3b7bc944285993d866ee34007
 SHA512:
-  metadata.gz: eaf92481864d37b545ccf7507541fbd64777eb6ff6369e2f8a674f31341bc2ec439883dfa2964d410c1becc2adc92c2794c9a7a2e6a7a2e5050a78e2ae4fa181
-  data.tar.gz: 6ca6f91cc3bf270a2694cb5a8a194cc1f4fe8270440ada751a4082f0ae27489c0798743a351d8850e1fbf4e81eb0aac207bee563995e8aa821d2008b2b6916e2
+  metadata.gz: 9ebee2313bc7d60b27c6e42e0909fbb1102cca3c220f25575d1c755b18f3d1c00b7ea0dfec36646155a7aff325ba47c99af202c9b7fbf226d45c4fbb07b8bff9
+  data.tar.gz: 3b089fdc8447a0a56c66d10d64c809eb26ddc31be6800a55c095409e87e649047afbc42fa1872eab8fd68b7939bd6845edc194b5ec4ab03beca602408f320596

data/CHANGELOG.md

@@ -12,6 +12,70 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-11-03
+
+### Added
+
+- Add `Agent#start_hosted`, `Agent::HostedInvocation` and immutable
+  `Agent::ApprovalWait` for safely detaching an exclusively owned standalone Agent
+  at its first committed Tool approval wait. A new incarnation can use the
+  existing `load` and `approve` operations to continue the same execution.
+- Add `Agent::Store#standalone_approval_wait` to query the committed approval fact without
+  transferring a live worker claim. Delivery deduplication, exclusive claims and
+  verified worker termination remain application responsibilities. Standalone
+  detachment does not transfer parent Workflows or shared children; supported
+  direct-child handoff and saved Workflow events are separate APIs below.
+
+- Add `Workflow#send_saved_event` to restore a declared wait by Workflow instance
+  ID and expected revision before applying an event. The host can reject a
+  delayed delivery even when the same Workflow later returns to an identical wait.
+- Allow an Orchestrator's hosted handle to detach its local parent and direct
+  child together at a saved child Tool approval. The host supplies the child's
+  execution and approval request IDs and retains the parent's execution ID for
+  resumption on another worker. Both workers can remain alive.
+- Add `MultiAgent::Orchestrator#approve_hosted_child` to answer a restored
+  direct child's approval with a hosted handle. If the same execution asks for
+  another approval, the worker can release the pair at the new wait. A third
+  worker can restore that wait without replaying the earlier Tool call.
+- Add `MultiAgent::Orchestrator#unload_with_completed_child!` for a worker
+  that has finished a direct child dispatch. It can release the local owners
+  while keeping the conversation, execution results and native slot history.
+
+### Fixed
+
+- Bind native subagent dispatch context to each prepared Tool instance so that
+  cached Tool methods do not keep completed Orchestrators alive after unload
+  (Issue #440). Saved SQLite execution and conversation history is preserved.
+- Keep distinct native Tool call/result pairs when a provider reuses its call ID
+  in later responses on the same Agent. A subsequent request can use the saved
+  conversation without executing either Tool again to rebuild context.
+- Restore mutable Workflow context fields from durable checkpoints when
+  delivering a saved event or starting another invocation of the same instance.
+  Actions can update nested strings, arrays and hashes without changing the
+  original checkpoint.
+- Continue using an Agent after a human rejects a Tool call. Model input for the
+  next turn omits the rejected, incomplete Tool exchange. The original journal
+  and public conversation history remain available for inspection.
+
+### Compatibility and verification
+
+- Worker APIs require 0.32.0 or later; applications using `start_hosted` cannot
+  run against 0.31.0. The existing [0.31 storage and Agent Tool migration
+  requirements](docs/migrations/0.31.md) still apply. This release does not add a
+  persistence mapping migration or change those stored execution formats.
+- Native handoff and completed-owner release cover one direct child in an
+  isolated dispatch batch. Delivery deduplication, exclusive claims, ACKs and
+  verified worker termination belong to the application. General graph transfer,
+  multi-host fencing, supervisor restart and recovery of unknown external Tool
+  effects are not established by these examples.
+- Worker acceptance uses fixed HTTP responses, actual Ruby processes and SQLite,
+  including Ubuntu 24.04 and 26.04. It does not establish live-model acceptance.
+- LM Studio/gpt-oss PEG parsing remains a known unresolved limitation. The latest
+  pre-release standard verifier reported 101 passed, 2 failed and 0 skipped;
+  Examples 01 and 22 received provider PEG errors, also reproduced before Worker
+  support. Known-error identification and bounded retry do not fix the provider's
+  root cause. These two failures are tracked separately from Worker acceptance.
+
 ## [0.31.0] - 2026-10-25
 
 ### Added

data/README.md

@@ -37,7 +37,8 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
-The following table describes the application APIs available in v0.31.0.
+The following table describes the application APIs available in v0.32.0.
+Worker hosting and completed parent/child release require v0.32.0 or later.
 Review the [0.31 migration notes](docs/migrations/0.31.md) before upgrading
 persistent applications or custom Agent Tool subclasses.
 
@@ -48,7 +49,12 @@ persistent applications or custom Agent Tool subclasses.
 | Agent `transcript_messages` / `transcript_messages_async` | Beta | Read immutable conversation Message values with the same restoration rules as execution results; [reading conversation state](docs/getting-started.md) |
 | `Phronomy::GeneratorVerifier`, its approval/lifetime operations and immutable `Result` with output-failure diagnostics | Beta | [Generation and structured-output contract](docs/architecture/structured-output-and-scope.md) |
 | `Agent.open_scope`, `Agent::Scope`, `Agent::Base#unload_async / #unload!`, `AgentUnloadedError` and `Agent::ScopeCleanupError` | Beta | Runtime-bound ownership and safe release of idle Agent incarnations without changing saved history or closing the Store; [contract](docs/architecture/dx05-agent-scope.md) |
+| `Agent::Base#start_hosted`, `Agent::HostedInvocation`, `Agent::ApprovalWait` and `Agent::Store#standalone_approval_wait` | Beta | Added in v0.32.0. Detach an exclusively owned standalone Agent at its first committed approval wait, then restore the same execution in another process; delivery claims and worker fencing remain application responsibilities; [contract](docs/runtime-and-concurrency.md#hosting-a-standalone-agent-through-approval) |
+| `Agent::HostedInvocation#detach!(execution_id:, approval_request_id:)` | Beta | Added in v0.32.0. Release an exclusively owned Orchestrator and its single direct subagent at the child's approval wait. A second worker can resume both saved executions while the first worker handles other requests. [Contract](docs/runtime-and-concurrency.md#hosting-an-orchestrator-through-a-child-approval) |
+| `MultiAgent::Orchestrator#approve_hosted_child` | Beta | Added in v0.32.0. Answer the current approval on a restored direct child. The returned handle can release the pair again if that child requests another approval during the same execution. [Contract](docs/runtime-and-concurrency.md#hosting-an-orchestrator-through-a-child-approval) |
+| `MultiAgent::Orchestrator#unload_with_completed_child!` | Beta | Added in v0.32.0. Release local owners after a direct child result has been imported and the parent has finished. The saved executions, transcripts and coordination history remain available. [Contract](docs/runtime-and-concurrency.md#releasing-a-completed-orchestrator-and-child) |
 | `Tools::Agent::CleanupError` | Beta | Added in v0.31.0. Preserves the child, result and failure causes when safe release fails; retry `child_agent.unload_async` for release only; [contract](docs/architecture/agent-tool-child-lifetime.md) |
+| `Workflow#send_saved_event` | Beta | Added in v0.32.0. Deliver an event to a specific revision of a persisted Workflow wait; [contract](docs/runtime-and-concurrency.md#delivering-an-event-to-a-saved-workflow-wait) |
 | `Workflow::Builder#task_state` and `WorkflowTaskResumeError` | Beta | State-entry-scoped Task completion, live cancellation and explicit restart rejection; [contract](docs/architecture/dx05-workflow-task-state.md) |
 | `Phronomy::Integrations::OrderedEventDelivery` | Beta | Optional ordered delivery with bounded admission and explicit drain lifetime; [usage](docs/ordered-event-delivery.md) |
 | `Phronomy::Error#code` and error constructor `code:` | Beta | Optional reason codes and bounded causes retained in saved failure diagnostics; [meaning and compatibility](docs/architecture/error-api-review.md) |

data/docs/features.md

@@ -106,6 +106,8 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 | **Durable Handoff** — `MultiAgent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with application prompts, Agent-validated output schemas and explicit output failures | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
+| **Hosted child approvals** — An Orchestrator can release a single direct child and its parent at successive Tool approvals within the same child execution. The host transfers exclusive ownership between workers. [Contract](runtime-and-concurrency.md#hosting-an-orchestrator-through-a-child-approval) | Beta |
+| **Completed native child release** — A host can unload the local Orchestrator and its finished direct child while preserving their saved results, conversation and coordination history. [Contract](runtime-and-concurrency.md#releasing-a-completed-orchestrator-and-child) | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
 | **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
 | **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |

data/docs/runtime-and-concurrency.md

@@ -668,6 +668,165 @@ imply durable Agent continuation reconstruction.
 `Phronomy.reset_runtime!` exists primarily for test isolation and performs a real
 Runtime shutdown before resetting configuration.
 
+## Hosting a standalone Agent through approval
+
+A host can release one suspended Agent and continue using its Ruby process for other Agents. Hold one external claim per mutable Agent while loading, executing, detaching and recording delivery. Persist a new request's reserved execution ID before dispatch. A host uses the existing incarnation-level listener to receive the approval request.
+
+For example, worker A starts a fresh reservation with `agent.start_hosted(reservation:, input:)`. If the run finishes directly, `handle.wait_result` returns the ordinary execution result. On an approval notification, call `handle.detach!(approval_request_id: request.id)` outside EventLoop. Success returns an immutable `ApprovalWait` with the execution ID, approval request ID and committed revision. The same handle then returns that wait. The released Agent object cannot be reused. Existing `invoke_async` handles keep their terminal-result contract.
+
+An incorrect or stale approval, outstanding physical work, concurrent operation, live scope or durable retention prevents transfer. A busy response leaves the host responsible for the claim. A spent reservation is rejected. After a verified worker exit, a host can query `store.standalone_approval_wait(agent_id:, execution_id:)` without loading the Agent. A missing or ineligible wait returns nil. Store errors and owner mismatches propagate. Only reclaim a delivery if the original worker is known to have stopped and its claim still matches.
+
+Worker B loads the Agent with an `on_event:` listener, checks the restored request against the accepted answer and calls `approve` with the execution and approval request IDs. The host owns input deduplication and result acknowledgement. For a direct subagent, use the parent's hosted handle as described below.
+
+## Hosting an Orchestrator through a child approval
+
+A hosted Orchestrator can release its local Agent and one direct subagent when
+the subagent is waiting for Tool approval. The parent execution has one reserved
+child slot and its current Tool batch contains only the dispatch for that slot.
+The host holds exclusive access to both Agents throughout the handoff. It
+delivers work to the next worker only after release succeeds.
+
+For example, worker A starts a parent with `start_hosted`. Its listener receives
+the child's approval request. A host thread outside EventLoop passes the IDs
+from that request to the parent handle.
+
+```ruby
+wait = handle.detach!(execution_id: request.execution_id, approval_request_id: request.id)
+```
+
+The returned `Agent::ApprovalWait` identifies the child execution, its approval
+request and its saved revision. Keep the parent Agent and execution IDs with the
+accepted request. Both old Agent objects reject later execution operations.
+Worker A can keep unrelated Agent instances and process another request.
+The parent's original result handle retains its
+`ExecutionRehydrationRequiredError` outcome at this boundary.
+
+Worker B loads the same parent class with its Agent Store, coordination Store
+and listener. `parent.resume_async(parent_execution_id)` restores the pending
+child and emits the same approval request. Compare its execution and request
+IDs with the accepted request. The parent attempt reports
+`ExecutionRehydrationRequiredError` while the child is waiting. Obtain the
+restored child from its registered class by child Agent ID, call
+`child.approve(child_execution_id, approval_request_id:, approved:)`, then
+`parent.resume(parent_execution_id)` to import the result. A rejection is a
+child outcome. The parent continues according to its own dispatch and Agent
+logic.
+
+If the child may need another handoff, the host answers the current approval
+through the restored parent on a host thread outside EventLoop. This returns a
+hosted handle for the child's operation. If the child finishes, the handle
+yields the child result and the parent can import it. If the child requests
+another approval, the host can use the handle to release the same pair.
+
+For example, B approves the child's `apply_request` and the same child execution
+then asks to call `publish_request`. B uses the first approval's ID to answer and
+the second approval's ID to detach. The queue below receives the child approval
+events from the listener installed when B loaded the parent. This fixture
+requests a second approval within its test timeout.
+
+```ruby
+require "timeout"
+
+answer = parent.approve_hosted_child(parent_execution_id,
+  execution_id: first.execution_id, approval_request_id: first.id, approved: true)
+second = Timeout.timeout(12) { approval_events.pop }
+wait = answer.detach!(execution_id: second.execution_id, approval_request_id: second.id)
+```
+
+After release, `answer.wait_result` returns the same child `ApprovalWait`.
+B sends the existing parent and child execution IDs and the **new** approval
+request ID to C. C restores the pair as B did and answers the new request.
+The completed first Tool stays recorded in the child execution. While the hosted
+answer is pending, read the saved execution to report progress. Calling
+`parent.resume` again can advance the parent revision and invalidate the
+handoff. Resume the parent after the child finishes. A host handling
+arbitrary conversations must observe both approval events and handle completion
+(`on_complete`), since the child can finish without requesting another Tool.
+
+A later user request can also start a new hosted execution on the same parent
+Agent. Its own child wait can be detached while the earlier terminal
+execution's native slot history is still retained.
+
+A wrong approval, another reserved child, overlapping local work, or a pending
+cancellation prevents transfer. On `AgentBusyError` the host keeps ownership.
+The child remains a coordinated execution in storage, including its original
+slot and retention. Once both executions complete in B, these retentions
+continue to guard ordinary `unload!`. This handoff preserves slot history.
+An application that has finished using that history can separately call
+`stores.multi_agent.forget_subagents(agent_id:, execution_id:)` to remove
+that execution's subagent extension and release its holds.
+The host serializes workers and owns request deduplication, claims, crash
+recovery and acknowledgement.
+
+## Releasing a completed Orchestrator and child
+
+A host can release the local owners once the parent has imported its direct
+child's outcome and both executions have finished. Phronomy keeps the durable
+reservation, execution results and both Agents' transcripts. A later worker
+can load the parent by its Agent ID and use that conversation for another turn.
+
+For example, after answering the last approval, the worker first lets the
+parent import the child's result. It then passes both execution IDs to the
+Orchestrator, on a host thread holding exclusive delivery for the pair. Call
+this outside an application persistence transaction so the ownership decision
+uses committed records.
+
+```ruby
+result = parent.resume(parent_execution_id)
+parent.unload_with_completed_child!(parent_execution_id,
+  execution_id: child_execution_id)
+```
+
+The method returns true on release. The parent and any matching resident child
+leave the local runtime registry together. Retrying on the released parent
+object returns false. A parent reloaded on its own can use the saved pair's IDs
+to unload without materializing the child. To display saved results without
+loading either Agent, use the Agent Store.
+
+A child may be complete while the parent is still waiting to import its result.
+In that case release is premature. Keep the host claim, finish the parent and
+then release. Active operations, a scoped owner or a conflicting retention can
+also prevent release. The method covers one imported, directly registered child
+of the specified execution. It does not sweep other child instances that the
+application previously left resident.
+
+Generic `unload!` and durable deletion continue to honor retention. Use
+`forget_subagents` only when the application intends to remove the stored
+coordination history. Once a host no longer needs an unloaded Agent, it can
+drop its own references to that instance and its operation handles.
+
+## Delivering an event to a saved Workflow wait
+
+A worker can restore a particular visit to a declared Workflow wait. The host holds
+one claim for the Workflow instance, selects the matching Workflow definition,
+and identifies the saved revision that should receive the event.
+
+For example, a parent waiting for a review stores the child's Agent and execution
+IDs in its context. A worker verifies the completed child result against those IDs.
+While it owns the parent claim, it calls the following method with the revision
+recorded for that wait:
+
+```ruby
+workflow.send_saved_event(workflow_instance_id: parent_id,
+  expected_revision: wait_revision, event: :review_ready, input: {answer: answer})
+```
+
+A later visit can have the same phase and fields but a different revision. The
+earlier delivery raises `Persistence::StateConflictError` before its transition
+executes. A transition whose guard rejects the input raises `ArgumentError` and
+leaves the checkpoint available for a corrected event. After an
+acknowledgement is lost, the host checks the durable parent state for evidence
+of this child's result before acknowledging or retrying the message. It must
+retain the original wait revision throughout retries.
+
+The host keeps its claim from reading the parent through committing the transition.
+Two workers could otherwise both run application actions before storage detects a
+conflict. The application must also restore the same Workflow definition and
+configuration. A revision identifies a stored state for one durable instance;
+do not delete and reuse its ID while old deliveries might still arrive. The
+revision does not identify deployed code or make an external Tool effect repeatable.
+A pending in-process `task_state` cannot be restored with this operation.
+
 ## Further design records
 
 The `docs/decisions/` directory contains the historical and current Architecture

data/lib/phronomy/agent/approval_wait.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Immutable reference to one committed standalone approval boundary.
+    ApprovalWait = Data.define(:execution_id, :approval_request_id, :execution_revision)
+  end
+end

data/lib/phronomy/agent/async_event_api.rb

@@ -12,6 +12,27 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
+      # Starts a fresh, standalone execution. Only this handle can detach its wait.
+      # The caller holds the external exclusive claim for this Agent.
+      def start_hosted(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
+        __with_operation do
+          if Phronomy::WaitPolicy.blocking_forbidden?
+            raise Phronomy::EventLoopReentrancyError, "start_hosted requires a host thread"
+          end
+          unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id && reservation.correlation.nil?
+            raise ArgumentError, "expected a standalone reservation for this Agent"
+          end
+          id = reservation.execution_id
+          unless persistence.observe_execution(agent_id: agent_id, execution_id: id).absent?
+            raise Phronomy::Persistence::StateConflictError, "Hosted execution #{id} already exists"
+          end
+          config = _prepare_output_config(config, nil, output_schema, schema_delivery)
+          task = _start_agent_operation(input, config: config.merge(phronomy_reserved_execution_id: id),
+            mode: :invoke, listener: _phronomy_event_listener)
+          build_hosted_invocation(id, task)
+        end
+      end
+
       def start_reserved_async(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
         __with_operation(async: true) do
           unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
@@ -210,6 +231,45 @@ module Phronomy
 
       private
 
+      # An optional composition hook validates the durable parent/child relation.
+      def hosted_child_approval_reader = nil
+
+      def build_hosted_invocation(id, task)
+        reader = hosted_child_approval_reader
+        return HostedInvocation.new(self, id, task) unless reader
+
+        HostedInvocation.new(self, id, task) do |execution_id, approval_id|
+          owner = __execution_environment.registry.agent_execution_owner(execution_id)
+          reader.call(agent_id, id, execution_id, approval_id, live_child: owner.agent) if owner
+        end
+      end
+
+      def resume_hosted_child_approval(parent_execution_id, execution_id:, approval_request_id:, approved:, config:)
+        __with_operation do
+          if Phronomy::WaitPolicy.blocking_forbidden?
+            raise Phronomy::EventLoopReentrancyError, "approve_hosted_child requires a host thread"
+          end
+          reader = hosted_child_approval_reader
+          parent_wait = execution_coordinator.recovered_coordination_wait
+          unless reader && parent_wait && parent_wait.execution_id == parent_execution_id && parent_wait.current?
+            raise Phronomy::AgentBusyError, "Parent has no matching recovered coordination wait"
+          end
+          owner = __execution_environment.registry.agent_execution_owner(execution_id)
+          unless owner&.status == :suspended
+            raise Phronomy::AgentBusyError, "No matching local child approval wait"
+          end
+          lookup = lambda do |child_execution_id, approval_id|
+            reader.call(agent_id, parent_execution_id, child_execution_id, approval_id,
+              parent_revision: parent_wait.revision, live_child: owner.agent)
+          end
+          wait = lookup.call(execution_id, approval_request_id)
+          raise Phronomy::AgentBusyError, "No matching hosted child approval wait" unless wait
+          task = owner.coordinator.resume(wait.execution_id, approval_request_id: wait.approval_request_id, approved: approved,
+            config: owner.agent._prepare_invocation_config(config, nil), parent_wait: parent_wait)
+          HostedInvocation.new(self, parent_execution_id, task, resumed_from: wait, &lookup)
+        end
+      end
+
       def _prepare_output_config(config, invocation_context, schema, schema_delivery)
         config = _prepare_invocation_config(config, invocation_context)
         if schema.nil?

data/lib/phronomy/agent/base.rb

@@ -752,7 +752,7 @@ module Phronomy
         true
       end
 
-      def _prepare_invocation_config(config, invocation_context)
+      protected def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
         if config.keys.any? { |key| %w[output_schema schema_delivery response_schema phronomy_output_contract].include?(key.to_s) }

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

@@ -156,6 +156,10 @@ module Phronomy
       end
 
       def reconcile(failure)
+        # A suspended exact observer may already have released its operation.
+        # A logically cancelled observer still needs physical acknowledgement.
+        return if @completion.physical_complete?
+
         task = @environment.submit(on_full: :raise) do
           execution = read_execution
           if execution&.terminal?

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,7 @@ module Phronomy
       TerminalCommitReady = Data.define(
         :coordinator, :operation, :delivery, :outcome, :error
       )
+      DetachHostedWait = Data.define(:coordinator, :wait, :task, :parent, :completion)
       SuspensionCancelledCommand = Data.define(:coordinator, :execution_id)
 
       DeferredTerminalCommand = Data.define(
@@ -125,11 +156,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,
@@ -248,6 +279,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 +298,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 +370,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 +976,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 +1169,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 +1577,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)