insika 0.8.0 → 1.0.1

data/lib/insika/tool_definition.rb

@@ -20,7 +20,7 @@ module Insika
   #     "group" => string|nil, "tags" => ["b2b",...] }  #//
   #
   # `parameters` is **JSON Schema** (the interlingua of OpenAI/Anthropic/MCP):
-  # a nestable object, fed straight into RubyLLM's `params_schema` (provider-
+  # a nestable object, fed straight into RubyLLM's `parameters_schema` (provider-
   # agnostic). The **flat array** (`[{name,type,required}]`) is SUGAR for the simple
   # case: it is lifted to JSON Schema at build time. The sugar covers scalars and
   # `array:<scalar>` — it CANNOT express an array of objects, and says so instead of
@@ -35,10 +35,17 @@ module Insika
   ToolDefinition = Data.define(
     :name, :description, :parameters, :request, :response,
     :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when,
-    :evidence                       # Insika::Evidence::Spec | nil
+    :evidence,                      # Insika::Evidence::Spec | nil
+    :requires_evidence,             # { "params" => [String] } | nil
+    :presentation                   # { component:, ids:, max: } | nil — a UI tool, no HTTP
   )
 
   class ToolDefinition
+    # Terminal tool results finish the current batch without another model request.
+    Halt = Data.define(:content) do
+      def to_s = content.to_s
+    end
+
     # Flat-sugar types: the SCALARS, plus `array:<scalar>` for a list. There is no bare
     # `array`: an array without an item type is an INCOMPLETE declaration, and the
     # engine refuses to guess one (see lift_flat_params).
@@ -73,9 +80,9 @@ module Insika
     # Builds + validates. Raises Insika::ValidationError. Accepts keyword args
     # (already-normalized symbol keys); use from_h for a raw Hash from the store/UI.
     # `parameters` accepts JSON Schema (Hash) OR the legacy flat array.
-    def self.build(name:, description:, request:, parameters: nil, response: nil,
+    def self.build(name:, description:, request: nil, parameters: nil, response: nil,
                    secret_headers: nil, side_effect: nil, timeout: nil, group: nil, tags: nil,
-                   halt_when: nil, evidence: nil)
+                   halt_when: nil, evidence: nil, presentation: nil, requires_evidence: nil)
       name = name.to_s
       raise Insika::ValidationError, "name must match #{NAME_RE.inspect}" unless NAME_RE.match?(name)
 
@@ -83,15 +90,21 @@ module Insika
       raise Insika::ValidationError, "description is required" if desc.empty?
 
       schema = normalize_params(parameters)
-      req = normalize_request(request, top_level_names(schema))
+      # A tool is EITHER an HTTP call or a presentation — never both, never neither.
+      if request && presentation
+        raise Insika::ValidationError, "a tool declares either 'request' or 'presentation', not both"
+      end
+
+      pres = normalize_presentation(presentation, schema)
+      req = pres ? nil : normalize_request(request || {}, top_level_names(schema))
       resp = normalize_response(response)
       if resp[:extract] == "evidence_envelope" && evidence.nil?
         raise Insika::ValidationError,
               "extract 'evidence_envelope' requires an 'evidence' declaration"
       end
 
-      method = req[:method]
-      effect = side_effect.nil? ? !IDEMPOTENT.include?(method) : (side_effect ? true : false)
+      method = req && req[:method]
+      effect = side_effect.nil? ? !(method.nil? || IDEMPOTENT.include?(method)) : (side_effect ? true : false)
 
       new(
         name: name, description: desc, parameters: schema, request: req, response: resp,
@@ -99,7 +112,9 @@ module Insika
         timeout: timeout.nil? ? nil : Integer(timeout),
         group: normalize_group(group), tags: normalize_tags(tags),
         halt_when: normalize_halt_when(halt_when),
-        evidence: Insika::Evidence::Spec.parse(evidence)
+        evidence: Insika::Evidence::Spec.parse(evidence),
+        presentation: pres,
+        requires_evidence: normalize_requires_evidence(requires_evidence, top_level_names(schema))
       )
     end
 
@@ -108,12 +123,64 @@ module Insika
       h = deep_symbolize(hash)
       build(
         name: h[:name], description: h[:description], parameters: h[:parameters],
-        request: h[:request] || {}, response: h[:response],
+        request: h[:request], response: h[:response],
         secret_headers: h[:secret_headers], side_effect: h[:side_effect], timeout: h[:timeout],
-        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence]
+        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence],
+        presentation: h[:presentation], requires_evidence: h[:requires_evidence]
       )
     end
 
