phronomy 0.31.0 → 0.33.0

data/docs/runtime-and-concurrency.md

@@ -211,6 +211,37 @@ Worker authorization/execution outcomes return as values carrying
 `tool_invocation_id`; the Tool FSMSession consumes a mismatched semantic result
 without advancing its current state.
 
+## Tool approval display
+
+A Tool chooses which arguments and derived facts a person may see. Agent asks
+the Tool for both when it builds a new `ToolApprovalRequest` item and takes a
+snapshot of the result. Approval policy and Tool execution use their own inputs.
+
+For example, a Tool can declare `redact_params :token`. The default
+`Tool::Base#approval_display(arguments:, facts:)` masks `token` in the
+argument display and masks string values in facts. A numeric fact such as
+`recipient_count: 3` can still be shown. Use fixed fact names and choose
+aggregates that are appropriate to disclose.
+
+If `redact_params :auth` covers `auth: {pin: 627018}`, the default also
+masks a fact such as `echo: 627018`. It checks JSON values copied from inside
+sensitive hashes and arrays. A matching fact key causes that entry to be
+omitted. The declared
+argument's own hash keys are treated as field names. If those names are
+themselves confidential, keep them out of fact keys. Equality also masks
+unrelated facts with the same value. The Tool author chooses which computed
+values may be shown. For example, an arithmetic transformation of a PIN can
+still disclose it even if the result differs from the original. Override
+`approval_display` to explicitly select safe fields when publishing such facts.
+
+To customize both fields, return a Hash with the symbol keys `:arguments` and
+`:facts`, each holding a displayable Hash. The hook runs on EventLoop while
+Agent prepares the approval. Build the result from the supplied values without
+blocking or performing I/O. A wrapper can forward the operation to its
+underlying Tool. If a Tool omits the operation, the item contains an
+empty Hash for each field. Existing saved approval items retain the display
+data recorded when they were created.
+
 ## Approval suspension and live owner lookup
 
 Approval suspension retains the same process-local Agent and AgentInvocation but
@@ -668,6 +699,170 @@ 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.
+
+The hosted handle matches the requested approval to its saved wait and local
+owner. That owner's execution coordinator submits the detach command to
+EventLoop, which rechecks ownership before releasing the Agent. The host waits
+for the result before handing the execution to another worker.
+
+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/docs/shared-state-sharing.md

