smith-agents 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 988c5dc6e794da7b78889dc17db5801c9ad8ebf99a008a0b043bdc56e7115126
-  data.tar.gz: ad4ecd254dd213b16e2b5e27730fed50fdd6491b86d45d5d76f40ba620a0bc33
+  metadata.gz: 450ce06c1d96f41a8b6ae6d0c0dd1b8dcc88b58d3da786d8536a26ecc8f111bb
+  data.tar.gz: 7b0696ff9aaccc3016ebef5223c4ded71aeeb883d1a1b70e6f2ab5959657e1da
 SHA512:
-  metadata.gz: e439e1c6cc4cae2feffdb3a258e9abe94dd6f90a7641e76e36784921f09864d53d4d96616823ef2bfb43c56aa5cc9082eb689fffd4fc1464fa51e752f724139f
-  data.tar.gz: 6d7bbf59a8b7c5297078af12b08a2b092287c5def28df0dac69cc10553e308abb238512e275166e372b08dcd155b6583e898d91b25b89ef4303ea5da09476eb4
+  metadata.gz: da3c5cb55ef7efac304f223eb7ce468f058b4d85c9c4b60ea102f50882789d067eaf9c2a212871eb66a215f7f1cce2baa29de945dd3c0f2c0cc084d187fec1ae
+  data.tar.gz: 910ec83bc644cdbb5ad1a737ef1aa95af3d5ca784d952fea9179ae4b7e44d49a1edf7a7ae2b067c7a83a227bb623d3d6c798cc45a8d254501ff397f99e876b69

data/CHANGELOG.md

@@ -4,7 +4,44 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
-## [Unreleased]
+## [0.7.0] - 2026-07-21
+
+### Added
+
+- Add an opaque host invocation context for tool adapters, propagated through
+  Smith parallel/fan-out branches and concurrent tools on individual chats
+  created by `Smith::Agent` without globally changing RubyLLM behavior. Durable
+  workers receive it only when the host installs a fresh process-local context.
+- Add opt-in strict tool-result capture with typed failure diagnostics and
+  persistence-safe reconstruction.
+
+### Changed
+
+- Bump `Smith::EXECUTION_SEMANTICS_VERSION` to `3` because composite branch
+  failure transport now preserves strict tool-capture uncertainty and its
+  typed tool metadata across persistence.
+- Support RubyLLM `>= 1.15, < 1.17`; Smith's per-chat concurrent tool context
+  integration is verified against those execution interfaces and fails closed
+  when the required chat hook is unavailable.
+
+### Fixed
+
+- Make agent tool-call allowance atomic across concurrent tool calls.
+- Install Smith's tool execution boundary on direct and persisted agent chat
+  entry points (`chat`, `create`, `create!`, and `find`) without modifying raw
+  RubyLLM chats globally, and capture invocation context independently for each
+  tool execution batch.
+- Give strict capture uncertainty precedence over sibling concurrent failures,
+  reject unusable collectors before host hooks or tool execution, and prevent
+  transition retries from replaying an uncertain tool outcome.
+- Preserve process-fatal failures across concurrent tool callbacks and root
+  workflow branches regardless of sibling completion order.
+- Reject malformed or future strict-capture diagnostics at persistence
+  boundaries, while preserving legacy non-capture composite error transport.
+- Preserve the existing per-concrete-class `capture_result` opt-in behavior and
+  the public `BranchEnv` member shape.
+
+## [0.6.1] - 2026-07-20
 
 ### Fixed
 

data/docs/TOOLS_AND_GUARDRAILS.md

@@ -80,6 +80,67 @@ Captured tool results survive persistence — they are included in `to_state` an
 
 `tool_results` is designed for compact structured evidence (URLs, metadata, refs). Hosts should avoid storing large raw payloads there. If large tool outputs are needed, use artifacts and capture refs or metadata instead.
 
+Capture is best-effort by default for backward compatibility. Hosts that cannot
+complete a workflow checkpoint without captured evidence can opt into strict
+capture:
+
+```ruby
+class VerifiedSearch < Smith::Tool
+  capture_result(strict: true) do |kwargs, result|
+    { query: kwargs.fetch(:query), urls: extract_urls(result) }
+  end
+end
+```
+
+Strict capture raises `Smith::ToolCaptureFailed` when no workflow collector is
+active, the collector is not callable, the capture block fails or returns `nil`, or the collector rejects the
+entry by raising an exception. A collector return value of `nil` or `false` is
+accepted; delivery is rejected only when the collector raises. Best-effort
+capture logs and continues as before.
+
+Capture policy is declared per concrete tool class and is not inherited. This
+preserves the historical opt-in contract and prevents a subclass from beginning
+to capture or fail strictly without its own declaration.
+
+Strict capture validates that a collector exists before `perform`, but the
+capture block and collector run after `perform` returns. It is therefore
+post-result evidence, not a pre-effect transaction or durable operation receipt.
+`Smith::ToolCaptureFailed` is terminal: direct retry declarations are rejected,
+and broad explicit retry classes such as `StandardError` do not override that
+classification, because the external outcome may already have occurred. Hosts
+must give side-effecting tools their own idempotent operation receipt and
+reconciliation boundary before retrying them. Read-only tools can use strict
+capture to fail closed when their result cannot be checkpointed.
+
+### Host Invocation Context
+
+Hosts can expose one opaque, execution-scoped value to tool adapters without
+placing host identity or credentials in model arguments:
+
+```ruby
+Smith::Tool.with_invocation_context(execution_context) do
+  workflow.advance
+end
+
+Smith::Tool.current_invocation_context
+```
+
+Smith does not inspect, serialize, or persist this value. The scope restores the
+previous value even when execution raises, and the value propagates through
+Smith-managed same-agent and heterogeneous parallel branches, durable composite
+branch workers, and concurrent tool calls on chats returned by the Smith agent
+entry points `chat`, `create`, `create!`, and `find`. Invocation context is
+captured independently for each concurrent tool batch, so reusing a chat cannot
+retain a previous execution's scope. Smith scopes only those chat instances;
+requiring Smith does not alter raw RubyLLM chats. Arbitrary chats, threads, or
+fibers created by host code are outside this boundary and must install their own
+scope. Hosts remain responsible for using an immutable value and installing a
+fresh context after durable resume; context-dependent adapters must fail closed
+when no context is installed. Smith supports RubyLLM `>= 1.15, < 1.17` for this
+integration and fails closed if the required per-chat tool execution hook is
+unavailable. RubyLLM fiber concurrency still requires its optional `async`
+dependency; Smith does not make that scheduler a runtime dependency.
+
 You can still use RubyLLM agent tool wiring on your agents:
 
 ```ruby
@@ -137,4 +198,3 @@ class GuardedWorkflow < Smith::Workflow
   end
 end
 ```