+    # PRESENTATION: a tool whose job is to SHOW something, not to fetch it. The model
+    # picks ids, the engine validates them against the session's evidence ledger and
+    # joins the cards an evidence tool already returned (Tools::Present). No HTTP.
+    #
+    #   "presentation" => { "component" => "product_cards",   # what the channel renders
+    #                       "ids" => "product_ids",           # the array:string param
+    #                       "max" => 8 }                      # 1..16, the attachment cap
+    #
+    # -> { component:, ids:, max: } | nil
+    def self.normalize_presentation(raw, schema)
+      return nil if raw.nil?
+
+      h = deep_symbolize(raw)
+      raise Insika::ValidationError, "presentation must be an object" unless h.is_a?(Hash)
+
+      component = h[:component].to_s
+      unless NAME_RE.match?(component)
+        raise Insika::ValidationError, "presentation.component must match #{NAME_RE.inspect}"
+      end
+
+      ids = h[:ids].to_s
+      prop = (schema["properties"] || {})[ids]
+      unless prop.is_a?(Hash) && prop["type"] == "array" && prop.dig("items", "type") == "string"
+        raise Insika::ValidationError,
+              "presentation.ids must name a declared array:string parameter (got #{ids.inspect})"
+      end
+
+      max = h[:max].nil? ? Insika::Evidence::MAX_ATTACHMENTS : Integer(h[:max], exception: false)
+      unless max.is_a?(Integer) && max.between?(1, Insika::Evidence::MAX_ATTACHMENTS)
+        raise Insika::ValidationError, "presentation.max must be 1..#{Insika::Evidence::MAX_ATTACHMENTS}"
+      end
+
+      { component: component, ids: ids, max: max }
+    end
+    private_class_method :normalize_presentation
+
+    def presentation? = !presentation.nil?
+
+    # Public because an MCP tool has the same question to answer and there must be
+    # one reading of "these parameters may only carry an id some tool returned".
+    def self.normalize_requires_evidence(value, param_names)
+      return nil if value.nil?
+
+      params = value.is_a?(Hash) ? deep_symbolize(value)[:params] : value
+      unless params.is_a?(Array) && !params.empty? && params.all? { |p| param_names.include?(p.to_s) }
+        raise Insika::ValidationError, "requires_evidence needs a non-empty list of declared top-level parameters"
+      end
+
+      { "params" => params.map(&:to_s).uniq }
+    end
+
     # Group: enablement label by DATA (not name convention),
     # target of AgentProfile's `tools_allow_groups`. Trimmed; empty/nil -> nil.
     def self.normalize_group(group)
