turnkit 0.4.2 → 0.6.0

data/lib/turnkit/specialists.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "pathname"
+require "uri"
+
+module TurnKit
+  # Small, composable factories for common specialist agents. The returned
+  # objects are ordinary Agent and Tool instances and may be further configured
+  # or subclassed by applications.
+  module Specialists
+    ORACLE_INSTRUCTIONS = <<~TEXT.strip
+      Act as an expert advisor. Inspect the supplied read-only sources before
+      drawing conclusions. Complete the requested analysis, distinguish facts
+      from recommendations, state material uncertainty, and return the full
+      result. Never claim to have changed application state.
+    TEXT
+
+    LIBRARIAN_INSTRUCTIONS = <<~TEXT.strip
+      Research the configured external GitHub repository using the repository
+      tool. Read the relevant files and history, not merely repository titles.
+      Return a complete answer with source URLs for factual claims and identify
+      the ref or comparison used. Do not imply that repository state was changed.
+    TEXT
+
+    PAINTER_INSTRUCTIONS = <<~TEXT.strip
+      Create or edit the requested image with the image tool. Translate the task
+      into a precise visual prompt, pass all relevant reference images and mask,
+      and return the generated image artifact. Generation is permitted only when
+      the application authorization gate allows the tool call.
+    TEXT
+
+    class ReadOnlyTool < Tool
+      recovery :replay_safe
+      def self.read_only? = true
+      def read_only? = true
+    end
+
+    class ReadFile < ReadOnlyTool
+      tool_name "read_file"
+      description "Read a UTF-8 text file beneath the configured root."
+      parameter :path, :string, required: true, description: "Path relative to the configured root."
+
+      def initialize(root:, max_bytes: 100_000)
+        @root = Pathname(root).expand_path.realpath
+        @max_bytes = Integer(max_bytes)
+      end
+
+      def call(path:, context:)
+        target = confined_path(path)
+        raise ToolError, "not a file: #{path}" unless target.file?
+        raise ToolError, "file exceeds #{@max_bytes} bytes" if target.size > @max_bytes
+
+        { "path" => target.relative_path_from(@root).to_s, "content" => target.binread.force_encoding(Encoding::UTF_8) }
+      rescue Errno::ENOENT, Errno::EACCES, ArgumentError => error
+        raise ToolError, "cannot read #{path}: #{error.message}"
+      end
+
+      private
+
+      def confined_path(path)
+        candidate = @root.join(path.to_s).realpath
+        prefix = @root.to_s + File::SEPARATOR
+        raise ToolError, "path is outside configured root" unless candidate == @root || candidate.to_s.start_with?(prefix)
+
+        candidate
+      end
+    end
+
+    class GitHubRepository < ReadOnlyTool
+      tool_name "github_repository_read"
+      description "Read files, repository metadata, commits, diffs, and issues from one configured GitHub repository."
+      parameter :operation, :enum, required: true, enum: %w[repository file history diff issues issue comments]
+      parameter :path, :string, description: "Repository-relative file path (file operation)."
+      parameter :ref, :string, description: "Branch, tag, or commit for file/history operations."
+      parameter :base, :string, description: "Base ref for a diff."
+      parameter :head, :string, description: "Head ref for a diff."
+      parameter :number, :integer, description: "Issue number."
+      parameter :state, :enum, enum: %w[open closed all], default: "open"
+      parameter :page, :integer, default: 1
+
+      API_HOST = "api.github.com"
+
+      def initialize(repository:, client: nil, token: ENV["GITHUB_TOKEN"])
+        @repository = normalize_repository(repository)
+        @client = client || method(:http_get)
+        @token = token.to_s
+      end
+
+      def call(operation:, path: nil, ref: nil, base: nil, head: nil, number: nil, state: "open", page: 1, context:)
+        endpoint, query = endpoint_for(operation, path: path, ref: ref, base: base, head: head,
+          number: number, state: state, page: page)
+        uri = URI::HTTPS.build(host: API_HOST, path: "/repos/#{@repository}#{endpoint.empty? ? '' : '/' + endpoint}", query: URI.encode_www_form(query))
+        response = @client.call(uri: uri, headers: headers)
+        status, body = unpack_response(response)
+        raise ToolError, "GitHub API returned HTTP #{status}" unless status.between?(200, 299)
+
+        data = JSON.parse(body)
+        if operation == "file" && data.is_a?(Hash) && data["encoding"] == "base64"
+          data = data.merge("content" => Base64.decode64(data.fetch("content")))
+        end
+        { "repository" => @repository, "operation" => operation, "source" => source_url(operation, data, uri), "data" => data }
+      rescue JSON::ParserError => error
+        raise ToolError, "invalid GitHub API response: #{error.message}"
+      end
+
+      private
+
+      def normalize_repository(value)
+        repository = value.to_s
+        raise ArgumentError, "repository must be owner/name" unless repository.match?(%r{\A[A-Za-z0-9][A-Za-z0-9_-]*/[A-Za-z0-9_.-]+\z}) && !%w[. ..].include?(repository.split('/').last)
+
+        repository
+      end
+
+      def endpoint_for(operation, path:, ref:, base:, head:, number:, state:, page:)
+        case operation
+        when "repository" then [ "", {} ]
+        when "file"
+          raise ToolValidationError, "path is required for file" if path.to_s.empty?
+          raise ToolValidationError, "invalid repository path" if path.to_s.split("/").include?("..") || path.to_s.start_with?("/")
+          [ "contents/#{path.to_s.split('/').map { |part| escape_segment(part) }.join('/')}", compact_query(ref: ref) ]
+        when "history" then [ "commits", compact_query(sha: ref, path: path, page: page, per_page: 30) ]
+        when "diff"
+          raise ToolValidationError, "base and head are required for diff" if base.to_s.empty? || head.to_s.empty?
+          [ "compare/#{escape_segment(base)}...#{escape_segment(head)}", {} ]
+        when "issues" then [ "issues", compact_query(state: state, page: page, per_page: 30) ]
+        when "issue"
+          raise ToolValidationError, "number is required for issue" unless number
+          [ "issues/#{Integer(number)}", {} ]
+        when "comments"
+          raise ToolValidationError, "positive issue number is required" unless number && number.positive?
+          [ "issues/#{number}/comments", compact_query(page: page, per_page: 30) ]
+        else raise ToolValidationError, "unknown operation: #{operation}"
+        end
+      end
+
+      def escape_segment(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+      def compact_query(**values) = values.reject { |_key, value| value.nil? || value.to_s.empty? }
+
+      def headers
+        result = { "Accept" => "application/vnd.github+json", "User-Agent" => "TurnKit" }
+        result["Authorization"] = "Bearer #{@token}" unless @token.empty?
+        result
+      end
+
+      def http_get(uri:, headers:)
+        raise ToolError, "unsafe GitHub API endpoint" unless uri.is_a?(URI::HTTPS) && uri.host == API_HOST && uri.port == 443
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 45) { |http| http.get(uri.request_uri, headers) }
+        # Redirects are deliberately not followed, preventing credentials from
+        # being forwarded to a different endpoint.
+        [ response.code.to_i, response.body.to_s ]
+      end
+
+      def unpack_response(response)
+        return [ Integer(response[0]), response[1].to_s ] if response.is_a?(Array) && response.length == 2
+        return [ Integer(response.code), response.body.to_s ] if response.respond_to?(:code) && response.respond_to?(:body)
+
+        raise ToolError, "GitHub client must return [status, body] or an HTTP response"
+      end
+
+      def source_url(operation, data, uri)
+        return data["html_url"] if data.is_a?(Hash) && data["html_url"].to_s.start_with?("https://github.com/")
+        return data.first["html_url"] if data.is_a?(Array) && data.first.is_a?(Hash) && data.first["html_url"].to_s.start_with?("https://github.com/")
+
+        uri.to_s
+      end
+    end
+
+    class PaintImage < ImageTool
+      tool_name "paint_image"
+      description "Generate or edit an image after application authorization."
+      parameter :prompt, :string, required: true
+      parameter :reference_images, :array, default: [], items: :string
+      parameter :mask, :string
+      terminal! { |result| JSON.generate(result) }
+
+      def initialize(model:, authorization:, provider: nil, size: nil, params: {}, max_reference_images: nil)
+        raise ArgumentError, "authorization must be callable" unless authorization.respond_to?(:call)
+        @image_model, @authorization, @provider, @size = model, authorization, provider, size
+        @params, @max_reference_images = params, max_reference_images
+      end
+
+      def call(prompt:, reference_images: [], mask: nil, context:)
+        references = Array(reference_images)
+        if @max_reference_images && references.length > Integer(@max_reference_images)
+          raise ToolValidationError, "reference_images exceeds configured limit of #{@max_reference_images}"
+        end
+        request = { prompt: prompt, model: @image_model, provider: @provider, size: @size,
+          input_images: references, mask: mask, params: @params }
+        raise ToolError, "image generation was not authorized" unless @authorization.call(request.dup, context: context) == true
+
+        image = context.turn.paint(request.delete(:prompt), **request, metadata: { "specialist" => "painter" })
+        message = context.turn.conversation.messages.reverse.find(&:image?)
+        { "conversation_id" => context.turn.conversation.id, "image_message_id" => message.id,
+          "image" => image.to_h.reject { |key, _| key == "data" } }
+      end
+    end
+
+    module_function
+
+    def oracle(model:, tools: nil, root: Dir.pwd, client: nil, instructions: nil, **agent_options)
+      require_model!(model)
+      configured = tools.nil? ? [ ReadFile.new(root: root) ] : Array(tools)
+      validate_read_only!(configured + skill_tools(agent_options))
+      raise ArgumentError, "read-only specialists cannot delegate to unchecked subagents" if Array(agent_options[:sub_agents]).any?
+      Agent.new(name: "oracle", description: "Read-only expert analysis and advice.", model: model,
+        tools: configured, client: client, instructions: combine(ORACLE_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def librarian(repository:, model:, client: nil, github_client: nil, token: ENV["GITHUB_TOKEN"], tools: [], instructions: nil, **agent_options)
+      require_model!(model)
+      repository_tool = GitHubRepository.new(repository: repository, client: github_client, token: token)
+      validate_read_only!(Array(tools) + skill_tools(agent_options))
+      raise ArgumentError, "read-only specialists cannot delegate to unchecked subagents" if Array(agent_options[:sub_agents]).any?
+      Agent.new(name: "librarian", description: "Source-backed research in an external GitHub repository.", model: model,
+        tools: [ repository_tool, *Array(tools) ], client: client,
+        instructions: combine(LIBRARIAN_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def painter(model:, image_model:, authorization:, client: nil, tools: [], instructions: nil, provider: nil, size: nil,
+      params: {}, max_reference_images: nil, **agent_options)
+      require_model!(model)
+      require_model!(image_model)
+      image_tool = PaintImage.new(model: image_model, authorization: authorization, provider: provider, size: size,
+        params: params, max_reference_images: max_reference_images)
+      Agent.new(name: "painter", description: "Authorized image generation and editing.", model: model,
+        tools: [ image_tool, *Array(tools) ], client: client,
+        instructions: combine(PAINTER_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def skill_tools(options)
+      (Array(options[:skills]) + Array(options[:available_skills])).flat_map(&:tools)
+    end
+    private_class_method :skill_tools
+
+    def validate_read_only!(tools)
+      invalid = tools.reject { |tool| tool.respond_to?(:read_only?) && tool.read_only? == true }
+      raise ArgumentError, "read-only specialist tools must explicitly report read_only? == true" if invalid.any?
+    end
+    private_class_method :validate_read_only!
+
+    def require_model!(model)
+      raise ArgumentError, "model is required" if model.nil? || model.to_s.empty?
+    end
+    private_class_method :require_model!
+
+    def combine(base, extra) = [ base, extra.to_s.strip ].reject(&:empty?).join("\n\n")
+    private_class_method :combine
+  end
+end

data/lib/turnkit/store.rb

@@ -2,6 +2,9 @@
 
 module TurnKit
   class Store
+    def atomic(_conversation_id, &) = raise(NotImplementedError)
+    def atomic_graph(&) = atomic(nil, &)
+
     def create_conversation(_attributes) = raise(NotImplementedError)
     def load_conversation(_id) = raise(NotImplementedError)
 
@@ -17,12 +20,49 @@ module TurnKit
     # is not in `from`), so concurrent workers cannot both claim a turn.
     def claim_turn(_id, from: "pending", to: "running", **_attributes) = raise(NotImplementedError)
     def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil) = raise(NotImplementedError)
+    # Public inventory. Maintenance uses the explicitly bounded active scope.
+    def list_submitted_turns(limit: nil) = raise(NotImplementedError)
+    def list_actionable_turns(limit:) = raise(NotImplementedError)
+    def list_stale_inline_turns(before:, limit:) = raise(NotImplementedError)
+
+    # Stores may optimize these continuation queries without loading history.
+    def busy_conversation?(id, include_pending: true)
+      list_turns(conversation_id: id).any? { |row| %w[running waiting].include?(row["status"]) || (include_pending && row["submitted_at"] && row["status"] == "pending") }
+    end
+
+    def next_delivery_trigger(id)
+      consumed = list_turns(conversation_id: id).reject { |row| row["status"] == "pending" && !row["submitted_at"] }.map { |row| row["context_message_sequence"] }.max.to_i
+      list_messages(id).select { |row| row.dig("metadata", "delivery_id") && row["sequence"] > consumed }.last
+    end
+
+    def create_delivery(_attributes) = raise(NotImplementedError)
+    def load_delivery(_id) = raise(NotImplementedError)
+    def update_delivery(_id, _attributes) = raise(NotImplementedError)
+    def list_deliveries(source_conversation_id: nil, destination_conversation_id: nil, pending: false, limit: nil) = raise(NotImplementedError)
+
+    def create_wait(turn_id:, target_turn_id:) = raise(NotImplementedError)
+    def list_waits(turn_id: nil, target_turn_id: nil) = raise(NotImplementedError)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)
     def load_tool_execution(_id) = raise(NotImplementedError)
-    def update_tool_execution(_id, _attributes) = raise(NotImplementedError)
+    # claim_tool_execution mirrors claim_turn: an atomic compare-and-set on
+    # status, so a tool result recorded by a live worker and a reconciler
+    # marking the execution interrupted cannot overwrite each other.
+    def claim_tool_execution(_id, from: "running", to: "completed", **_attributes) = raise(NotImplementedError)
     def list_tool_executions(turn_id:) = raise(NotImplementedError)
 
-    def find_stale_turns(before:) = []
+    # Inline abandoned work is fenced and left stale for application-directed
+    # continuation. Submitted work is resumed by Background.reconcile instead.
+    def reconcile_stale_turns(before:)
+      list_stale_inline_turns(before: before, limit: TurnKit.maintenance_batch_size).filter_map do |record|
+        atomic(Background.root_conversation(self, record)) do
+          current = load_turn(record.fetch("id"))
+          anchor = current["heartbeat_at"] || current["started_at"] || current["created_at"]
+          next if current["submitted_at"] || !%w[pending running].include?(current["status"]) || anchor >= before
+
+          update_turn(current.fetch("id"), status: "stale", claim_token: nil, completed_at: Clock.now)
+        end
+      end
+    end
   end
 end

data/lib/turnkit/sub_agent_tool.rb

@@ -17,17 +17,20 @@ module TurnKit
       end
     end
 
-    def call(task:, context:)
-      sub_agent = self.class.agent
+    def self.build_child(task:, context:)
+      sub_agent = agent
       parent_turn = context.turn
       lineage = {
         "parent_conversation_id" => parent_turn.conversation.id,
         "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => context.execution.id
+        "parent_tool_execution_id" => context.execution.id,
+        "principal" => context.principal
       }
-      conversation = sub_agent.conversation(metadata: lineage)
+      store = parent_turn.store
+      record = store.create_conversation("agent_name" => sub_agent.name, "model" => sub_agent.effective_model, "metadata" => lineage)
+      conversation = Conversation.new(agent: sub_agent, record: record, store: store, model: sub_agent.effective_model, metadata: lineage)
       trigger = conversation.say(task, metadata: lineage)
-      child = conversation.run!(
+      conversation.build_turn(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
         parent_turn: parent_turn,
@@ -35,10 +38,23 @@ module TurnKit
         depth: parent_turn.depth + 1,
         model: sub_agent.effective_model,
         agent: sub_agent,
+        principal: context.principal,
         on_event: parent_turn.agent.effective_on_event
       )
-      error = child.store.load_turn(child.id)["error"] if child.failed?
-      { "conversation_id" => conversation.id, "turn_id" => child.id, "status" => child.status, "result" => child.output_text, "output_data" => child.output_data, "error" => error }.compact
+    end
+
+    def self.result(record)
+      { "conversation_id" => record.fetch("conversation_id"), "turn_id" => record.fetch("id"),
+        "status" => record.fetch("status"), "result" => record["output_text"].to_s,
+        "output_data" => record["output_data"], "error" => record["error"] }.compact
+    end
+
+    def call(task:, context:)
+      Authorization.authorize!(:launch_agent, principal: context.principal, turn: context.turn,
+        agent: self.class.agent, arguments: { "task" => task })
+      child = self.class.build_child(task: task, context: context)
+      child.run!
+      SubAgentTool.result(child.store.load_turn(child.id))
     end
   end
 end

data/lib/turnkit/system_prompt.rb

@@ -7,7 +7,7 @@ module TurnKit
     PROMPT_MODES = %i[full minimal task none].freeze
     MODE_SECTIONS = {
       full: DEFAULT_SECTIONS,
-      minimal: %i[agent sub_agent instructions behavior tools environment],
+      minimal: %i[agent sub_agent instructions behavior loaded_skills available_skills tools environment],
       task: DEFAULT_SECTIONS,
       none: []
     }.freeze
@@ -181,7 +181,7 @@ module TurnKit
     end
 
     def tools_section
-      tools = agent.effective_tools
+      tools = agent.effective_tools(turn: turn)
 
       if tools.empty?
         tagged("tools_available", "(none)\n\nNo tools are available for this turn.")
@@ -197,9 +197,7 @@ module TurnKit
     end
 
     def subject_section
-      return nil unless conversation.subject&.respond_to?(:to_prompt)
-
-      value = conversation.subject.to_prompt.to_s.strip
+      value = conversation.subject_prompt.strip
       return nil if value.empty?
 
       untrusted_section(
@@ -211,9 +209,11 @@ module TurnKit
     end
 
     def live_context_section
-      contributions = Array(TurnKit.context_contributors).filter_map do |contributor|
+      contributors = agent.context_contributors
+      contributions = contributors.filter_map do |contributor|
         normalize_context_contribution(contributor.call(prompt_build_context))
       end
+      contributions.unshift(normalize_context_contribution(name: "run_context", content: JSON.generate(turn.context), trusted: false)) unless turn.context.empty?
       return nil if contributions.empty?
 
       body = contributions.map do |contribution|
@@ -280,7 +280,7 @@ module TurnKit
         "stable_chars" => stable.length,
         "dynamic_chars" => dynamic.length,
         "sections" => sections.map(&:to_s),
-        "tool_count" => agent.effective_tools.length
+        "tool_count" => agent.effective_tools(turn: turn).length
       }
     end
 

data/lib/turnkit/tool.rb

@@ -54,6 +54,17 @@ module TurnKit
         @ends_turn || false
       end
 
+      # :unknown is the safe default for external effects. :replay_safe means
+      # the application/tool honors ToolContext#idempotency_key on retries.
+      def recovery(value = nil)
+        if value
+          value = value.to_sym
+          raise ArgumentError, "recovery must be :unknown or :replay_safe" unless %i[unknown replay_safe].include?(value)
+          @recovery = value
+        end
+        @recovery || (superclass.respond_to?(:recovery) ? superclass.recovery : :unknown)
+      end
+
       def completion_message(result)
         case @completion_message
         when nil

data/lib/turnkit/tool_runner.rb

@@ -7,14 +7,22 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
+      waiting = false
       tool_calls.each_with_index do |tool_call, index|
-        execution = run(tool_call)
+        # Fan out a contiguous group of subagents, but never reorder ordinary
+        # tools across it or execute past a terminal tool.
+        return :waiting if waiting && !subagent?(tool_for(tool_call.name))
+        execution = run(tool_call, defer_result: waiting)
+        if execution == :waiting
+          waiting = true
+          next
+        end
         if execution.completed? && tool_for(tool_call.name)&.ends_turn?
           skip_remaining(tool_calls.drop(index + 1), terminal: tool_call)
           return execution
         end
       end
-      nil
+      waiting ? :waiting : nil
     end
 
     def completion_message(execution)
@@ -25,11 +33,30 @@ module TurnKit
     private
       attr_reader :turn
 
-      def run(tool_call)
-        execution = ToolExecution.new(create_execution(tool_call))
-        heartbeat!
-
+      def run(tool_call, defer_result: false)
+        @defer_result = defer_result
         tool = tool_for(tool_call.name)
+        existing = turn.store.list_tool_executions(turn_id: turn.id).find { |row| row["tool_call_id"] == tool_call.id }
+        if existing && !%w[pending running].include?(existing["status"])
+          execution = ToolExecution.new(existing)
+          append_result_once(execution, tool_call, execution.result || execution.error, error: !execution.completed? && !execution.cancelled?)
+          return execution
+        end
+
+        denied = nil
+        execution = turn.store.atomic do
+          execution = ToolExecution.new(existing || create_execution(tool_call))
+          unless existing
+            begin
+              turn.execution_budget(excluding: execution.id).count_tool_execution!(tool_call.name)
+            rescue BudgetError => error
+              denied = error
+              finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+            end
+          end
+          execution
+        end
+        raise denied if denied
 
         unless tool
           return finish_error(execution, tool_call, "unknown tool: #{tool_call.name}")
@@ -39,20 +66,33 @@ module TurnKit
           return finish_error(execution, tool_call, tool_call.arguments_error)
         end
 
-        begin
-          turn.budget.count_tool_execution!(tool_call.name)
-        rescue BudgetError => error
-          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
-          raise
+        if execution.status == "pending" && !subagent?(tool) && ![WaitTool, LaunchAgentTool, SendMessageTool].include?(tool)
+          claimed = turn.store.claim_tool_execution(execution.id, from: "pending", to: "running", started_at: Clock.now)
+          raise LostClaim, "tool execution claim was revoked" unless claimed
+          execution = ToolExecution.new(claimed)
         end
 
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
-          normalize_payload(call_tool(tool, tool_call.arguments, context: context))
+          Authorization.authorize!(:tool, principal: context.principal, turn: turn, tool: tool, arguments: tool_call.arguments)
+          # Observe cancellation/reconciliation immediately before crossing the
+          # external-effect boundary. Calls already sent cannot be recalled.
+          turn.store.atomic { true }
+          if turn.background? && subagent?(tool)
+            return delegate(tool, tool_call, context)
+          end
+          value = call_tool(tool, tool_call.arguments, context: context)
+          return :waiting if value == :waiting && tool == WaitTool
+          normalize_payload(value)
+        rescue LostClaim
+          raise
         rescue BudgetError => error
           finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
           raise
+        rescue AuthorizationError => error
+          return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "authorization_denied" => true })
         rescue StandardError => error
+          raise if turn.background? && !error.is_a?(ToolError)
           return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
         end
         finish_success(execution, tool_call, payload)
@@ -63,7 +103,7 @@ module TurnKit
           "turn_id" => turn.id,
           "tool_call_id" => tool_call.id,
           "tool_name" => tool_call.name,
-          "status" => "running",
+          "status" => turn.background? && (subagent?(tool_for(tool_call.name)) || [WaitTool, LaunchAgentTool, SendMessageTool].include?(tool_for(tool_call.name))) ? "pending" : "running",
           "arguments" => tool_call.arguments,
           "started_at" => Clock.now
         )
@@ -71,9 +111,12 @@ module TurnKit
 
       def finish_success(execution, tool_call, payload)
         json = payload.to_json
-        attrs = turn.store.update_tool_execution(execution.id, "status" => "completed", "result" => payload, "completed_at" => Clock.now)
-        append_result(execution, tool_call, payload, json: json, error: false)
-        heartbeat!
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "completed", result: payload, completed_at: Clock.now)
+          append_result_once(execution, tool_call, payload) if row
+          row
+        end
+        return superseded_execution(execution) unless attrs
         turn.emit("tool_call.completed", id: tool_call.id, name: tool_call.name, result_chars: json.length)
         ToolExecution.new(attrs)
       end
@@ -81,18 +124,30 @@ module TurnKit
       def finish_error(execution, tool_call, message, details: nil)
         error = { "message" => message.to_s, "details" => details }.compact
         json = error.to_json
-        attrs = turn.store.update_tool_execution(execution.id, "status" => "failed", "error" => error, "completed_at" => Clock.now)
-        append_result(execution, tool_call, error, json: json, error: true)
-        heartbeat!
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "failed", error: error, completed_at: Clock.now)
+          append_result_once(execution, tool_call, error, error: true) if row
+          row
+        end
+        return superseded_execution(execution) unless attrs
         turn.emit("tool_call.failed", id: tool_call.id, name: tool_call.name, error: error, result_chars: json.length)
         ToolExecution.new(attrs)
       end
 
