ask-agent 0.40.19 → 0.40.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46ea77e0ac0feca360164604367729e05f15e22212f479c59ad1954da5e5e924
-  data.tar.gz: 5a1e0198d2e4d9faf7831bd1c7f8520a82a01c7fff46a9a94512a60a6d285409
+  metadata.gz: 8ad845b7f0d67966819af4e0f588f47ff44793e874b56c08dd13208dc3334e5d
+  data.tar.gz: 52c5ef1af2a97cb7cb41a7247c19a614e75ca5138f7192ad71ecde7ffdc3eede
 SHA512:
-  metadata.gz: d195e1e86df0f281de603cdd607d0b2d88bbbc3d07f4c46b5dbb81235fd102d7f4a19781e625b8ddd8c304babb47eaf60fa894c6513b5e944f493b0e4928c74f
-  data.tar.gz: c4289b1c74e4ee05de9ffe2c0c266e46599e49c546b0c22c23ea76258a23e291dd5804e3d5cdd0d514375540fc22d7732a920de1e6d303f7dfde0fcbc04ca883
+  metadata.gz: '078e71e0cf4fd80c5d08badd68377eb4b73cf0923f46dc6f065bab94d3106323892bb307acf717ea3640907939e5706645b42986c5d1fc003544801e2fece9e0'
+  data.tar.gz: '068595e1f29705bcda12462c342b49a4a5a2d055c5f5f75c5c24edbe02bd8475a8803e6f7ecebb0fddd782dac84e168db8f877d6fe6e2eda566d2bb000e15f26'

data/lib/ask/agent/chat.rb

@@ -64,7 +64,6 @@ module Ask
         @messages << Ask::Message.new(role: :user, content: merge_attachments(message, attachments)) if has_message || attachments
 
         stream = block_given?
-        tool_defs = @tools.map { |t| Ask::ToolDef.from_tool(t) }
 
         calls_acc = {}
         response_msg = chat_with_retry(stream, calls_acc, &block)

data/lib/ask/agent/loop.rb

@@ -103,7 +103,7 @@ module Ask
           # when the background work completes.
           user_results = tool_executor.execute(
             user_tool_calls, tools, hooks: hooks, event_emitter: event_emitter,
-            session_id: session_id,
+            session_id: session_id, turn: @turn_count,
             result_callback: lambda do |tool_call_id, result|
               tc = user_tool_calls[tool_call_id]
               next unless tc

data/lib/ask/agent/session.rb

@@ -878,10 +878,10 @@ end
       private
 
       def build_audit_log(config)
-          config ||= Ask::Agent.configuration.audit_log
-          return nil unless config
-          Ask::Agent::Policies::AuditLog.new(self, adapter: config)
-        end
+        config ||= Ask::Agent.configuration.audit_log
+        return nil unless config
+        Ask::Agent::Policies::AuditLog.new(self, adapter: config)
+      end
 
       # Build the approval queue + policy when approval is enabled.
       #

data/lib/ask/agent/tool_executor.rb

@@ -3,6 +3,8 @@
 module Ask
   module Agent
     class ToolExecutor
+      include Ask::Runtime::ToolExecutor
+
       CRITICAL_ERROR_CLASSES = %w[
         Ask::Unauthorized
         Ask::Forbidden
@@ -22,23 +24,41 @@ module Ask
 
       attr_writer :telemetry
 
-      def execute(tool_calls, tools, hooks:, event_emitter:, session_id: nil, result_callback: nil)
+      # Public entry point — dispatches between two contracts:
+      #
+      #   Batch API:    execute(tool_calls, tools, hooks:, event_emitter:, ...)
+      #   Runtime API:  execute(tool_call, context:)
+      #
+      # The discriminator is the first argument: a Hash triggers the batch path,
+      # anything else (typically an Ask::Runtime::ToolCall) triggers the runtime path.
+      def execute(tool_calls_or_call, tools_or_context = nil, **rest)
+        if tool_calls_or_call.is_a?(Hash)
+          execute_batch(tool_calls_or_call, tools_or_context, **rest)
+        else
+          ctx = rest.key?(:context) ? rest[:context] : tools_or_context
+          _runtime_execute(tool_calls_or_call, context: ctx)
+        end
+      end
+
+      def execute_batch(tool_calls, tools, hooks:, event_emitter:, session_id: nil, turn: nil, result_callback: nil, runtime_event_sink: nil)
         return [] if tool_calls.empty?
 
         @total_executions = 0
         @session_id = session_id
-        sibling_abort = ToolAbortController.new
+        @turn = turn
+        @last_tools = tools
+        sibling_abort = CallbackAbortController.new
 
         if @parallel
-          execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
+          execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, runtime_event_sink, &result_callback)
         else
-          execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort) do |id, result|
+          execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort, runtime_event_sink) do |id, result|
             result_callback&.call(id, result)
           end
         end
       end
 