@@ -414,7 +481,7 @@ module Insika
       h = {
         "name" => name, "description" => description,
         "parameters" => parameters,
-        "request" => request.transform_keys(&:to_s),
+        "request" => request&.transform_keys(&:to_s),
         "response" => response.transform_keys(&:to_s),
         "secret_headers" => secret_headers,
         "side_effect" => side_effect, "timeout" => timeout,
@@ -424,6 +491,8 @@ module Insika
       # present only when declared — a tool without evidence is byte-identical
       # to today (no declaration, no envelope processing).
       h["evidence"] = evidence.to_h if evidence
+      h["requires_evidence"] = requires_evidence if requires_evidence
+      h["presentation"] = presentation.transform_keys(&:to_s) if presentation
       h
     end
 
@@ -479,7 +548,7 @@ module Insika
       nil
     end
 
-    # HOW `say` REACHES THE EXECUTOR. RubyLLM's `Tool::Halt` carries one value, and
+    # HOW `say` REACHES THE EXECUTOR. Insika::ToolDefinition::Halt carries one value, and
     # that value is the tool's payload (the trace records it, and the model never
     # sees it — the halt ends the loop). So a halt that has something to publish
     # carries BOTH, under keys distinctive enough that a trace reader knows what
@@ -513,7 +582,7 @@ module Insika
 
     # FLAT view of the top-level properties (name/type/description/required) — for
     # RubyLLM's `#parameters` (discovery/tool_search) and the simple authoring UI.
-    # The full nested schema goes through `params_schema` (DataDefinedTool). Symbol-
+    # The full nested schema goes through `parameters_schema` (DataDefinedTool). Symbol-
     # keyed for compat with callers that already consumed the flat params.
     def top_level_params
       props = parameters["properties"] || {}

data/lib/insika/tool_envelope.rb

@@ -9,9 +9,29 @@ module Insika
   # + recording of a non-idempotent side-effect BEFORE the result returns to the
   # model. Delegates everything else (name/description/params) to the real tool.
   #
-  # The tool loop belongs to RubyLLM; this is a decorator over the instances —
-  # the Executor never drives roundtrips.
+  # RubyLLM executes tools; this decorator enforces Insika's per-call policy.
   class ToolEnvelope < SimpleDelegator
+    # Fiber-local slot where a tool leaves its timing breakdown for this call's trace.
+    TIMING_KEY = :insika_tool_timing
+
+    PROVENANCE_INSTRUCTION = "This value was not returned by any tool in this conversation. " \
+                             "Find it with a tool that returns it — a search or a lookup by id — " \
+                             "then call this tool again with an id from that result."
+
+    # The words the model reads when a call is held. They are the only thing
+    # standing between a correct store and a customer who was told the opposite:
+    # the engine can refuse the write, it cannot refuse the sentence. Measured —
+    # one reply in twenty announced a held purchase as closed — so the reply's
+    # SHAPE is stated before anything else, and the lie is named concretely
+    # rather than as "do not say it happened".
+    CONFIRMATION_INSTRUCTION = "NOT DONE — nothing was written, and nothing will be until the customer " \
+                               "answers this very message. Your reply must ASK: say exactly what will " \
+                               "happen, with these arguments, and end with the question. A reply that " \
+                               "reports it as finished — 'done', 'closed', 'created', any past tense — is " \
+                               "false, and the customer will act on it. On their next message: if they " \
+                               "confirm, call confirm_pending with this pending_id; if they decline, " \
+                               "change anything, or ask for something else, call cancel_pending."
+
     # The tool timeout's OWN class: distinct from Async::TimeoutError so that
     # the rescue below NEVER swallows the TURN timeout (which uses the default of
     # with_timeout). Without this, a turn overflowing while the fiber is inside a
@@ -20,48 +40,122 @@ module Insika
     ToolTimeout = Class.new(StandardError)
     private_constant :ToolTimeout
 
+    # RubyLLM asks the tool's CLASS whether to defer its definition (tool
+    # search), and a delegator's class is this one. No Insika tool defers, so
+    # every envelope is sent as an ordinary tool.
+    def self.deferred? = false
+
+    # A gate's refusal. A plain Hash subclass: it reaches the model exactly as the
+    # `{status:, gate:, ...}` it always was, and the engine's own readers (the
+    # :tool_result outcome, the trace) recognize a refusal by CLASS — a data tool
+    # answering `{"status":"blocked","gate":"fraud_review"}` for a held order is
+    # not one, whatever keys it happens to use.
+    class Blocked < Hash; end
+
+    # A call held for the customer's confirmation. Same Hash-subclass trick as
+    # Blocked, and a different class on purpose: nothing was refused and nothing
+    # ran — the next customer message decides, through confirm_pending.
+    class Held < Hash; end
+
     def initialize(tool, state:, checkpoint_store:, tool_registry:, timeout:,
-                   skip_side_effects: [], trace_recorder: nil)
+                   skip_side_effects: [], trace_recorder: nil, event_stream: nil)
       super(tool)
       @state = state
       @checkpoint_store = checkpoint_store
       @tool_registry = tool_registry
       @timeout = timeout
-      @skip_side_effects = Array(skip_side_effects) # ids already completed in the interrupted turn
+      @event_stream = event_stream
+      @skip_side_effects = Array(skip_side_effects).dup # ids already completed in the interrupted turn
       @trace_recorder = trace_recorder # duck-type: #record(session_id:, entry:). nil = no trace.
     end
 
     # Entry point that RubyLLM invokes (Tool#call in the pinned version).
     # A timeout overflow returns to the MODEL as a serialized error — it does
     # not bring down the turn.