@@ -0,0 +1,223 @@
+# Custom sharing in SharedState
+
+SharedState can coordinate member Agents while an application owns the shared
+data and the Tools that access it. The application provides one invocation-scoped
+binding; SharedState owns member order, cycles, stopping decisions and final
+aggregation. This Experimental extension is available since v0.33.0.
+
+For example, an issue-review team can share records with `category` and `status`
+fields. Its search Tool accepts those fields as separate arguments instead of
+forcing the application to encode every record and condition as finding text.
+
+## Application provider and binding
+
+A provider scopes shared resources around one synchronous team invocation. Its
+binding contains an opaque store and a Tool-definition builder. SharedState
+passes the store to application callbacks and does not require store methods or
+a particular record schema.
+
+For example, an application provider can open an issue board, yield its binding,
+and close the board in `ensure`:
+
+```ruby
+class IssueSharing
+  def open(input:, config:)
+    board = IssueBoard.new
+    yield Phronomy::MultiAgent::SharedState::Binding.new(
+      store: board,
+      tools: ->(member:, cycle:) { build_issue_tools(board, member, cycle) }
+    )
+  ensure
+    board&.close
+  end
+end
+```
+
+This excerpt shows the provider boundary. The
+[complete executable application example](examples/shared_state_custom_sharing.rb)
+defines its store, Tool builder, member Agent, team and offline check.
+
+The provider must respond to `open(input:, config:)` and yield exactly one
+`Phronomy::MultiAgent::SharedState::Binding` synchronously during that call.
+Zero yields, multiple yields or an invalid binding violate the protocol and
+raise `ArgumentError`. Do not retain the block for deferred execution. The
+provider owns cleanup, including failures raised by member execution or
+aggregation; SharedState does not call `close` on the opaque store.
+
+`Binding.new(store:, tools:)` accepts a callable Tool builder. The public
+`binding.store` returns the opaque store, and
+`binding.tool_definitions(member:, cycle:)` calls the builder. `member` is the
+registered Agent class; `cycle` is the current positive cycle number. The builder
+must return a Hash whose keys are Tool classes and whose values are aliases or
+`nil`, using the same Tool-definition shape as the existing Agent Tool API.
+Arrays are not accepted. Invalid configuration or protocol values raise
+`ArgumentError`.
+
+## Team composition and definition identity
+
+A team selects its provider and supplies the application operations that consume
+the shared store. The provider's stable ID and version identify the meaning of
+its injected Tools independently from an individual member's definition.
+
+For example, the complete issue-review example declares:
+
+```ruby
+class ReviewTeam < Phronomy::MultiAgent::SharedState
+  sharing IssueSharing.new, id: "shared-issues", version: 1
+  member Researcher
+  max_cycles 2
+  coordination "Use search_issues to inspect relevant issues. " \
+               "Use record_issue to record each new issue with its category and status."
+  aggregate { |board| board.snapshot }
+end
+```
+
+Custom sharing requires an explicit `aggregate` block because SharedState does
+not know how to read the application store. An optional `terminate_when` block
+also receives that same store. Existing cycle order, stopping rules and result
+shape remain in place. `config:` is provided to the sharing provider; this does
+not introduce forwarding of `config:` to member invocations.
+
+In custom mode, SharedState adds only the Tools returned by the application's
+builder. It does not add `read_store` or `write_finding`, and it does not append
+stored records to member prompts. The prompt consists of coordination text, the
+task input and any member instruction. The member's existing Tools and aliases
+remain available. Conflicting effective Tool names are rejected rather than
+silently replacing an existing Tool.
+
+Use a stable sharing ID and increment its version whenever the injected Tool
+schemas or behavior change. Custom generated Agent identity incorporates that
+ID/version alongside the member definition. A new store instance per invocation
+does not by itself require a new sharing ID. The application must not substitute
+different Tool semantics under an unchanged sharing revision.
+The ID must be a nonempty String and the version must be a positive Integer.
+
+The default mode remains available when `.sharing` is not configured. It retains
+the existing invocation-local KnowledgeStore, built-in Tools, full-store prompt
+behavior and instrumentation revision 1. This extension does not add a `query`
+argument to the default `read_store` Tool or a search method to that store.
+
+## Deriving an Agent with a complete Tool set
+
+The public `Agent::Base.with_tools(definitions, id:, version:)` factory creates
+an Agent subclass with a replacement Tool map and an explicit definition
+identity. Agent owns preservation of its authoring settings; SharedState uses
+this public operation after composing the member and application Tools. It does
+not need to read Agent private settings.
+
+For example, inside the complete example's module, a provider can supply the
+entire Tool map for a derived researcher class:
+
+```ruby
+IssueSharing.new.open(input: "Review authentication", config: {}) do |binding|
+  tool_map = binding.tool_definitions(member: Researcher, cycle: 1)
+  derived = Researcher.with_tools(
+    tool_map, id: "issue-researcher-with-board", version: 1
+  )
+  # `derived` is a class; no Agent instance or Runtime resource was created.
+end
+```
+
+`definitions` is the complete Hash of Tool classes to aliases or `nil`; this
+factory does not merge Tools or detect naming collisions. SharedState performs
+those operations before calling it. A missing parent Tool is removed, and a
+`nil` alias uses the Tool's own name even when the parent assigned an alias.
+The supplied ID and version identify the derived definition directly.
+
+The factory preserves Phronomy-authored model, provider, instructions,
+ContextPolicy, generation settings, LLM-input hook and filters. Filter lists
+are independent while configured filter and callback instances remain shared.
+The original class is unchanged. This explicit factory does not change general
+Agent subclass inheritance or define copying rules for application-specific
+class state.
+
+## Application search and LLM input
+
+Application Tools own record fields and search conditions. ContextPolicy and the
+existing input-validation path continue to own LLM-input selection and budget
+checks. A custom provider does not become another Context engine.
+
+For example, `search_issues(category: "security", status: "open")` in the complete
+example applies both field conditions and returns matching records as JSON. A
+search can leave three records in the store while returning only one match. Its
+Tool parameter types and enumerations use the existing Tool schema API.
+
+The example has no result-size cap. A broad query may still produce a large Tool
+result, and this extension does not make that result optional, rewrite recorded
+Tool output or bypass the final input-budget check. Applications that need
+paging, compaction or another acquisition policy must define that behavior
+explicitly through the existing appropriate contracts.
+
+SharedState continues to use the member's configured ContextPolicy. The binding
+does not automatically populate `before_llm_input` candidates, inspect Context
+internals or manage a provider message buffer. Example 22's adaptive reader is a
+separate application implementation; this extension alone does not migrate it
+or remove its existing private-API dependency.
+
+## Lifetime and verification
+
+The provider owns resources for one synchronous invocation. SharedState does not
+define a database schema, durable binding identity or process-transfer protocol
+for the application's store. A live binding does not become a persisted
+continuation. Custom sharing requires each member invocation to reach a terminal
+state before coordination proceeds.
+
+For example, the application file can check its store and Tools without calling
+an LLM:
+
+```sh
+bundle exec ruby docs/examples/shared_state_custom_sharing.rb --offline
+```
+
+The check opens the provider, records three issues through `Tool#call`, searches
+with both category and status, verifies one match and three retained records,
+and verifies provider cleanup. It uses the real Tool argument-validation path.
+It does not exercise the SharedState Agent loop or establish live-model,
+database or multi-process acceptance.
+
+In custom mode, SharedState releases terminal member instances through the
+Agent's public `unload!` operation. A normal Agent approval wait keeps the public
+`invoke` call pending. SharedState consequently stays inside the provider's
+`open` block and retains its resources; it does not return a suspended result or
+close the provider merely because an internal execution reaches an approval
+wait. The application remains responsible for answering or cancelling approvals.
+
+For example, when a member waits for approval of `record_issue`, the board stays
+open while that invocation waits. An approval allows the Tool and member to
+complete before aggregation and provider cleanup. A cancellation that ends the
+member invocation also allows cleanup to run. The in-memory example's `ensure`
+is scoped to the end of the invocation, not the start of an approval wait. This
+is a live wait in the current process, not a way to release a Worker and restore
+the board on another one.
+
+The [SharedState integration suite](../spec/integration/shared_state_spec.rb)
+separately exercises this approval lifecycle using a real Agent and fixed LLM
+responses. It checks that the provider stays open and aggregation has not run
+during the wait; after a public approval response, the Tool writes its record,
+aggregation runs, the provider closes and the member is released. Fixed
+responses verify the execution path, not a live model's Tool-selection behavior.
+
+The lifecycle guard also detects a custom `invoke` override that returns a Hash
+with a suspended status before reaching completion. That exceptional early
+return raises `SharedState::MemberLifecycleError` with `reason: :suspended` and
+stops coordination before later members or aggregation. It is not the behavior
+of normal Agent HITL. SharedState does not approve, deny, cancel or unload the
+pending execution on the application's behalf. Providers handling this case
+must decide whether to retain their resources; merely retaining a binding adds
+no SharedState resume operation.
+
+`MemberLifecycleError#reason` also reports `:release_failed`. The error exposes
+`agent`, the available `result`, `primary_error` and `release_error`. A failed
+release preserves the Agent reference and both failure details when invocation
+and release fail together, so the application can inspect the original failure
+and decide whether to retry release. The provider's `open` scope can rescue this
+error before its cleanup policy runs. Rescuing a coordination failure inside
+`open` does not turn the invocation into success: SharedState still reports the
+failure if the provider returns normally.
+
+To run the team from an application, configure Phronomy's LLM backend normally,
+set `PHRONOMY_EXAMPLE_MODEL` to that backend's model ID before requiring the file,
+then invoke `SharedStateCustomSharingExample::ReviewTeam.new.invoke(task)`.
+The example's fallback model name is a placeholder, not a remotely available
+model. A DB-backed provider may replace the example's in-memory board, but its
+transactions, isolation and recovery behavior remain application responsibilities.

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

