phronomy 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eeef6dddca310da11fcdcaf7ffc2490191151cfa070384be8d04f84366efb08
-  data.tar.gz: 2b43c66ff8c5484360b2a953bcdd4aa754ef99c3b7bc944285993d866ee34007
+  metadata.gz: e696f701b22d91c4ccb8f566e28274b73e9fd69704a673e18a687a1d377b4583
+  data.tar.gz: 7a63749fb58c70fb6c74a843a601bb48401ffe35fa02de03a63fa9f8d6320552
 SHA512:
-  metadata.gz: 9ebee2313bc7d60b27c6e42e0909fbb1102cca3c220f25575d1c755b18f3d1c00b7ea0dfec36646155a7aff325ba47c99af202c9b7fbf226d45c4fbb07b8bff9
-  data.tar.gz: 3b089fdc8447a0a56c66d10d64c809eb26ddc31be6800a55c095409e87e649047afbc42fa1872eab8fd68b7939bd6845edc194b5ec4ab03beca602408f320596
+  metadata.gz: af029ecc2491d2912c48fef847f8501ce255040759bb5d8edba3949d2bea0352b2a6a89e731d70493570c5b72d26e094ed03d80aff412f6805af21a0da588219
+  data.tar.gz: 529ece7bc74b4096d332e9f39a3097933f1441797f5dc22b5bb9ec9d5b39fde2c42709d2b53e83b99a3e42ec6e2e9a227920f10371e6ac65772241cb54d0abc7

data/CHANGELOG.md

@@ -12,6 +12,83 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-11-14
+
+### Added
+
+- Add public `ContextPolicyInput#input_token_limit` and
+  `#with_input_token_limit(limit)` for immutable, non-expanding selection limits,
+  plus protected `ContextPolicy#estimate_tokens(content)` using the same
+  canonical estimator as generated Policy items. Applications can reserve input
+  capacity while retaining DefaultPolicy selection without constructing private
+  budget objects or calling private token-estimation helpers. These operations
+  do not change model capabilities, generation settings or final validation.
+- Add `Agent::Base.with_tools(definitions, id:, version:)` to derive an Agent
+  class with a complete replacement Tool map and explicit definition identity.
+  The factory preserves Phronomy authoring settings and independently copies
+  filter lists; configured callable instances remain shared. Custom SharedState
+  uses this public operation after merging member and application Tools. General
+  Agent subclass inheritance remains unchanged.
+- Add `MultiAgent::SharedState.sharing(provider, id:, version:)` and the public
+  `SharedState::Binding` value. A synchronous provider opens one application-owned
+  store for an invocation and supplies Tool definitions for each member/cycle.
+  Applications define their own records, search arguments and cleanup without
+  overriding SharedState private methods. Custom sharing requires an explicit
+  aggregation block and does not inject the default findings Tools or append
+  stored records to member prompts.
+- Include the sharing provider's stable ID and semantic version in custom
+  generated Agent definition identity. Default SharedState retains its existing
+  built-in Tools, prompts and instrumentation revision 1. The extension adds no
+  database adapter, ContextPolicy implementation or durable sharing lifecycle.
+- Release terminal custom-sharing members through the public Agent lifecycle
+  operation. Normal Agent approval waits keep the invocation and provider open.
+  `SharedState::MemberLifecycleError` reports failed release or a custom
+  `invoke` override returning a suspended result prematurely, with the Agent and
+  available result/error details. It does not automatically answer approvals or
+  release a pending execution; application providers retain responsibility for
+  resource cleanup and recovery policy.
+
+### Changed
+
+- Reuse the immutable argument schema prepared by an explicit `parameters`
+  declaration. Each Tool instance compiles its own validator on first use.
+
+### Fixed
+
+- Build each human-facing Tool approval item from the Tool's public
+  `approval_display(arguments:, facts:)` result. A Tool without this operation
+  contributes empty argument and fact maps to new approval requests. Tool
+  execution and policy evaluation still receive their original inputs.
+- Apply the default approval display's sensitive-value check to values inside
+  a Tool's redacted hash or array arguments, including copies used as fact keys.
+
+### Security
+
+- Use patched ActiveRecord 8.0 development dependencies, including ActiveSupport
+  8.0.5.2 or later in the 8.0 series. Remove unused ActiveJob and SQLite3
+  development dependencies; the examples retain the dependencies they use.
+  The published gem's runtime dependencies are unchanged.
+- Provide Bundler Audit in the development bundle and check the complete
+  dependency set in pull-request CI and immediately before release publication.
+
+### Compatibility and verification
+
+- The new SharedState sharing, Agent Tool composition and Context budgeting APIs
+  require 0.33.0 or later and remain Experimental. Default sharing and ordinary
+  Agent subclass inheritance retain their existing behavior. Custom sharing is
+  synchronous and invocation-scoped; it does not add durable sharing recovery.
+- Approval display is selected by each Tool. Custom Tool implementations without
+  `approval_display` expose empty display maps; execution and policy evaluation
+  still use the original arguments. Review custom display overrides for safe
+  human-facing fields when upgrading.
+- Observed LM Studio/gpt-oss PEG-format failures remain unresolved.
+  The existing adapter identifies known errors and bounds retries; this release
+  does not claim to fix their root cause or establish full real-LLM acceptance.
+  The latest full examples verification recorded 102 passed, 1 failed and no
+  skips (Example 22: HTTP 400). A separate Qwen Example 22 run completed all three
+  cycles, but took 2,220 seconds and does not replace the full verifier result
+  or satisfy its 240-second per-example limit.
+
 ## [0.32.0] - 2026-11-03
 
 ### Added