-    def call(args)
+    def call(args = {}, tool_call: nil, **kwargs)
+      @state.current_tool_call = tool_call if tool_call
+      run(args.merge(kwargs), hold: true, native_call: tool_call && native_approvals?)
+    end
+
+    def requires_approval? = native_approvals? && approval_required?
+
+    def approval_tool_name = real_name
+
+    # RubyLLM queries this while inspecting and partitioning pending calls.
+    # Keep it read-only; policy refusals still return through #call as tool results.
+    def approval_resolver
+      ->(call) do
+        next true if @skip_side_effects.include?(call.id.to_s) || provenance_block(call.arguments) || customer_confirm?
+
+        native_approval_decision(call.arguments, call.id)
+      end
+    end
+
+    # The confirmed re-run of a held call (Tools::ConfirmPending): every check but
+    # the hold itself — provenance, approval, fencing, evidence, the side-effect
+    # record and the trace all still apply to the write.
+    def call_confirmed(args) = run(args, hold: false)
+
+    private
+
+    def run(args, hold:, native_call: false)
       # A non-idempotent tool call ALREADY COMPLETED in the interrupted
       # turn -> respond with a marker, NEVER re-execute. The marker returns to
       # the model, keeping the tool-use protocol intact.
       call_id = correlation_id
-      return { "skipped" => "already_executed" } if call_id && @skip_side_effects.include?(call_id)
-
-      # Approval gate: a tool marked `approval` suspends the turn in
-      # :waiting until the operator resolves it. Delegates to the coordinator (the
-      # Executor), which creates/queries the PendingAction and blocks via the
-      # mailbox. Rejection returns to the MODEL as an error (the turn continues),
-      # it does not bring down the turn. CancelledError/TimeoutError from the wait
-      # propagate (they are not ToolTimeout).
+      continuation = native_call && @state.approval_continuation
+      if call_id && @skip_side_effects.include?(call_id)
+        halt = continuation && continuation.dig("halts", call_id)
+        return ToolDefinition::Halt.new(content: halt["content"]) if halt
+
+        return { "skipped" => "already_executed" }
+      end
+
+      started = monotonic
+      if (blocked = provenance_block(args))
+        trace(call_id, args, blocked, started)
+        emit_blocked(blocked)
+        return blocked
+      end
+
+      # Customer confirmation: the call is recorded and returned to the model as
+      # held; the turn goes on to ask. After the provenance gate (an id the customer
+      # never saw is not put to them as real) and before approval.
+      if hold && (held = confirmation_hold(args))
+        trace(call_id, args, held, started)
+        return held
+      end
+
+      # Native calls recheck the persisted decision after RubyLLM's resolver.
+      # Direct/workflow calls still create and await approval through the mailbox.
+      # Cancellation and turn timeout propagate from that wait (not ToolTimeout).
       if approval_required?
-        decision = @state.approval_coordinator.request_approval(
-          task: @state.task, turn: @state.turn, tool: real_name, args: args, actor: @state.actor
-        )
-        return { error: "rejected by operator" } unless decision.to_s == "approved"
+        approved = if native_call
+          native_approval_decision(args, call_id) == true
+        else
+          @state.approval_coordinator.request_approval(
+            task: @state.task, turn: @state.turn, tool: real_name, args: args, actor: @state.actor
+          ).to_s == "approved"
+        end
+        return { error: "rejected by operator" } unless approved
       end
 
       started = monotonic
-      result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { __getobj__.call(args) } }
+      Thread.current[TIMING_KEY] = nil
+      result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { invoke(args) } }
       # the ONE seam every tool result passes on its way to the model.
       # For a declared-evidence tool: reshape to the lean envelope, record the ids
       # on the ledger, hoard the attachments. No evidence = the result passes
       # through untouched (one nil-check — parity).
+      capture_shared_result(call_id, result)
       result = process_evidence(result)
-      record_side_effect!(call_id) if side_effect?
+      result = fence(result)
+      if side_effect?
+        halt = { "content" => result.content } if continuation && result.is_a?(ToolDefinition::Halt)
+        record_side_effect!(call_id, **(halt ? { halt: halt } : {}))
+        (continuation["halts"] ||= {})[call_id] = halt if halt
+        @skip_side_effects << call_id if native_call
+      end
       trace(call_id, args, result, started)
       result
     rescue ToolTimeout
@@ -70,10 +164,17 @@ module Insika
       err
     end
 
