insika 0.0.1 → 0.2.0

data/lib/insika/tools/concurrency.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+
+module Insika
+  module Tools
+    # Fan-out INSIDE a single tool (§): when a tool must gather N
+    # independent I/O calls (stock + price + promo + delivery) into ONE result,
+    # `gather` runs them CONCURRENTLY on the turn's reactor and returns their values
+    # IN ORDER. Because a data-tool spends its time on the HTTP wait, those waits
+    # overlap → wall-clock ≈ the slowest call, not the sum.
+    #
+    # This is the "aggregator tool" pattern: the model makes ONE tool call and the
+    # concurrency is an implementation detail of that tool — no change to the agent
+    # loop, no dependency on parallel tool execution. Use it in a custom
+    # Ruby tool's #execute:
+    #
+    #   def execute(store_id:)
+    #     stock, price, promo = Insika::Tools::Concurrency.gather(
+    #       -> { fetch_stock(store_id) },
+    #       -> { fetch_price(store_id) },
+    #       -> { fetch_promo(store_id) }
+    #     )
+    #     { stock:, price:, promo: }
+    #   end
+    #
+    # Bounded by `max` concurrent (default 8) to respect upstream rate limits. Runs
+    # correctly whether or not there is already a reactor (a tool runs inside the
+    # turn's Async fiber; `Sync` reuses it, and starts one otherwise for tests).
+    module Concurrency
+      DEFAULT_MAX = 8
+
+      module_function
+
+      # blocks: callables (procs/lambdas) or a block yielding an index. Returns an
+      # Array of results aligned to the input order. An exception in any block
+      # propagates (the caller decides how to degrade — this helper does not swallow).
+      def gather(*blocks, max: DEFAULT_MAX)
+        blocks = blocks.flatten
+        return [] if blocks.empty?
+
+        results = Array.new(blocks.size)
+        Sync do
+          semaphore = Async::Semaphore.new([max, blocks.size].min)
+          blocks.each_with_index.map do |blk, i|
+            semaphore.async { results[i] = blk.call }
+          end.each(&:wait)
+        end
+        results
+      end
+    end
+  end
+end