data/README.md

@@ -37,13 +37,19 @@ 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.32.0.
+The following table describes the application APIs available in v0.33.0.
+The new sharing, Tool composition and Context budgeting operations remain
+Experimental; their introduction version is shown below.
 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.
 
 | API | Stability | Contract |
 |---|---|---|
+| `Context::ContextPolicyInput#input_token_limit / #with_input_token_limit` and protected `ContextPolicy#estimate_tokens` | Experimental (since v0.33.0) | Inspect and constrain selection budgets and estimate candidate content through Context-owned operations. [Policy budgeting](docs/context-policy-budgeting.md) |
+| `Agent::Base.with_tools(definitions, id:, version:)` | Experimental (since v0.33.0) | Derive an Agent class with a complete replacement Tool map and explicit definition identity while preserving Phronomy authoring settings and filters. [Tool composition](docs/shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) |
+| `MultiAgent::SharedState.sharing(provider, id:, version:)`, `SharedState::Binding` and `SharedState::MemberLifecycleError` | Experimental (since v0.33.0) | Connect application-owned shared data and Tools to sequential coordination through a synchronous invocation-scoped provider. [Custom sharing contract and example](docs/shared-state-sharing.md) |
+| `Tool::Base#approval_display(arguments:, facts:)` | Beta (since v0.33.0) | The Tool selects the arguments and derived facts a person can see in an approval request. [Approval display](docs/runtime-and-concurrency.md#tool-approval-display) |
 | `Phronomy::LLMAdapter::LMStudio` | Beta | Explicit known-output-error identification and bounded opt-in retry; [policy and evidence limits](docs/architecture/lm-studio-output-failures.md) |
 | Agent `output_schema:`, `schema_delivery:`, `Agent::OutputError` and `OutputParser::JsonSchemaParser` | Beta | Agent returns validated immutable JSON or an explicit output failure; [contract and migration](docs/architecture/structured-output-and-scope.md) |
 | 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) |

data/RELEASE_CHECKLIST.md

