insika 0.8.0 → 0.9.0

data/lib/insika/prefix_fingerprint.rb

@@ -9,47 +9,52 @@ module Insika
   # (name + description + parameters.inspect, executor.rb:957). Outputs are
   # PII-free digests: it never sees message text, only hashes leave this class.
   # Pure stdlib (digest/sha2), no gem, no IO.
+  #
+  # The chain follows the cache boundary: the cumulative "prefix" is over the
+  # IDENTITY categories + tool_schemas only — the bytes the cache breakpoint
+  # actually covers. Volatile categories (memory, knowledge, briefing, request)
+  # render below the breakpoint, so a change there is not a prefix invalidation;
+  # they still get their own digest (the trace shows them) but sit AFTER the
+  # "prefix" key, outside the chain.
   class PrefixFingerprint
     # -> { "prompt" => "sha256…", …, "tool_schemas" => "sha256…",
-    #      "prefix" => "sha256…" }
-    # Keys are the demodulized, downcased provider ids, in render order.
+    #      "prefix" => "sha256…", "memory" => "sha256…", … }
+    # Keys are the demodulized, downcased provider ids. Order: identity
+    # categories (render order), "tool_schemas", "prefix", then the volatile
+    # categories — everything before "prefix" is the chain.
     # A category with no fragments is absent (not an empty hash).
     # The category digest = SHA256 of the category's fragments joined "\n\n"
     # (the Builder's separator — the digest matches rendered bytes).
-    # "prefix" = SHA256 of the category digests concatenated IN CHAIN ORDER
-    # (identity categories, then volatile, then tool_schemas) — any divergence
-    # anywhere above the boundary changes it.
+    # "prefix" = SHA256 of the chain digests concatenated in order — any
+    # divergence anywhere above the boundary changes it. A fragment with no
+    # layer stamp reads as volatile, like everywhere else.
     def self.compute(system_fragments, tool_serial:)
-      digests = {} # category name -> digest, insertion = render order
-      grouped = system_fragments.group_by { |f| category(f.source) }
-      grouped.each do |name, frags|
-        digests[name] = digest(frags.map(&:content).join("\n\n"))
-      end
+      identity, volatile = system_fragments.partition { |f| (f.layer || :volatile) == :identity }
+      digests = category_digests(identity)
       digests["tool_schemas"] = digest(tool_serial.to_s) unless tool_serial.nil?
       digests["prefix"] = digest(digests.values.join) unless digests.empty?
-      digests
+      digests.merge(category_digests(volatile))
     end
 
-    # -> String | nil. The first category (in CURRENT chain order) whose digest
-    # differs or is absent from `previous`; else the first PREVIOUS key now
-    # absent from the current chain (a vanished block is a divergence too);
-    # else nil. nil `previous` (first turn) -> nil. The returned name is a
-    # category id — PII-free by construction.
-    #
-    # The cumulative "prefix" key is deliberately SKIPPED in the scan: its
-    # digest changes whenever ANY category moves, so scanning it would shadow a
-    # vanished block (every surviving category matches, "prefix" differs, and
-    # the vanished-fallback below becomes unreachable — reporting `broke:
-    # prefix` instead of the category that actually left).
+    # -> String | nil. nil when the cumulative "prefix" did not move (a
+    # volatile change is not an invalidation). Else the first chain category
+    # (in CURRENT chain order) whose digest differs or is absent from
+    # `previous`; else the first PREVIOUS chain key now absent from the current
+    # chain (a vanished block is a divergence too). nil `previous` (first turn)
+    # -> nil. The returned name is a category id — PII-free by construction.
     def self.invalidation_reason(current, previous)
       return nil unless previous.is_a?(Hash)
+      return nil if current["prefix"] == previous["prefix"]
 
-      current.each_key do |name|
-        next if name == "prefix"
+      chain(current).find { |name| previous[name] != current[name] } ||
+        (chain(previous) - current.keys).first
+    end
+
+    def self.chain(map) = map.keys.take_while { |k| k != "prefix" }
 
-        return name unless previous[name] == current[name]
-      end
-      (previous.keys - current.keys).first
+    def self.category_digests(fragments)
+      fragments.group_by { |f| category(f.source) }
+               .transform_values { |frags| digest(frags.map(&:content).join("\n\n")) }
     end
 
     def self.category(source) = source.to_s.split("::").last.to_s.downcase

