phronomy 0.32.0 → 0.34.0

data/docs/features.md

@@ -90,7 +90,7 @@ Backend authors continue to implement the synchronous SPI only.
 | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |
 | **InvocationContext** — Explicit cancellation/deadline/policy plus observability-correlation context for Agent and Workflow invocations | Beta |
 | **Metrics** — OffloadPool active/queue/abandoned metrics plus EventLoop queue/lag metrics | Beta |
-| **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown` | Beta |
+| **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown`; use the result's `cleanup_complete?` for resource release and `clean?` for a graceful shutdown; [cleanup migration](migrations/cleanup-audit.md) | Beta |
 
 ## Agent and workflow patterns
 
@@ -109,7 +109,9 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 | **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 |
+| **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; default member derivation preserves Phronomy authoring settings through `Agent::Base.with_tools`; see the [sharing contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) and [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
+| **Agent Tool composition** — `Agent::Base.with_tools(definitions, id:, version:)` derives a class with a complete replacement Tool map while preserving Phronomy authoring settings and filters; [contract](shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) | Experimental (Unreleased) |
+| **Custom shared data and Tools** — `SharedState.sharing(provider, id:, version:)` and `SharedState::Binding` connect application-owned stores and Tool definitions without private overrides; [contract and executable example](shared-state-sharing.md) | Experimental (Unreleased) |
 | **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 |
 | **`tool_approval_policy`** — Application-defined allow/approve/reject policy using a value-only `ApprovalEvaluationRequest` without live Agent/Tool references | Beta |
 

data/docs/mcp-client.md

@@ -10,8 +10,10 @@ Phronomy supports the official `mcp` Ruby SDK **1.x**. MCP SDK 0.x is not suppor
 - `http://...`
 - `https://...`
 
-HTTP and SSE support are standard dependencies of Phronomy through `faraday` and
-`event_stream_parser`.
+For HTTP and HTTPS servers, Phronomy delegates to the MCP SDK's
+`MCP::Client::HTTP` transport. RubyLLM already brings in `event_stream_parser`
+for server-sent events. See the [HTTP dependency rationale](architecture/trust-acceptance-followup.md#http-dependency-correction)
+for Phronomy's Faraday and Net::HTTP adapter requirements.
 
 ## Input-schema subset
 

data/docs/migrations/cleanup-audit.md

@@ -0,0 +1,89 @@
+# Cleanup audit migration
+
+Phronomy 0.34.0 removes redundant internal operations and old public entry points
+whose behavior is already provided by a current operation. Applications must
+use the current names; the removed names have no compatibility aliases. Current
+record writers are unchanged. The subsequent [legacy-format cleanup](legacy-format-removal.md)
+also removes old read fallbacks and explicitly retires two data-conversion
+entry points. It does not rewrite existing stores.
+
+For example, an application checking whether Runtime resources were released
+uses `cleanup_complete?` on the result returned by `Runtime#shutdown`. The
+removed `success?` method delegated to that same predicate.
+
+## Runtime cleanup completion
+
+Use `cleanup_complete?` to determine whether Runtime-owned resources have stopped.
+Use `clean?` only when the application also needs a graceful, error-free shutdown;
+that stricter predicate is retained and is not a replacement for `success?`.
+
+Before:
+
+```ruby
+result = runtime.shutdown
+resources_released = result.success?
+```
+
+After:
+
+```ruby
+result = runtime.shutdown
+resources_released = result.cleanup_complete?
+```
+
+The same replacement applies to a shutdown result returned by
+`Runtime.reset_default!`. Existing reset guards still reject incomplete cleanup.
+
+## EventLoop reentrancy errors
+
+Rescue `Phronomy::EventLoopReentrancyError` when a synchronous operation would
+block the EventLoop control thread. Framework operations already raise this
+class. The removed `SchedulerReentrancyError` was an empty subclass and did not
+add a distinct failure or recovery behavior.
+
+Before:
+
+```ruby
+begin
+  Phronomy::Diagnostics.assert_not_in_event_loop!
+rescue Phronomy::SchedulerReentrancyError => error
+  warn error.message
+end
+```
+
+After:
+
+```ruby
+begin
+  Phronomy::Diagnostics.assert_not_in_event_loop!
+rescue Phronomy::EventLoopReentrancyError => error
+  warn error.message
+end
+```
+
+Ruby rescue matches a class and its subclasses, not its parent. The old rescue
+above therefore did not catch a directly raised `EventLoopReentrancyError` even
+before this cleanup. The current error name describes the actual failure.
+
+## Internal operations
+
+Internal cleanup keeps behavior at its owning boundary. Context item factories
+call the protected `ContextPolicy#estimate_tokens` extension operation directly.
+Tool approval requests obtain one display projection and snapshot its arguments
+and facts in the public approval Item.
+
+For example, an application that renders approval details continues to use
+`ToolApprovalRequest::Item#arguments` and `#facts`; it does not need the removed
+internal `ToolInvocation#display_arguments` and `#display_facts` getters. The
+public `Tool::Base#approval_display` extension operation remains available.
+
+The cleanup also removes the unused internal `AgentInvocation#streaming?`,
+`RecoveryRules.subject_key`, and `Execution#__while_open` and
+`Execution#__cancellation_token` methods. Scope-owned operations used by result
+composition remain in `ExecutionScopeState`. Five completed scripts for migrating
+the repository's own test sources are removed. The subsequent legacy-format
+cleanup separately retires the pre-S3 migration API and old Result JSON converter.
+
+`JournalProjection#llm_call_records` and
+`LLMInputManifest#referenced_content_refs` remain available. Lack of calls from
+the repository does not make an application-facing operation removable.

data/docs/migrations/legacy-format-removal.md

@@ -0,0 +1,55 @@
+# Legacy-format cleanup
+
+Phronomy 0.34.0 keeps current saved facts and removes specific historical read
+fallbacks and conversion facilities. It does not rewrite stores or introduce a
+new record version. Retiring the conversion facilities is an intentional removal
+of migration support, not a claim that another public API replaces them.
+
+For example, a newly authorized Tool operation continues to store its validated
+arguments, including type coercion and meaningful null values. Its reader no
+longer reconstructs those arguments from an older raw-input field.
+
+## Handoff conversation groups
+
+Handoff uses the conversation group recorded by the current Context assembly.
+The historical selection-unit ID and kind no longer supply grouping or category
+information. Segments without a current group still use the ordinary per-segment
+fallback; reserved internal metadata is still removed from transferred content.
+
+For example, current Tool-call and Tool-result segments share
+`context_policy_conversation_group_id` and remain together when a Handoff policy
+selects that exchange. A saved `selection_unit_id` is no longer an alternative
+source for that relationship. The Manifest codec remains strict about its
+supported version and required fields.
+
+## Authorized Tool arguments
+
+Agent Store reads the exact validated argument snapshot for an authorized
+operation. The raw request remains a separate fact and is not a substitute when
+the validated snapshot is absent.
+
+For example, raw `{"count":"2","optional":null}` may validate as
+`{"count":2,"optional":null}`. Authorization matching must use the integer and
+retain the explicit null. An authorized record missing `validated_arguments`
+fails instead of falling back to `arguments` and dropping null values.
+
+Provider-response recovery can temporarily record an `authorized` placeholder
+without that snapshot. The normal `framework_calls` continuation validates its
+Tool invocation and saves the prepared snapshot before an operation consumer
+reads it. Directly projecting the intermediate placeholder is rejected; its
+status alone is not proof that its arguments have been validated. A resumed
+`framework_tools` continuation instead uses its previously saved dispatch
+snapshot.
+
+## Retired conversion support
+
+The pre-S3 `Persistence::Migration::InitialFormatMigration` API and the
+GeneratorVerifier Result JSON converter are removed, along with the former
+command's usage instructions. There is no compatibility alias or replacement
+conversion command. Ordinary Agent and Workflow persistence, current Manifest
+decoding and GeneratorVerifier Result validation remain in their owning domains.
+
+For example, `GeneratorVerifier::Result.from_h` still requires `failure` even
+when its value is null. It does not add missing fields to historical JSON.
+The separate `PersistenceComposition::Unit4Migration` snapshot conversion is
+retained and was not an implementation of either removed conversion facility.

data/docs/migrations/r8-unit6.md

@@ -91,8 +91,10 @@ an explicit items schema to restrict them.
 Storage SPI and SQL schemas are unchanged. New Tool batch metadata additionally
 records `validated_arguments`, separately from the unchanged raw request fields.
 Agent authorization projects and compares that exact snapshot (including explicit
-null in explicit schemas). Older snapshots without this field use the historical
-raw-argument/optional-nil-omission rule. Existing journal message boundaries,
+null in explicit schemas). Authorization projection requires this validated
+dispatch evidence; it does not infer approved values from raw request fields.
+Provider-recovery placeholders are revalidated and replaced by the normal Tool
+dispatch barrier before framework operations run. Existing journal message boundaries,
 Tool call identities and recorded usage remain readable. Legacy top-level
 thought_signature is decoded into opaque CallRequest metadata and rendered by
 the backend. Old SDK usage field spellings remain accepted by SavedContextReader.

data/docs/migrations/shared-state-multi-agent.md

@@ -42,3 +42,8 @@ for one invocation only.
 
 See [ADR-053](../decisions/053-shared-state-coordination-ownership.md) for the
 ownership and compatibility decision.
+
+The later [custom sharing extension](../shared-state-sharing.md) is opt-in and
+leaves the default behavior described above intact. It gives an application
+explicit ownership of its store and Tool definitions; its generated identity
+also records the application's sharing ID and semantic version.

data/docs/migrations/vector-async-clients.md

@@ -107,4 +107,9 @@ The public class names below are unchanged. Their implementation files move:
 Use `require "phronomy"` and the public constants. Direct partial-load paths are
 not the public loading contract; no require shim is kept in the contract
 directories. Backend Contracts have no execution or implementation dependency.
-P4 Storage/ContentStore work remains pending.
+P4 Storage/ContentStore work is implemented; see the
+[Storage asynchronous execution guide](storage-async-client.md).
+[ADR-062](../decisions/062-content-store-service.md) subsequently classified
+ContentStore as a content service over Storage, rather than a physical backend.
+The final P5 cross-repository/API/documentation review remains pending, as
+recorded in [Backend responsibilities](../architecture/backend-groups.md).

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
@@ -672,6 +703,11 @@ Runtime shutdown before resetting configuration.
 
 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.

data/docs/shared-state-sharing.md

@@ -0,0 +1,233 @@
+# 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 Tools with either its built-in
+sharing Tools or the application's 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.
+
+The default findings-store mode now preserves these settings through the same
+factory. For example, a member configured with `max_iterations 3` and
+`temperature 0.25` keeps those settings when SharedState adds `read_store` and
+`write_finding`. Member Tool aliases, the generated definition identity and the
+default store/prompt behavior remain unchanged. This fixes the earlier default
+derivation, which explicitly copied only the model setting.
+
+## 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. Its current version uses the public sharing
+contract and Context budgeting APIs introduced in v0.33.0; its previous private
+overrides have been removed. The application still owns adaptive retrieval and
+budget allocation rather than delegating those policies to the sharing binding.
+
+## 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/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)

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

@@ -114,10 +114,6 @@ module Phronomy
         @callback_failure = nil
       end
 
-      def streaming?
-        @mode == :stream
-      end
-
       def set_graph_metadata(phase: nil)
         @phase = phase
       end

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

@@ -105,6 +105,7 @@ module Phronomy
         :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(
@@ -179,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.

data/lib/phronomy/agent/handoff/transfer_projection.rb

@@ -83,9 +83,6 @@ module Phronomy
         return :current_request if segment.delivery.to_sym == :ask_argument
         return nil if CONTROL_CATEGORIES.include?(segment.category.to_sym)
         return :knowledge if segment.category.to_sym == :knowledge
-        unit_kind = segment.metadata["selection_unit_kind"] ||
-          segment.metadata[:selection_unit_kind]
-        return :tool_exchanges if unit_kind.to_s == "tool_exchange"
 
         case segment.category.to_sym
         when :external_message, :assistant_message, :tool_message,
@@ -102,12 +99,6 @@ module Phronomy
           return "context-policy-conversation:#{conversation_group_id}"
         end
 
-        # Compatibility for finalized pre-ACS-04 manifests. New manifests use
-        # context_policy_conversation_group_id and do not recreate Phronomy::Context::Unit.
-        unit_id = segment.metadata["selection_unit_id"] ||
-          segment.metadata[:selection_unit_id]
-        return "unit:#{unit_id}" if unit_id
-
         "segment:#{policy_category}:#{segment.position}"
       end
 

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

@@ -57,8 +57,8 @@ module Phronomy
         ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
       end
 
-      # Historical durable fields are not accepted here. Explicit migration must
-      # convert them to the current semantic payload first.
+      # Reads the current semantic payload only. Historical durable fields are
+      # rejected rather than converted.
       def self.from_h(hash)
         source = hash.to_h { |key, value| [key.to_s, value] }
         expected = ATTRIBUTES.map(&:to_s).sort