-      def execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
+      def execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, runtime_event_sink, &result_callback)
         threads = []
         mutex = Mutex.new
         results = {}
@@ -58,7 +78,7 @@ module Ask
                 next
               end
 
-              result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
+              result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort, runtime_event_sink)
               mutex.synchronize { results[id] = result }
 
               # Stream result back as it completes
@@ -87,12 +107,12 @@ module Ask
         tool_calls.keys.filter_map { |id| results[id]&.merge(tool_call_id: id) }
       end
 
-      def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
+      def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort, runtime_event_sink, &result_callback)
         results = []
         tool_calls.each do |id, tool_call|
           break if sibling_abort.aborted?
 
-          result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
+          result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort, runtime_event_sink)
           results << result.merge(tool_call_id: id)
           result_callback&.call(id, result)
           break if result[:critical_failure]
@@ -103,7 +123,300 @@ module Ask
 
       private
 
-      def execute_single_tool(tool_call, tools, hooks, event_emitter, abort_controller = nil)
+      class CallbackAbortController < ToolAbortController
+        def initialize
+          super
+          @abort_callbacks = []
+        end
+
+        def abort!
+          callbacks_to_run = @mutex.synchronize do
+            was_aborted = @aborted
+            @aborted = true
+            was_aborted ? [] : @abort_callbacks.dup
+          end
+          callbacks_to_run.each(&:call)
+          self
+        end
+
+        def on_abort(&block)
+          raise ArgumentError, "block required" unless block
+
+          already = @mutex.synchronize do
+            if @aborted
+              true
+            else
+              @abort_callbacks << block
+              false
+            end
+          end
+          block.call if already
+          self
+        end
+      end
+
+      def build_runtime_tool_call(tool_call, effective_args: nil)
+        input = begin
+          raw = effective_args || tool_call.arguments
+          parsed = raw.is_a?(String) ? JSON.parse(raw) : raw
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+
+        Ask::Runtime::ToolCall.new(
+          id: tool_call.id,
+          tool_name: tool_call.name,
+          input: input,
+          session_id: @session_id,
+          turn: @turn
+        )
+      end
+
+      def build_runtime_context(abort_controller)
+        canceller = AbortControllerCancellerAdapter.new(abort_controller) if abort_controller
+
+        Ask::Runtime::ExecutionContext.new(
+          session_id: @session_id,
+          turn: @turn,
+          canceller: canceller
+        )
+      end
+
+      class AbortControllerCancellerAdapter
+        def initialize(abort_controller)
+          @abort_controller = abort_controller
+          @callbacks = []
+          @mutex = Mutex.new
+
+          if abort_controller.respond_to?(:on_abort)
+            abort_controller.on_abort { fire_callbacks }
+          end
+        end
+
+        def cancelled?
+          @abort_controller.aborted?
+        end
+
+        def cancel
+          @abort_controller.abort!
+          fire_callbacks
+          self
+        end
+
+        def on_cancel(&block)
+          raise ArgumentError, "block required" unless block
+
+          already = @mutex.synchronize do
+            if @abort_controller.aborted?
+              true
+            else
+              @callbacks << block
+              false
+            end
+          end
+          block.call if already
+          self
+        end
+
+        def inspect
+          "#<Ask::Agent::ToolExecutor::AbortControllerCancellerAdapter cancelled=#{cancelled?}>"
+        end
+
+        private
+
+        def fire_callbacks
+          callbacks_to_run = @mutex.synchronize do
+            snapshot = @callbacks.dup
+            @callbacks.clear
+            snapshot
+          end
+          callbacks_to_run.each(&:call)
+        end
+      end
+
+      # ----------------------------------------------------------------
+      # Runtime contract: execute a single tool call and return ToolResult
+      # ----------------------------------------------------------------
+
+      # Implements Ask::Runtime::ToolExecutor#execute.
+      #
+      # This is the single-call entry point for the runtime contract.
+      # It does NOT run hooks, emit agent events, or manage batches — it is
+      # the pure runtime execution path that the batch API delegates to
+      # internally (via execute_single_tool).
+      #
+      # @param tool_call [Ask::Runtime::ToolCall] the tool-call request
+      # @param context [Ask::Runtime::ExecutionContext, nil] execution context
+      # @return [Ask::Runtime::ToolResult] the normalized result
+      def _runtime_execute(tool_call, context: nil)
+        context ||= Ask::Runtime::ExecutionContext.new
+        started_at = Time.now
+        started_call = tool_call.with(state: :running, started_at: started_at)
+        emit_runtime_event(context.event_sink, :tool_started,
+          Ask::Runtime::Events::ToolStarted.new(
+            tool_call: started_call, execution_context: context, timestamp: started_at
+          ))
+
+        return runtime_cancel(started_call, context, started_at, "Cancelled before execution") if context.cancelled?
+
+        tool = find_tool_for_runtime(tool_call.tool_name)
+
+        result = if tool
+          invoke_tool_with_retry(tool, tool_call.id, tool_call.input, context.canceller)
+        else
+          Ask::Runtime::ToolResult.failure("Tool not found: #{tool_call.tool_name}")
+        end
+
+        return runtime_cancel(started_call, context, started_at, "Cancelled during execution") if context.cancelled?
+
+        runtime_finish(started_call, context, result, started_at)
+      end
+
+      def runtime_finish(started_call, context, result, started_at)
+        finished_at = Time.now
+        duration = finished_at - started_at
+        result = Ask::Runtime::ToolResult.new(
+          result: result.result, outcome: result.outcome, duration: duration
+        )
+        state = if result.timeout?
+          :timed_out
+        elsif result.failure?
+          :failed
+        else
+          :completed
+        end
+        finished_call = started_call.with(
+          state: state,
+          tool_result: result,
+          error: result.error_message,
+          finished_at: finished_at
+        )
+        emit_runtime_terminal_event(
+          context.event_sink, state,
+          tool_call: finished_call, tool_result: result,
+          execution_context: context, timestamp: finished_at, duration: duration
+        )
+        result
+      end
+
+      def runtime_cancel(started_call, context, started_at, reason)
+        finished_at = Time.now
+        duration = finished_at - started_at
+        result = Ask::Runtime::ToolResult.new(
+          result: Ask::Result.failure(reason), outcome: :cancelled, duration: duration
+        )
+        finished_call = started_call.with(
+          state: :cancelled,
+          tool_result: result,
+          error: result.error_message,
+          finished_at: finished_at
+        )
+        emit_runtime_terminal_event(
+          context.event_sink, :cancelled,
+          tool_call: finished_call, tool_result: result,
+          execution_context: context, timestamp: finished_at, duration: duration
+        )
+        result
+      end
+
+      # Find a tool by name for the runtime contract path.
+      # Uses the last-known tools list from execute_batch, or nil.
+      def find_tool_for_runtime(tool_name)
+        @last_tools&.find { |t| t.name == tool_name }
+      end
+
+      # ----------------------------------------------------------------
+      # Shared execution core — used by both batch and runtime paths
+      # ----------------------------------------------------------------
+
+      # Invoke a tool with retry logic, returning an Ask::Runtime::ToolResult.
+      #
+      # This is the single source of truth for tool invocation. It wraps
+      # try_call and handles retryable errors, producing a normalized
+      # ToolResult that both the batch and runtime paths consume.
+      def invoke_tool_with_retry(tool, tool_call_id, args, abort_controller = nil)
+        @max_retries.times do |attempt|
+          if abort_cancelled?(abort_controller)
+            return Ask::Runtime::ToolResult.cancelled("Aborted")
+          end
+
+          result = try_call(tool, args, abort_controller)
+          return result unless result.failure? && retryable_error?(result)
+
+          sleep((2 ** attempt) * 0.5 + rand(0.0..0.5))
+        end
+
+        if abort_cancelled?(abort_controller)
+          return Ask::Runtime::ToolResult.cancelled("Aborted")
+        end
+        try_call(tool, args)
+      end
+
+      # Check if the abort controller signals cancellation.
+      # Handles both ToolAbortController (aborted?) and Canceller (cancelled?).
+      def abort_cancelled?(controller)
+        return false unless controller
+        return true if controller.respond_to?(:aborted?) && controller.aborted?
+        return true if controller.respond_to?(:cancelled?) && controller.cancelled?
+        false
+      end
+
+      # Invoke a tool once, returning an Ask::Runtime::ToolResult.
+      #
+      # Normalizes all tool return types (Ask::Result, Hash, String, pending)
+      # into the canonical ToolResult shape.  Preserves halted metadata for
+      # the batch path to consume.
+      def try_call(tool, args, abort_controller = nil)
+        raw = tool.call(args, abort_controller: abort_controller)
+
+        if raw.respond_to?(:pending?) && raw.pending?
+          return Ask::Runtime::ToolResult.success(data: raw)
+        end
+
+        if raw.respond_to?(:ok?)
+          if raw.ok?
+            # Preserve the Ask::Result as the ToolResult's result object
+            # so downstream code can access metadata (e.g. halted flag).
+            Ask::Runtime::ToolResult.new(result: raw, outcome: :success)
+          else
+            Ask::Runtime::ToolResult.failure(extract_error_message(raw))
+          end
+        else
+          Ask::Runtime::ToolResult.success(data: raw)
+        end
+      rescue => e
+        Ask::Runtime::ToolResult.failure("#{e.class}: #{e.message}")
+      end
+
+      # Extract the output payload from an Ask::Result, unwrapping the wrapper
+      # so ToolResult.output carries the actual data.
+      def unwrap_output(result)
+        result.respond_to?(:output) ? result.output : result
+      end
+
+      # Extract a string error message from a failed Ask::Result.
+      def extract_error_message(result)
+        msg = result.respond_to?(:error_message) ? result.error_message : nil
+        msg || result.to_s
+      end
+
+      # Check if a ToolResult represents a retryable error.
+      def retryable_error?(tool_result)
+        return false unless tool_result.failure?
+
+        error_msg = tool_result.error_message.to_s
+        # Extract the class name from "ClassName: message" format.
+        # Split on ": " (colon-space) to avoid breaking on :: namespaces.
+        error_class_name = error_msg.split(": ").first
+        retryable_error_name?(error_class_name)
+      end
+
+      # ----------------------------------------------------------------
+      # Batch path: execute_single_tool (unchanged public behavior)
+      # ----------------------------------------------------------------
+
+      def execute_single_tool(tool_call, tools, hooks, event_emitter, abort_controller = nil, runtime_event_sink = nil)
         return aborted_result(tool_call) if abort_controller&.aborted?
 
         tool = tools.find { |t| t.name == tool_call.name }
