ask-agent 0.40.19 → 0.40.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46ea77e0ac0feca360164604367729e05f15e22212f479c59ad1954da5e5e924
-  data.tar.gz: 5a1e0198d2e4d9faf7831bd1c7f8520a82a01c7fff46a9a94512a60a6d285409
+  metadata.gz: 8119f78526cac8f96b7f6506c1d40e046127dccad46015252e9ea0805e15c677
+  data.tar.gz: be381f8d8fbb4b104ba79ab0a1cece93918c8ef028bfdb4fc24dd6ae49399726
 SHA512:
-  metadata.gz: d195e1e86df0f281de603cdd607d0b2d88bbbc3d07f4c46b5dbb81235fd102d7f4a19781e625b8ddd8c304babb47eaf60fa894c6513b5e944f493b0e4928c74f
-  data.tar.gz: c4289b1c74e4ee05de9ffe2c0c266e46599e49c546b0c22c23ea76258a23e291dd5804e3d5cdd0d514375540fc22d7732a920de1e6d303f7dfde0fcbc04ca883
+  metadata.gz: aee841408cd187f95b2d54f6bbb0820fac09865bf58f1af38680b1847088a8aca7c1a187008e93a98a6cf39941fd65e0690dd78a16b6d07491c6d0ec0573bcf2
+  data.tar.gz: c6b6c736800ae14baa95355f692294da8f428af180c404852a5aa9141905d5bfb776994f59aab21e772f3263e40c3c542b32009cee779f1263ade62c8d095cb5

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## [Unreleased]
+
+
+## [0.40.21] — 2026-09-22
+
+### Added
+
+- **`Ask::Agent::SessionAdapter` — bridges an agent session to
+  `Ask::Session::Host`.** Records user input and per-run snapshots as
+  event-sourced ask-session events, maps agent events (turn, streaming,
+  tool, todo, plan, error) onto session event types with `trace_id` /
+  `causation_id` propagation, and resumes from the latest snapshot
+  (`SessionAdapter.resume`). Resume survives process restarts when the host
+  store is durable (e.g. `Ask::Session::ProviderStore` over
+  `ask-state-providers`). Requires the new runtime dependency
+  `ask-session >= 0.1.0` (the single session store; no second store added).
+  Resume validates the snapshot before restoring, so a malformed snapshot
+  raises `SessionAdapter::Error` instead of leaving the agent half-restored.
+
+### Fixed
+
+- **`Session#turn_count` is now maintained during runs.** The counter was
+  only ever reset at run start (or restored from a checkpoint), never
+  incremented — so `SessionEnd`, audit-log entries, persisted
+  `metadata.turn_count`, and `SessionAdapter` snapshots all recorded `0` for
+  live runs. Turns are now counted on `TurnStart`, matching the loop's own
+  count (`reset: true` scopes it to the run; `reset: false` accumulates).
+
+
+## [0.40.20] — 2026-09-21
+
+### Changed
+
+- **Agent tool execution unified with ask-runtime.** `ToolExecutor` runs
+  tool calls through the runtime's execution contract, exposing the current
+  runtime call and execution context (`Ask.current_runtime_call` /
+  `Ask.current_runtime_context`) while a tool executes, and conforming to
+  the runtime executor contract.
+- Requires `ask-runtime >= 0.1.0`.
+
+
+## [0.40.19] — 2026-09-20
+
+### Added
+
+- **Bundled `agent.build_agents` skill** — teaches building agents with
+  ask-rb (definitions, sessions, tools, configuration, common patterns).
+  Auto-discovered via `Gem.find_files` when ask-skills is present.
+- **`askr skills install` / `askr skills uninstall`** with
+  `--global|--local|--dir`, plus auto-sync of managed skill copies on
+  every CLI invocation.
+
+
+## [0.40.18] — 2026-09-19
+
+### Changed
+
+- **`Agent.new` and `Session.new` unified.** The shared implementation
+  lives in `Session.build_from_definition`; `Agent.new` delegates to it,
+  `Session.new` supports definition lookup, and `Ask.chat` accepts `name:`
+  for definition lookup. The duplicate `build_session_from_definition` and
+  `resolve_definition_tools` helpers were removed from the `Agent` module.
+
+
 ## [0.40.17] — 2026-09-18
 
 ### Added

data/README.md

@@ -102,6 +102,35 @@ under multiple OpenAI-compatible providers). A `provider:` passed to
 `Session.new` or declared in an agent `Definition` always wins over the global
 default.
 
