turnkit 0.4.1 → 0.4.2

data/lib/turnkit/agent.rb

@@ -2,26 +2,46 @@
 
 module TurnKit
   class Agent
+    ORCHESTRATOR_PREAMBLE = <<~TEXT.strip
+      You are an autonomous task orchestrator. Navigate from the application
+      request to a final output without asking the user follow-up questions.
+
+      Use the available tools to gather context, inspect sources, take actions,
+      persist outputs, and verify work. Use loaded skills as reusable workflow
+      patterns. Iterate when work needs missing context, critique, revision, or
+      verification.
+
+      When multiple independent items need the same kind of fetch or read, and
+      an available batch tool can handle them in one call, prefer the batch tool
+      over repeated one-item tool calls.
+
+      Stop when the task is complete, when the available context and tools are
+      sufficient for the best possible answer, or when further iteration would
+      not materially improve the result. Respect runtime, cost, and iteration
+      limits.
+    TEXT
+
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
     attr_reader :client, :store, :max_iterations, :timeout, :max_spend, :max_depth, :max_tool_executions, :max_tool_executions_by_name
     attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction, :output_schema, :input_schema, :on_event
     attr_reader :output_policy, :output_policy_mode, :output_policy_model, :output_retries
 
-    def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
+    def initialize(name:, description: "", model: nil, instructions: "", orchestrator: false, tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
       max_iterations: nil, timeout: nil, max_spend: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil,
       output_schema: nil, input_schema: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, output_retries: 0, on_event: nil)
       @name = name.to_s
       @description = description.to_s
       @model = model
-      @instructions = instructions.to_s
+      @orchestrator = orchestrator ? true : false
+      @instructions = compose_instructions(instructions)
       @tools = Array(tools)
       @skills = Array(skills)
       @available_skills = Array(available_skills)
       @sub_agents = Array(sub_agents)
       @system_prompt = system_prompt
       @prompt_sections = prompt_sections
-      @prompt_mode = prompt_mode&.to_sym
+      @prompt_mode = prompt_mode&.to_sym || (:task if @orchestrator)
       @client = client
       @store = store
       @max_iterations = max_iterations