@@ -139,53 +452,101 @@ module Ask
           name: tool_call.name, arguments: args, id: tool_call.id
         ))
 
+        runtime_call = build_runtime_tool_call(tool_call, effective_args: args)
+        # Expose the pending runtime call before execution starts so tools
+        # can observe the full pending → running → terminal lifecycle.
+        Thread.current[:ask_agent_runtime_call] = runtime_call
+        runtime_context = build_runtime_context(abort_controller)
+
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        start_timestamp = Time.now
         Thread.current[:ask_agent_tool_call_id] = tool_call.id
-        result = begin
-          execute_with_retry(tool, tool_call.id, args, abort_controller)
+        Thread.current[:ask_agent_runtime_context] = runtime_context
+
+        # Transition to :running once execution is active and observable by tools.
+        running_call = runtime_call.with(state: :running, started_at: start_timestamp)
+        Thread.current[:ask_agent_runtime_call] = running_call
+
+        # Emit runtime ToolStarted event (one per tool call).
+        emit_runtime_event(runtime_event_sink, :tool_started,
+          Ask::Runtime::Events::ToolStarted.new(
+            tool_call: running_call, execution_context: runtime_context, timestamp: start_timestamp
+          ))
+
+        # Shared execution core — invoke tool with retry, get ToolResult.
+        tool_result = begin
+          invoke_tool_with_retry(tool, tool_call.id, args, abort_controller)
         rescue Exception => e