@@ -38,6 +38,10 @@ Copy it into the GitHub Release draft and check off each item.
 - [ ] No new `requires_approval` tools missing the approval gate
 - [ ] No secrets, credentials, or PII in tool descriptions, schema strings, or spec fixtures
 - [ ] Dependency audit passes: `bundle exec bundler-audit check --update`
+  Run `bundle install` first; the development Gemfile provides the audit tool.
+  Audit the complete resolved bundle, including development and test dependencies,
+  without advisory exclusions. A runtime-only audit does not satisfy this gate.
+  The dependency-audit CI job and the release workflow enforce the same command.
 
 ---
 

data/docs/architecture/structured-output-and-scope.md

@@ -83,10 +83,11 @@ with lazy grammar` is a known native schema/Tool rejection. It is classified as
 stream operations. Unrelated string errors and requests without a schema retain
 their ordinary transport-error behavior. The adapter neither downgrades schemas
 nor replays requests. RubyLLM's configured transport retry policy is independent.
-The minimum Faraday streaming callback omits the HTTP status, so RubyLLM may
-surface this same exact rejection as `ServerError`; its cause is preserved too.
-That synthetic server status can trigger SDK retries before the adapter receives
-the error. Adapter replay tests disable SDK retries to verify their own boundary.
+On the supported HTTP stack, the known schema rejection retains its
+`RubyLLM::BadRequestError` cause even when streaming. An HTTP 500 with the same
+body retains its `RubyLLM::ServerError` cause. The
+[HTTP dependency rationale](trust-acceptance-followup.md#http-dependency-correction)
+documents the tested versions and request counts.
 
 `Response` records finish_reason (stop, tool_calls, length, content_filter, refusal,
 unknown), refusal and raw_finish_reason metadata. Only normal final completion can

data/docs/architecture/trust-acceptance-followup.md

@@ -37,6 +37,21 @@ retain the SDK server-error cause. Configured SDK retries for 429/500 remain;
 a 400 rejection is one HTTP attempt even with three retries configured.
 Partial-stream replay and callback identity regressions remain in place.
 
+RubyLLM owns HTTP transport selection for model calls. Phronomy's LLM and
+Embeddings adapters recognize Faraday exception classes at the SDK boundary.
+The two gemspec declarations are a temporary workaround for the streaming
+status bug. Remove both when all supported RubyLLM versions preserve the
+status or exclude the affected HTTP stack through their own dependencies.
+
+Verify removal with the two Phronomy declarations omitted. Resolve the minimum
+supported RubyLLM and its permitted HTTP dependencies without the existing CI
+pins. If the old pair still resolves, test it explicitly. If RubyLLM excludes
+it, confirm resolution rejects it and test the new minimum. In both cases run
+`spec/integration/transport_error_spec.rb` against the minimum and the normal
+bundle. With three retries configured, a streaming HTTP 400 with a string
+error body must retain its 400 cause and send one POST. An HTTP 500 with the
+same body must retain its 500 cause and send four POSTs.
+
 Before and after, application handling uses the same public API:
 
 ```ruby

data/docs/context-policy-budgeting.md