-

data/lib/smith/agent.rb

@@ -2,6 +2,8 @@
 
 require "ruby_llm"
 
+require_relative "tool"
+
 module Smith
   class Agent < RubyLLM::Agent
     EXECUTION_IDENTITY_UNSET = Object.new.freeze
@@ -195,11 +197,23 @@ module Smith
         kwargs = inject_reserved_inputs(kwargs, profile)
         kwargs = nil_fill_declared_inputs(kwargs)
 
-        llm_chat = super
+        llm_chat = install_tool_execution_context(super)
         Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
         llm_chat
       end
 
+      def create(**kwargs)
+        install_tool_execution_context(super)
+      end
+
+      def create!(**kwargs)
+        install_tool_execution_context(super)
+      end
+
+      def find(id, **kwargs)
+        install_tool_execution_context(super)
+      end
+
       # Normalizes the |ctx| DSL across RubyLLM's block-form attribute setters.
       #
       # RubyLLM evaluates these blocks via `runtime.instance_exec(&block)`,
@@ -255,6 +269,14 @@ module Smith
 
       private
 
+      def install_tool_execution_context(chat_object)
+        return unless chat_object
+
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        Tool::ChatExecutionContext.install(llm_chat)
+        chat_object
+      end
+
       def resolve_profile(model_id)
         return nil unless model_id
         return nil unless defined?(Smith::Models)

data/lib/smith/tool/budget_enforcement.rb

@@ -10,23 +10,21 @@ module Smith
         ledger = self.class.current_ledger
         workflow_active = ledger&.limits&.key?(:tool_calls)
 
-        check_agent_tool_calls!(allowance)
-        commit_tool_call_charges!(ledger, allowance, workflow_active)
-      end
-
-      def check_agent_tool_calls!(allowance)
-        return unless allowance
+        if allowance.is_a?(CallAllowance)
+          return allowance.charge! { commit_workflow_tool_call!(ledger, workflow_active) }
+        end
+        if allowance.is_a?(Hash)
+          return CallAllowance.charge_legacy!(allowance) { commit_workflow_tool_call!(ledger, workflow_active) }
+        end
 
-        raise BudgetExceeded, "agent tool_calls budget exceeded" if allowance[:remaining] <= 0
+        commit_workflow_tool_call!(ledger, workflow_active)
       end
 
-      def commit_tool_call_charges!(ledger, allowance, workflow_active)
-        if workflow_active
-          reservation = ledger.reserve!(:tool_calls, 1)
-          ledger.reconcile!(reservation, 1)
-        end
+      def commit_workflow_tool_call!(ledger, workflow_active)
+        return unless workflow_active
 
-        allowance[:remaining] -= 1 if allowance
+        reservation = ledger.reserve!(:tool_calls, 1)
+        ledger.reconcile!(reservation, 1)
       end
     end
   end

data/lib/smith/tool/call_allowance.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class CallAllowance
+      LEGACY_MUTEX = Mutex.new
+      LEGACY_ALLOWANCE_MUTEXES = ObjectSpace::WeakMap.new
+      private_constant :LEGACY_MUTEX
+      private_constant :LEGACY_ALLOWANCE_MUTEXES
+
+      def self.charge_legacy!(allowance)
+        legacy_allowance_mutex(allowance).synchronize do
+          Thread.handle_interrupt(Object => :never) do
+            remaining = allowance[:remaining]
+            unless remaining.is_a?(Integer) && remaining.positive?
+              raise BudgetExceeded, "agent tool_calls budget exceeded"
+            end
+
+            yield if block_given?
+            allowance[:remaining] = remaining - 1
+          end
+        end
+      end
+
+      def self.legacy_allowance_mutex(allowance)
+        LEGACY_MUTEX.synchronize do
+          LEGACY_ALLOWANCE_MUTEXES[allowance] ||= Mutex.new
+        end
+      end
+      private_class_method :legacy_allowance_mutex
+
+      def initialize(remaining)
+        unless remaining.is_a?(Integer) && remaining >= 0
+          raise ArgumentError, "tool call allowance must be a non-negative integer"
+        end
+
+        @remaining = remaining
+        @mutex = Mutex.new
+      end
+
+      def charge!
+        @mutex.synchronize do
+          Thread.handle_interrupt(Object => :never) do
+            raise BudgetExceeded, "agent tool_calls budget exceeded" unless @remaining.positive?
+
+            yield if block_given?
+            @remaining -= 1
+          end
+        end
+      end
+
+      def remaining
+        @mutex.synchronize { @remaining }
+      end
+
+      def [](key)
+        remaining if key == :remaining
+      end
+    end
+  end
+end