data/lib/insika/profile_source.rb

@@ -115,6 +115,7 @@ module Insika
         # only a stored explicit false turns the discipline block off.
         tool_persistence: h[:tool_persistence],
         tool_output_compression: h[:tool_output_compression],
+        fencing: h[:fencing],
         # params/model_policy: the resolver tolerates string keys from
         # the JSON round-trip (ModelResolver#normalize_params / ModelPolicy), so no
         # re-symbolization needed here.

data/lib/insika/server/app.rb

@@ -56,8 +56,13 @@ module Insika
                      config:, pending_action_store: nil, a2a: nil, provisioner: nil,
                      workflow_registry: nil, onboarding: nil, profiles: nil,
                      channels: nil, logger: nil, token_store: nil, outcome_store: nil,
-                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil)
+                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil,
+                     settings_store: nil)
         @command_bus = command_bus
+        # READ for one gate: `POST /v1/conversations/:id/seed` answers only while
+        # the platform setting `evals.seeding` is on. nil = no settings = seeding
+        # off (fail-closed — the base wiring has no SettingsStore and cannot seed).
+        @settings_store = settings_store
         @event_stream = event_stream
         @session_store = session_store
         @task_store = task_store
@@ -132,6 +137,8 @@ module Insika
         error_response(422, e)
       rescue Insika::NotFoundError => e
         error_response(404, e)
+      rescue Insika::ConflictError => e
+        error_response(409, e) # the write contradicts existing state (a seed on a used conversation)
       rescue Async::TimeoutError => e
         error_response(504, e) # synchronous control request exceeded the ceiling
       rescue StandardError => e
@@ -186,6 +193,8 @@ module Insika
           handle_trigger_workflow(req, name)
         in ["POST", ["v1", "responses"]]
           handle_responses(req)
+        in ["POST", ["v1", "conversations", id, "seed"]]
+          handle_seed(req, id)
         in ["POST", ["v1", "outcomes"]] if @outcome_store
           handle_record_outcome(req)
         in ["GET", ["v1", "outcomes"]] if @outcome_store
@@ -427,6 +436,38 @@ module Insika
                               tenant: tenant)
       end
 
+      # POST /v1/conversations/:id/seed — loads the snapshot an eval case starts from
+      # (its `state:` — evidence ids, memory facts/notes, history, briefing fields)
+      # into the conversation BEFORE its first turn. Body = the state mapping, plus an
+      # optional `customer` (the memory scope the turns will carry). Same Bearer as
+      # /v1/responses and the same id namespacing for a tenant, so the seeded session
+      # IS the one the turn continues. 200 {session}; 409 when the conversation
+      # already has messages (seeding a used one is a test bug, not a merge).
+      #
+      # Refused (auth error) unless the platform setting `evals.seeding` is on. A seeded
+      # conversation is a fabricated precondition written under the tenant token:
+      # right on the machine running snapshot evals, wrong in production — so the
+      # default is off and the doctor warns while it is on.
+      def handle_seed(req, id)
+        return auth_error(403, "seeding is off (settings evals.seeding)") unless seeding_enabled?
+
+        body = parse_body(req)
+        tenant = req_tenant(req)
+        # the conversation id as the TURN will send it in `user` — the path
+        # segment arrives percent-encoded (the eval transport encodes "loja:c1").
+        conv = URI.decode_www_form_component(id)
+        payload = { id: scoped_session_id(tenant, conv), state: body.except(:customer) }
+        (customer = Insika::Coercion.presence(body[:customer])) && (payload[:customer] = customer)
+        command = Insika::Command.build(:seed_session, payload, transport: :http, tenant: tenant)
+        session = dispatch_with_timeout(command)
+        json_response(200, { session: session.to_h })
+      end
+
+      def seeding_enabled?
+        settings = @settings_store&.get
+        settings.is_a?(Hash) && (settings["evals"] || {})["seeding"] == true
+      end
+
       # POST /v1/agents — provisions (upserts) an agent from a standardized
       # PACK. Same Bearer as /v1/responses (gateway_token,
       # fail-closed). The consumer (GatewayClient/ProvisionStore) sends the pack as
