phronomy 0.31.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7eb1f72acaa35f02d5f848dac344ea971e6ef190544d2b200fe367409e48e92
-  data.tar.gz: 26b2de048b30845bdbf973a5e26a6d5fa4b734295d31b81cec2530e9dd896dc8
+  metadata.gz: e696f701b22d91c4ccb8f566e28274b73e9fd69704a673e18a687a1d377b4583
+  data.tar.gz: 7a63749fb58c70fb6c74a843a601bb48401ffe35fa02de03a63fa9f8d6320552
 SHA512:
-  metadata.gz: eaf92481864d37b545ccf7507541fbd64777eb6ff6369e2f8a674f31341bc2ec439883dfa2964d410c1becc2adc92c2794c9a7a2e6a7a2e5050a78e2ae4fa181
-  data.tar.gz: 6ca6f91cc3bf270a2694cb5a8a194cc1f4fe8270440ada751a4082f0ae27489c0798743a351d8850e1fbf4e81eb0aac207bee563995e8aa821d2008b2b6916e2
+  metadata.gz: af029ecc2491d2912c48fef847f8501ce255040759bb5d8edba3949d2bea0352b2a6a89e731d70493570c5b72d26e094ed03d80aff412f6805af21a0da588219
+  data.tar.gz: 529ece7bc74b4096d332e9f39a3097933f1441797f5dc22b5bb9ec9d5b39fde2c42709d2b53e83b99a3e42ec6e2e9a227920f10371e6ac65772241cb54d0abc7

data/CHANGELOG.md

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

data/README.md

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

data/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

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