data/lib/smith/tool/capture.rb

@@ -3,19 +3,75 @@
 module Smith
   class Tool < RubyLLM::Tool
     module Capture
+      CAPTURE_FAILED = Object.new.freeze
+      private_constant :CAPTURE_FAILED
+
       private
 
+      def ensure_capture_ready!
+        return unless self.class.capture_result && self.class.capture_result_strict?
+
+        capture_collector(true)
+      end
+
       def capture_result_if_configured(kwargs, result)
         block = self.class.capture_result
         return unless block
 
-        collector = self.class.current_tool_result_collector
+        capture_with_policy(block, kwargs, result, self.class.capture_result_strict?)
+      end
+
+      def capture_with_policy(block, kwargs, result, strict)
+        collector = capture_collector(strict)
         return unless collector
 
-        captured = block.call(kwargs, result)
-        collector.call({ tool: name.to_s, captured: captured }) if captured
+        captured = captured_value(block, kwargs, result, strict)
+        return if captured.equal?(CAPTURE_FAILED)
+
+        append_capture(collector, captured, strict)
+      end
+
+      def capture_collector(strict)
+        collector = self.class.current_tool_result_collector
+        return collector unless strict
+        return collector if collector.respond_to?(:call)
+
+        reason = collector.nil? ? :collector_missing : :collector_invalid
+        raise tool_capture_failed(reason)
+      end
+
+      def captured_value(block, kwargs, result, strict)
+        captured = call_capture_block(block, kwargs, result, strict)
+        return captured if captured.equal?(CAPTURE_FAILED)
+        return captured unless captured.nil? && strict
+
+        raise tool_capture_failed(:capture_empty)
+      end
+
+      def call_capture_block(block, kwargs, result, strict)
+        block.call(kwargs, result)
       rescue StandardError => e
-        Smith.config.logger&.warn("[Smith] capture_result failed for #{name}: #{e.message}")
+        capture_failure(e, strict, reason: :capture_block_failed)
+      end
+
+      def append_capture(collector, captured, strict)
+        collector.call({ tool: name.to_s, captured: captured }) if strict || captured
+      rescue StandardError => e
+        capture_failure(e, strict, reason: :collector_failed)
+      end
+
+      def capture_failure(error, strict, reason:)
+        return CAPTURE_FAILED.tap { log_capture_failure(error) } unless strict
+
+        raise tool_capture_failed(reason), cause: error
+      end
+
+      def tool_capture_failed(reason)
+        ToolCaptureFailed.for_runtime(tool_name: name, reason:)
+      end
+
+      def log_capture_failure(error)
+        Smith.config.logger&.warn("[Smith] capture_result failed for #{name}: #{error.message}")
       end
     end
   end

data/lib/smith/tool/capture_configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module CaptureConfiguration
+      def capture_result(strict: false, &block)
+        return @capture_result unless block
+
+        raise ArgumentError, "capture_result strict must be true or false" unless [true, false].include?(strict)
+
+        @capture_result_strict = strict
+        @capture_result = block
+      end
+
+      def capture_result_strict?
+        @capture_result_strict == true
+      end
+    end
+  end
+end

data/lib/smith/tool/chat_execution_context.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module ChatExecutionContext
+      def self.install(chat)
+        return chat unless chat.respond_to?(:tools) && chat.tools.respond_to?(:values)
+        unless chat.respond_to?(:execute_tool, true)
+          raise Error, "unsupported RubyLLM chat execution interface: missing #execute_tool"
+        end
+
+        chat.extend(self) unless chat.singleton_class < self
+        chat.__send__(:install_smith_tool_execution_context)
+        chat
+      end
+
+      private
+
+      def install_smith_tool_execution_context
+        return if defined?(@smith_tool_execution_batches_mutex)
+
+        @smith_tool_execution_batches = {}.compare_by_identity
+        @smith_tool_execution_batches_mutex = Mutex.new
+      end
+
+      def execute_tool(tool_call)
+        batch = execution_batch(tool_call)
+        return super unless batch
+
+        Tool::ScopedContext.around(batch.fetch(:context)) { super }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        record_batch_failure(batch, e) if batch
+        raise
+      end
+
+      def execute_tools_concurrently(tool_calls, ...)
+        batch = execution_batch_context
+        register_execution_batch(tool_calls, batch)
+        super
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise e unless e.is_a?(StandardError)
+
+        fatal_failure = first_failure(batch&.fetch(:fatal_failures))
+        raise fatal_failure if fatal_failure
+
+        capture_failure = first_failure(batch&.fetch(:capture_failures))
+        raise capture_failure if capture_failure
+
+        raise
+      ensure
+        unregister_execution_batch(tool_calls, batch)
+      end
+
+      def execution_batch_context
+        {
+          context: Tool::ScopedContext.capture,
+          capture_failures: Queue.new,
+          fatal_failures: Queue.new
+        }.freeze
+      end
+
+      def register_execution_batch(tool_calls, batch)
+        @smith_tool_execution_batches_mutex.synchronize do
+          tool_calls.each_value do |tool_call|
+            raise Error, "tool call is already active on this chat" if @smith_tool_execution_batches.key?(tool_call)
+
+            @smith_tool_execution_batches[tool_call] = batch
+          end
+        end
+      end
+
+      def unregister_execution_batch(tool_calls, batch)
+        return unless tool_calls && batch
+
+        @smith_tool_execution_batches_mutex.synchronize do
+          tool_calls.each_value do |tool_call|
+            @smith_tool_execution_batches.delete(tool_call) if @smith_tool_execution_batches[tool_call].equal?(batch)
+          end
+        end
+      end
+
+      def execution_batch(tool_call)
+        @smith_tool_execution_batches_mutex.synchronize do
+          @smith_tool_execution_batches[tool_call]
+        end
+      end
+
+      def record_batch_failure(batch, error)
+        if error.is_a?(ToolCaptureFailed)
+          batch.fetch(:capture_failures).push(error)
+        elsif !error.is_a?(StandardError)
+          batch.fetch(:fatal_failures).push(error)
+        end
+      end
+
+      def first_failure(queue)
+        return unless queue
+
+        queue.pop(true)
+      rescue ThreadError
+        nil
+      end
+    end
+  end
+end