-          { result: e.message, is_error: true, error: e.class.name }
-        ensure
-          Thread.current[:ask_agent_tool_call_id] = nil
+          Ask::Runtime::ToolResult.failure("#{e.class}: #{e.message}")
         end
-        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).to_i
+
+        # Classify into terminal state + legacy agent result hash.
+        terminal_state, legacy_result = classify_tool_result(tool_result, abort_controller)
+
+        # Transition runtime call to terminal state and attach ToolResult
+        # BEFORE clearing thread locals so tools can observe the full lifecycle
+        # including the unwrapped ToolResult.output.
+        finished_call = running_call.with(
+          state: terminal_state,
+          tool_result: tool_result,
+          error: tool_result.error_message,
+          finished_at: Time.now
+        )
+        Thread.current[:ask_agent_runtime_call] = finished_call
+
+        # Clear all thread locals — even on errors — so no stale or
+        # terminal runtime objects remain in Thread.current after cleanup.
+        Thread.current[:ask_agent_tool_call_id] = nil
+        Thread.current[:ask_agent_runtime_call] = nil
+        Thread.current[:ask_agent_runtime_context] = nil
+
+        duration_secs = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        duration_ms = (duration_secs * 1000).to_i
         @total_executions += 1
 
+        # Emit runtime terminal event (exactly one per tool call).
+        emit_runtime_terminal_event(
+          runtime_event_sink, terminal_state,
+          tool_call: finished_call, tool_result: tool_result,
+          execution_context: runtime_context, timestamp: Time.now,
+          duration: duration_secs
+        )
+
         return aborted_result(tool_call) if abort_controller&.aborted?
 
