insika 0.7.0 → 0.9.0

data/lib/insika/studio/app.rb

@@ -45,8 +45,11 @@ module Studio
     }.freeze
 
     # Plugins that do NOT depend on the secret (loaded at class definition).
+    # The templates are UTF-8 ("Signing in…"). Tilt reads them in the PROCESS
+    # locale, and a host with no LANG (a bare container, a systemd unit) reads
+    # US-ASCII and 500s on the login page — found by the release install proof.
     plugin :render, views: File.expand_path("views", __dir__), engine: "erb",
-                    layout: "layout", escape: true
+                    layout: "layout", escape: true, template_opts: { default_encoding: "UTF-8" }
     plugin :hash_branches
     plugin :h
 
@@ -1976,11 +1979,12 @@ end
         name: t["name"].to_s, description: t["description"].to_s,
         method: req["method"] || "GET", url: req["url"].to_s,
         parameters: params_text(t["parameters"]),
+        requires_evidence: Array(t.dig("requires_evidence", "params")).join(", "),
         query: env_lines(req["query"]), headers: env_lines(req["headers"]),
         secret_headers: Array(t["secret_headers"]).join(", "),
         body: req["body"].to_s,
         extract: resp["extract"] || "body_raw", path: resp["path"].to_s,
-        timeout: t["timeout"]
+        timeout: t["timeout"], presentation: t["presentation"]
       }
     end
 
@@ -2078,7 +2082,14 @@ end
         "providers" => insika[:llm_provider_store] ? insika[:llm_provider_store].all.size : 0,
         "MCP servers" => insika[:mcp_store] ? insika[:mcp_store].all.size : 0
       }
-      now = Time.now
+      # UTC, deliberately: sessions stamp `updated_at` with `Time.now.utc.iso8601`,
+      # and every bucket below is keyed by a calendar part (date, hour) of that
+      # stamp. A LOCAL `now` mixes two clocks — on a UTC-3 host, from 21:00 local
+      # onward "today" is already tomorrow in UTC, so the day buckets stopped
+      # matching and the 24h floor was built three hours in the future, silently
+      # emptying both charts. Instant comparisons (`cutoff`) never had the bug;
+      # calendar arithmetic did.
+      now = Time.now.utc
       cutoff = now - (5 * 60)
       @active_now = sessions.count { |s| (t = parse_time(s.updated_at)) && t >= cutoff }
       @recent = sessions.sort_by { |s| s.updated_at.to_s }.reverse.first(8)
@@ -2089,8 +2100,11 @@ end
       # Trend affordances on the traffic stat cards: today vs yesterday from
       # the 14-day series (config counts — agents/skills/tools/providers —
       # have no daily shape and honestly show no trend).
-      today, yesterday = @activity.last(2).map(&:last)
-      @conv_trend = today - yesterday.to_i
+      # `@activity` is OLDEST FIRST and ends at today, so the last pair reads
+      # [yesterday, today]. Destructured the other way round it reported a
+      # first-conversation-of-the-day as "−1", every day.
+      yesterday, today = @activity.last(2).map(&:last)
+      @conv_trend = today.to_i - yesterday.to_i
       @msg_trend = message_delta(sessions, now)
       @persistence = insika.dig(:config, :persistence)
       view("home")
@@ -2113,11 +2127,14 @@ end
     end
 
     # [[Date, count], …] — one bucket per day over the window, most-recent last.
+    # `now` is UTC (render_home) and so is every `t` — see #utc_time. Both sides
+    # of the bucket key must be read off the same clock or the join silently
+    # misses.
     def activity_by_day(sessions, days:, now:)
       today = now.to_date
       buckets = Hash.new(0)
       sessions.each do |s|
-        t = parse_time(s.updated_at) or next
+        t = utc_time(s.updated_at) or next
         buckets[t.to_date] += 1
       end
       (0...days).to_a.reverse.map { |i| d = today - i; [d, buckets[d]] }