data/lib/smith/tool/scoped_context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module ScopedContext
+      CONTEXT_KEYS = {
+        current_guardrails: :smith_tool_guardrails,
+        current_deadline: :smith_tool_deadline,
+        current_ledger: :smith_tool_ledger,
+        current_tool_call_allowance: :smith_tool_call_allowance,
+        current_tool_result_collector: :smith_tool_result_collector,
+        current_invocation_context: :smith_tool_invocation_context
+      }.freeze
+
+      CONTEXT_KEYS.each do |reader, key|
+        define_method(reader) { Thread.current[key] }
+        define_method("#{reader}=") { |value| Thread.current[key] = value }
+      end
+
+      def self.capture
+        CONTEXT_KEYS.to_h { |reader, key| [reader, Thread.current[key]] }.freeze
+      end
+
+      def self.around(values, &block)
+        raise ArgumentError, "block required" unless block
+
+        validate!(values)
+        previous = capture
+        Thread.handle_interrupt(Object => :never) do
+          install(values)
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            install(previous)
+          end
+        end
+      end
+
+      def with_invocation_context(value, &block)
+        raise ArgumentError, "block required" unless block
+
+        previous = current_invocation_context
+        Thread.handle_interrupt(Object => :never) do
+          self.current_invocation_context = value
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            self.current_invocation_context = previous
+          end
+        end
+      end
+
+      def self.install(values)
+        CONTEXT_KEYS.each do |reader, key|
+          Thread.current[key] = values.fetch(reader)
+        end
+      end
+      private_class_method :install
+
+      def self.validate!(values)
+        complete = values.is_a?(Hash) && values.length == CONTEXT_KEYS.length && CONTEXT_KEYS.each_key.all? do |key|
+          values.key?(key)
+        end
+        return if complete
+
+        raise ArgumentError, "tool context must contain the complete scoped context"
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/smith/tool.rb

@@ -4,15 +4,22 @@ require "ruby_llm"
 
 require_relative "tool/capability_builder"
 require_relative "tool/policy"
+require_relative "tool/call_allowance"
 require_relative "tool/budget_enforcement"
+require_relative "tool_capture_failed"
 require_relative "tool/capture"
+require_relative "tool/capture_configuration"
 require_relative "tool/compatibility"
+require_relative "tool/scoped_context"
+require_relative "tool/chat_execution_context"
 
 module Smith
   class Tool < RubyLLM::Tool
     include Policy
     include BudgetEnforcement
     include Capture
+    extend CaptureConfiguration
+    extend ScopedContext
 
     class << self
       # Tool subclasses inherit the parent's compatible_with spec by
@@ -40,46 +47,6 @@ module Smith
 
       attr_reader :compatible_with_spec
 
-      def current_guardrails
-        Thread.current[:smith_tool_guardrails]
-      end
-
-      def current_guardrails=(value)
-        Thread.current[:smith_tool_guardrails] = value
-      end
-
-      def current_deadline
-        Thread.current[:smith_tool_deadline]
-      end
-
-      def current_deadline=(value)
-        Thread.current[:smith_tool_deadline] = value
-      end
-
-      def current_ledger
-        Thread.current[:smith_tool_ledger]
-      end
-
-      def current_ledger=(value)
-        Thread.current[:smith_tool_ledger] = value
-      end
-
-      def current_tool_call_allowance
-        Thread.current[:smith_tool_call_allowance]
-      end
-
-      def current_tool_call_allowance=(value)
-        Thread.current[:smith_tool_call_allowance] = value
-      end
-
-      def current_tool_result_collector
-        Thread.current[:smith_tool_result_collector]
-      end
-
-      def current_tool_result_collector=(value)
-        Thread.current[:smith_tool_result_collector] = value
-      end
-
       def category(value = nil)
         return @category if value.nil?
 
@@ -105,15 +72,10 @@ module Smith
 
         @before_execute = block
       end
-
-      def capture_result(&block)
-        return @capture_result unless block_given?
-
-        @capture_result = block
-      end
     end
 
     def execute(**kwargs)
+      ensure_capture_ready!
       run_before_execute_hook!(kwargs)
       check_tool_deadline!
       check_privilege!(kwargs)