data/lib/insika/tools/data_defined_tool.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "json"
+require "erb"
+
+module Insika
+  module Tools
+    # DATA-DEFINED tool: one class, N instances parameterized by a
+    # ToolDefinition (the same pattern as A2ARemote). It makes an HTTP call described
+    # in config — no Ruby code per tool. Since it inherits RubyLLM::Tool (pulls in the gem),
+    # it is NOT required in lib/insika.rb; the overlay loads it lazily at registration
+    #
+    # Contract preserved by duck-typing: it overrides name/description/parameters/
+    # execute; RubyLLM's params_schema derives from #parameters automatically.
+    # execute NEVER raises — an error (missing param, blocked egress, HTTP, parse)
+    # becomes `{ error: }` to the model, like the other tools.
+    class DataDefinedTool < RubyLLM::Tool
+      def initialize(definition:, http:, egress: Insika::EgressGuard, egress_options: {},
+                     event_stream: nil, turn_context: {})
+        @definition = definition
+        @http = http
+        @egress = egress
+        @egress_options = egress_options
+        @event_stream = event_stream
+        @turn_context = symbolize_ctx(turn_context)
+        super()
+      end
+
+      # Turn context: the registry tool does NOT receive TurnState,
+      # so the Executor DEPOSITS the turn ids here, per-turn
+      # (chat/agent/tenant/store). They resolve {{ctx.*}} — SEPARATE from the model's
+      # {{param}} — to emit X-Chat-Id/X-Store-Id/X-Agent-Id. They come from the TURN, never from
+      # the model (R2). Reader for testing; the writer is the Executor's injection point.
+      attr_reader :turn_context
+
+      def turn_context=(ctx)
+        @turn_context = symbolize_ctx(ctx)
+      end
+
+      # name/description/parameters per INSTANCE (otherwise the model would see the name
+      # derived from the class for every data-tool).
+      def name = @definition.name
+      def description = @definition.description
+
+      # FULL (nested) JSON Schema straight into RubyLLM's params_schema — it is what
+      # the providers serialize (OpenAI/Anthropic/Gemini/Bedrock prefer
+      # params_schema; parameters is just a fallback). Provider-agnostic and
+      # the only form that expresses nesting (object/array/enum).,.
+      def params_schema = @definition.parameters
+
+      # FLAT top-level view for discovery (tool_search calls #parameters on the resolved
+      # tool). The real nested schema goes through #params_schema above.
+      def parameters
+        @parameters ||= @definition.top_level_params.each_with_object({}) do |p, acc|
+          sym = p[:name].to_sym
+          acc[sym] = RubyLLM::Parameter.new(sym, type: p[:type], desc: p[:description], required: p[:required])
+        end
+      end
+
+      # The args are checked against the tool's own JSON Schema BEFORE the request is
+      # built: a call the schema does not allow becomes `{ error: }` the model can act
+      # on, instead of a wrongly-shaped request that a backend answers 200 to.
+      def execute(**kwargs)
+        if (bad = Insika::SchemaGuard.violation(@definition.parameters, kwargs))
+          return { error: bad }
+        end
+
+        req = build_request(kwargs)
+        reason = @egress.violation(req[:url], **@egress_options)
+        return { error: "destination blocked: #{reason}" } if reason
+
+        result = @http.request(**req)
+        emit(result[:status])
+        payload = extract(result)
+        # The RESPONSE says the turn is over (`halt_when`): the backend already
+        # answered the customer, so letting the model comment would deliver the
+        # message twice. RubyLLM's Tool::Halt ends its loop right here — no second
+        # provider call, and the decision is the engine's, not a request in a prompt.
+        # Only on a 2xx: an error body that happens to carry the value is a failure,
+        # and a failure must reach the model.
+        if http_ok?(result) && @definition.halt?(result[:body])
+          # `say` (optional) travels WITH the halt so the Executor can publish it when
+          # the model wrote no lead-in. Wrapped only when there is one, so every tool
+          # that declares no `say` keeps producing exactly the payload it always did.
+          say = @definition.halt_say(result[:body])
+          return RubyLLM::Tool::Halt.new(say ? Insika::ToolDefinition.wrap_halt(payload, say) : payload)
+        end
+
+        payload
+      rescue StandardError => e
+        { error: "HTTP call failed: #{e.message}" }
+      end
+
+      private
+
+      # Interpolates the definition's templates with the model's args, escaping by
+      # context: url/query -> percent-encode; header -> strips CR/LF (anti-injection);
+      # body -> JSON escaping.
+      def build_request(kwargs)
+        r = @definition.request
+        url = interpolate(r[:url], kwargs, :url)
+        url = append_query(url, r[:query], kwargs)
+        headers = r[:headers].transform_values { |v| interpolate(v, kwargs, :header) }
+        body = r[:body] && interpolate(r[:body], kwargs, :body)
+        { method: r[:method], url: url, headers: headers, body: body, timeout: @definition.timeout }
+      end
+
+      def append_query(url, query, kwargs)
+        return url if query.nil? || query.empty?
+
+        pairs = query.map { |k, v| "#{ERB::Util.url_encode(k)}=#{interpolate(v, kwargs, :query)}" }
+        url + (url.include?("?") ? "&" : "?") + pairs.join("&")
+      end
+
+      def interpolate(template, kwargs, mode)
+        template.to_s.gsub(Insika::ToolDefinition::PLACEHOLDER_RE) do
+          encode(resolve(Regexp.last_match(1), kwargs), mode)
+        end
+      end
+
+      # ctx.* -> TURN context (deposited by the Executor); the rest -> MODEL args
+      # (kwargs). The split is the/R2 trust boundary: the model does
+      # not choose which chat/store the tool accesses.
+      def resolve(name, kwargs)
+        prefix = Insika::ToolDefinition::CTX_PREFIX
+        if name.start_with?(prefix)
+          @turn_context[name.delete_prefix(prefix).to_sym]
+        else
+          kwargs[name.to_sym]
+        end
+      end
+
+      def symbolize_ctx(ctx)
+        (ctx || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def encode(value, mode)
+        case mode
+        when :url, :query then ERB::Util.url_encode(value.to_s)
+        when :header then value.to_s.gsub(/[\r\n]/, "")
+        when :body then value.is_a?(String) ? value.to_json[1..-2] : value.to_json
+        end
+      end
+
+      def extract(result)
+        case @definition.response[:extract]
+        when "status" then { status: result[:status] }
+        when "body_raw" then http_ok?(result) ? result[:body] : http_error(result)
+        when "json_path" then extract_json(result)
+        end
+      end
+
+      def extract_json(result)
+        return http_error(result) unless http_ok?(result)
+
+        parsed = begin
+          JSON.parse(result[:body])
+        rescue JSON::ParserError
+          return { error: "response is not JSON" }
+        end
+        dig_path(parsed, @definition.response[:path])
+      end
+
+      def dig_path(obj, path)
+        path.split(".").reduce(obj) do |cur, seg|
+          return { error: "path '#{path}' not found in the response" } unless cur.is_a?(Hash) && cur.key?(seg)
+
+          cur[seg]
+        end
+      end
+
+      # 2xx only. A 3xx is NOT success: the HttpClient does not follow redirects
+      # (the EgressGuard cleared the authored URL, not the hop's destination), and
+      # servers send a 3xx with an empty body — so treating it as ok handed the
+      # model "" and it narrated a plausible outage. A moved API must read as an
+      # error naming its new URL, which is a definition to fix.
+      def http_ok?(result) = result[:status] >= 200 && result[:status] < 300
+
+      # A non-2xx is an ERROR — the backend said so, and the model has to know the call
+      # failed. But the body of a failure is often the backend TALKING: an envelope with
+      # a status and an instruction ("chat not found — ask the person to start over").
+      # Flattening it into a 200-char slice of a string threw that away exactly when the
+      # model needed it most, so a JSON body rides along parsed, under its own key.
+      # A non-JSON body (an HTML error page) stays truncated: it is noise, not a message.
+      ERROR_BODY_MAX = 2_000
+
+      def http_error(result)
+        if (300..399).cover?(result[:status]) && result[:location]
+          return { error: "HTTP #{result[:status]}: moved to #{result[:location]}" }
+        end
+
+        raw = result[:body].to_s
+        parsed = parse_error_body(raw)
+        return { error: "HTTP #{result[:status]}", body: parsed } if parsed
+
+        { error: "HTTP #{result[:status]}: #{raw[0, 200]}" }
+      end
+
+      # -> parsed JSON body worth forwarding | nil (not JSON, or too big to be a message).
+      def parse_error_body(raw)
+        return nil if raw.empty? || raw.bytesize > ERROR_BODY_MAX
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # No task correlation (registry tool does not receive TurnState) -> meta {}.
+      # Emits only name + status: NEVER body/headers (0 secret leakage, R2).
+      def emit(status)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :data_tool_call, data: { tool: @definition.name, status: status }, meta: {}
+                            ))
+      end
+    end
+  end
+end