-        hook_result = hooks.run_after_tool(tool_call, result, {})
+        hook_result = hooks.run_after_tool(tool_call, legacy_result, {})
         if hook_result&.dig(:action) == :transform
-          result = hook_result[:result]
+          legacy_result = hook_result[:result]
         end
 
-        is_error = result[:is_error] == true
-        critical = is_error && critical_error?(result[:error])
-        halted = result[:halted] == true
+        is_error = legacy_result[:is_error] == true
+        critical = is_error && critical_error?(legacy_result[:error])
+        halted = legacy_result[:halted] == true
 
         if halted
           abort_controller&.abort!
         end
 
         if is_error && @telemetry
-          @telemetry.log(:tool_error, session_id: @session_id, tool_name: tool_call.name, error_class: result[:error] || "RuntimeError", error_message: result[:result].to_s)
+          @telemetry.log(:tool_error, session_id: @session_id, tool_name: tool_call.name, error_class: legacy_result[:error] || "RuntimeError", error_message: legacy_result[:result].to_s)
         end
 
         event_emitter.emit(Events::ToolExecutionEnd.new(
-          name: tool_call.name, id: tool_call.id, result: result, is_error: is_error, duration_ms: duration
+          name: tool_call.name, id: tool_call.id, result: legacy_result, is_error: is_error, duration_ms: duration_ms
         ))
 
         message = if is_error
-          tool_result = result[:result]
-          error_msg = if tool_result.is_a?(Hash) && tool_result[:error]
-            tool_result[:error].to_s
-          elsif tool_result.is_a?(String)
-            tool_result
+          inner = legacy_result[:result]
+          error_msg = if inner.is_a?(Hash) && inner[:error]
+            inner[:error].to_s
+          elsif inner.is_a?(String)
+            inner
           else
-            result.to_s
+            legacy_result.to_s
           end
           "Tool #{tool_call.name} error: #{error_msg}"
         else
-          result[:result].to_s
+          legacy_result[:result].to_s
         end
 
         # Large outputs never enter the transcript: store the full message