@@ -69,8 +89,11 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
-      task = task || prompt
+    def orchestrator?
+      @orchestrator
+    end
+
+    def run(task, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
       raise ArgumentError, "task is required" if task.to_s.empty?
       SchemaCheck.validate!(input, input_schema, error_class: InputError, label: "input") if input_schema
 
@@ -151,16 +174,19 @@ module TurnKit
       end
     end
 
-    def build_budget(root_started_at: Clock.now)
-      Budget.new(
+    def budget_limits
+      {
         max_iterations: max_iterations || TurnKit.max_iterations,
         timeout: timeout || TurnKit.timeout,
         max_depth: max_depth || TurnKit.max_depth,
         max_tool_executions: max_tool_executions || TurnKit.max_tool_executions,
         max_tool_executions_by_name: max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
-        max_spend: max_spend || TurnKit.max_spend,
-        root_started_at: root_started_at
-      )
+        max_spend: max_spend || TurnKit.max_spend
+      }
+    end
+
+    def build_budget(root_started_at: Clock.now)
+      Budget.new(**budget_limits, root_started_at: root_started_at)
     end
 
     def instructions_with_skills
@@ -170,6 +196,13 @@ module TurnKit
     end
 
     private
+      def compose_instructions(instructions)
+        parts = []
+        parts << ORCHESTRATOR_PREAMBLE if @orchestrator
+        parts << instructions.to_s.strip unless instructions.to_s.strip.empty?
+        parts.join("\n\n")
+      end
+
       def validate_tools!
         effective_tools.each do |tool|
           next if tool.is_a?(Class) && tool < Tool

data/lib/turnkit/budget.rb

@@ -29,7 +29,7 @@ module TurnKit
 
     def seed!(turns:, tool_executions:)
       @mutex.synchronize do
-        @iterations = Array(turns).sum { |turn| (turn["options"] || {})["iterations"].to_i }
+        @iterations = Array(turns).sum { |turn| Turn.iterations_for(turn) }
         completed = Array(tool_executions).select { |execution| %w[completed failed].include?(execution["status"]) && !execution.dig("error", "details", "budget_denied") }
         @tool_executions = completed.length
         completed.each { |execution| @tool_executions_by_name[execution.fetch("tool_name").to_s] += 1 }

data/lib/turnkit/client.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 module TurnKit
+  # The adapter contract. TurnKit calls clients with the full keyword
+  # signatures below. Custom adapters should subclass TurnKit::Client (or
+  # accept the same keywords) and must not execute tools themselves; TurnKit
+  # runs tools and persists their results.
   class Client
     def validate!(model:)
       true
     end
 
-    def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
+    def chat(model:, messages:, tools:, instructions:, dynamic_instructions: nil, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
       raise NotImplementedError
     end
 

data/lib/turnkit/compaction.rb

@@ -3,19 +3,19 @@
 module TurnKit
   module Compaction
     DEFAULTS = {
-      "enabled" => true,
-      "threshold" => 0.75,
-      "context_limit" => 128_000,
-      "reserved_tokens" => 20_000,
-      "head_messages" => 0,
-      "tail_messages" => 12,
-      "tail_tokens" => 8_000,
-      "summary_ratio" => 0.20,
-      "min_summary_tokens" => 1_000,
-      "max_summary_tokens" => 12_000,
-      "tool_output_max_chars" => 2_000,
-      "model" => nil,
-      "client" => nil
+      enabled: true,
+      threshold: 0.75,
+      context_limit: 128_000,
+      reserved_tokens: 20_000,
+      head_messages: 0,
+      tail_messages: 12,
+      tail_tokens: 8_000,
+      summary_ratio: 0.20,
+      min_summary_tokens: 1_000,
+      max_summary_tokens: 12_000,
+      tool_output_max_chars: 2_000,
+      model: nil,
+      client: nil
     }.freeze
 
     KNOWN_KEYS = DEFAULTS.keys.freeze
@@ -92,7 +92,7 @@ module TurnKit
     module_function
 
     def enabled_for?(agent, overrides = {})
-      policy_for(agent, overrides)["enabled"]
+      policy_for(agent, overrides)[:enabled]
     end
 
     def policy_for(agent, overrides = {})
@@ -100,9 +100,9 @@ module TurnKit
       local = normalize_config(agent.compaction)
       override = normalize_config(overrides)
 
-      return DEFAULTS.merge("enabled" => false) if global == false
-      return DEFAULTS.merge("enabled" => false) if local == false
-      return DEFAULTS.merge("enabled" => false) if override == false
+      return DEFAULTS.merge(enabled: false) if global == false
+      return DEFAULTS.merge(enabled: false) if local == false
+      return DEFAULTS.merge(enabled: false) if override == false
 
       DEFAULTS.merge(global || {}).merge(local || {}).merge(override || {})
     end
@@ -112,7 +112,7 @@ module TurnKit
 
       force = turn.compact == true if force.nil?
       policy = policy_for(turn.agent)
-      return unless policy["enabled"]
+      return unless policy[:enabled]
 
       messages = project(turn.conversation.messages_for_turn(turn))
       return unless force || over_threshold?(messages, policy)
@@ -127,7 +127,7 @@ module TurnKit
 
     def compact!(conversation, agent:, turn: nil, focus: nil, auto: false, overrides: {}, force: true)
       policy = policy_for(agent, overrides)
-      raise CompactionError, "compaction is disabled" unless policy["enabled"]
+      raise CompactionError, "compaction is disabled" unless policy[:enabled]
 
       messages = turn ? conversation.messages_for_turn(turn) : conversation.messages
       projected = project(messages)
@@ -135,14 +135,14 @@ module TurnKit
       return nil if selected.nil? && auto
       raise CompactionError, "not enough messages to compact" unless selected
 
-      selected_tokens = estimate_messages_tokens(selected.fetch("middle"))
+      selected_tokens = estimate_messages_tokens(selected.fetch(:middle))
       return nil if auto && !force && !over_threshold?(projected, policy)
 
       summary = generate_summary(
         agent: agent,
         policy: policy,
-        messages: selected.fetch("middle"),
-        previous_summary: selected["previous_summary"]&.text,
+        messages: selected.fetch(:middle),
+        previous_summary: selected[:previous_summary]&.text,
         focus: focus,
         target_tokens: summary_budget(selected_tokens, policy),
         fallback_model: turn&.model || conversation.model || agent.effective_model,
@@ -209,25 +209,25 @@ module TurnKit
     end
 
     def summary_budget(input_tokens, policy)
-      budget = (input_tokens.to_i * policy["summary_ratio"].to_f).ceil
-      budget = [ budget, policy["min_summary_tokens"].to_i ].max
-      [ budget, policy["max_summary_tokens"].to_i ].min
+      budget = (input_tokens.to_i * policy[:summary_ratio].to_f).ceil
+      budget = [ budget, policy[:min_summary_tokens].to_i ].max
+      [ budget, policy[:max_summary_tokens].to_i ].min
     end
 
     def over_threshold?(messages, policy)
-      usable = [ policy["context_limit"].to_i - policy["reserved_tokens"].to_i, 1 ].max
-      estimate_messages_tokens(messages) >= (usable * policy["threshold"].to_f)
+      usable = [ policy[:context_limit].to_i - policy[:reserved_tokens].to_i, 1 ].max
+      estimate_messages_tokens(messages) >= (usable * policy[:threshold].to_f)
     end
 
     def select_messages(messages, policy)
       rows = Array(messages)
-      return nil if rows.length <= policy["head_messages"].to_i + 1
+      return nil if rows.length <= policy[:head_messages].to_i + 1
 
       previous_summary = rows.reverse.find(&:context_summary?)
       candidates = rows.reject(&:context_summary?)
-      return nil if candidates.length <= policy["head_messages"].to_i + 1
+      return nil if candidates.length <= policy[:head_messages].to_i + 1
 
-      head_count = policy["head_messages"].to_i
+      head_count = policy[:head_messages].to_i
       tail_start = tail_start_index(candidates, policy)
       tail_start = [ tail_start, head_count ].max
       tail_start = expand_tail_start_for_tool_pairs(candidates, tail_start)
@@ -242,11 +242,11 @@ module TurnKit
       end
 
       {
-        "middle" => middle,
-        "previous_summary" => previous_summary,
-        "replaces_from_sequence" => from_sequence,
-        "replaces_through_sequence" => through_sequence,
-        "tail_start_sequence" => candidates[tail_start]&.sequence
+        middle: middle,
+        previous_summary: previous_summary,
+        replaces_from_sequence: from_sequence,
+        replaces_through_sequence: through_sequence,
+        tail_start_sequence: candidates[tail_start]&.sequence
       }
     end
 
@@ -290,7 +290,7 @@ module TurnKit
       when false
         false
       when Hash
-        attrs = value.transform_keys(&:to_s)
+        attrs = value.transform_keys(&:to_sym)
         unknown = attrs.keys - KNOWN_KEYS
         raise ConfigError, "unknown compaction options: #{unknown.join(", ")}" if unknown.any?
 
@@ -323,8 +323,8 @@ module TurnKit
     end
 
     def tail_start_index(messages, policy)
-      max_messages = policy["tail_messages"].to_i
-      max_tokens = policy["tail_tokens"].to_i
+      max_messages = policy[:tail_messages].to_i
+      max_tokens = policy[:tail_tokens].to_i
       count = 0
       tokens = 0
       index = messages.length
@@ -357,8 +357,8 @@ module TurnKit
     end
 
     def generate_summary(agent:, policy:, messages:, previous_summary:, focus:, target_tokens:, fallback_model:, conversation_id:, turn_id:, turn: nil)
-      client = policy["client"] || agent.effective_client
-      model = policy["model"] || fallback_model
+      client = policy[:client] || agent.effective_client
+      model = policy[:model] || fallback_model
       safe_messages = messages.map { |message| sanitize_message(message, policy) }
       prompt = build_prompt(previous_summary: previous_summary, focus: focus, target_tokens: target_tokens)
       attrs = {
@@ -369,7 +369,7 @@ module TurnKit
         metadata: { compaction: true, conversation_id: conversation_id, turn_id: turn_id }
       }
       result = if turn
-        turn.internal_model_call(**attrs, purpose: "compaction", client: policy["client"])
+        turn.internal_model_call(**attrs, purpose: "compaction", client: policy[:client])
       else
         client.validate!(model: model)
         client.chat(**attrs)
@@ -383,7 +383,7 @@ module TurnKit
     def sanitize_message(message, policy)
       return message unless message.tool_result?
 
-      max = policy["tool_output_max_chars"].to_i
+      max = policy[:tool_output_max_chars].to_i
       return message if max <= 0 || message.text.length <= max
 
       attrs = message.to_h
@@ -392,7 +392,7 @@ module TurnKit
     end
 
     def append_summary(conversation, turn:, summary:, selected:, policy:, focus:, auto:, input_tokens:)
-      model = policy["model"] || turn&.model || conversation.model || conversation.agent.effective_model
+      model = policy[:model] || turn&.model || conversation.model || conversation.agent.effective_model
       conversation.append_message(
         role: "assistant",
         kind: "context_summary",
@@ -402,9 +402,9 @@ module TurnKit
           "compaction" => {
             "auto" => auto,
             "focus" => focus,
-            "replaces_from_sequence" => selected.fetch("replaces_from_sequence"),
-            "replaces_through_sequence" => selected.fetch("replaces_through_sequence"),
-            "tail_start_sequence" => selected["tail_start_sequence"],
+            "replaces_from_sequence" => selected.fetch(:replaces_from_sequence),
+            "replaces_through_sequence" => selected.fetch(:replaces_through_sequence),
+            "tail_start_sequence" => selected[:tail_start_sequence],
             "summary_model" => model,
             "input_tokens" => input_tokens,
             "summary_tokens" => estimate_text_tokens(summary),

data/lib/turnkit/cost.rb

@@ -48,42 +48,40 @@ module TurnKit
       from_usage(Usage.from_h(usage), model: attrs["model"])
     end
 
+    RATE_KEYS = %i[input output cache_read cache_write thinking].freeze
+
+    # Rates are USD per million tokens, keyed by component.
     def self.from_rates(usage, rates)
       rates = rates.transform_keys(&:to_sym)
+      unknown = rates.keys - RATE_KEYS
+      raise ConfigError, "unknown cost rate keys: #{unknown.join(", ")} (use: #{RATE_KEYS.join(", ")})" if unknown.any?
+
       new(
-        input: amount(usage.input_tokens, rates[:input] || rates[:input_per_million]),
-        output: amount(usage.output_tokens, rates[:output] || rates[:output_per_million]),
-        cache_read: amount(usage.cached_tokens, rates[:cache_read] || rates[:cached_input] || rates[:cache_read_input_per_million] || rates[:cached_input_per_million]),
-        cache_write: amount(usage.cache_write_tokens, rates[:cache_write] || rates[:cache_creation] || rates[:cache_write_input_per_million] || rates[:cache_creation_input_per_million]),
-        thinking: amount(usage.thinking_tokens, rates[:thinking] || rates[:reasoning] || rates[:thinking_output] || rates[:reasoning_output] || rates[:thinking_output_per_million] || rates[:reasoning_output_per_million]),
+        input: amount(usage.input_tokens, rates[:input]),
+        output: amount(usage.output_tokens, rates[:output]),
+        cache_read: amount(usage.cached_tokens, rates[:cache_read]),
+        cache_write: amount(usage.cache_write_tokens, rates[:cache_write]),
+        thinking: amount(usage.thinking_tokens, rates[:thinking]),
         strict: true
       )
     end
 
+    # Estimates cost from RubyLLM's model pricing registry (ruby_llm >= 1.16).
+    # Returns an empty Cost when ruby_llm is not loaded or the model is not in
+    # the registry; any other failure raises.
     def self.from_ruby_llm(usage, model)
-      require "ruby_llm"
-
-      model_info = ::RubyLLM.models.find(model) if model
-      return new unless model_info
-
-      if defined?(::RubyLLM::Cost)
-        tokens = ::RubyLLM::Tokens.new(
-          input: usage.input_tokens,
-          output: usage.output_tokens,
-          cached: usage.cached_tokens,
-          cache_creation: usage.cache_write_tokens,
-          thinking: usage.thinking_tokens
-        )
-        from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
-      else
-        from_rates(
-          usage,
-          input: model_info.input_price_per_million,
-          output: model_info.output_price_per_million,
-          cached_input: model_info.pricing&.text_tokens&.cached_input
-        )
-      end
-    rescue LoadError, StandardError
+      return new unless defined?(::RubyLLM) && model
+
+      model_info = ::RubyLLM.models.find(model)
+      tokens = ::RubyLLM::Tokens.new(
+        input: usage.input_tokens,
+        output: usage.output_tokens,
+        cached: usage.cached_tokens,
+        cache_creation: usage.cache_write_tokens,
+        thinking: usage.thinking_tokens
+      )
+      from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
+    rescue ::RubyLLM::ModelNotFoundError
       new
     end
 
@@ -92,9 +90,9 @@ module TurnKit
       new(
         input: hash[:input],
         output: hash[:output],
-        cache_read: hash[:cache_read] || hash[:cached_input],
-        cache_write: hash[:cache_write] || hash[:cache_creation],
-        thinking: hash[:thinking] || hash[:reasoning] || hash[:thinking_output] || hash[:reasoning_output],
+        cache_read: hash[:cache_read],
+        cache_write: hash[:cache_write],
+        thinking: hash[:thinking],
         total: hash[:total]
       )
     end

data/lib/turnkit/image_result.rb

@@ -23,6 +23,7 @@ module TurnKit
       @metadata = metadata || {}
     end
 
+    # Performs network IO when the image is URL-backed.
     def to_blob
       raise Error, "image has no url or data" if url.to_s.empty? && data.to_s.empty?
 

data/lib/turnkit/image_tool.rb

@@ -11,8 +11,8 @@ module TurnKit
       end
     end
 
-    def call(turnkit_context:, **arguments)
-      turnkit_context.turn.paint(
+    def call(context:, **arguments)
+      context.turn.paint(
         prompt(**arguments),
         model: self.class.model,
         provider: self.class.provider,

data/lib/turnkit/media_analysis_result.rb

@@ -24,8 +24,6 @@ module TurnKit
       !data.nil?
     end
 
-    alias structured? data?
-
     def cost
       Cost.from_usage(usage, model: model)
     end

data/lib/turnkit/model_request.rb

@@ -2,13 +2,14 @@
 
 module TurnKit
   class ModelRequest
-    attr_reader :model, :messages, :tools, :instructions, :thinking, :output_schema, :metadata, :report
+    attr_reader :model, :messages, :tools, :instructions, :dynamic_instructions, :thinking, :output_schema, :metadata, :report
 
-    def initialize(model:, messages:, tools:, instructions:, thinking: nil, output_schema: nil, metadata: {}, report: nil)
+    def initialize(model:, messages:, tools:, instructions:, dynamic_instructions: nil, thinking: nil, output_schema: nil, metadata: {}, report: nil)
       @model = model
       @messages = Array(messages)
       @tools = Array(tools)
       @instructions = instructions.to_s
+      @dynamic_instructions = dynamic_instructions.to_s
       @thinking = thinking
       @output_schema = output_schema
       @metadata = metadata || {}
@@ -25,6 +26,7 @@ module TurnKit
         "messages" => messages,
         "tools" => tool_names,
         "instructions" => instructions,
+        "dynamic_instructions" => dynamic_instructions,
         "thinking" => thinking,
         "output_schema" => output_schema,
         "metadata" => metadata,

data/lib/turnkit/output_policy.rb

@@ -75,7 +75,7 @@ module TurnKit
       else
         audit_client = client || TurnKit.client
         audit_client.validate!(model: model_name)
-        chat(audit_client, model: model_name, messages: audit_messages(output), tools: [], instructions: audit_instructions, thinking: thinking, output_schema: DEFAULT_SCHEMA, metadata: { output_policy: name })
+        audit_client.chat(model: model_name, messages: audit_messages(output), tools: [], instructions: audit_instructions, thinking: thinking, output_schema: DEFAULT_SCHEMA, metadata: { output_policy: name })
       end
       data = result.output_data || parse_json(result.text)
       return if data.fetch("approved", false)
@@ -111,20 +111,6 @@ module TurnKit
         [ { role: :user, content: JSON.generate(output: output) } ]
       end
 
-      def chat(client, **kwargs)
-        accepted = chat_keyword_names(client)
-        kwargs = kwargs.slice(*accepted) unless accepted.include?(:keyrest)
-        client.chat(**kwargs)
-      end
-
-      def chat_keyword_names(client)
-        client.method(:chat).parameters.filter_map do |kind, name|
-          return [ :keyrest ] if kind == :keyrest
-
-          name if %i[key keyreq].include?(kind)
-        end
-      end
-
       def parse_json(value)
         JSON.parse(extract_json(value.to_s))
       rescue JSON::ParserError

data/lib/turnkit/run.rb

@@ -11,16 +11,12 @@ module TurnKit
     def id = turn.id
     def root_turn_id = turn.root_turn_id
     def status = turn.status
-    def output = output_text
     def output_text = turn.output_text
     def output_data = turn.output_data
     def policy_audit = turn.policy_audit
     def policy_clean? = policy_audit.nil? || policy_audit.fetch("clean", false)
     def usage = Usage.from_records(turn_records)
     def cost = Cost.from_records(turn_records)
-    def steps = turn_records.length
-    def tool_calls = tool_executions
-    def persisted? = true
 
     def error
       turn.store.load_turn(id)["error"]

data/lib/turnkit/store.rb

@@ -12,12 +12,10 @@ module TurnKit
     def create_turn(_attributes) = raise(NotImplementedError)
     def load_turn(_id) = raise(NotImplementedError)
     def update_turn(_id, _attributes) = raise(NotImplementedError)
-    def claim_turn(id, from: "pending", to: "running", **attributes)
-      turn = load_turn(id)
-      return nil unless turn["status"] == from
-
-      update_turn(id, attributes.merge(status: to))
-    end
+    # claim_turn is the concurrency-safety point: it must atomically
+    # compare-and-set status from `from` to `to` (returning nil when the turn
+    # 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)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)

data/lib/turnkit/sub_agent_tool.rb

@@ -2,8 +2,7 @@
 
 module TurnKit
   class SubAgentTool < Tool
-    parameter :task, :string, required: true, description: "The task for the sub-agent to complete."
-    parameter :context, :string, required: false, description: "Relevant context for the sub-agent."
+    parameter :task, :string, required: true, description: "The complete task for the sub-agent, including all relevant context."
 
     def self.for(agent)
       Class.new(self) do
@@ -18,25 +17,21 @@ module TurnKit
       end
     end
 
-    def call(task:, context: nil, turnkit_context:)
+    def call(task:, context:)
       sub_agent = self.class.agent
-      parent_turn = turnkit_context.turn
-      prompt = [ task, context ].compact.join("\n\n")
-      conversation = sub_agent.conversation(metadata: {
+      parent_turn = context.turn
+      lineage = {
         "parent_conversation_id" => parent_turn.conversation.id,
         "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => turnkit_context.execution.id
-      })
-      trigger = conversation.say(prompt, metadata: {
-        "parent_conversation_id" => parent_turn.conversation.id,
-        "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => turnkit_context.execution.id
-      })
+        "parent_tool_execution_id" => context.execution.id
+      }
+      conversation = sub_agent.conversation(metadata: lineage)
+      trigger = conversation.say(task, metadata: lineage)
       child = conversation.run!(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
         parent_turn: parent_turn,
-        parent_tool_execution: turnkit_context.execution,
+        parent_tool_execution: context.execution,
         depth: parent_turn.depth + 1,
         model: sub_agent.effective_model,
         agent: sub_agent,