data/lib/insika/tools/load_skill.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "time"
+
+module Insika
+  module Tools
+    # Level 2 of progressive disclosure: loads the full SKILL.md body
+    # on demand. Respects the agent's allowlist (the model does not load a
+    # skill that the policy did not expose).
+    #
+    # `require "ruby_llm"` stays in THIS file (it inherits from
+    # RubyLLM::Tool), which is why it does NOT enter lib/insika.rb: the Executor
+    # loads it lazily inside create_chat.
+    class LoadSkill < RubyLLM::Tool
+      description "Loads the complete instructions (SKILL.md) of a skill by name"
+      param :name, desc: "Exact skill name, as listed in <available_skills>"
+
+      # RubyLLM::Tool#name derives from self.class.name — for a nested class it produces
+      # "insika--tools--load_skill", not "load_skill" (which wire_callbacks/
+      # :skill_activated and SkillCatalog#format_for_prompt assume). Explicit
+      # override. Coexists with
+      # `param :name` (verified: the param is still present).
+      def name = "load_skill"
+
+      # trace_recorder/state are OPTIONAL (nil = no trace, parity): this tool is
+      # deliberately NOT enveloped (ToolAssembly#wrap_tools), and the envelope is
+      # what records the tool trace — so without recording HERE, the one call an
+      # operator most needs to audit is the only one missing from the Studio's
+      # trace. Same shape as ToolSearch, which also emits its own event.
+      # `agent` selects WHICH body a name resolves to: an agent that specialized a
+      # shared skill must be served its own version, under the same bare name. nil =
+      # the shared scope only (parity).
+      def initialize(catalog, allowed_names, trace_recorder: nil, state: nil, agent: nil)
+        @catalog = catalog
+        @allowed = Array(allowed_names).map(&:to_s)
+        @trace_recorder = trace_recorder
+        @state = state
+        @agent = agent
+        super()
+      end
+
+      def execute(name:)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = load(name)
+        trace(name, result, started)
+        result
+      end
+
+      private
+
+      def load(name)
+        return { error: "skill '#{name}' not available for this agent" } unless @allowed.include?(name.to_s)
+
+        skill = @catalog.find(name, agent: @agent)
+        return { error: "skill '#{name}' not found" } unless skill
+
+        with_companions(skill)
+      end
+
+      # A skill's declared `companions:` come back in the SAME call, so the model
+      # cannot end up holding half a recipe (the reference table without the procedure
+      # that reads it — measured on a real pack, and the searches came out malformed).
+      #
+      # A lone skill returns its bare body, byte for byte as before: only a skill that
+      # actually declares companions pays the wrapper. Restricted to `@allowed`, which
+      # is the LAZY allowed set — a companion that is eager is already in the prompt in
+      # full, so fetching it again would only buy a duplicate.
+      def with_companions(skill)
+        extras = Array(skill.companions).filter_map do |name|
+          next unless @allowed.include?(name.to_s) && name.to_s != skill.name
+
+          @catalog.find(name, agent: @agent)
+        end
+        return skill.body if extras.empty?
+
+        ([skill] + extras).uniq(&:name)
+                          .map { |s| %(<skill name="#{s.name}">\n#{s.body}\n</skill>) }.join("\n\n")
+      end
+
+      # Mirrors ToolEnvelope#trace (same entry shape, so the Studio renders it
+      # like any other call). Clipping/masking is the ToolTraceStore's job.
+      # NEVER breaks the turn — the trace is observability.
+      def trace(name, result, started)
+        return unless @trace_recorder && @state&.task&.session_id
+
+        @trace_recorder.record(
+          session_id: @state.task.session_id,
+          entry: { "turn" => @state.turn, "tool" => "load_skill", "call_id" => "",
+                   "args" => { "name" => name.to_s }, "result" => result,
+                   "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+                   "at" => Time.now.utc.iso8601 }
+        )
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/insika/tools/remember.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # Write path of the cross-session memory: the agent stores a
+    # fact (key+value, durable upsert) or a note (value without key) on demand.
+    # Deterministic — NO model call.
+    # System builtin (like load_skill/tool_search): `require "ruby_llm"` stays
+    # in THIS file, loaded lazily by the Executor in create_chat.
+    class Remember < RubyLLM::Tool
+      description "Stores information to remember in future conversations. Use `key` " \
+                  "for a durable key-value fact (overwrites the previous one); omit " \
+                  "`key` for a free-form note."
+      param :value, desc: "The content to remember"
+      param :key, desc: "Fact key (e.g.: 'plan', 'name'); omit for a note", required: false
+
+      # otherwise RubyLLM derives "insika--tools--remember" from the class name.
+      def name = "remember"
+
+      def initialize(store, tenant, event_stream:, state:)
+        @store = store
+        @tenant = tenant
+        @event_stream = event_stream
+        @state = state
+        super()
+      end
+
+      def execute(value:, key: nil)
+        if key.to_s.strip.empty?
+          note = @store.add_note(tenant: @tenant, text: value.to_s)
+          emit("note", note.id)
+          { remembered: "note", id: note.id }
+        else
+          @store.put_fact(tenant: @tenant, key: key.to_s, value: value.to_s)
+          emit("fact", key.to_s)
+          { remembered: "fact", key: key.to_s }
+        end
+      end
+
+      private
+
+      def emit(kind, ref)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_written,
+                             data: { kind: kind, key: ref },
+                             meta: { task_id: @state.task.id, session_id: @state.task.session_id }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/tools/stuck_signal.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # The agent's deterministic "I cannot proceed" signal (WS5). A
+    # system builtin like remember: the model calls it when it determines it cannot
+    # continue (out of scope, missing data, a case a human must take over). It ends
+    # the turn with `outcome: :stuck` recorded in the contract (the executor reads
+    # `state.stuck_outcome` at stage 8/9 and tags the terminal event) and a final
+    # message: the model's lead-in when it wrote one, else this tool's `message`.
+    #
+    # The ENGINE does not decide what "stuck" means — the consumer does. This tool
+    # is the deterministic signal the Agent.Shop subscribes to (`:turn_stuck` /
+    # `outcome: "stuck"`) to run its escalation (CRM/operator, which answers with
+    # `MessageOrigin::OPERATOR`). Nothing about handoff, pause or resume lives here.
+    class StuckSignal < RubyLLM::Tool
+      description "Signal that you cannot proceed and end the turn. Use when the " \
+                  "request is out of your scope, you lack the data to help, or a human " \
+                  "must take over. Write your final sentence to the customer first."
+      param :reason, desc: "Why you cannot proceed (goes to the operator, not the customer)"
+      param :message, desc: "Optional final message if you wrote none", required: false
+
+      def name = "signal_stuck"
+
+      def initialize(state:, **)
+        @state = state
+        super()
+      end
+
+      def execute(reason:, message: nil)
+        @state.stuck_outcome = { reason: reason.to_s, message: message.to_s }
+        # A Halt ends the tool loop here, so the turn cannot continue after declaring
+        # stuck. The payload's `say` is the fallback final message when the model
+        # wrote no lead-in (the executor's halt_answer already prefers the lead-in).
+        RubyLLM::Tool::Halt.new(Insika::ToolDefinition.wrap_halt(
+                                  { "reason" => reason.to_s },
+                                  message.to_s
+                                ))
+      end
+    end
+  end
+end

data/lib/insika/tools/subagent.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # In-process delegation to a CHILD agent — the Flue
+    # `session.task()` primitive. A system tool (like remember/load_skill): wired
+    # by the ChatBuilder ONLY when `profile.subagents` is present, so `require
+    # "ruby_llm"` stays in this file (loaded lazily in create_chat). NOT enveloped
+    # (system tool) — in the synchronous mode the child lives in the parent's
+    # envelope and re-runs on the parent's resume.
+    #
+    # It holds no delegation logic itself: `execute` reads the parent TurnState
+    # (the subagents allowlist + resolved model for inheritance + depth) and hands
+    # off to `Executor#run_subagent`, which spawns the isolated child turn and
+    # returns its result. The child result = its text + the linked child session
+    # id (R3).
+    class Subagent < RubyLLM::Tool
+      description "Delegates a self-contained task to a specialized child agent. " \
+                  "The child runs in an ISOLATED context (it does not see this " \
+                  "conversation) — pass everything it needs in `message`. By default " \
+                  "it BLOCKS and returns the child's final answer. Set async:true to " \
+                  "fire-and-forget a long task: it returns immediately and the child's " \
+                  "result arrives later as a new message on this conversation."
+      param :agent, desc: "Id of the child agent to delegate to (must be one this agent may spawn)"
+      param :message, desc: "The self-contained task/prompt for the child agent"
+      param :async, type: :boolean, required: false,
+                    desc: "true = dispatch and continue (result delivered later); default false = wait for the answer"
+
+      # otherwise RubyLLM derives "insika--tools--subagent" from the class name.
+      def name = "spawn_subagent"
+
+      def initialize(runner:, state:)
+        @runner = runner
+        @state = state
+        @allowed = Array(state.profile.subagents).map(&:to_s)
+        super()
+      end
+
+      # The parent's allowlist is per-TURN data, so it is named per instance: the
+      # ids go into the description AND as an `enum` on `agent`. Measured, not
+      # guessed — with only "must be one this agent may spawn" in the schema, a
+      # real provider answered "let me check which agents are available" and then
+      # did the work itself instead of delegating. A model cannot call what it
+      # cannot name.
+      def description
+        return super if @allowed.empty?
+
+        "#{super} Agents you may spawn: #{@allowed.join(', ')}."
+      end
+
+      def params_schema
+        @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[agent])
+      end
+
+      # The child result is returned to the model as the tool result. On error we
+      # return { error: } (never raise) — a bad `agent`/depth/child failure is a
+      # message to the model, not a turn-killer (parity with A2ARemote).
+      def execute(agent:, message:, async: false)
+        result = @runner.run_subagent(agent: agent.to_s, message: message.to_s,
+                                      parent_state: @state, async: async == true)
+        return { error: result[:error] } if result[:error]
+
+        # async dispatch: the ack (the child result arrives later as a new turn).
+        return { dispatched: true, agent: result[:agent], session_id: result[:session_id] } if result[:dispatched]
+
+        # sync: link the child session id alongside the text so a multi-step parent
+        # can reference it and the transcript stays auditable (R3).
+        { text: result[:text], session_id: result[:session_id] }
+      end
+    end
+  end
+end

data/lib/insika/tools/subagents.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # PARALLEL fan-out of child agents: delegate N self-contained
+    # tasks at once and get all answers back together, in ONE parent turn. Sibling
+    # of `spawn_subagent` (single); this one always sync-joins — the children run
+    # concurrently (their provider waits overlap on the reactor) and the combined
+    # result comes back as this tool's result. A system tool wired by the ChatBuilder
+    # when `profile.subagents` is present; `require "ruby_llm"` stays in this file
+    # (loaded lazily in create_chat). NOT enveloped (children live in the parent's
+    # envelope, same as the sync single).
+    class Subagents < RubyLLM::Tool
+      description "Delegates SEVERAL self-contained tasks to child agents IN " \
+                  "PARALLEL and returns all their answers together. Use this — not " \
+                  "repeated spawn_subagent calls — when you have multiple independent " \
+                  "subtasks whose results you'll combine: it runs them concurrently " \
+                  "(much faster). Each child runs in an ISOLATED context, so put " \
+                  "everything it needs in its `message`."
+      # array-of-objects param via the explicit JSON-schema form (the `param` DSL
+      # only reaches strings/scalars). Top-level `tasks` arrives as a kwarg to execute.
+      params(
+        type: "object",
+        properties: {
+          tasks: {
+            type: "array",
+            description: "The independent subtasks to run in parallel",
+            items: {
+              type: "object",
+              properties: {
+                agent: { type: "string", description: "id of the child agent (must be one this agent may spawn)" },
+                message: { type: "string", description: "the self-contained task/prompt for that child" }
+              },
+              required: %w[agent message]
+            }
+          }
+        },
+        required: %w[tasks]
+      )
+
+      # otherwise RubyLLM derives "insika--tools--subagents" from the class name.
+      def name = "spawn_subagents"
+
+      def initialize(runner:, state:)
+        @runner = runner
+        @state = state
+        @allowed = Array(state.profile.subagents).map(&:to_s)
+        super()
+      end
+
+      # Same reason as `spawn_subagent`: the parent's allowlist is per-turn data,
+      # so the ids are named per instance — in the description and as an `enum` on
+      # each task's `agent`. See Tools::AgentEnum.
+      def description
+        return super if @allowed.empty?
+
+        "#{super} Agents you may spawn: #{@allowed.join(', ')}."
+      end
+
+      def params_schema
+        @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[tasks agent])
+      end
+
+      # -> { results: [{agent:, text:, session_id:} | {agent:, error:}] } | { error: }.
+      # Never raises: a bad envelope / per-task failure is a message to the model.
+      def execute(tasks:)
+        result = @runner.run_subagents(tasks: Array(tasks), parent_state: @state)
+        return { error: result[:error] } if result[:error]
+
+        { results: result[:results] }
+      end
+    end
+  end
+end