+## Durable sessions (ask-session)
+
+`Ask::Agent::SessionAdapter` bridges a session to an event-sourced
+`Ask::Session::Host`. Every run records the user input, the mapped agent
+events, and an `agent.snapshot`; `SessionAdapter.resume` restores the latest
+snapshot — including after a process restart, as long as the host store is
+durable (for example `Ask::Session::ProviderStore` over
+`ask-state-providers`' SQLite adapter).
+
+```ruby
+require "ask-agent"
+require "ask/session"
+
+host = Ask::Session::Host.new(store: Ask::Session::Store.new)
+
+session = Ask::Agent::Session.new(model: "gpt-4o", id: "chat-1")
+adapter = Ask::Agent::SessionAdapter.create(agent: session, host: host)
+adapter.run("Hello")
+
+# Later (even in a new process, with the same durable store):
+resumed = Ask::Agent::Session.new(model: "gpt-4o", id: "chat-1")
+adapter = Ask::Agent::SessionAdapter.resume(agent: resumed, host: host, session_id: "chat-1")
+adapter.run("Continue where we left off")
+```
+
+`SessionAdapter::Error` is raised when the session record or its latest
+snapshot cannot be found. This requires the `ask-session` gem (a runtime
+dependency of ask-agent).
+
 ## Full documentation
 
 The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.

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

@@ -107,7 +107,10 @@ module Ask
         @turn_id = 0
         @queued_steers = []
         @steer_mutex = Mutex.new
-        on(Events::TurnStart) { @turn_id += 1 }
+        on(Events::TurnStart) do
+          @turn_id += 1
+          @turn_count += 1
+        end
         @created_at = Time.now
         @_no_tools_instructed = false
 
@@ -878,10 +881,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/session_adapter.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ask/session"
+
+module Ask
+  module Agent
+    # Adapter that bridges an Ask::Agent::Session to an Ask::Session::Host.
+    #
+    # Maps agent events to event-sourced ask-session events, persists a
+    # snapshot at the end of each run, and supports resume from the latest
+    # durable snapshot.
+    #
+    #   adapter = SessionAdapter.create(agent: session, host: host)
+    #   result = adapter.run("Hello")
+    #
+    #   restored = SessionAdapter.resume(agent: session, host: host, session_id: id)
+    #   restored.run("Follow up")
+    #
+    class SessionAdapter
+      SNAPSHOT_TYPE = "agent.snapshot"
+
+      # Raised when resume cannot find the ask-session record or its
+      # latest snapshot.
+      class Error < Ask::Agent::Error; end
+
+      attr_reader :agent, :host, :session_id
+
+      def initialize(agent:, host:, session_id: agent.id, metadata: {}, create: false)
+        @agent = agent
+        @host = host
+        @session_id = session_id
+        @current_trace_id = nil
+        @current_turn_id = nil
+        @current_causation_id = nil
+
+        @host.create(id: @session_id, metadata: metadata) if create
+
+        attach_event_handler
+      end
+
+      # Create a new ask-session record and return the adapter.
+      #
+      # @param agent [Ask::Agent::Session] the agent session
+      # @param host [Ask::Session::Host] the session host
+      # @param metadata [Hash] session metadata
+      # @return [SessionAdapter]
+      def self.create(agent:, host:, metadata: {})
+        record = host.create(id: agent.id, metadata: metadata)
+        new(agent: agent, host: host, session_id: record.id, metadata: metadata, create: false)
+      end
+
+      # Attach to an existing ask-session and restore the latest snapshot.
+      #
+      # Contract: Ask::Session::Host#session raises
+      # Ask::Session::NotFoundError for a missing record (it never returns
+      # nil); both missing-session and missing-snapshot failures surface as
+      # SessionAdapter::Error.
+      #
+      # @param agent [Ask::Agent::Session] the agent session (will be populated from snapshot)
+      # @param host [Ask::Session::Host] the session host
+      # @param session_id [String] the ask-session record id
+      # @return [SessionAdapter]
+      # @raise [SessionAdapter::Error] if the session or snapshot is not found
+      def self.resume(agent:, host:, session_id:)
+        begin
+          host.session(session_id)
+        rescue Ask::Session::NotFoundError
+          raise Error, "Session not found: #{session_id.inspect}"
+        end
+
+        events = host.events(session_id)
+        snapshot_event = events.reverse_each.find { |e| e.type == SNAPSHOT_TYPE }
+        raise Error, "No snapshot found for session #{session_id.inspect}" unless snapshot_event
+
+        payload = snapshot_event.payload
+        messages = payload[:messages] || payload["messages"] || []
+
+        # Validate before mutating the agent so a malformed snapshot cannot
+        # leave it half-restored.
+        messages.each do |msg|
+          role = msg.is_a?(Hash) ? (msg[:role] || msg["role"]) : nil
+          raise Error, "Snapshot for session #{session_id.inspect} contains a message without a role" unless role
+        end
+
+        agent.instance_variable_set(:@turn_count, payload[:turn_count] || payload["turn_count"] || 0)
+        agent.chat.reset_messages!
+        messages.each do |msg|
+          agent.chat.add_message(
+            role: (msg[:role] || msg["role"]).to_sym,
+            content: deserialize_content(msg[:content] || msg["content"]),
+            tool_call_id: msg[:tool_call_id] || msg["tool_call_id"],
+            tool_calls: msg[:tool_calls] || msg["tool_calls"]
+          )
+        end
+        agent.instance_variable_set(:@messages, agent.chat.messages.dup)
+
+        new(agent: agent, host: host, session_id: session_id, create: false)
+      end
+
+      # Current trace id for the running trace.
+      # @return [String, nil]
+      def current_trace_id
+        @current_trace_id
+      end
+
+      # Current turn identifier (stable per TurnStart).
+      # @return [Integer, nil]
+      def current_turn_id
+        @current_turn_id
+      end
+
+      # Run the agent and record events in the ask-session.
+      #
+      # @param message [String] the user message
+      # @param trace_id [String, nil] optional trace id (auto-generated if nil)
+      # @param causation_id [String, nil] optional causation id linking to the
+      #   event that caused this run
+      # @param options [Hash] forwarded to agent.run
+      # @return [String] the agent response
+      def run(message, trace_id: nil, causation_id: nil, **options)
+        @current_trace_id = trace_id || "trace_#{SecureRandom.hex(8)}"
+        @current_causation_id = causation_id
+
+        # Record user input as a message event.
+        input_event = @host.send_message(
+          @session_id,
+          content: message.to_s,
+          trace_id: @current_trace_id,
+          causation_id: @current_causation_id
+        )
+        @current_causation_id ||= input_event.trace_id
+
+        begin
+          result = @agent.run(message, **options)
+
+          # Append snapshot for resume.
+          snapshot = build_snapshot
+          @host.append(
+            @session_id,
+            type: SNAPSHOT_TYPE,
+            payload: snapshot,
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+
+          result
+        rescue Ask::Agent::Aborted
+          @host.append(
+            @session_id,
+            type: "turn.aborted",
+            payload: { turn_id: @current_turn_id },
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+          raise
+        rescue => e
+          @host.append(
+            @session_id,
+            type: "turn.failed",
+            payload: { error: e.message, error_class: e.class.name },
+            trace_id: @current_trace_id,
+            causation_id: @current_causation_id
+          )
+          raise
+        ensure
+          @current_turn_id = nil
+          @current_causation_id = nil
+        end
+      end
+
+      # Request agent abort without writing a terminal session event.
+      def abort
+        @agent.abort
+      end
+
+      # Close the ask-session (terminal: :closed).
+      def close
+        @host.close(@session_id)
+      end
+
+      # Abort the ask-session (terminal: :aborted).
+      def abort_session
+        @host.abort(@session_id)
+      end
+
+      private
+
+      def attach_event_handler
+        @agent.on_event do |event|
+          handle_event(event)
+        end
+      end
+
+      def handle_event(event)
+        trace_id = @current_trace_id
+        causation_id = @current_causation_id
+        turn_id = @current_turn_id
+
+        case event
+        when Events::TurnStart
+          @current_turn_id = (@current_turn_id || 0) + 1
+          turn_id = @current_turn_id
+          @host.append(@session_id, type: "turn.started", payload: { turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::TextDelta
+          @host.append(@session_id, type: "model.streaming", payload: { content: event.content, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ThinkingDelta
+          @host.append(@session_id, type: "model.thinking", payload: { content: event.content, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionStart
+          @host.append(@session_id, type: "tool.use", payload: { tool_name: event.name, arguments: event.arguments, tool_call_id: event.id, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionUpdate
+          @host.append(@session_id, type: "tool.delta", payload: { tool_name: event.name, tool_call_id: event.id, partial_result: event.partial_result, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::ToolExecutionEnd
+          @host.append(@session_id, type: "tool.result", payload: { tool_name: event.name, tool_call_id: event.id, result: event.result, is_error: event.is_error, duration_ms: event.duration_ms, turn_id: turn_id }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::TodoUpdated
+          @host.append(@session_id, type: "todos.updated", payload: { todos: event.todos }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanProposed
+          @host.append(@session_id, type: "plan.proposed", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanApproved
+          @host.append(@session_id, type: "plan.approved", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::PlanRejected
+          @host.append(@session_id, type: "plan.rejected", payload: { plan: event.plan }, trace_id: trace_id, causation_id: causation_id)
+
+        when Events::Error
+          @host.append(@session_id, type: "error", payload: { message: event.error, recoverable: event.recoverable }, trace_id: trace_id, causation_id: causation_id)
+        end
+      end
+
+      def build_snapshot
+        {
+          messages: (@agent.messages || []).map(&:to_h),
+          turn_count: @agent.turn_count || 0
+        }
+      end
+
+      def self.deserialize_content(content)
+        content.is_a?(Array) ? content.map { |block| Ask::Content.from_h(block) } : content
+      end
+    end
+  end
+end

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.21"
   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
@@ -215,6 +216,7 @@ require_relative "agent/chat"
 require_relative "agent/telemetry"
 require_relative "agent/tool_abort_controller"
 require_relative "agent/session"
+require_relative "agent/session_adapter"
 require_relative "agent/loop"
 require_relative "agent/reflector"
 require_relative "agent/evaluator"
@@ -258,6 +260,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.21
 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
@@ -107,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: ask-session
+  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: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -202,6 +230,7 @@ files:
 - lib/ask/agent/reflector.rb
 - lib/ask/agent/scheduler.rb
 - lib/ask/agent/session.rb
+- lib/ask/agent/session_adapter.rb
 - lib/ask/agent/stream_transforms/base.rb
 - lib/ask/agent/stream_transforms/extract_json.rb
 - lib/ask/agent/stream_transforms/pipeline.rb