@@ -2131,7 +2148,7 @@ end
       floor = Time.utc(now.year, now.month, now.day, now.hour) - (hours - 1) * 3600
       buckets = Hash.new(0)
       sessions.each do |s|
-        t = parse_time(s.updated_at) or next
+        t = utc_time(s.updated_at) or next
         h = Time.utc(t.year, t.month, t.day, t.hour)
         buckets[h] += 1 if h >= floor
       end
@@ -2144,11 +2161,20 @@ end
     def message_delta(sessions, now)
       today = now.to_date
       sum = ->(date) do
-        sessions.sum { |s| (t = parse_time(s.updated_at)) && t.to_date == date ? Array(s.messages).size : 0 }
+        sessions.sum { |s| (t = utc_time(s.updated_at)) && t.to_date == date ? Array(s.messages).size : 0 }
       end
       sum.call(today) - sum.call(today - 1)
     end
 
+    # A stamp read for its CALENDAR parts, always in UTC. `Time.parse` honours
+    # whatever offset the string carries — ours are `Z`, but a record written by
+    # anything else would otherwise bucket by its own zone. `getutc`, not `utc`:
+    # the latter mutates the receiver.
+    def utc_time(value)
+      t = parse_time(value)
+      t&.getutc
+    end
+
     # --- History -------------------------------------------------------------
 
     # Recent conversations (all agents — the Session doesn't stamp the agent that

data/lib/insika/studio/forms.rb

@@ -77,6 +77,7 @@ module Studio
         # unchecked box saves an explicit false — both spellings of ON collapse.
         tool_persistence: r.params["tool_persistence"] == "1",
         tool_output_compression: r.params["tool_output_compression"] == "1",
+        fencing: r.params["fencing"] == "1",
         subagents: list_patch(r, "subagents"),
         capabilities: list_patch(r, "capabilities"),
         tools_deferred: list_patch(r, "tools_deferred"),
@@ -386,7 +387,7 @@ module Studio
     # record on write, so anything missing here is erased — a save that only fixed a
     # typo in the description would silently drop them (the class of bug already
     # paid for once). `stored` carries them through untouched.
-    UNEDITED_TOOL_FIELDS = %w[group tags halt_when].freeze
+    UNEDITED_TOOL_FIELDS = %w[group tags halt_when evidence presentation side_effect].freeze
 
     # :write_data_tool payload from the form. nested request/response;
     # headers/query as "key=value" per line (same idiom as the MCP env —
@@ -394,12 +395,17 @@ module Studio
     # `stored` = the definition being edited (nil when creating).
     def tool_patch(r, stored = nil)
       preserved = (stored || {}).slice(*UNEDITED_TOOL_FIELDS).compact