data/lib/smith/tool_capture_failed.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "error"
+
+module Smith
+  class ToolCaptureFailed < Error
+    REASONS = %i[
+      collector_missing collector_invalid capture_empty capture_block_failed collector_failed
+    ].freeze
+    REASONS_BY_NAME = REASONS.to_h { |reason| [reason.to_s.freeze, reason] }.freeze
+    DETAIL_NAMES = %i[tool_name reason].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_TOOL_NAME_BYTES = 256
+    private_constant :REASONS, :REASONS_BY_NAME, :DETAIL_NAMES, :DETAIL_KEYS, :MAX_TOOL_NAME_BYTES
+
+    attr_reader :tool_name, :reason
+
+    def initialize(tool_name:, reason:)
+      @tool_name = normalize_tool_name(tool_name)
+      @reason = normalize_reason(reason)
+      super("strict result capture failed for #{@tool_name}: #{@reason}")
+    end
+
+    def details
+      { tool_name:, reason: }.freeze
+    end
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(tool_name: values.fetch(:tool_name), reason: values.fetch(:reason))
+    end
+
+    def self.for_runtime(tool_name:, reason:)
+      new(tool_name:, reason:)
+    rescue ArgumentError
+      new(tool_name: diagnostic_tool_name(tool_name), reason:)
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "tool capture failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = normalize_detail_name(key)
+        unless DETAIL_NAMES.include?(name)
+          raise ArgumentError, "tool capture failure details contain an unknown attribute"
+        end
+        raise ArgumentError, "tool capture failure details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = value
+      end
+      missing = DETAIL_NAMES - values.keys
+      raise ArgumentError, "tool capture failure details are missing required attributes" if missing.any?
+
+      values
+    end
+
+    def self.normalize_detail_name(key)
+      return key if key.is_a?(Symbol)
+
+      DETAIL_KEYS[key] if key.is_a?(String)
+    end
+
+    def self.diagnostic_tool_name(value)
+      bytes = value.to_s.b
+      return "anonymous_tool" if bytes.empty?
+
+      "tool_#{Digest::SHA256.hexdigest(bytes)}"
+    end
+    private_class_method :normalize_details, :normalize_detail_name, :diagnostic_tool_name
+
+    private
+
+    def normalize_tool_name(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError, "tool capture failure tool name must be a String or Symbol"
+      end
+
+      name = value.to_s
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8" unless name.valid_encoding?
+
+      name = name.encode(Encoding::UTF_8)
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8" unless name.valid_encoding?
+
+      unless name.bytesize.between?(1, MAX_TOOL_NAME_BYTES)
+        raise ArgumentError, "tool capture failure tool name must be a bounded non-empty value"
+      end
+
+      name.dup.freeze
+    rescue EncodingError
+      raise ArgumentError, "tool capture failure tool name must be valid UTF-8"
+    end
+
+    def normalize_reason(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError, "tool capture failure reason must be a String or Symbol"
+      end
+
+      REASONS_BY_NAME.fetch(value.to_s) do
+        raise ArgumentError, "tool capture failure reason is not recognized"
+      end
+    end
+  end
+end

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.6.1"
-  EXECUTION_SEMANTICS_VERSION = "2"
+  VERSION = "0.7.0"
+  EXECUTION_SEMANTICS_VERSION = "3"
 end

data/lib/smith/workflow/composite/branch_failure.rb

@@ -12,21 +12,29 @@ module Smith
           "error_class" => :error_class,
           "error_family" => :error_family,
           "retryable" => :retryable,
-          "kind" => :kind
+          "kind" => :kind,
+          "tool_name" => :tool_name,
+          "reason" => :reason
         }.freeze
-        DETAIL_NAMES = DETAIL_KEYS.values.freeze
-        private_constant :DETAIL_KEYS, :DETAIL_NAMES
+        REQUIRED_DETAIL_NAMES = %i[branch_key error_class error_family retryable kind].freeze
+        OPTIONAL_DETAIL_NAMES = %i[tool_name reason].freeze
+        DETAIL_NAMES = (REQUIRED_DETAIL_NAMES + OPTIONAL_DETAIL_NAMES).freeze
+        private_constant :DETAIL_KEYS, :REQUIRED_DETAIL_NAMES, :OPTIONAL_DETAIL_NAMES, :DETAIL_NAMES
 
-        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :details
+        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :tool_name, :reason, :details
 
         def self.from_details(details)
           values = normalize_details(details)
-          error = Error.new(
+          error_attributes = {
             class_name: values.fetch(:error_class),
             family: values.fetch(:error_family),
             retryable: values.fetch(:retryable),
             kind: values.fetch(:kind)
-          )
+          }
+          OPTIONAL_DETAIL_NAMES.each do |name|
+            error_attributes[name] = values[name] if values.key?(name)
+          end
+          error = Error.new(error_attributes)
           new(branch_key: values.fetch(:branch_key), error:)
         end
 
@@ -42,7 +50,7 @@ module Smith
 
             normalized[name] = value
           end
-          missing = DETAIL_NAMES - normalized.keys
+          missing = REQUIRED_DETAIL_NAMES - normalized.keys
           raise ArgumentError, "composite branch failure details are missing required attributes" if missing.any?
 
           normalized
@@ -60,10 +68,7 @@ module Smith
         def initialize(branch_key:, error:)
           validate_arguments!(branch_key, error)
           @branch_key = branch_key.dup.freeze
-          @error_class = error.class_name.dup.freeze
-          @error_family = error.family.dup.freeze
-          @retryable = error.retryable
-          @kind = error.kind&.dup&.freeze
+          copy_error_attributes(error)
           @details = failure_details
           super("composite branch #{branch_key.inspect} failed")
         end
@@ -76,14 +81,30 @@ module Smith
           raise ArgumentError, "composite branch failure requires typed error evidence" unless error.is_a?(Error)
         end
 
+        def copy_error_attributes(error)
+          @error_class = owned_string(error.class_name)
+          @error_family = owned_string(error.family)
+          @retryable = error.retryable
+          @kind = owned_string(error.kind)
+          @tool_name = owned_string(error.tool_name)
+          @reason = owned_string(error.reason)
+        end
+
+        def owned_string(value)
+          value&.dup&.freeze
+        end
+
         def failure_details
-          {
+          values = {
             branch_key: @branch_key,
             error_class: @error_class,
             error_family: @error_family,
             retryable: @retryable,
             kind: @kind
-          }.freeze
+          }
+          values[:tool_name] = @tool_name if @tool_name
+          values[:reason] = @reason if @reason
+          values.freeze
         end
       end
     end

data/lib/smith/workflow/composite/branch_outcome.rb

@@ -82,6 +82,12 @@ module Smith
           def serializable(values)
             values.merge(error: values[:error]&.to_h, effects: values.fetch(:effects).to_h)
           end
+
+          def legacy_serializable(values)
+            serializable(values).tap do |payload|
+              payload[:error] = payload[:error]&.except(:tool_name, :reason)
+            end
+          end
         end
 
         def initialize(attributes)
@@ -89,8 +95,7 @@ module Smith
           owned[:output] = self.class.send(:normalize_output, owned[:output])
           super(owned)
           validate_shape!
-          expected = PayloadDigest.call(self.class.send(:serializable, to_h.except(:digest)))
-          raise ArgumentError, "composite branch outcome digest does not match" unless digest == expected
+          validate_digest!
         end
 
         def succeeded? = status == :succeeded
@@ -98,6 +103,18 @@ module Smith
 
         private
 
+        def validate_digest!
+          values = to_h.except(:digest)
+          payloads = [self.class.send(:serializable, values)]
+          payloads << self.class.send(:legacy_serializable, values) if legacy_digest_allowed?
+          expected = payloads.map { PayloadDigest.call(_1) }
+          raise ArgumentError, "composite branch outcome digest does not match" unless expected.include?(digest)
+        end
+
+        def legacy_digest_allowed?
+          error.nil? || (error.tool_name.nil? && error.reason.nil?)
+        end
+
         def validate_shape!
           valid = succeeded? ? error.nil? : error && output.nil?
           raise ArgumentError, "composite branch outcome fields do not match status" unless valid

data/lib/smith/workflow/composite/error.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../types"
+require_relative "../../tool_capture_failed"
 require_relative "payload"
 
 module Smith
@@ -8,12 +9,15 @@ module Smith
     module Composite
       class Error < Payload
         FAMILIES = %w[
-          tool_guardrail_failed deterministic_step_failure deadline_exceeded
-          agent_error workflow_error other
+          tool_capture_failed tool_guardrail_failed deterministic_step_failure
+          deadline_exceeded agent_error workflow_error other
         ].freeze
         ALWAYS_RETRYABLE_FAMILIES = %w[deadline_exceeded agent_error].freeze
         CONDITIONALLY_RETRYABLE_FAMILIES = %w[tool_guardrail_failed deterministic_step_failure].freeze
+        OPTIONAL_METADATA = %i[tool_name reason].freeze
+        STRING_METADATA = %i[kind tool_name reason].freeze
         private_constant :ALWAYS_RETRYABLE_FAMILIES, :CONDITIONALLY_RETRYABLE_FAMILIES
+        private_constant :OPTIONAL_METADATA, :STRING_METADATA
         OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
         private_constant :OwnedString
 
@@ -21,17 +25,43 @@ module Smith
         attribute :family, OwnedString.enum(*FAMILIES)
         attribute :retryable, Types::Bool
         attribute? :kind, OwnedString.constrained(min_size: 1, max_size: 128).optional
+        attribute? :tool_name, OwnedString.constrained(min_size: 1, max_size: 256).optional
+        attribute? :reason, OwnedString.constrained(min_size: 1, max_size: 128).optional
+
+        class << self
+          def normalize_attributes(attributes)
+            return super unless attributes.is_a?(Hash)
+
+            super(attributes_with_optional_metadata(attributes))
+          end
+
+          private
+
+          def attributes_with_optional_metadata(attributes)
+            values = {}
+            Hash.instance_method(:each_pair).bind_call(attributes) { |key, value| values[key] = value }
+            OPTIONAL_METADATA.each do |name|
+              values[name] = nil unless values.key?(name) || values.key?(name.to_s)
+            end
+            values
+          end
+        end
 
         def initialize(attributes)
-          owned = self.class.normalize_attributes(attributes)
-          owned[:kind] = owned[:kind].to_s if owned[:kind]
-          super(owned)
+          super(normalize_error_attributes(attributes))
           validate_retryability!
           validate_kind!
+          validate_tool_capture_metadata!
         end
 
         private
 
+        def normalize_error_attributes(attributes)
+          self.class.normalize_attributes(attributes).tap do |normalized|
+            STRING_METADATA.each { |name| normalized[name] = normalized[name].to_s if normalized[name] }
+          end
+        end
+
         def validate_retryability!
           valid = if ALWAYS_RETRYABLE_FAMILIES.include?(family)
                     retryable
@@ -48,6 +78,24 @@ module Smith
 
           raise ArgumentError, "composite error kind is not valid for its family"
         end
+
+        def validate_tool_capture_metadata!
+          valid = if family == "tool_capture_failed"
+                    valid_tool_capture_metadata?
+                  else
+                    tool_name.nil? && reason.nil?
+                  end
+          return if valid
+
+          raise ArgumentError, "composite error tool metadata does not match its family"
+        end
+
+        def valid_tool_capture_metadata?
+          ToolCaptureFailed.from_details(tool_name:, reason:)
+          true
+        rescue ArgumentError
+          false
+        end
       end
     end
   end

data/lib/smith/workflow/composite/error_evidence.rb

@@ -3,6 +3,7 @@
 require "dry-initializer"
 
 require_relative "../../errors"
+require_relative "../../tool_capture_failed"
 require_relative "error"
 
 module Smith
@@ -16,12 +17,14 @@ module Smith
         def self.call(error) = new(error).call
 
         def call
-          Error.new(
+          attributes = {
             class_name: error_class_name,
             family: error_family,
             retryable: retryable_error?,
             kind: error_kind
-          )
+          }
+          attributes.merge!(tool_capture_metadata) if error.is_a?(ToolCaptureFailed)
+          Error.new(attributes)
         end
 
         private
@@ -47,6 +50,7 @@ module Smith
 
         def error_family
           case error
+          when ToolCaptureFailed then "tool_capture_failed"
           when ToolGuardrailFailed then "tool_guardrail_failed"
           when DeterministicStepFailure then "deterministic_step_failure"
           when DeadlineExceeded then "deadline_exceeded"
@@ -55,6 +59,10 @@ module Smith
           else "other"
           end
         end
+
+        def tool_capture_metadata
+          { tool_name: error.tool_name, reason: error.reason.to_s }
+        end
       end
     end
   end

data/lib/smith/workflow/deadline_enforcement.rb

@@ -74,7 +74,7 @@ module Smith
 
       def apply_agent_tool_calls(agent_class)
         agent_tc = agent_class&.budget&.dig(:tool_calls)
-        Tool.current_tool_call_allowance = agent_tc ? { remaining: agent_tc } : nil
+        Tool.current_tool_call_allowance = agent_tc ? Tool::CallAllowance.new(agent_tc) : nil
       end
 
       def clear_agent_tool_calls

data/lib/smith/workflow/fanout_execution.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "branch_env"
-
 module Smith
   class Workflow
     module FanoutExecution
       private
 
+      def fanout_branch_environment(branches, branch_agent_classes, prepared_input)
+        BranchEnv.new(
+          prepared_input:,
+          guardrail_sources: nil,
+          scoped_store: propagate_scoped_artifacts,
+          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
+          deadline: wall_clock_deadline
+        )
+      end
+
       def run_guarded_fanout_step(transition)
         branches = transition.fanout_config.fetch(:branches)
         branch_agent_classes = fanout_agent_classes(transition, branches)
@@ -26,13 +34,7 @@ module Smith
       def execute_fanout_step(transition, branches: nil, branch_agent_classes: nil, prepared_input: nil)
         branches ||= transition.fanout_config.fetch(:branches)
         branch_agent_classes ||= fanout_agent_classes(transition, branches)
-        env = BranchEnv.new(
-          prepared_input: prepared_input,
-          guardrail_sources: nil,
-          scoped_store: propagate_scoped_artifacts,
-          branch_estimates: fanout_branch_estimates(branches, branch_agent_classes),
-          deadline: wall_clock_deadline
-        )
+        env = fanout_branch_environment(branches, branch_agent_classes, prepared_input)
 
         branch_calls = branches.map do |branch_key, agent_name|
           PreparedBranchExecution.instance_method(:prepared_branch).bind_call(
@@ -98,12 +100,11 @@ module Smith
       def fanout_branch_estimates(branches, branch_agent_classes)
         return {} unless @ledger
 
-        branch_count = branches.length
         branches.each_with_object({}) do |(branch_key, _agent_name), map|
           agent_class = branch_agent_classes.fetch(branch_key)
           map[branch_key] = compute_branch_estimates(
             @ledger,
-            branch_count: branch_count,
+            branch_count: branches.length,
             agent_budget: agent_class&.budget
           )
         end

data/lib/smith/workflow/parallel/cancellation_signal.rb

@@ -12,7 +12,7 @@ module Smith
 
         def cancel!(error = nil)
           @mutex.synchronize do
-            @reason ||= error
+            @reason = Parallel.preferred_error([@reason, error])
             @cancelled = true
           end
         end

data/lib/smith/workflow/parallel/root_execution.rb

@@ -73,7 +73,7 @@ module Smith
 
         def resolve(futures)
           fulfilled, values, reasons = Concurrent::Promises.zip(*futures).result
-          raise(@signal.reason || Parallel.preferred_error(reasons)) unless fulfilled
+          raise(Parallel.preferred_error([@signal.reason, *reasons])) unless fulfilled
 
           values
         end

data/lib/smith/workflow/parallel.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
+require_relative "../tool_capture_failed"
 require_relative "parallel/cancellation"
 require_relative "parallel/cancellation_signal"
 require_relative "parallel/execution_context"
@@ -36,7 +38,10 @@ module Smith
 
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
-        errors.find { |error| !error.is_a?(Cancellation) } || errors.first
+        errors.find { |error| !error.is_a?(StandardError) } ||
+          errors.find { |error| error.is_a?(ToolCaptureFailed) } ||
+          errors.find { |error| !error.is_a?(Cancellation) } ||
+          errors.first
       end
     end
   end

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -6,13 +6,20 @@ module Smith
       private
 
       def prepared_branch(implementation, *arguments)
+        tool_context = Tool::ScopedContext.capture
         unless @split_step_active_execution_authorization
-          return proc { |signal| __send__(implementation.name, *arguments, signal) }
+          return proc do |signal|
+            Tool::ScopedContext.around(tool_context) do
+              __send__(implementation.name, *arguments, signal)
+            end
+          end
         end
 
         proc do |signal|
           run = proc { implementation.bind_call(self, *arguments, signal) }
-          PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          Tool::ScopedContext.around(tool_context) do
+            PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          end
         end
       end
 

data/lib/smith/workflow/retry_execution.rb

@@ -24,6 +24,7 @@ module Smith
 
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
+        return false if error.is_a?(ToolCaptureFailed)
 
         classes = config.fetch(:error_classes)
         if classes.any?

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -68,18 +68,27 @@ module Smith
         def composite_branch_environment(execution, input, agent_class, transition)
           branch = execution.branch
           budget = branch.budget.transform_keys(&:to_sym)
-          branch_key = fetch_composite_fanout_branch(transition, branch.key).first unless execution.kind == :parallel
-          estimates = execution.kind == :parallel ? budget : { branch_key => budget }
           BranchEnv.new(
             prepared_input: input.agent_messages,
             guardrail_sources: Tool.current_guardrails,
             scoped_store: propagate_scoped_artifacts,
-            branch_estimates: estimates,
+            branch_estimates: composite_branch_estimates(execution, transition, budget),
             deadline: wall_clock_deadline,
-            agent_class: execution.kind == :parallel ? agent_class : nil
+            agent_class: composite_parallel_agent(execution, agent_class)
           )
         end
 
+        def composite_branch_estimates(execution, transition, budget)
+          return budget if execution.kind == :parallel
+
+          branch_key = fetch_composite_fanout_branch(transition, execution.branch.key).first
+          { branch_key => budget }
+        end
+
+        def composite_parallel_agent(execution, agent_class)
+          agent_class if execution.kind == :parallel
+        end
+
         def composite_branch_ledger(branch)
           return if branch.budget.empty?
 

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -16,6 +16,7 @@ module Smith
         current_ledger
         current_tool_call_allowance
         current_tool_result_collector
+        current_invocation_context
       ].freeze
       THREAD_KEYS = %i[
         smith_call_deadline

data/lib/smith/workflow/transition.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../tool_capture_failed"
+
 module Smith
   class Workflow
     class Transition
@@ -334,6 +336,10 @@ module Smith
 
           raise WorkflowError, "retry_on error classes must inherit from StandardError"
         end
+        if error_classes.any? { |error_class| error_class <= ToolCaptureFailed }
+          message = "retry_on cannot retry Smith::ToolCaptureFailed because the tool outcome may be uncertain"
+          raise WorkflowError, message
+        end
 
         ExponentialBackoff.new(
           attempts:,

data/lib/smith/workflow.rb

@@ -38,6 +38,9 @@ module Smith
     # expose `attr_reader :retryable` only, with no setter, so kwargs
     # MUST flow through `initialize`.
     KNOWN_RECONSTRUCTORS = {
+      "Smith::ToolCaptureFailed" => ->(s) {
+        Smith::ToolCaptureFailed.from_details(s.fetch(:error_details))
+      },
       "Smith::ToolGuardrailFailed" => ->(s) {
         Smith::ToolGuardrailFailed.new(s[:error_message], retryable: s[:error_retryable])
       },
@@ -227,6 +230,7 @@ module Smith
         # so a real DSF doesn't get classified as workflow_error.
         error_family = case err
                        when Smith::DeterministicStepFailure then "deterministic_step_failure"
+                       when Smith::ToolCaptureFailed        then "tool_capture_failed"
                        when Smith::ToolGuardrailFailed      then "tool_guardrail_failed"
                        when Smith::DeadlineExceeded         then "deadline_exceeded"
                        when Smith::AgentError               then "agent_error"
@@ -378,6 +382,8 @@ module Smith
         )
       when "tool_guardrail_failed"
         Smith::ToolGuardrailFailed.new(snap[:error_message], retryable: snap[:error_retryable])
+      when "tool_capture_failed"
+        Smith::ToolCaptureFailed.from_details(snap.fetch(:error_details))
       when "deadline_exceeded" then Smith::DeadlineExceeded.new(snap[:error_message])
       when "agent_error"       then Smith::AgentError.new(snap[:error_message])
       when "workflow_error"    then Smith::WorkflowError.new(snap[:error_message])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Samuel Ralak
@@ -117,16 +117,22 @@ dependencies:
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.17'
 description: Smith is a workflow-first multi-agent orchestration library built on
   RubyLLM. It provides state machine modeling, typed contracts, budget enforcement,
   guardrails, and observability for agent workflows.
@@ -237,10 +243,15 @@ files:
 - lib/smith/tasks/doctor.rake
 - lib/smith/tool.rb
 - lib/smith/tool/budget_enforcement.rb
+- lib/smith/tool/call_allowance.rb
 - lib/smith/tool/capability_builder.rb
 - lib/smith/tool/capture.rb
+- lib/smith/tool/capture_configuration.rb
+- lib/smith/tool/chat_execution_context.rb
 - lib/smith/tool/compatibility.rb
 - lib/smith/tool/policy.rb
+- lib/smith/tool/scoped_context.rb
+- lib/smith/tool_capture_failed.rb
 - lib/smith/tools.rb
 - lib/smith/tools/think.rb
 - lib/smith/tools/url_fetcher.rb