@@ -0,0 +1,108 @@
+# Context Policy budgeting
+
+Applications choose how much model input capacity to use for one selection.
+Context exposes that capacity and candidate estimates, while the framework keeps
+its internal budget representation and final input validation.
+
+For example, a review Policy can reserve part of the available input for its own
+safety margin, then let DefaultPolicy choose history within the smaller limit.
+No application needs to construct a private budget object for that operation.
+
+## Reading and constraining input limits
+
+A Policy input reports its current selection limit and can derive another input
+with a smaller limit. Derivation preserves the original input and all its
+material; it does not change model capabilities or generation settings.
+
+For example, an input with a limit of 8192 can produce a selection input capped
+at 5632. The original input still reports 8192. The derived input cannot later
+increase its limit above 5632.
+
+```ruby
+require "phronomy"
+
+class ReservedInputPolicy < Phronomy::Context::ContextPolicy
+  def call(input)
+    limit = input.input_token_limit
+    unless limit
+      raise Phronomy::ConfigurationError, "Review requires known model input capacity"
+    end
+
+    selection_limit = limit - limit / 4 - limit / 16
+    selected_input = input.with_input_token_limit(selection_limit)
+    Phronomy::Context::DefaultPolicy.instance.call(selected_input)
+  end
+end
+```
+
+`input_token_limit` returns an Integer or `nil` for an unknown limit.
+`with_input_token_limit(limit)` requires a positive Integer without coercion;
+zero, negative values, strings and floating-point values raise `ArgumentError`.
+Increasing a known limit also raises `ArgumentError`. The returned
+`ContextPolicyInput` is immutable, and its other field values are unchanged.
+
+When the original limit is unknown, an explicit positive selection cap is
+allowed. That cap expresses application policy and does not establish that the
+model can accept that input. Applications that require known capability must
+reject `nil`, as the example above does.
+
+The cap controls selection performed with the derived input. The framework's
+final validation still uses the actual model budget; returning a different Plan
+does not make the derived cap a new global validator. It does not set an output
+token limit, alter a saved Manifest, or affect another Agent call.
+
+## Estimating candidate content
+
+A Policy can estimate proposed content through the same canonical encoding and
+estimator used by its generated items. The Policy remains responsible for
+choosing complete items and preserving required conversation groups.
+
+For example, a retrieval Policy can fit a JSON page before adding it as
+knowledge. JSON escaping contributes to the estimate because the complete
+serialized page is measured.
+
+```ruby
+require "phronomy"
+require "json"
+
+class PageKnowledgePolicy < Phronomy::Context::ContextPolicy
+  def initialize(page:, allowance:)
+    @page = page
+    @allowance = allowance
+  end
+
+  def call(input)
+    content = JSON.generate(@page)
+    if estimate_tokens(content) > @allowance
+      raise Phronomy::Context::BudgetExceededError, "Retrieved page exceeds its allowance"
+    end
+
+    page = knowledge_item(content: content, required: true)
+    Phronomy::Context::DefaultPolicy.instance.call(
+      input.with(knowledge: input.knowledge + [page])
+    )
+  end
+end
+```
+
+`estimate_tokens(content)` is a protected subclass helper. Strings are estimated
+as text; other values use the framework's canonical JSON encoding. The helper
+uses the existing estimator and does not introduce a second token-counting
+algorithm. Estimates are approximate unless the configured estimator provides
+model-specific counts. A successful estimate does not guarantee provider
+acceptance or replace final input validation.
+
+## Compatibility and ownership
+
+These operations belong to the Context contract and reuse its existing budget
+and estimation mechanisms. Applications own allocation ratios and retrieval
+policy; DefaultPolicy retains its current selection algorithm.
+
+For example, Example 22 can budget retrieved findings through these operations
+while SharedState continues to coordinate Agents and application Tools continue
+to own the finding store. No SharedState-to-Context dependency is introduced.
+
+The operations are Experimental and available since v0.33.0. Existing private
+budget and estimation classes remain implementation details. Existing ContextPolicy
+factories and DefaultPolicy behavior are unchanged, and the protected helper
+applies equally to normal Agent calls and SharedState member calls.