@@ -200,8 +561,8 @@ module Ask
         # Collect tool-produced deliverables (metadata[:artifact]) into the
         # session's artifact store. Best-effort: a malformed artifact is
         # noted in the message, never a tool failure.
-        if @artifact_store && result[:result].respond_to?(:metadata) &&
-           (artifact = result[:result].metadata[:artifact])
+        if @artifact_store && legacy_result[:result].respond_to?(:metadata) &&
+           (artifact = legacy_result[:result].metadata[:artifact])
           begin
             attrs = symbolize_artifact(artifact)
             @artifact_store.store(@session_id, **attrs)
@@ -210,8 +571,8 @@ module Ask
           end
         end
 
-        inner = result[:result]
-        status = if result[:is_error] == true
+        inner = legacy_result[:result]
+        status = if legacy_result[:is_error] == true
           "error"
         elsif inner.respond_to?(:pending?) && inner.pending?
           "pending"
@@ -223,42 +584,33 @@ module Ask
           tool_name: tool_call.name,
           message: message,
           status: status,
-          result: result,
+          result: legacy_result,
           critical_failure: critical,
           halted: halted
         }
       end
 
-      def execute_with_retry(tool, tool_call_id, args, abort_controller = nil)
-        @max_retries.times do |attempt|
-          return { result: nil, is_error: true, error: "Aborted" } if abort_controller&.aborted?
-
-          result = try_call(tool, args, abort_controller)
-          return result unless result[:is_error] && retryable_error_name?(result[:error])
+      def emit_runtime_event(sink, event_type, event)
+        return unless sink
 
-          sleep((2 ** attempt) * 0.5 + rand(0.0..0.5))
-        end
+        sink.emit(event_type, event: event)
+      end
 
-        return { result: nil, is_error: true, error: "Aborted" } if abort_controller&.aborted?
-        try_call(tool, args)
+      def emit_runtime_terminal_event(sink, terminal_state, **attrs)
+        return unless sink
+
+        event_class = case terminal_state
+                      when :completed then Ask::Runtime::Events::ToolCompleted
+                      when :failed then Ask::Runtime::Events::ToolFailed
+                      when :cancelled then Ask::Runtime::Events::ToolCancelled
+                      when :timed_out then Ask::Runtime::Events::ToolTimedOut
+                      else return
+                      end
+        sink.emit(terminal_event_type(terminal_state), event: event_class.new(**attrs))
       end
 
-      def try_call(tool, args, abort_controller = nil)
-        result = tool.call(args, abort_controller: abort_controller)
-        is_error = if result.respond_to?(:pending?) && result.pending?
-          false  # async tool: work continues in the background
-        elsif result.respond_to?(:ok?)
-          !result.ok?
-        else
-          false
-        end
-        hash = { result: result, is_error: is_error }
-        if result.respond_to?(:metadata) && result.metadata&.dig(:halted)
-          hash[:halted] = true
-        end
-        hash
-      rescue => e
-        { result: e.message, is_error: true, error: e.class.name }
+      def terminal_event_type(state)
+        "tool_#{state}".to_sym
       end
 
       # Store a large tool message in the output store and return a short
@@ -307,6 +659,103 @@ module Ask
           aborted: true
         }
       end