-      def append_result(execution, tool_call, payload, json: payload.to_json, error: false)
+      # The execution was reconciled (interrupted) while the tool ran; a
+      # synthetic result message already exists, so the late result is dropped.
+      def superseded_execution(execution)
+        ToolExecution.new(turn.store.load_tool_execution(execution.id))
+      end
+
+      def append_result_once(execution, tool_call, payload, error: false)
+        return if @defer_result
+        return if turn.store.list_messages(turn.conversation.id).any? { |row| row["tool_execution_id"] == execution.id }
+
         message = turn.conversation.append_message(
           role: "tool",
           kind: "tool_result",
-          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => json, "error" => error } ],
+          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => payload.to_json, "error" => error } ],
           turn_id: turn.id,
           tool_execution_id: execution.id,
           metadata: { "tool_name" => tool_call.name }
@@ -102,20 +157,45 @@ module TurnKit
 
       def skip_remaining(calls, terminal:)
         calls.each do |call|
-          payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
-          execution = ToolExecution.new(create_execution(call))
-          attrs = turn.store.update_tool_execution(execution.id, "status" => "cancelled", "result" => payload, "completed_at" => Clock.now)
-          append_result(ToolExecution.new(attrs), call, payload)
-          turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          turn.store.atomic do
+            next if turn.store.list_tool_executions(turn_id: turn.id).any? { |row| row["tool_call_id"] == call.id }
+            payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
+            execution = ToolExecution.new(create_execution(call))
+            attrs = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "cancelled", result: payload, completed_at: Clock.now)
+            append_result_once(ToolExecution.new(attrs), call, payload)
+            turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          end
         end
       end
 
