turnkit 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb1f58cfea02169c68e433d8a8b84dc5eb2a8a54f18ea9e89853e4ad85445ccd
-  data.tar.gz: '085c56655a5e11670528b157926a6003a04a074944adaf7cf61730cc18c5d6a3'
+  metadata.gz: ceb5e53317935ed6bb840b8b6e06157138fb95027f35ed798259a7c9bebbbcbd
+  data.tar.gz: e4c9f08152c55fa2e7619285f723fb1cba673a9760e9952b8d6792f87333ae71
 SHA512:
-  metadata.gz: 38ef2c605e8ee0d5a15417db75a6efce91b045103f68f86a241f7db788806b63ab6dbdd16cc40b1bee24b54ed93f6b83fb9331e13dbf6d06900bc79f4e7305d8
-  data.tar.gz: a9a752449f11422b599b9eaba4598441a295366fc4ab1dddccb136689d9279c2e8b426de9d1f2f8b45fe74011209bd22942e388033892547b5f8355a65d8e56c
+  metadata.gz: eb629f09b9566f782014dbefaaf98a2e238c9cd39728628360a09147f117d44a043c513f8191ad1f89cd9b63c428b52fef27679d28d3a02737d64bff8762b1cc
+  data.tar.gz: 290d3a6c992c30deac5923f7c74a86f25b5fcf8fef851a84ccceae4f72e9fe3f32d9768efff08b465c2c2b4144140306b2182c9ef4168aa2f54e8555805206d7

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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

data/README.md

@@ -590,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
@@ -839,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

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/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_runner.rb

@@ -93,6 +93,8 @@ 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!
@@ -191,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.7.2"
+  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.2
+  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,