-      preserved.merge(
+      method = presence(r.params["method"]) || "GET"
+      # A stored side_effect describes the stored method. When the method changes
+      # (a GET turned POST) it is dropped so the store re-derives it — the write
+      # gate and the resume skip both read it.
+      preserved.delete("side_effect") unless method == (stored || {}).dig("request", "method")
+      patch = preserved.merge(
         name: presence(r.params["name"]),
         description: r.params["description"].to_s,
         parameters: parse_parameters(r.params["parameters"]),
         request: {
-          method: presence(r.params["method"]) || "GET",
+          method: method,
           url: r.params["url"].to_s,
           headers: parse_kv_lines(r.params["headers"]),
           query: parse_kv_lines(r.params["query"]),
@@ -410,8 +416,17 @@ module Studio
           path: presence(r.params["path"])
         },
         secret_headers: split_list(r.params["secret_headers"]),
+        requires_evidence: if r.params.key?("requires_evidence")
+                             split_list(r.params["requires_evidence"]).then { |names| names.empty? ? nil : names }
+                           else
+                             (stored || {})["requires_evidence"]
+                           end,
         timeout: presence(r.params["timeout"])
       )
+      # A presentation tool makes no request: the form's HTTP fields are blank and
+      # the definition refuses both halves at once.
+      patch.delete(:request) if preserved["presentation"]
+      patch
     end
 
     # Parameters, TWO accepted syntaxes in one field (auto-detected, no mode toggle):
@@ -461,6 +476,17 @@ module Studio
       # per-tenant map in the record — the view says so.
       v = presence(r.params["memory_ttl_days"])
       patch["memory_ttl_days"] = v.nil? ? nil : Integer(v)
+      # In-session compaction (RFC-0044). The checkbox is authoritative on
+      # this form (unchecked = disable); the numbers keep their stored value
+      # when cleared (deep_merge — the defaults backstop a fresh record);
+      # model blank = nil = the platform utility_model.
+      compaction = { "enabled" => r.params["compaction_enabled"] == "1",
+                     "model" => presence(r.params["compaction_model"]) }
+      %w[keep_last compact_after].each do |f|
+        v = presence(r.params["compaction_#{f}"])
+        compaction[f] = Integer(v) if v
+      end
+      patch["compaction"] = compaction
       patch
     end
 

data/lib/insika/studio/views/_agent_tab_config.erb

@@ -490,12 +490,16 @@
         </label>
         <label class="check">
           <input type="checkbox" name="prompt_caching" value="1"<%== " checked" if @agent.prompt_caching %>>
-          prompt caching <span class="muted">— Anthropic breakpoint; ON requires a byte-stable system prompt</span>
+          prompt caching <span class="muted">— Anthropic breakpoint at the identity layer; memory/knowledge render below it</span>
         </label>
         <label class="check">
           <input type="checkbox" name="tool_output_compression" value="1"<%== " checked" if @agent.tool_output_compression %>>
           tool output compression <span class="muted">— mechanical dedupe of repeated tool results</span>
         </label>
+        <label class="check">
+          <input type="checkbox" name="fencing" value="1"<%== " checked" if @agent.fencing %>>
+          fencing <span class="muted">— sanitize tool results, memory and knowledge before the model reads them (invisible characters, forged turn markers, transcript-shaped tags) and add the "data, not instructions" notice</span>
+        </label>
         <label class="check">
           <input type="checkbox" name="tool_persistence" value="1"<%== " checked" unless @agent.tool_persistence == false %>>
           tool persistence <span class="muted">— the engine's "Tool discipline" prompt block (retry weak/empty tool results differently); ON by default</span>

data/lib/insika/studio/views/session.erb

@@ -185,7 +185,7 @@
                   <% traces[turn].each do |t| %>
                     <details class="trace-item <%= t["ok"] ? "ok" : "err" %>">
                       <summary>
-                        <span class="badge"><%= t["ok"] ? "ok" : "error" %></span>
+                        <span class="badge"><%= t["gate"] ? "blocked: #{t["gate"]}" : (t["ok"] ? "ok" : "error") %></span>
                         <strong><%= t["tool"] %></strong>
                         <span class="lat"><%= t["ms"] %>ms</span>
                         <span class="at"><%= t["at"] %></span>

data/lib/insika/studio/views/settings.erb

@@ -43,6 +43,17 @@
             <label>Memory TTL (days)<input type="text" name="memory_ttl_days" value="<%= @settings["memory_ttl_days"] %>" inputmode="numeric" placeholder="blank = off"></label>
           </div>
           <p class="muted">Memory TTL: how many days a customer memory cell lives before the daily sweep prunes it (per-fact <code>expires_at</code> overrides always win). Editing here sets the platform default for <strong>every</strong> cell; a per-tenant map authored in the settings record is replaced by this save.</p>
+          <hr>
+          <label class="check">
+            <input type="checkbox" name="compaction_enabled" value="1"<%== " checked" if @settings.dig("compaction", "enabled") %>>
+            in-session compaction — summarize old turns past the threshold
+          </label>
+          <div class="grid-2">
+            <label>keep_last <span class="muted">(messages kept verbatim)</span><input type="text" name="compaction_keep_last" value="<%= @settings.dig("compaction", "keep_last") %>" inputmode="numeric"></label>
+            <label>compact_after <span class="muted">(uncompacted messages that trigger it)</span><input type="text" name="compaction_compact_after" value="<%= @settings.dig("compaction", "compact_after") %>" inputmode="numeric"></label>
+          </div>
+          <label>compaction model <span class="muted">(blank = the platform utility_model)</span><input type="text" name="compaction_model" value="<%= @settings.dig("compaction", "model") %>" placeholder="deepseek-v4-flash"></label>
+          <p class="muted">When a session's uncompacted transcript grows past <code>compact_after</code> messages, everything but the last <code>keep_last</code> is summarized by the cheap model into one <code>&lt;conversation_summary&gt;</code> fragment; the tail stays verbatim and the boundary is stable (the prompt cache holds after it). Runs post-turn, off the critical path.</p>
         </form>
       </div>
 

data/lib/insika/studio/views/tool_edit.erb

@@ -33,7 +33,7 @@
   </label>
 
   <label>url <span class="muted">(https; use <code>{{param}}</code>)</span>
-    <input type="text" name="url" value="<%= @form[:url] %>" placeholder="https://viacep.com.br/ws/{{cep}}/json" required>
+    <input type="text" name="url" value="<%= @form[:url] %>" placeholder="https://viacep.com.br/ws/{{cep}}/json"<%== " required" unless @form[:presentation] %>>
   </label>
 
   <label>parameters <span class="muted">(one per line: <code>name | type | required|optional | description</code> — type is <code>string</code>/<code>number</code>/<code>integer</code>/<code>boolean</code> or <code>array:string</code>. For a list of objects or a nested object, paste a full <strong>JSON Schema</strong> instead: any text starting with <code>{</code> is read as one.)</span>
@@ -62,7 +62,7 @@
   <div class="grid-2">
     <label>response
       <select name="extract">
-        <% [["body_raw", "raw body"], ["json_path", "JSON field"], ["status", "status only"]].each do |v, lbl| %>
+        <% [["body_raw", "raw body"], ["json_path", "JSON field"], ["status", "status only"], ["evidence_envelope", "evidence envelope"]].each do |v, lbl| %>
           <option value="<%= v %>"<%== " selected" if @form[:extract] == v %>><%= lbl %></option>
         <% end %>
       </select>
@@ -72,6 +72,10 @@
     </label>
   </div>
 
+  <label>requires_evidence <span class="muted">(parameter names, comma-separated; each ID must first be returned by a tool in this conversation)</span>
+    <input type="text" name="requires_evidence" value="<%= @form[:requires_evidence] %>" placeholder="product_id">
+  </label>
+
   <label>timeout <span class="muted">(seconds, optional)</span>
     <input type="number" name="timeout" value="<%= @form[:timeout] %>" min="1" placeholder="30">
   </label>

data/lib/insika/telemetry/recorder.rb

@@ -40,7 +40,8 @@ module Insika
       # and units are part of the documented contract (docs/OBSERVABILITY.md) —
       # renaming one breaks every dashboard built on it.
       class Instruments
-        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration
+        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration,
+                    :cache_hit_rate, :loop_intervened, :context_compacted, :tool_blocked
 
         def initialize(meter)
           @turns = meter.create_counter("insika.turns", unit: "{turn}",
@@ -55,6 +56,14 @@ module Insika
                                                                   description: "Tool invocations")
           @tool_duration = meter.create_histogram("insika.tool.duration", unit: "s",
                                                                          description: "Wall time of a tool call")
+          @cache_hit_rate = meter.create_histogram("insika.cache.hit_rate", unit: "%",
+                                                                            description: "Prompt-cache hit rate of a turn (cached / billed prompt tokens)")
+          @loop_intervened = meter.create_counter("insika.tool.loop_intervened", unit: "{intervention}",
+                                                                                 description: "Loop-detector warnings delivered to the model")
+          @tool_blocked = meter.create_counter("insika.tool.blocked", unit: "{call}",
+                                               description: "Tool calls blocked before execution")
+          @context_compacted = meter.create_counter("insika.context.compacted", unit: "{compaction}",
+                                                                                description: "In-session compactions persisted (RFC-0044)")
         end
       end
 
@@ -73,6 +82,9 @@ module Insika
         when :tool_call      then start_tool(meta, data)
         when :tool_result    then finish_tool(meta)
         when :data_tool_call then point_tool(meta, data)
+        when :tool_loop_intervened then count_loop(meta, data)
+        when :tool_blocked then count_blocked(meta, data)
+        when :context_compacted then count_compaction(data)
         when :task_completed then finish_turn(meta, data, :ok)
         when :task_failed    then finish_turn(meta, data, :error)
         when :task_cancelled then finish_turn(meta, data, :cancelled)
@@ -166,6 +178,54 @@ module Insika
         @instruments.turns.add(1, attributes: labels)
         @instruments.turn_duration.record(seconds, attributes: labels) if seconds
         count_usage(turn, usage)
+        count_cache_hit(turn, usage)
+      end
+
+      # Same arithmetic as the Executor's per-agent series (stamp_cache_hit):
+      # the billed prompt is fresh input + cache reads + cache writes, and the
+      # hit rate is reads over the whole billed prompt — always in [0,100]. A
+      # turn with no billed prompt tokens (no usage, usage without the fields)
+      # records nothing: absence is not a 0% hit.
+      def count_cache_hit(turn, usage)
+        return unless usage
+
+        billed = usage[:input_tokens].to_i + usage[:cached_tokens].to_i +
+                 usage[:cache_creation_tokens].to_i
+        return unless billed.positive?
+
+        rate = (usage[:cached_tokens].to_i * 100.0) / billed
+        base = turn.labels.merge(attrs("insika.model" => usage[:model]&.to_s))
+        @instruments.cache_hit_rate.record(rate, attributes: base)
+      end
+
+      # The loop detector delivered its one-shot warning (`:tool_loop_intervened`,
+      # counts and the tool name, never arguments). An orphan event (no open turn)
+      # is ignored, like every other consumer of this stream.
+      def count_loop(meta, data)
+        return unless @instruments
+
+        turn = @turns[meta[:task_id]] or return
+        labels = turn.labels.merge(attrs("insika.tool" => data[:name]&.to_s))
+        @instruments.loop_intervened.add(1, attributes: labels)
+      end
+
+      def count_blocked(meta, data)
+        return unless @instruments
+
+        turn = @turns[meta[:task_id]] or return
+        labels = turn.labels.merge(attrs("insika.tool" => data[:name]&.to_s,
+                                         "insika.gate" => data[:gate]&.to_s))
+        @instruments.tool_blocked.add(1, attributes: labels)
+      end
+
+      # A compaction persisted (`:context_compacted`, RFC-0044) — counted by
+      # agent/model, INDEPENDENT of any open turn: it fires post-turn, usually
+      # after task_completed already closed the span.
+      def count_compaction(data)
+        return unless @instruments
+
+        labels = attrs("insika.agent" => data[:agent]&.to_s, "insika.model" => data[:model]&.to_s)
+        @instruments.context_compacted.add(1, attributes: labels)
       end
 
       # Tokens ride ONE counter split by `insika.token.type` (instead of four

data/lib/insika/templates/daily-digest/README.md

@@ -31,6 +31,15 @@ in the Playground — the artifact lands on the Artifacts tab either way.
 - The **numbers** are not. Swap the literal string in `agent.rb` for a
   `data_tool` against your own sales API and nothing else changes.
 
+## When the report needs real data
+
+One agent doing 30–50 tool calls at one reasoning effort is how a report turn
+hits the 300 s timeout. The recipe is to split the phases across agents —
+`thinking: "low"` miners fanned out with `spawn_subagents`, a `thinking: "high"`
+orchestrator that plans and writes. See
+[Artifacts](https://github.com/guizaols/insika/blob/main/docs/ARTIFACTS.md), "Reasoning effort on a report turn",
+and the `research-analyst` template for the fan-out shape.
+
 ## Edit it
 
 The skill's instructions are the actual report spec — change the palette,

data/lib/insika/templates/research-analyst/agent.rb

@@ -12,6 +12,12 @@
 # of a business idea, IN PARALLEL (each in its own isolated context), then
 # the lead synthesizes one recommendation.
 #
+# Reasoning effort is split by ROLE, not spread evenly: the specialists answer
+# one narrow question each (`thinking: "low"`), the lead plans the delegation
+# and weighs three answers against each other (`thinking: "high"`). A child
+# inherits the environment as a DEFAULT only, so its own `params` wins. See
+# docs/ARTIFACTS.md, "Reasoning effort on a report turn".
+#
 #   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
 #   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb --serve
 require "insika"
@@ -21,19 +27,23 @@ team = Insika.system do
 
   agent("market") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the MARKET angle of a business idea: audience, demand, competitors. Three sentences."
   end
   agent("technical") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the TECHNICAL/OPERATIONAL angle of a business idea: what it takes to build and run it. Three sentences."
   end
   agent("risk") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the RISK angle of a business idea: what could make it fail. Three sentences."
   end
 
   agent "analyst" do
     model "deepseek-v4-flash"
+    params thinking: "high"
     instructions <<~PROMPT
       You are a research LEAD with no expertise of your own — never answer
       from your own knowledge. Given a business idea, call spawn_subagents

data/lib/insika/tool_assembly.rb

@@ -58,14 +58,13 @@ module Insika
     # capability alias.
     def assemble_tool_instances(allowed, state)
       names = state.respond_to?(:capability_names) ? (state.capability_names || {}) : {}
-      ctx = state.respond_to?(:turn_context) ? state.turn_context : nil
-      return instantiate_tools(allowed, ctx) if names.empty?
+      return instantiate_tools(allowed, state) if names.empty?
 
       # Dedup by the ENTRY NAME (registry key = impl_name) BEFORE
       # instantiating — the INSTANCE's `.name` (RubyLLM) is not the registration
       # name.
       direct = Array(allowed).reject { |e| e.respond_to?(:name) && names.key?(e.name.to_s) }
-      instantiate_tools(direct, ctx) + capability_tool_instances(names, ctx)
+      instantiate_tools(direct, state) + capability_tool_instances(names, state)
     end
 
     # Envelopes each allowed tool (per-call timeout + side-effect recording).
@@ -78,7 +77,7 @@ module Insika
         ToolEnvelope.new(tool, state: state, checkpoint_store: @checkpoint_store,
                                tool_registry: @tool_registry, timeout: timeout,
                                skip_side_effects: skip_side_effects,
-                               trace_recorder: @tool_trace_store)
+                               trace_recorder: @tool_trace_store, event_stream: @event_stream)
       end
     end
 
@@ -99,16 +98,19 @@ module Insika
       return unless state.respond_to?(:tool_gate) && state.respond_to?(:tool_concurrency)
 
       cap = state.tool_concurrency
-      state.tool_gate = cap ? Async::Semaphore.new(cap) : nil
+      state.tool_gate = cap && cap > 1 ? Async::Semaphore.new(cap) : nil
+      if state.respond_to?(:side_effect_gate=)
+        state.side_effect_gate = state.tool_gate ? Async::Semaphore.new(1) : nil
+      end
     end
 
     # Real Engine -> Entries (respond to factory); fakes -> ready instances.
     # `turn_context` is deposited into the instances that expose it
     # (data-tools); the rest ignore it (parity).
-    def instantiate_tools(allowed, turn_context = nil)
+    def instantiate_tools(allowed, state = nil)
       Array(allowed).map do |t|
         tool = t.respond_to?(:factory) ? t.factory.call : t
-        inject_turn_context(tool, turn_context)
+        inject_turn_context(tool, state)
         tool
       end
     end
@@ -116,22 +118,28 @@ module Insika
     # seam: deposits the turn context into the freshly created instance
     # (same idea as `remember`, which receives tenant/state) BEFORE the
     # ToolEnvelope. Duck-typed: only what exposes `turn_context=` (DataDefinedTool)
-    # receives it. nil (a state with no turn_context, e.g. a test stub) -> no-op.
-    def inject_turn_context(tool, turn_context)
-      return if turn_context.nil?
+    # receives it; a tool that exposes `turn_state=` (a presentation tool, which
+    # reads the ledger and the hoarded cards) receives the state itself. nil (a
+    # state with no turn_context, e.g. a test stub) -> no-op.
+    def inject_turn_context(tool, state)
+      return if state.nil?
+
+      tool.turn_state = state if tool.respond_to?(:turn_state=)
+      ctx = state.respond_to?(:turn_context) ? state.turn_context : nil
+      return if ctx.nil?
 
-      tool.turn_context = turn_context if tool.respond_to?(:turn_context=)
+      tool.turn_context = ctx if tool.respond_to?(:turn_context=)
     end
 
     # impl_name -> Capability::ResolvedTool(capability_name:), STILL without
     # ToolEnvelope (the call site's wrap_tools wraps the whole set — same
     # order impl -> ResolvedTool -> ToolEnvelope). entry already validated in
     # resolve_capabilities.
-    def capability_tool_instances(names, turn_context = nil)
+    def capability_tool_instances(names, state = nil)
       names.map do |impl_name, capability_name|
         entry = @tool_registry.entries.find { |e| e.name == impl_name }
         tool = entry.factory.call
-        inject_turn_context(tool, turn_context)
+        inject_turn_context(tool, state)
         Capability::ResolvedTool.new(tool, capability_name: capability_name,
                                            impl_name: impl_name)
       end

data/lib/insika/tool_batch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Insika
+  # The batch arithmetic behind every mid-turn `user` append.
+  #
+  # A model step that calls tools produces ONE assistant message announcing N
+  # tool calls, followed by N `role: tool` messages. Anthropic rejects a `user`
+  # message that lands between two of those results outright, so the ONLY valid
+  # append point inside a turn is the instant the Nth result closes the batch.
+  # SteerInjector discovered this rule; LoopDetector and TurnBudget both live by
+  # it, which is why the counting lives here instead of twice.
+  #
+  # Not a general-purpose helper: it answers one question ("did a batch just
+  # close?") and remembers one fact ("was this batch halted"), because a
+  # `halt_when` batch has no next model step and anything appended there would
+  # sit unread forever.
+  class ToolBatch
+    def initialize
+      @expected = nil # tool calls announced by the batch in flight (nil = none)
+      @seen = 0
+      @halted = false
+    end
+
+    # Feeds a RubyLLM message (duck-typed). True EXACTLY on the message that
+    # closes a batch of tool calls — the append boundary. Everything else,
+    # including the assistant message that opens the batch, is false.
+    def closed?(message)
+      role = field(message, :role).to_s
+      return open(message) if role == "assistant"
+      return false unless role == "tool" && @expected
+
+      @seen += 1
+      return false if @seen < @expected
+
+      @expected = nil
+      true
+    end
+
+    # From after_tool_result, with the RAW result: a Tool::Halt is only
+    # recognizable there.
+    def halt!(result)
+      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+    end
+
+    def halted? = @halted
+
+    private
+
+    # An assistant message with no tool calls is the model TALKING: the turn is
+    # ending, so nothing is in flight any more.
+    def open(message)
+      calls = field(message, :tool_calls)
+      size = calls.respond_to?(:size) ? calls.size : 0
+      @expected = size.zero? ? nil : size
+      @seen = 0
+      @halted = false
+      false
+    end
+
+    def field(message, name)
+      return message.public_send(name) if message.respond_to?(name)
+      return message[name] || message[name.to_s] if message.respond_to?(:[])
+
+      nil
+    end
+  end
+end