-      def heartbeat!
-        turn.send(:heartbeat!)
+      def subagent?(tool)
+        tool.is_a?(Class) && tool < SubAgentTool
+      end
+
+      def delegate(tool, call, context)
+        arguments = tool.validate_arguments(call.arguments)
+        Authorization.authorize!(:launch_agent, principal: context.principal, turn: turn, agent: tool.agent, arguments: arguments)
+        TurnKit.resolve_agent(tool.agent.name)
+        child = turn.store.atomic_graph do
+          turn.store.atomic(Background.root_conversation(turn.store, turn.store.load_turn(turn.id))) do
+            row = turn.store.list_turns(root_turn_id: turn.root_turn_id).find { |candidate| candidate["parent_tool_execution_id"] == context.execution.id }
+            unless row
+              built = tool.build_child(task: arguments.fetch("task"), context: context)
+              row = turn.store.update_turn(built.id, submitted_at: Clock.now)
+            end
+            Background.wait(turn, [row.fetch("id")])
+            row
+          end
+        end
+        unless Background::TERMINAL.include?(child["status"])
+          Background.enqueue(child.fetch("id")) if child["status"] == "pending"
+          return :waiting
+        end
+        finish_success(context.execution, call, SubAgentTool.result(child))
       end
 
       def tool_for(name)
-        turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
+        turn.agent.effective_tools(turn: turn).find { |tool| tool.tool_name == name.to_s }
       end
 
       def call_tool(tool, arguments, context:)