@@ -77,6 +77,8 @@ module Phronomy
 
         def tool_aliases
           own = @tool_aliases || {}
+          return own if @tool_aliases_replace_inherited
+
           if superclass.respond_to?(:tool_aliases)
             superclass.tool_aliases.merge(own)
           else
@@ -84,6 +86,29 @@ module Phronomy
           end
         end
 
+        # Derive an Agent definition with a complete replacement Tool map.
+        # Phronomy authoring settings and filters are preserved; mutable filter
+        # lists are independent, while configured callable instances are shared.
+        # No Agent instance or Runtime resource is created by this factory.
+        # @param definitions [Hash<Class, String, nil>] Tool classes and aliases
+        # @param id [String] identity for the derived Agent definition
+        # @param version [Integer] revision for the derived Agent definition
+        # @return [Class<Phronomy::Agent::Base>]
+        # @api public
+        def with_tools(definitions, id:, version:)
+          unless definitions.is_a?(Hash)
+            raise ArgumentError, "with_tools expects a Hash of ToolClass => alias_or_nil"
+          end
+
+          derived = Class.new(self)
+          derived.agent_definition(id: id, version: version)
+          copy_authoring_settings_to(derived)
+          copy_authoring_filters_to(derived)
+          derived.tools(definitions)
+          derived.instance_variable_set(:@tool_aliases_replace_inherited, true)
+          derived
+        end
+
         def provider(name = nil)
           if name
             @provider = name
@@ -263,6 +288,34 @@ module Phronomy
 
         private
 
+        def copy_authoring_settings_to(derived)
+          settings = {
+            model: model,
+            provider: provider,
+            instructions: instructions,
+            context_policy: context_policy,
+            temperature: temperature,
+            max_iterations: max_iterations,
+            cache_instructions: cache_instructions,
+            max_output_tokens: max_output_tokens,
+            before_llm_input: before_llm_input
+          }
+          settings.each do |name, value|
+            derived.public_send(name, value) unless value.nil?
+          end
+          # These getters inherit by ivar presence. An explicit nil preserves
+          # absence even if the source class is configured again later.
+          %i[provider instructions].each do |name|
+            derived.instance_variable_set(:"@#{name}", nil) if settings[name].nil?
+          end
+        end
+
+        def copy_authoring_filters_to(derived)
+          _class_input_filters.each { |filter| derived.input_filter(filter) }
+          _class_output_filters.each { |filter| derived.output_filter(filter) }
+          _class_tool_result_filters.each { |filter| derived.tool_result_filter(filter) }
+        end
+
         def __construct_owned_agent(owner_runtime, reserved_agent_id, *args, **kwargs, &block)
           instance = allocate
           instance.send(:__prepare_runtime_owner!, owner_runtime, reserved_agent_id)
@@ -752,7 +805,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?