turnkit 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170286a1c5a1975fe34234a667c946c465cb6512509be4bf06d397f48b2f9f2e
-  data.tar.gz: 8798216dcaece0679c5f8365ee5a2af900b9660694cb3a640c1924f99b814c5d
+  metadata.gz: ceb5e53317935ed6bb840b8b6e06157138fb95027f35ed798259a7c9bebbbcbd
+  data.tar.gz: e4c9f08152c55fa2e7619285f723fb1cba673a9760e9952b8d6792f87333ae71
 SHA512:
-  metadata.gz: 2e0286f571241210786433490a66cbf54d7b2453e1202d60ada2a45ae7fa6c1c370857cf6ad96348ab1cb1e4d16bdbdf0b8a26ccc59cb7a712718f0e9e309ba8
-  data.tar.gz: 85dcbfe855bc6937f495eddbc7a20bd32ba994035b024b8958b08cf9ce69c1ac5f98171722373462c034a8426f658788fd13c8ee49cb9d6b7954369c38a749f5
+  metadata.gz: eb629f09b9566f782014dbefaaf98a2e238c9cd39728628360a09147f117d44a043c513f8191ad1f89cd9b63c428b52fef27679d28d3a02737d64bff8762b1cc
+  data.tar.gz: 290d3a6c992c30deac5923f7c74a86f25b5fcf8fef851a84ccceae4f72e9fe3f32d9768efff08b465c2c2b4144140306b2182c9ef4168aa2f54e8555805206d7

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.8.0 - 2026-09-18
+
+- Add typed delegation to `SubAgentTool`: subclasses declare their own
+  parameters, an `agent` class macro (or instance `agent`), and `task_for` to
+  build the child task inside the runtime so bulk data never enters the parent
+  context. Emit `sub_agent.delegated` with `task_chars` per delegation, and
+  auto-register agents owned by sub-agent tools alongside `sub_agents`.
+- Add `Agent#tool_policy`, a per-agent routing/cost gate that runs after
+  authorization and returns `:allow` or `[:block, reason]`; blocked calls return
+  the reason to the model with `details["tool_policy_blocked"]`.
+- Add `examples/shunt`, a Spotify Portal-style context router with
+  `bulk_read`/`code_write` worker agents, a large-file `read_file` gate, and
+  measured savings.
+- Breaking: `SubAgentTool#build_child` is an instance method, and the `task`
+  parameter is declared only on `SubAgentTool.for` classes.
+
+## 0.7.2 - 2026-09-10
+
+- Add explicit `Tool.budget_completion!` for replay-safe local terminal saves
+  from an already-billed response that reaches the spend limit. Persist the
+  exact eligible call ID with the response; skip other batch calls and preserve
+  ordinary authorization, validation, receipts, fencing and recovery. Ambiguous
+  or failed saves fail without another model request.
+- Treat exact spend exhaustion as a bound and recheck persisted spend before
+  model, media and ordinary tool dispatch. Terminal status alone does not permit
+  over-budget execution; the opt-in does not waive other runtime limits.
+
 ## 0.7.1 - 2026-09-10
 
 - Preserve OpenAI prompt prefixes with durable, append-only dynamic context

data/README.md