-    private
-
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+    def invoke(args)
+      tool = __getobj__
+      if tool.respond_to?(:parameters_schema)
+        tool.call(**args.transform_keys(&:to_sym), tool_call: @state.current_tool_call)
+      else
+        tool.call(args)
+      end
+    end
+
     # with parallel tool calls on, the turn's shared semaphore
     # (TurnState#tool_gate, sized by `limits[:tool_concurrency]`) caps how many run
     # at once. Wraps the REAL call ONLY — the approval wait and the skip check are
@@ -83,21 +184,120 @@ module Insika
     # wall-clock the model waited. No gate (the default, serial) = straight through.
     def with_gate(&)
       gate = @state.respond_to?(:tool_gate) ? @state.tool_gate : nil
-      gate ? gate.acquire(&) : yield
+      return yield unless gate
+
+      serial = @state.respond_to?(:side_effect_gate) ? @state.side_effect_gate : nil
+      return gate.acquire(&) unless side_effect? && serial
+
+      # Backends may read-modify-write. Serialize writes before taking a slot,
+      # so queued writes cannot keep independent reads from running.
+      serial.acquire { gate.acquire(&) }
+    end
+
+    def provenance_block(args)
+      tool = __getobj__
+      requirement = tool.respond_to?(:requires_evidence) ? tool.requires_evidence : nil
+      return unless requirement
+
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      known = ledger ? ledger.ids : []
+      optional = optional_params(tool)
+      requirement.fetch("params").each do |param|
+        value = args.key?(param) ? args[param] : args[param.to_sym]
+        # A parameter the schema marks optional and the model left out carries no
+        # id to ground — nothing to check (a REQUIRED one left out is still a
+        # block: the write would run without the id the gate exists for).
+        next if value.nil? && ledger && optional.include?(param)
+
+        values = value.is_a?(Array) ? value : [value]
+        values = [nil] if values.empty? && !ledger
+        values.each do |id|
+          next if ledger && known.include?(id.to_s)
+
+          return Blocked[{ "status" => "blocked", "gate" => "provenance", "param" => param,
+                           "value" => id.to_s, "instruction" => PROVENANCE_INSTRUCTION }]
+        end
+      end
+      nil
+    end
+
+    # The wrapped tool's top-level parameters NOT in the schema's `required`
+    # (DataDefinedTool exposes its definition's schema; a code tool exposes none
+    # -> every declared parameter is treated as required).
+    def optional_params(tool)
+      return [] unless tool.respond_to?(:parameters_schema) && (schema = tool.parameters_schema).is_a?(Hash)
+
+      schema = Coercion.deep_stringify(schema)
+
+      (schema["properties"] || {}).keys.map(&:to_s) - Array(schema["required"]).map(&:to_s)
+    end
+
+    def confirmation_hold(args)
+      return unless customer_confirm?
+
+      store = @state.respond_to?(:pending_action_store) ? @state.pending_action_store : nil
+      task = @state.task
+      if store.nil? || task.nil? || task.session_id.nil?
+        # Fail loud, never run: a write that needs the customer's word and has
+        # nowhere to wait for it is a misconfiguration, not a pass.
+        missing = store.nil? ? "no PendingActionStore" : "no session"
+        raise Insika::Error, "tool '#{real_name}' needs the customer's confirmation but the turn has #{missing} to hold it in"
+      end
+
+      id = PendingActionStore.confirmation_id(task.session_id, real_name)
+      store.create(id: id, task_id: task.id, session_id: task.session_id, turn: @state.turn,
+                   tool: real_name, args: args || {}, kind: PendingActionStore::CUSTOMER)
+      @event_stream&.emit(Insika::Event.new(
+        type: :confirmation_requested,
+        data: { pending_id: id, tool: real_name, args: args },
+        meta: { task_id: task.id, session_id: task.session_id }
+      ))
+      # Key order is what the model reads first: the verdict, then the instruction,
+      # then the echo of what it asked for — the echo alone reads like a success.
+      Held[{ "executed" => false, "status" => "pending_confirmation", "gate" => "confirmation",
+             "instruction" => CONFIRMATION_INSTRUCTION, "tool" => real_name, "args" => args,
+             "pending_id" => id }]
+    end
+
+    def customer_confirm?
+      profile = @state.respond_to?(:profile) ? @state.profile : nil
+      list = profile.respond_to?(:customer_confirm) ? profile.customer_confirm : nil
+      Array(list).include?(real_name)
+    end
+
+    def emit_blocked(result)
+      task = @state.task # nil on a one-shot turn, like `trace` already assumes
+      @event_stream&.emit(Insika::Event.new(
+        type: :tool_blocked,
+        data: { name: real_name, gate: result["gate"], param: result["param"] },
+        meta: task ? { task_id: task.id, session_id: task.session_id } : {}
+      ))
     end
 
     # Records the call for debugging in the Studio (name + model args + result +
     # ms), keyed by the SESSION. Masking/truncation is the ToolTraceStore's job;
     # here we only collect. NEVER breaks the turn (trace is observability).