data/docs/examples/shared_state_custom_sharing.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "phronomy"
+
+module SharedStateCustomSharingExample
+  class IssueBoard
+    attr_reader :closed
+
+    def initialize
+      @records = []
+      @closed = false
+    end
+
+    def record(content:, category:, status:, author:, cycle:)
+      raise "Issue board is closed" if closed
+
+      row = {id: @records.length + 1, content: content.dup.freeze,
+             category: category.dup.freeze, status: status.dup.freeze,
+             author: author.dup.freeze, cycle: cycle}.freeze
+      @records << row
+      row
+    end
+
+    def search(category: nil, status: nil)
+      snapshot.select do |row|
+        (category.nil? || row.fetch(:category) == category) &&
+          (status.nil? || row.fetch(:status) == status)
+      end
+    end
+
+    def snapshot
+      raise "Issue board is closed" if closed
+
+      @records.dup.freeze
+    end
+
+    def close
+      @records.clear
+      @closed = true
+    end
+  end
+
+  class IssueSharing
+    def open(input:, config:)
+      board = IssueBoard.new
+      yield Phronomy::MultiAgent::SharedState::Binding.new(
+        store: board,
+        tools: ->(member:, cycle:) { tool_definitions(board, member, cycle) }
+      )
+    ensure
+      board&.close
+    end
+
+    private
+
+    def tool_definitions(board, member, cycle)
+      {
+        record_tool(board, member.agent_definition.fetch(:id), cycle) => nil,
+        search_tool(board) => nil
+      }
+    end
+
+    def record_tool(board, author, cycle)
+      Class.new(Phronomy::Tool::Base) do
+        tool_name "record_issue"
+        description "Record one issue with an explicit category and status."
+        execution_mode :cooperative
+        param :content, type: :string, desc: "The issue description."
+        param :category, type: :string, enum: %w[security performance],
+          desc: "The issue category."
+        param :status, type: :string, enum: %w[open closed],
+          desc: "The issue status."
+
+        define_method(:execute) do |content:, category:, status:|
+          board.record(content: content, category: category, status: status,
+            author: author, cycle: cycle).to_json
+        end
+      end
+    end
+
+    def search_tool(board)
+      Class.new(Phronomy::Tool::Base) do
+        tool_name "search_issues"
+        description "Read issues matching all supplied category and status filters."
+        execution_mode :cooperative
+        param :category, type: :string, required: false, enum: %w[security performance],
+          desc: "Optional exact category filter."
+        param :status, type: :string, required: false, enum: %w[open closed],
+          desc: "Optional exact status filter."
+
+        define_method(:execute) do |category: nil, status: nil|
+          board.search(category: category, status: status).to_json
+        end
+      end
+    end
+  end
+
+  class Researcher < Phronomy::Agent::Base
+    agent_definition id: "shared-issue-researcher", version: 1
+    model ENV.fetch("PHRONOMY_EXAMPLE_MODEL", "configured-model")
+  end
+
+  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
+
+  module OfflineDemo
+    def self.run
+      opened_board = nil
+      output = IssueSharing.new.open(input: "Review authentication", config: {}) do |binding|
+        opened_board = binding.store
+        definitions = binding.tool_definitions(member: Researcher, cycle: 1)
+        tools = definitions.keys.to_h { |tool| [tool.tool_name, tool.new] }
+        recorder = tools.fetch("record_issue")
+        recorder.call({"content" => "Missing token validation", "category" => "security", "status" => "open"})
+        recorder.call({"content" => "Slow cache lookup", "category" => "performance", "status" => "open"})
+        recorder.call({"content" => "Session expiry corrected", "category" => "security", "status" => "closed"})
+
+        matches = JSON.parse(tools.fetch("search_issues").call({"category" => "security", "status" => "open"}))
+        unless matches.map { |row| row.fetch("content") } == ["Missing token validation"]
+          raise "Search did not apply both filters"
+        end
+        all_records = binding.store.snapshot
+        raise "Search changed the board" unless all_records.length == 3
+
+        {matches: matches, total_records: all_records.length}
+      end
+      raise "Provider did not close the board" unless opened_board.closed
+
+      puts JSON.pretty_generate(output.merge(provider_closed: true))
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  abort "Run with --offline, or require this file from a configured Phronomy application." unless ARGV == ["--offline"]
+
+  SharedStateCustomSharingExample::OfflineDemo.run
+end

data/docs/features.md

@@ -110,6 +110,8 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 | **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 |
+| **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/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/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.