@@ -323,6 +323,50 @@ class SaveBrief < TurnKit::Tool
 end
 ```
 
+### Saving an already-billed final response at the spend limit
+
+By default, reaching `max_spend` stops the turn before further work. A model
+response can itself reach or exceed that limit: its usage and proposed tool
+calls are persisted, but an ordinary terminal tool is not allowed to run.
+
+For a **local, idempotent final save only**, explicitly opt in on the tool:
+
+```ruby
+class SavePacket < TurnKit::Tool
+  terminal! { |result| "Saved #{result.fetch('id')}." }
+  recovery :replay_safe
+  budget_completion!
+
+  # Define parameters and call normally. Validate the complete packet before
+  # saving; persist context.idempotency_key with the save in one transaction.
+end
+```
+
+`budget_completion!` requires both terminal behavior and `recovery :replay_safe`.
+It is an application promise that the tool only validates/saves already acquired
+output locally: no model calls, acquisition, or child launches. Terminal status
+alone never grants this exception, and the marker is not inherited implicitly.
+
+When the billed response reaches the spend limit, TurnKit atomically records the
+sole eligible call ID with that response. The normal tool runner executes only
+that call; other calls in the batch get skipped receipts and paired tool results,
+even if they precede the save. Zero or multiple eligible calls fail without tool
+dispatch. No new model request is allowed in the exhausted turn, including
+compaction, model-backed output audits, image generation, or media analysis.
+
+Authorization, argument validation, claim fencing, cancellation, timeout/depth,
+and global/per-tool execution limits still apply. Invalid saves must raise
+`ToolValidationError`/`ToolError`; an ordinary error-shaped hash is still tool
+result data. Failed receipts are never replayed or repaired with another model
+call. Failed local output audits also terminate rather than request revision;
+model-backed audits cannot run at exhaustion. Use local validation for this path.
+
+Worker recovery reuses the persisted call/execution and its idempotency key;
+completed receipts are not re-executed. The application must make the save and
+its receipt atomic. An already-started external effect cannot be recalled by
+cancellation, so this marker must not be applied to acquisition tools. No schema
+migration is needed; upgrade workers together before enabling the opt-in.
+
 ### Output audits and policies
 
 Use output audits for deterministic checks that should not depend on another
@@ -546,6 +590,28 @@ puts turn.output_text
 
 Rely on TurnKit to validate tools and model-provided arguments.
 
+#### Tool policies
+
+Gate tool calls per agent for routing or cost, separately from identity
+authorization:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "reporter",
+  tools: [ReadFile, BulkRead],
+  tool_policy: lambda do |tool:, arguments:, context:|
+    next :allow unless tool.is_a?(ReadFile) && File.foreach(arguments["path"]).count > 350
+    [:block, "File is large. Use `bulk_read` with a question, or re-read with `offset`/`limit`."]
+  end
+)
+```
+
+The policy runs after authorization and before the tool executes. Return
+`:allow` (or `nil`) to proceed, or `[:block, reason]` to return the reason to
+the model as a tool error with `details["tool_policy_blocked"] = true`. Keep
+`authorization_policy` for who may call what; use `tool_policy` for how much and
+which way.
+
 ### Images
 
 Generate images inside a durable turn with `turn.paint`. The image call uses the
@@ -795,6 +861,32 @@ puts turn.output_text
 
 Use sub-agents for isolated child conversations.
 
+#### Typed delegation
+
+Subclass `SubAgentTool` to build the child task from typed arguments so bulk
+data never enters the parent's context:
+
+```ruby
+class BulkRead < TurnKit::SubAgentTool
+  agent reader
+  description "Read files and answer a question about them."
+
+  parameter :question, :string, required: true
+  parameter :paths, :array, required: true, items: :string
+
+  def task_for(question:, paths:)
+    files = paths.map { |path| "<file path=\"#{path}\">\n#{File.read(path)}\n</file>" }
+    "#{question}\n\n#{files.join("\n")}"
+  end
+end
+```
+
+The parent model supplies `question` and `paths`; `task_for` runs inside the
+runtime, and only the child's answer returns to the parent. Override `agent` on
+an instance when the child agent is configured at runtime. Each delegation emits
+`sub_agent.delegated` with `task_chars`, so avoided parent context is
+measurable. See [`examples/shunt`](examples/shunt) for a complete routing setup.
+
 #### Oracle- and Librarian-style specialists
 
 Use ordinary agents, not a second specialist runtime. Give each specialist its