+    def capture_shared_result(call_id, result)
+      return unless @state.respond_to?(:shared_conversations) && @state.shared_conversations
+
+      @state.shared_conversations.record_tool_result(task: @state.task, call_id: call_id, result: result)
+    end
+
     def trace(call_id, args, result, started)
+      capture_shared_result(call_id, result)
+      timing = Thread.current[TIMING_KEY] || {}
+      Thread.current[TIMING_KEY] = nil
+      ms = started ? ((monotonic - started) * 1000).round : nil
+      TurnTiming.current&.tool(real_name, ToolTraceStore.ok?(result), ms)
       return unless @trace_recorder && @state.task&.session_id
 
       @trace_recorder.record(
         session_id: @state.task.session_id,
-        entry: { "turn" => @state.turn, "tool" => real_name, "call_id" => call_id.to_s,
+        entry: { "task_id" => @state.task.id.to_s, "turn" => @state.turn, "tool" => real_name, "call_id" => call_id.to_s,
                  "args" => args, "result" => result,
-                 "ms" => started ? ((monotonic - started) * 1000).round : nil,
-                 "at" => Time.now.utc.iso8601 }
+                 "gate" => result.is_a?(Blocked) || result.is_a?(Held) ? result["gate"] : nil,
+                 "ms" => ms,
+                 "at" => Time.now.utc.iso8601 }.merge(timing)
       )
     rescue StandardError
       nil
@@ -114,8 +314,18 @@ module Insika
     # Does the current tool require approval? (names come from the Resolution
     # via state).
     def approval_required?
-      @state.respond_to?(:requires_approval) &&
-        Array(@state.requires_approval).include?(real_name)
+      (@state.respond_to?(:requires_approval) && Array(@state.requires_approval).include?(real_name)) ||
+        (__getobj__.respond_to?(:requires_approval?) && __getobj__.requires_approval?)
+    end
+
+    def native_approvals?
+      @state.respond_to?(:native_approvals) && @state.native_approvals == true
+    end
+
+    def native_approval_decision(args, call_id)
+      @state.approval_coordinator.approval_decision(
+        task: @state.task, turn: @state.turn, tool: real_name, args: args, call_id: call_id
+      )
     end
 
     # The call's correlation: the provider id (RubyLLM chat, via
@@ -135,11 +345,36 @@ module Insika
     end
 
     # Written BEFORE the tool result returns to the model.
-    def record_side_effect!(call_id)
+    def record_side_effect!(call_id, **metadata)
       return if call_id.to_s.empty?
 
       @checkpoint_store.record_side_effect(@state.task.id, turn: @state.turn,
-                                                           tool_call_id: call_id)
+                                                           tool_call_id: call_id, **metadata)
+    end
+
+    # ----   fencing ----------------------------------------------
+
+    # After the evidence reshape (the lean envelope is already the shape the
+    # model reads): every String leaf sanitized, keys and non-strings untouched,
+    # each leaf capped at the platform's `fencing.max_chars`. Off = bytes
+    # identical to today. An error hash is engine-authored — never touched.
+    def fence(result)
+      return result unless Insika::Fence.enabled?(@state.profile)
+      return result if result.is_a?(Hash) && (result[:error] || result["error"])
+
+      max = (@state.respond_to?(:fence_max_chars) && @state.fence_max_chars) || Insika::Fence::DEFAULT_MAX_CHARS
+      return Insika::Fence.sanitize_value(result, max_chars: max) unless lean_evidence?(result)
+
+      # A lean evidence result: the LINES are third-party text, the IDS are keys.
+      # The ledger recorded the ids byte-exact and a presentation or a write joins
+      # on them, so NFKC must not touch them (a fullwidth digit in a SKU would
+      # stop matching the moment the model repeated it).
+      items = result["items"].map { |i| i.merge("line" => Insika::Fence.sanitize_text(i["line"].to_s, max_chars: max)) }
+      result.merge("items" => items)
+    end
+
+    def lean_evidence?(result)
+      evidence_spec && result.is_a?(Hash) && result["items"].is_a?(Array)
     end
 
     # ----   evidence ---------------------------------------------