+
+      # Map a ToolResult to a runtime terminal state and a legacy agent
+      # result hash.  Returns [terminal_state_symbol, legacy_hash].
+      #
+      # This is the shared classification logic: the runtime path uses the
+      # ToolResult directly; the batch path wraps it in the agent's hash
+      # format for backward compatibility.
+      def classify_tool_result(tool_result, abort_controller)
+        if abort_controller&.aborted?
+          return [:cancelled, { result: "Aborted by sibling failure", is_error: true, error: "Aborted" }]
+        end
+
+        halted = tool_halted?(tool_result)
+
+        case tool_result.outcome
+        when :cancelled
+          [:cancelled, { result: tool_result.error_message, is_error: true, error: "Aborted" }]
+        when :failure
+          error_class = extract_error_class(tool_result.error_message)
+          [:failed, { result: tool_result.error_message, is_error: true, error: error_class }]
+        when :timeout
+          [:timed_out, { result: tool_result.error_message, is_error: true, error: "Timeout" }]
+        when :success
+          if tool_result.output.respond_to?(:pending?) && tool_result.output.pending?
+            [:completed, { result: tool_result.output, is_error: false, halted: halted }]
+          else
+            # Preserve the original Ask::Result in the legacy hash for
+            # backward compatibility — tools that return Ask::Result get
+            # their result object in [:result][:result].
+            legacy_inner = if tool_result.result.is_a?(Ask::Result)
+              tool_result.result
+            else
+              tool_result.output
+            end
+            [:completed, { result: legacy_inner, is_error: false, halted: halted }]
+          end
+        else
+          [:completed, { result: tool_result.output, is_error: false, halted: halted }]
+        end
+      end
+
+      # Detect if a tool result carries halted metadata.
+      # Checks the underlying Ask::Result (ToolResult.result) for halted
+      # metadata, since that's where tools set it via Ask::Result.ok(..., metadata: { halted: true }).
+      def tool_halted?(tool_result)
+        return false unless tool_result.success?
+
+        inner = tool_result.result
+        inner.respond_to?(:metadata) && inner.metadata&.dig(:halted) == true
+      end
+
+      # Extract the error class name from a tool failure message.
+      # Messages from try_call are formatted as "ClassName: message".
+      # Split on ": " (colon-space) to avoid breaking on :: namespaces.
+      def extract_error_class(error_message)
+        return "Error" unless error_message
+        error_message.split(": ").first || "Error"
+      end
+
+      # Legacy classify_result for backward compatibility with code that
+      # passes raw agent result hashes.  Delegates to the shared
+      # classify_tool_result after wrapping the hash in a ToolResult.
+      def classify_result(result, abort_controller)
+        tool_result = if abort_controller&.aborted?
+          Ask::Runtime::ToolResult.cancelled("Aborted by sibling failure")
+        elsif result[:is_error] == true
+          error_msg = extract_error_from_hash(result)
+          Ask::Runtime::ToolResult.failure(error_msg)
+        else
+          inner = result[:result]
+          if inner.respond_to?(:pending?) && inner.pending?
+            Ask::Runtime::ToolResult.success(data: inner)
+          else
+            data = if inner.is_a?(Ask::Result)
+              inner.output
+            elsif inner.is_a?(Hash) && inner.key?(:result)
+              inner[:result]
+            else
+              inner
+            end
+            Ask::Runtime::ToolResult.success(data: data)
+          end
+        end
+
+        classify_tool_result(tool_result, abort_controller)
+      end
+
+      def extract_error_from_hash(result)
+        inner = result[:result]
+        if inner.is_a?(Hash) && inner[:error]
+          inner[:error].to_s
+        elsif inner.is_a?(String)
+          inner
+        else
+          result.to_s
+        end
+      end
     end
   end
 end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.40.19"
+    VERSION = "0.40.20"
   end
 end

data/lib/ask/agent.rb

@@ -8,6 +8,7 @@ require "ask/skills"
 require "ask-llm-providers"
 require "ask-tools"
 require "ask-state-providers"
+require "ask-runtime"
 
 module Ask
   module Agent
@@ -258,6 +259,20 @@ module Ask
       def current_tool_call_id
         Thread.current[:ask_agent_tool_call_id]
       end
+
+      # @return [Ask::Runtime::ToolCall, nil] the runtime tool call for the
+      #   currently executing tool on this thread. Available only during tool
+      #   execution inside ToolExecutor.
+      def current_runtime_call
+        Thread.current[:ask_agent_runtime_call]
+      end
+
+      # @return [Ask::Runtime::ExecutionContext, nil] the runtime execution
+      #   context for the currently executing tool on this thread. Available
+      #   only during tool execution inside ToolExecutor.
+      def current_runtime_context
+        Thread.current[:ask_agent_runtime_context]
+      end
     end
   end
 end

data/lib/ask-agent.rb

@@ -2,4 +2,5 @@
 
 require "ask-llm-providers"
 require "ask-tools"
+require "ask-runtime"
 require "ask/agent"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.40.19
+  version: 0.40.20
 platform: ruby
 authors:
 - Kaka Ruto
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: ask-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: ask-state-providers
   requirement: !ruby/object:Gem::Requirement