@@ -1058,7 +1150,9 @@ TurnKit.timeout = 300
 ```
 
 `max_spend` is the only spend-limit name in the public API.
-
+Spend equal to the limit is exhausted, not just spend above it. Dispatch checks
+use persisted aggregate spend, including after recovery and before internal
+model/media calls. Committed response cost is retained even when the turn fails.
 
 Customize cost rates with USD-per-million-token component keys:
 

data/lib/turnkit/agent.rb

@@ -24,10 +24,10 @@ module TurnKit
     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, :context_contributors
+    attr_reader :output_policy, :output_policy_mode, :output_policy_model, :output_retries, :context_contributors, :tool_policy
 
     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,
+      tool_policy: nil, 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, context_contributors: [], inherit_globals: true)
       @name = name.to_s
@@ -39,6 +39,7 @@ module TurnKit
       @skills = Array(skills).dup.freeze
       @available_skills = ((inherit_globals ? Array(TurnKit.available_skills) : []) + Array(available_skills)).uniq { |skill| skill.key }.freeze
       @sub_agents = Array(sub_agents).dup.freeze
+      @tool_policy = tool_policy
       @system_prompt = system_prompt
       @prompt_sections = prompt_sections
       @prompt_mode = prompt_mode&.to_sym || (:task if @orchestrator)

data/lib/turnkit/background.rb

@@ -264,7 +264,7 @@ module TurnKit
             loaded = Background.load_turn(record.fetch("id"), store: store)
             tool = loaded.agent.effective_tools(turn: loaded).find { |candidate| candidate.tool_name == execution["tool_name"] }
             recovery = tool.is_a?(Class) ? tool.recovery : tool&.class&.recovery
-            ordinary = tool && !(tool.is_a?(Class) && tool < SubAgentTool) &&
+            ordinary = tool && !SubAgentTool.delegates?(tool) &&
               ![WaitTool, LaunchAgentTool, SendMessageTool].include?(tool)
             if ordinary && recovery == :replay_safe
               store.claim_tool_execution(execution.fetch("id"), to: "pending", started_at: nil)

data/lib/turnkit/budget.rb

@@ -67,14 +67,18 @@ module TurnKit
 
       @mutex.synchronize do
         @cost += cost.to_f
-        raise BudgetError, "cost limit reached" if @cost > max_spend
+        raise BudgetError, "cost limit reached" if spend_exhausted?
       end
     end
 
-    def check!(depth:)
+    def spend_exhausted?
+      max_spend && @cost >= max_spend
+    end
+
+    def check!(depth:, allow_exhausted_spend: false)
       raise BudgetError, "maximum sub-agent depth reached" if max_depth && depth > max_depth
       raise BudgetError, "turn timed out" if timeout && Clock.now >= root_started_at + timeout
-      raise BudgetError, "cost limit reached" if max_spend && @cost > max_spend
+      raise BudgetError, "cost limit reached" if spend_exhausted? && !allow_exhausted_spend
     end
 
     private

data/lib/turnkit/coordination_tools.rb

@@ -39,7 +39,7 @@ module TurnKit
         if existing
           child = existing
         else
-          built = SubAgentTool.for(agent).build_child(task: task, context: context)
+          built = SubAgentTool.for(agent).new.build_child(task: task, context: context)
           options = parent.store.load_turn(built.id).fetch("options")
           options = options.merge("callback_conversation_id" => parent.conversation.id) if callback
           child = parent.store.update_turn(built.id, submitted_at: Clock.now, options: options)

data/lib/turnkit/sub_agent_tool.rb

@@ -1,24 +1,48 @@
 # frozen_string_literal: true
 
 module TurnKit
+  # Runs a child agent in a fresh conversation and returns only its final result.
+  # `SubAgentTool.for(agent)` exposes an agent as a tool taking `task`. Subclasses
+  # declare their own parameters and override `task_for` to assemble the task in
+  # Ruby, so bulk data (file contents, records) reaches the child without ever
+  # entering the parent model's context. The child comes from the `agent` class
+  # macro or an instance-level `agent` override.
   class SubAgentTool < Tool
-    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
-        @agent = agent
-        tool_name agent.name
-        description agent.description.empty? ? "Delegate work to #{agent.name}." : agent.description
-        usage_hint "Use when work can be delegated independently to #{agent.name}. Pass a complete task and only relevant context."
+    class << self
+      def agent(value = nil)
+        @agent = value if value
+        @agent || (superclass < SubAgentTool ? superclass.agent : nil)
+      end
 
-        class << self
-          attr_reader :agent
+      def for(agent)
+        sub_agent = agent
+        Class.new(self) do
+          agent sub_agent
+          tool_name sub_agent.name
+          description sub_agent.description.empty? ? "Delegate work to #{sub_agent.name}." : sub_agent.description
+          usage_hint "Use when work can be delegated independently to #{sub_agent.name}. Pass a complete task and only relevant context."
+          parameter :task, :string, required: true, description: "The complete task for the sub-agent, including all relevant context."
         end
       end
+
+      def delegates?(tool)
+        tool.is_a?(self) || (tool.is_a?(Class) && tool <= self)
+      end
+
+      def 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
     end
 
-    def self.build_child(task:, context:)
-      sub_agent = agent
+    def agent = self.class.agent
+
+    def task_for(**arguments)
+      arguments.fetch(:task)
+    end
+
+    def build_child(task:, context:)
       parent_turn = context.turn
       lineage = {
         "parent_conversation_id" => parent_turn.conversation.id,
@@ -27,32 +51,28 @@ module TurnKit
         "principal" => context.principal
       }
       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)
+      record = store.create_conversation("agent_name" => agent.name, "model" => agent.effective_model, "metadata" => lineage)
+      conversation = Conversation.new(agent: agent, record: record, store: store, model: agent.effective_model, metadata: lineage)
       trigger = conversation.say(task, metadata: lineage)
+      parent_turn.emit("sub_agent.delegated", id: context.execution.tool_call_id, name: agent.name,
+        conversation_id: record.fetch("id"), task_chars: task.length)
       conversation.build_turn(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
         parent_turn: parent_turn,
         parent_tool_execution: context.execution,
         depth: parent_turn.depth + 1,
-        model: sub_agent.effective_model,
-        agent: sub_agent,
+        model: agent.effective_model,
+        agent: agent,
         principal: context.principal,
         on_event: parent_turn.agent.effective_on_event
       )
     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:)
+    def call(context:, **arguments)
       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)
+        agent: agent, arguments: arguments.transform_keys(&:to_s))
+      child = build_child(task: task_for(**arguments), context: context)
       child.run!
       SubAgentTool.result(child.store.load_turn(child.id))
     end

data/lib/turnkit/tool.rb

@@ -54,6 +54,16 @@ module TurnKit
         @ends_turn || false
       end
 
+      # Explicit application promise: this terminal tool only validates/saves
+      # already acquired output locally, without model calls or acquisition.
+      def budget_completion!
+        @budget_completion = true
+      end
+
+      def budget_completion?
+        @budget_completion || 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)
@@ -79,6 +89,9 @@ module TurnKit
       def validate_definition!
         raise ArgumentError, "tool name is required" if tool_name.empty?
         raise ArgumentError, "invalid tool name: #{tool_name}" unless NAME_PATTERN.match?(tool_name)
+        if budget_completion? && (!ends_turn? || recovery != :replay_safe)
+          raise ArgumentError, "budget_completion! requires a terminal tool with recovery :replay_safe"
+        end
 
         parameters.each do |param|
           type = param.fetch(:type)
@@ -188,6 +201,7 @@ module TurnKit
     def input_schema = self.class.input_schema
     def validate_definition! = self.class.validate_definition!
     def ends_turn? = self.class.ends_turn?
+    def budget_completion? = self.class.budget_completion?
     def completion_message(result) = self.class.completion_message(result)
   end
 end

data/lib/turnkit/tool_runner.rb

@@ -7,6 +7,20 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
+      completion_id = turn.budget_completion_call_id
+      if completion_id
+        control = turn.control_boundary!
+        return control if control
+        selected = tool_calls.select { |call| call.id == completion_id }
+        tool = tool_for(selected.first&.name)
+        unless selected.length == 1 && tool&.budget_completion? && tool.ends_turn?
+          raise BudgetError, "budget completion is no longer available"
+        end
+        # Preserve pairing and receipts, regardless of where acquisition calls
+        # appear in the response. Only the durably selected call may execute.
+        skip_remaining(tool_calls - selected, terminal: selected.first)
+        tool_calls = selected
+      end
       waiting = false
       tool_calls.each_with_index do |tool_call, index|
         control = turn.control_boundary!
@@ -24,6 +38,7 @@ module TurnKit
           skip_remaining(tool_calls.drop(index + 1), terminal: tool_call)
           return execution
         end
+        raise BudgetError, "budget completion failed" if completion_id
       end
       waiting ? :waiting : nil
     end
@@ -78,10 +93,13 @@ module TurnKit
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
           Authorization.authorize!(:tool, principal: context.principal, turn: turn, tool: tool, arguments: tool_call.arguments)
+          blocked = tool_policy_block(tool, tool_call.arguments, context)
+          return finish_error(execution, tool_call, blocked, details: { "tool_policy_blocked" => true }) if blocked
           # Observe cancellation/reconciliation immediately before crossing the
           # external-effect boundary. Calls already sent cannot be recalled.
           control = turn.control_boundary!
           return control if control
+          turn.execution_budget.check!(depth: turn.depth, allow_exhausted_spend: turn.budget_completion_call_id == tool_call.id)
           if turn.background? && subagent?(tool)
             return delegate(tool, tool_call, context)
           end
@@ -164,7 +182,8 @@ module TurnKit
         calls.each do |call|
           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}" }
+            reason = turn.budget_completion_call_id ? "spend limit reached" : "turn ended by #{terminal.name}"
+            payload = { "skipped" => true, "message" => "not executed: #{reason}" }
             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)
@@ -174,20 +193,30 @@ module TurnKit
       end
 
       def subagent?(tool)
-        tool.is_a?(Class) && tool < SubAgentTool
+        SubAgentTool.delegates?(tool)
+      end
+
+      # Agent-owned routing/cost policy, distinct from identity authorization.
+      # Returns the block reason the model sees, or nil to proceed.
+      def tool_policy_block(tool, arguments, context)
+        decision, reason = turn.agent.tool_policy&.call(tool: tool, arguments: arguments, context: context)
+        return reason.to_s if decision == :block
+        raise ArgumentError, "tool_policy must return :allow or [:block, reason]" unless [ nil, :allow ].include?(decision)
       end
 
       def delegate(tool, call, context)
-        arguments = tool.validate_arguments(call.arguments)
+        tool = tool.new if tool.is_a?(Class)
+        arguments = tool.class.validate_arguments(call.arguments)
         Authorization.authorize!(:launch_agent, principal: context.principal, turn: turn, agent: tool.agent, arguments: arguments)
         TurnKit.resolve_agent(tool.agent.name)
+        task = tool.task_for(**arguments.transform_keys(&:to_sym))
         child = turn.store.atomic_graph do
           turn.store.atomic(Background.root_conversation(turn.store, turn.store.load_turn(turn.id))) do
             control = turn.control_boundary!
             next control if control
             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)
+              built = tool.build_child(task: task, context: context)
               row = turn.store.update_turn(built.id, submitted_at: Clock.now)
             end
             Background.wait(turn, [row.fetch("id")])

data/lib/turnkit/turn.rb

@@ -151,6 +151,10 @@ module TurnKit
       options.dig("state", "policy_audit") || options["policy_audit"]
     end
 
+    def budget_completion_call_id
+      @record.dig("options", "state", "budget_completion_call_id")
+    end
+
     # Reads iterations from options["state"], falling back to the legacy
     # top-level key for turns persisted before the state split.
     def self.iterations_for(record)
@@ -188,6 +192,7 @@ module TurnKit
     end
 
     def internal_model_call(model:, messages:, instructions:, tools: [], thinking: nil, output_schema: nil, metadata: {}, purpose:, client: nil)
+      execution_budget.check!(depth: depth)
       request = ModelRequest.new(
         model: model,
         messages: messages,
@@ -303,8 +308,8 @@ module TurnKit
             break
           end
           @budget = execution_budget
-          budget.check!(depth: depth)
           state = @record.dig("options", "state") || {}
+          budget.check!(depth: depth, allow_exhausted_spend: budget_completion_call_id && %w[tools output].include?(state["phase"]))
           case state["phase"] || "model"
           when "model"
             count_iteration!
@@ -320,10 +325,11 @@ module TurnKit
               add_usage!(result.usage, cost: cost)
               persist_assistant_message(result)
               update_state!("phase" => result.tool_calls? ? "tools" : "output", "parts" => result.parts,
-                "candidate" => result.text, "output_data" => result.output_data, "terminal_tool_name" => nil)
+                "candidate" => result.text, "output_data" => result.output_data, "terminal_tool_name" => nil,
+                "budget_completion_call_id" => select_budget_completion(result))
             end
             emit_model_completed("model.completed", result, cost, model: model)
-            budget.add_cost!(cost.total)
+            budget.add_cost!(cost.total) unless budget_completion_call_id
           when "tools"
             runner = ToolRunner.new(self)
             terminal = runner.dispatch(Result.new(parts: state.fetch("parts")).tool_calls)
@@ -344,6 +350,9 @@ module TurnKit
           when "output"
             candidate = state.fetch("candidate")
             audit = check_policy(candidate, output_data: state["output_data"])
+            if budget_completion_call_id && audit && !audit.clean?
+              raise BudgetError, "budget completion rejected: #{audit.messages.join('; ')}"
+            end
             revisions_used = state["revisions_used"].to_i
             if should_revise?(audit, revisions_used)
               store.atomic do
@@ -418,6 +427,7 @@ module TurnKit
 
       # Clients implement the TurnKit::Client keyword contract. See client.rb.
       def call_client(request, client: agent.effective_client)
+        execution_budget.check!(depth: depth)
         client.chat(
           model: request.model,
           messages: request.messages,
@@ -432,13 +442,26 @@ module TurnKit
       end
 
       def call_image_client(client, request)
+        execution_budget.check!(depth: depth)
         with_heartbeat { client.paint(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
       def call_media_client(client, request)
+        execution_budget.check!(depth: depth)
         with_heartbeat { client.view_media(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
+      def select_budget_completion(result)
+        return unless execution_budget.spend_exhausted?
+
+        tools = agent.effective_tools(turn: self)
+        candidates = result.tool_calls.select do |call|
+          tool = tools.find { |candidate| candidate.tool_name == call.name }
+          tool&.budget_completion? && tool.ends_turn?
+        end
+        candidates.first.id if candidates.length == 1
+      end
+
       def llm_messages(include_dynamic_context: false)
         messages = TurnKit::Compaction.project(conversation.messages_for_turn(self))
         # Delivery time is not application time. A next-turn message can arrive

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/lib/turnkit.rb

@@ -78,7 +78,8 @@ module TurnKit
 
   def self.register(agent)
     @agents[agent.name] = agent
-    agent.sub_agents.each { |child| register(child) }
+    tools = agent.effective_tools + agent.available_skills.flat_map(&:tools)
+    tools.each { |tool| register(tool.agent) if SubAgentTool.delegates?(tool) }
     agent
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Sam Couch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies: []
 description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
   runs, orchestrator agents, tool calling, skills, sub-agents, context compaction,