@@ -204,6 +439,8 @@ module Insika
 
       @state.evidence_attachments ||= []
       @state.evidence_attachments.concat(attachments)
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      ledger.record_cards(attachments) if ledger.respond_to?(:record_cards)
     end
   end
 end

data/lib/insika/tool_manifest.rb

@@ -73,6 +73,7 @@ module Insika
         "response" => binding[:response],
         "secret_headers" => binding[:secret_headers],
         "side_effect" => t["side_effect"],
+        "timeout" => t["timeout"],
         "group" => t["group"] || defaults["group"],       # per-group allowlist:
         "tags" => (Array(defaults["tags"]) | Array(t["tags"])), # inherited default; tags unioned
         # Per-tool only: "this result ends the turn" is a property of THIS backend's

data/lib/insika/tool_store.rb

@@ -35,6 +35,9 @@ module Insika
     # -> [String] names, lexicographic order.
     def names = @cs.keys(SCOPE)
 
+    # Changes whenever any config is written, in any process (ConfigStore#version_token).
+    def version_token = @cs.version_token
+
     # -> [Hash] MASKED definitions (for the UI).
     def all
       names.filter_map { |n| get(n) }
@@ -55,10 +58,13 @@ module Insika
       raise Insika::ValidationError, "tool '#{name}' already exists" if create_only && existing
 
       final = definition.to_h
-      final["request"]["headers"] = reconcile_secret_headers(
-        final["request"]["headers"], definition.secret_headers,
-        existing&.dig("definition", "request", "headers")
-      )
+      # A presentation tool makes no request — nothing to reconcile.
+      if final["request"]
+        final["request"]["headers"] = reconcile_secret_headers(
+          final["request"]["headers"], definition.secret_headers,
+          existing&.dig("definition", "request", "headers")
+        )
+      end
 
       rec = build_record(final, existing)
       @cs.put(SCOPE, name, rec)
@@ -110,6 +116,8 @@ module Insika
       secret = definition["secret_headers"] || []
       return definition if secret.empty?
 
+      return definition unless definition["request"]
+
       headers = (definition.dig("request", "headers") || {}).each_with_object({}) do |(k, v), acc|
         acc[k] = secret.include?(k) ? SecretMasking.mask(v) : v
       end

data/lib/insika/tool_trace_store.rb

@@ -37,6 +37,11 @@ module Insika
       nil
     end
 
+    # Conventional tool error = Hash with key "error"/:error (everything else is ok).
+    def self.ok?(result)
+      !(result.is_a?(Hash) && (result.key?("error") || result.key?(:error)))
+    end
+
     # -> [Hash] session entries in chronological order. [] if none.
     def for_session(session_id) = @store.get(SCOPE, session_id.to_s) || []
 
@@ -49,19 +54,21 @@ module Insika
       e = stringify_keys(entry)
       {
         "turn" => e["turn"], "tool" => e["tool"].to_s, "call_id" => e["call_id"].to_s,
-        "ok" => ok?(e["result"]),
+        "ok" => self.class.ok?(e["result"]),
         "args" => clip(mask(e["args"])), "result" => clip(mask(e["result"])),
         "ms" => e["ms"], "at" => e["at"].to_s
-      }
-    end
-
-    # Conventional tool error = Hash with key "error"/:error (everything else is ok).
-    def ok?(result)
-      !(result.is_a?(Hash) && (result.key?("error") || result.key?(:error)))
+      }.tap do |trace|
+        trace["task_id"] = e["task_id"].to_s if e["task_id"]
+        trace["gate"] = e["gate"].to_s if e["gate"]
+        # Timing breakdown a data-tool reports (see DataDefinedTool#record_timing).
+        %w[pre_ms http_ms server_ms].each { |k| trace[k] = e[k] if e[k].is_a?(Integer) }
+      end
     end
 
     # Masks values of sensitive keys (recursive); the rest pass through intact.
-    def mask(obj)
+    def mask(obj) = self.class.mask(obj)
+
+    def self.mask(obj)
       case obj
       when Hash
         obj.each_with_object({}) do |(k, v), acc|