@@ -625,6 +666,7 @@ TENANT_SURFACES = [
         ["POST", ["v1", "sessions"]],
         ["POST", ["v1", "messages"]],
         ["POST", ["v1", "responses"]],
+        ["POST", ["v1", "conversations", nil, "seed"]],
         ["POST", ["v1", "outcomes"]],
         ["GET", ["v1", "outcomes"]],
         ["POST", ["v1", "workflows", nil]],

data/lib/insika/server/rack_app.rb

@@ -80,6 +80,8 @@ module Insika
           outcome_store: @graph.outcome_store,
           # GET/PUT/DELETE /v1/mcp[/:name] — the config surface.
           mcp_store: @rt.component(:mcp_store),
+          # POST /v1/conversations/:id/seed answers only while `evals.seeding` is on.
+          settings_store: @rt.component(:settings_store),
           # a 500's error_ref must be findable in the process log.
           logger: $stdout
         )

data/lib/insika/server/responses.rb

@@ -95,7 +95,7 @@ module Insika
       end
 
       # Turn Event -> OpenAI Responses SSE frame | nil (event with no
-      # counterpart: :task_started, :tool_result, :skill_activated, ...).
+      # counterpart: :task_started, :skill_activated, ...).
       # Terminal events emit the final frame + `[DONE]` (close the stream).
       def frame_for(event)
         case event.type
@@ -103,9 +103,27 @@ module Insika
           sse("response.output_text.delta",
               { type: "response.output_text.delta", delta: event.data[:delta].to_s })
         when :tool_call
-          sse("response.output_item.added",
-              { type: "response.output_item.added",
-                item: { type: "function_call", name: event.data[:name].to_s } })
+          item = { type: "function_call", name: event.data[:name].to_s }
+          # The provider's call id, as the OpenAI item carries it: `added` and `done`
+          # are TWO frames of ONE call, and a consumer pairs them by this. Absent when
+          # the emitter had none.
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          # The call's arguments, as the OpenAI item carries them (a JSON string).
+          # Absent when the emitter had none to report.
+          (args = event.data[:arguments]) && (item[:arguments] = args.is_a?(String) ? args : JSON.generate(args))
+          sse("response.output_item.added", { type: "response.output_item.added", item: item })
+        when :tool_result
+          # How the call ENDED — ok / error / blocked (+ the gate that held it). Until
+          # this frame the stream carried tool NAMES only, so nothing outside the
+          # process could tell "the tool ran" from "a gate refused it" or "it errored".
+          # The result body itself stays inside: it is the model's input, not the
+          # consumer's answer. Same `call_id` as the `added` frame — a consumer that
+          # counts calls counts `added`, not both.
+          item = { type: "function_call", name: event.data[:name].to_s,
+                   status: (event.data[:status] || "ok").to_s }
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          (gate = event.data[:gate]) && (item[:gate] = gate.to_s)
+          sse("response.output_item.done", { type: "response.output_item.done", item: item })
         when :task_completed
           completed(event) + done
         when :task_failed
@@ -149,6 +167,15 @@ module Insika
           # Studio + the trace. Explicit (not a fall-through) to keep the closed
           # catalog honest.
           nil
+        when :ui
+          # A presentation tool's selection: what the customer should SEE alongside
+          # the answer. Namespaced like `insika.intermediate` — no OpenAI Responses
+          # counterpart, unknown to strict clients, safely ignored. `items` are the
+          # cards the engine validated and joined (id/url/caption); `dropped` is what
+          # the model asked for and could not be shown, with the reason.
+          sse("insika.ui", { type: "insika.ui", component: event.data[:component].to_s,
+                             title: event.data[:title], items: Array(event.data[:items]),
+                             count: event.data[:count].to_i, dropped: Array(event.data[:dropped]) })
         when :ttft
           # the live TTFB signal (WS6, INSIKA_TURN_TIMING opt-in): the provider's
           # ms-to-first-token, emitted when the first content chunk arrives.

data/lib/insika/session_store.rb

@@ -101,12 +101,15 @@ module Insika
     # appends this turn's evidence (ids + ungrounded delta) to the
     # session record. RMW like append_messages — the SessionActor serializes
     # same-session turns; the copy is in the method comment.
-    def append_evidence(id, ids:, ungrounded:)
+    def append_evidence(id, ids:, ungrounded:, cards: [])
       record = fetch!(id)
       ev = record["evidence"] ||= { "ids" => [], "ungrounded" => 0 }
       fresh = (ev["ids"] + Array(ids).map(&:to_s).reject(&:empty?)).uniq.last(EvidenceLedger::MAX_IDS)
       ev["ids"] = fresh
       ev["ungrounded"] = ev["ungrounded"].to_i + ungrounded.to_i
+      # the cards those ids came with (one per id, newest wins) — what a
+      # presentation tool joins on in a LATER turn. Absent until a card arrives.
+      ev["cards"] = EvidenceLedger.merge_cards(ev["cards"], cards) unless Array(cards).empty?
       record["updated_at"] = timestamp
       @store.set(SCOPE, key_for(id), record)
       to_session(record)

data/lib/insika/settings_store.rb

@@ -38,6 +38,10 @@ module Insika
       # = parity (nothing runs). Additive keys — reads overlay DEFAULTS.
       "compaction" => { "enabled" => false, "keep_last" => 20,
                         "compact_after" => 40, "model" => nil },
+      # Fencing (per-agent `fencing` flag): the cap on ONE string leaf of a tool
+      # result after sanitizing. Platform-wide — the leaf size is a context-budget
+      # concern, not a persona one. Additive key — reads overlay DEFAULTS.
+      "fencing" => { "max_chars" => 12_000 },
       # Data lifecycle (WS8, phase 2): the RETENTION window in days. The
       # tick's Retention sweep purges sessions (+traces), terminal tasks
       # (+checkpoints), memory cells and outcomes older than this. nil/0 =
@@ -81,7 +85,12 @@ module Insika
         "aggregate" => "median",
         "min_agreement" => 0.5,
         "quorum" => 1,
-        "tolerance" => 0.05
+        "tolerance" => 0.05,
+        # seeding -> opens POST /v1/conversations/:id/seed, the route a snapshot eval
+        #            loads a case's `state:` through. OFF by default: a seeded
+        #            conversation is a fabricated precondition, and production must
+        #            not accept one under the tenant token. The doctor warns when on.
+        "seeding" => false
       },
       # Edge limits — the platform layer of the EdgeLimiter.
       # nil/0 = off (opt-in). chat_rate_limit = turn attempts per chat per

data/lib/insika/spoken_transcript.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Insika
+  # The transcript slice an EXTRACTOR reads — memory distillation, knowledge
+  # extraction. Only what people said: `user` and `assistant` prose. A
+  # `role: tool` message is a product description, a search result, an FAQ body
+  # — third-party text; a customer fact or a learned concept distilled from it
+  # is a defect, not a behaviour to preserve. Tool-call payloads never render
+  # either (only `content` does). Indices are the ORIGINAL message positions,
+  # so a proposal's `turns` still point at the right message.
+  module SpokenTranscript
+    module_function
+
+    ROLES = %w[user assistant].freeze
+
+    # -> String, PII-redacted (what reaches the utility model follows the same
+    # redaction rule as what gets persisted). Messages are store records: string
+    # keys, like everything at the persistence boundary.
+    def render(messages)
+      lines = Array(messages).each_with_index.filter_map do |m, i|
+        role = m["role"].to_s
+        content = m["content"].to_s
+        next unless ROLES.include?(role) && !content.strip.empty?
+
+        "[#{i}] #{role}: #{content}"
+      end
+      redacted, = Insika::Safety::Detectors.redact(lines.join("\n"))
+      redacted
+    end
+  end
+end

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
 

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):

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/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

@@ -41,7 +41,7 @@ module Insika
       # renaming one breaks every dashboard built on it.
       class Instruments
         attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration,
-                    :cache_hit_rate, :loop_intervened, :context_compacted
+                    :cache_hit_rate, :loop_intervened, :context_compacted, :tool_blocked
 
         def initialize(meter)
           @turns = meter.create_counter("insika.turns", unit: "{turn}",
@@ -60,6 +60,8 @@ module Insika
                                                                             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
@@ -81,6 +83,7 @@ module Insika
         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)
@@ -206,6 +209,15 @@ module Insika
         @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.

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