little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/agent.rb

@@ -1,54 +1,59 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "assembly"
 require_relative "support/output_truncation"
 require_relative "tool_execution"
 
 module LittleGhost
-  # Define reusable agents that can answer, stream, call tools, and delegate work.
-  # Each subclass describes one application role with an inheritable Ruby DSL.
+  # Defines one reusable model-driven behavior with prompts, tools, and limits.
+  # Each Agent subclass describes one application role with an inheritable Ruby
+  # DSL. It can answer, stream, call tools, and delegate work.
   #
-  # A customer support agent can look up an account itself and give longer investigations
-  # to a research specialist:
-  #
-  #   class ResearchAgent < LittleGhost::Agent
-  #     description "Researches transfer failures"
-  #     model "customer_support.research"
-  #     tools LedgerSearchTool
-  #   end
+  # Start with one role and add capabilities as its work grows:
   #
   #   class CustomerSupportAgent < LittleGhost::Agent
   #     description "Handles support requests"
-  #     model :customer_support
-  #     limits max_turns: 40
-  #     tools AccountLookupTool
-  #     subagent ResearchAgent, kind: "research"
+  #     model "openrouter:openai/gpt-5.6-luna"
+  #     system_prompt "Answer customer questions clearly."
   #   end
   #
   #   run = CustomerSupportAgent.ask("Why is transfer 481 pending?")
   #   run.completed? # => true
-  #   run.response   # => "Transfer 481 is waiting for the receiving bank."
+  #   run.response
+  #   # One possible response: Transfer 481 is waiting for the receiving bank.
+  #
+  # An Agent is the smallest Assembly: it owns one model loop while inheriting
+  # the same +ask+ and +stream_ask+ entrypoints as coordinated assemblies.
+  # Add tools for application operations and subagents for model-directed
+  # delegation.
   #
-  # Class declarations are inherited. Prompts resolve by the agent's logical
-  # path unless +system_prompt+ or +system_template+ supplies one explicitly;
-  # tools and prompt locals may also be selected dynamically for each run.
-  # Capabilities such as skills, context management, loop detection, and
-  # delegation remain inactive until their DSL methods are called.
+  # Call a named Agent with
+  # ask[rdoc-ref:LittleGhost::Assembly.ask] when you need the final Run, or
+  # the streaming entrypoint[rdoc-ref:LittleGhost::Assembly.stream_ask] when you
+  # want events as the answer arrives.
   #
-  # The class-level +ask+ and +stream_ask+ helpers create fresh standalone
-  # entrypoints. Create an instance explicitly to reuse one Runtime across
-  # calls. Runtimes build bound instances internally; their +call+ method
-  # returns a RunResult and their +stream+ method follows the owning run's
-  # single-execution lifecycle. Closing an agent closes owned tools and any
-  # standalone workspace and sandbox.
-  # LittleGhost::Agent.ask uses <tt>You are a helpful agent.</tt> as its system
-  # prompt. Subclasses continue to use their inline or conventional prompts.
+  # Most applications call a named Agent class. LittleGhost automatically
+  # reuses the active Configuration's shared Runtime while building a fresh
+  # top-level Run for every call. Passing +runtime:+ is an advanced option for
+  # an explicitly isolated setup.
   #
-  # Models can return ordinary text or a locally validated structured result.
-  # Tool failures are sanitized before returning to the model, diagnostic
-  # capture can be disabled for sensitive agents, and cancellation, deadlines,
-  # and cleanup failures remain framework control flow.
-  class Agent
+  # Agent declarations are inherited. Define a short prompt inline, or place a
+  # growing prompt in <tt>app/prompts/customer_support/system.erb</tt> for
+  # +CustomerSupportAgent+. The {Prompts as Views guide}[rdoc-ref:docs/guides/prompt_views.md]
+  # explains conventional lookup, locals, and partials. Optional features such
+  # as skills, context management, loop detection, and delegation stay inactive
+  # until their DSL is used.
+  #
+  # Calling LittleGhost::Agent itself uses <tt>You are a helpful agent.</tt> as
+  # the system prompt. Subclasses use the inline or conventional prompt they
+  # declare.
+  #
+  # Models may return text or locally validated structured data. LittleGhost
+  # hides unexpected Tool exception messages from the model. See
+  # Run[rdoc-ref:LittleGhost::Run] for outcomes, cancellation, and cleanup, and
+  # Assembly[rdoc-ref:LittleGhost::Assembly] for the advanced run-scoped form.
+  class Agent < Assembly
     DEFAULT_SYSTEM_PROMPT = "You are a helpful agent." # :nodoc:
     DEFAULT_MAX_TOOL_RESULT_TOKENS = 10_000 # :nodoc:
     MAX_STRUCTURED_RESULT_BYTES = 1_000_000 # :nodoc:
@@ -64,11 +69,13 @@ module LittleGhost
       before_model after_model after_model_error
       before_tool after_tool
     ].freeze # :nodoc:
+    ExecutedTool = Data.define(:result, :companion_content) do # :nodoc:
+      def status = result.status
+      def content = result.content
+    end
 
     extend Support::ClassAttributes
 
-    class_attribute :agent_id_value
-    class_attribute :description_value
     class_attribute :model_value
     class_attribute :limits_value, default: {}
     class_attribute :result_schema_value
@@ -81,27 +88,6 @@ module LittleGhost
     class_attribute :callback_values, default: Support::Callbacks.new(*CALLBACKS)
 
     class << self
-      # Executes +message+ through a fresh standalone entrypoint and returns the
-      # completed LittleGhost::Run. Invocation +options+ are forwarded to #ask.
-      #
-      # Create an instance explicitly when reusing a Runtime or streaming events.
-      def ask(message, **options)
-        new.ask(message, **options)
-      end
-
-      # Streams +message+ through a fresh standalone entrypoint and returns an
-      # Enumerator of LittleGhost::StreamEvent objects. Invocation +options+
-      # are forwarded to #stream_ask.
-      #
-      # Create an instance explicitly when reusing one Runtime across calls.
-      def stream_ask(message, **options)
-        stream = nil
-        Enumerator.new do |events|
-          stream ||= new.stream_ask(message, **options)
-          stream.each { |event| events << event }
-        end
-      end
-
       # :call-seq:
       #   agent_id() -> String
       #   agent_id(value) -> String
@@ -110,9 +96,9 @@ module LittleGhost
       # Named subclasses derive it from their underscored class name without an
       # +Agent+ suffix; passing +value+ replaces that default.
       def agent_id(*values)
-        return agent_id_value || default_agent_id if values.empty?
+        return assembly_id if values.empty?
 
-        self.agent_id_value = values.fetch(0).to_s
+        assembly_id(values.fetch(0))
       end
 
       # The underscored, namespace-aware path used for conventional prompt lookup.
@@ -122,17 +108,6 @@ module LittleGhost
         parts.reject(&:empty?).map { |part| underscore(part) }.join("/")
       end
 
-      # :call-seq:
-      #   description() -> String
-      #   description(value) -> String
-      #
-      # The human-readable description shown when this agent is delegated.
-      def description(*values)
-        return description_value.to_s if values.empty?
-
-        self.description_value = values.fetch(0).to_s
-      end
-
       # :call-seq:
       #   model() -> String, Symbol, Hash, Proc, nil
       #   model(role_or_target) -> String, Symbol
@@ -189,9 +164,10 @@ module LittleGhost
       # strategy selection prefers provider-native structured output and falls
       # back to a terminal tool when supported.
       #
-      # A missing or invalid result receives one repair attempt before
-      # LittleGhost::StructuredResultError is raised. Invalid schemas and
-      # strategies raise LittleGhost::ConfigurationError immediately.
+      # During execution, a missing or invalid result receives one repair attempt
+      # before LittleGhost::StructuredResultError is raised inside the owning Run.
+      # A top-level +ask+ records it on a failed Run. Invalid schemas and strategies
+      # raise LittleGhost::ConfigurationError before execution begins.
       def result_schema(schema = nil, name: nil, description: nil, strategy: :auto, **schema_keywords)
         return result_schema_value if schema.nil? && schema_keywords.empty? && name.nil? && description.nil? && strategy == :auto
 
@@ -489,26 +465,37 @@ module LittleGhost
         end
       end
 
-      def default_agent_id
-        value = name.to_s.split("::").last.to_s.gsub(/Agent\z/, "").gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
-        (value.empty? ? "agent" : value).freeze
-      end
-
       def underscore(value)
         value.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
       end
     end
 
-    # Run-scoped model, tools, lifecycle, delegation, and execution resources
-    # available to agent extensions.
-    attr_reader :model, :tool_registry, :run, :delegation_activity, :agent_path, :workspace, :sandbox,
-      :max_tool_calls
+    # The resolved model used by this run-scoped Agent.
+    attr_reader :model
+    # Tools created and bound for this Agent's owning Run.
+    attr_reader :tool_registry
+    # The owning Run, or +nil+ for a standalone entrypoint.
+    attr_reader :run
+    # Shared delegation tracker, when subagents are enabled.
+    attr_reader :delegation_activity
+    # This Agent's location in the bounded subagent tree.
+    attr_reader :agent_path
+    # Run-scoped workspace available to Tools and extensions.
+    attr_reader :workspace
+    # Run-scoped sandbox used for filesystem and process operations.
+    attr_reader :sandbox
+    # Maximum Tool calls allowed during one invocation.
+    attr_reader :max_tool_calls
 
     # Creates either a standalone entrypoint or a run-scoped agent.
+    # :call-seq:
+    #   new(runtime: nil) -> Agent
+    #   new(model:, runtime:, tools:, run:, ...) -> Agent
     #
-    # Calling <tt>new</tt> without +model+ and +run+ creates the standalone form
-    # used by +ask+ and +stream_ask+. Runtime builders supply the remaining
-    # dependencies and apply class-level limits and declarations.
+    # The first form is the application-facing entrypoint. It may be reused for
+    # independent concurrent calls and creates a fresh Run for each one. The
+    # second form is run-scoped; Runtime builders supply its dependencies and it
+    # must not outlive or be shared outside its owning Run.
     def initialize(
       model: nil,
       runtime: nil,
@@ -526,16 +513,14 @@ module LittleGhost
       workspace: nil,
       sandbox: nil
     )
-      if model.nil? && run.nil?
-        @standalone = true
-        @runtime = runtime || Runtime.new(configuration: LittleGhost.configuration)
-        @workspace = workspace
-        @sandbox = sandbox
+      standalone = model.nil? && run.nil?
+      super(run:, runtime:, workspace:, sandbox:, standalone:)
+      if standalone
         @owns_resources = true
         @closed = false
         @close_mutex = Mutex.new
-        @interruptions_mutex = Mutex.new
-        @active_interruptions = []
+        @interjections_mutex = Mutex.new
+        @active_interjections = []
         return
       end
 
@@ -570,8 +555,12 @@ module LittleGhost
       @closed = false
       @close_mutex = Mutex.new
       @exclusive_tools_mutex = Mutex.new
-      @interruptions_mutex = Mutex.new
-      @active_interruptions = []
+      @interjections_mutex = Mutex.new
+      @active_interjections = []
+      @assembly_transitions_mutex = Mutex.new
+      @assembly_transitions = {}
+      @assembly_tool_batch_sizes = {}
+      @assembly_transition = nil
       raise ArgumentError, "max_turns must be at least 1" if @max_turns < 1
       raise ArgumentError, "max_tool_calls must be at least 1" if @max_tool_calls < 1
       raise ArgumentError, "max_tool_result_tokens must be at least 1" if @max_tool_result_tokens < 1
@@ -590,123 +579,85 @@ module LittleGhost
       execute_tools(tool_uses, context, events, parent_operation_id:, parent_trace_context:)
     end
 
-    def build_run(payload) # :nodoc:
-      options = {
-        agent_class: self.class,
-        entrypoint_class: self.class
-      }
-      options[:workspace] = workspace if workspace
-      options[:sandbox] = sandbox if sandbox
-      runtime.build_run(payload, **options)
-    end
+    def request_assembly_transition(value, context:) # :nodoc:
+      @assembly_transitions_mutex.synchronize do
+        unless @assembly_tool_batch_sizes[context] == 1
+          raise ToolError, "An assembly transition must be the only tool call in a model response"
+        end
+        if @assembly_transitions.key?(context)
+          raise ProtocolError, "Multiple assembly transitions were requested in one agent turn"
+        end
 
-    # Runs +input+ to completion.
-    #
-    # A standalone agent returns a LittleGhost::Run. An agent built inside a run
-    # returns its LittleGhost::RunResult.
-    def call(input = nil, **options)
-      return build_run(entrypoint_payload(input, options)).call if @standalone
-
-      result = nil
-      stream(input, **options).each do |event|
-        result = event.data[:result] if event.type == :invocation_stop
+        @assembly_transitions[context] = value
       end
-      result
-    end
-
-    # Runs +message+ to completion through the standalone or run-scoped agent.
-    def ask(message, **options)
-      call(message, **options)
+      value
     end
 
-    # Adds +message+ to one active invocation and waits for its ordinary text reply.
-    #
-    # The response may continue into tool calls; delivery does not stop the
-    # original invocation. Raises LittleGhost::AgentInterruptError when there is
-    # no unambiguous active target.
-    def interrupt(
-      message,
-      cancellation_token: Support::CancellationToken.new,
-      deadline: nil,
-      target_operation_id: nil,
-      interruption_id: nil,
-      batch_key: nil,
-      metadata: {}
-    )
-      interrupt_response(
-        message,
-        cancellation_token:,
-        deadline:,
-        target_operation_id:,
-        interruption_id:,
-        batch_key:,
-        metadata:
-      ).text
-    end
+    attr_reader :assembly_transition # :nodoc:
 
-    # Adds an interruption and returns the model's immediate response details.
+    # Adds an interjection and returns the model's immediate result details.
     #
     # Use +target_operation_id+ when an agent has multiple active invocations.
     # Messages may contain only text, image, or document content. The returned
-    # response value exposes +text+, +tool_calls?+, +interruption_ids+, and
-    # +batch_key+; tool calls may continue after this response. Depend on these
-    # methods rather than the response's concrete class.
-    def interrupt_response(
+    # result value exposes +text+, +tool_calls?+, +interjection_ids+, and
+    # +batch_key+; tool calls may continue after this result. Depend on these
+    # methods rather than the result's concrete class.
+    def interject(
       message,
       cancellation_token: Support::CancellationToken.new,
       deadline: nil,
       target_operation_id: nil,
-      interruption_id: nil,
+      interjection_id: nil,
       batch_key: nil,
       metadata: {}
     )
       message = Message.new(role: :user, content: message) if message.is_a?(String)
-      raise ArgumentError, "interrupt message must be a String or LittleGhost::Message" unless message.is_a?(Message)
+      raise ArgumentError, "interject message must be a String or LittleGhost::Message" unless message.is_a?(Message)
       safe_content = message.content.all? do |content|
         content.is_a?(Content::Text) ||
           content.is_a?(Content::Image) ||
           content.is_a?(Content::Document)
       end
       unless safe_content
-        raise ArgumentError, "interrupt message content must contain only text, images, or documents"
+        raise ArgumentError, "interject message content must contain only text, images, or documents"
       end
 
-      interruptions = @interruptions_mutex.synchronize do
+      interjections = @interjections_mutex.synchronize do
         active = if target_operation_id
-          @active_interruptions.select { |candidate| candidate.target_operation_id == target_operation_id }
+          @active_interjections.select { |candidate| candidate.target_operation_id == target_operation_id }
         else
-          @active_interruptions
+          @active_interjections
         end
         if active.empty?
-          raise AgentInterruptError, "Agent is not currently running"
+          raise AgentInterjectionError, "Agent is not currently running"
         end
         if active.length > 1
-          raise AgentInterruptError, "Agent has multiple active invocations; the interruption target is ambiguous"
+          raise AgentInterjectionError, "Agent has multiple active invocations; the interjection target is ambiguous"
         end
 
         active.first
       end
       options = {batch_key:, metadata:}
-      options[:id] = interruption_id unless interruption_id.nil?
-      ticket = interruptions.enqueue(message, **options)
+      options[:id] = interjection_id unless interjection_id.nil?
+      ticket = interjections.enqueue(message, **options)
       instrument(
-        :agent_interrupt_queued,
-        parent_operation_id: interruptions.operation_id,
-        interruption_id: ticket.id,
-        event_kind: :interrupt,
+        :agent_interjection_queued,
+        parent_operation_id: interjections.operation_id,
+        interjection_id: ticket.id,
+        event_kind: :interjection,
         diagnostic: {input: diagnostic_message(message)}
       )
       begin
         response = ticket.value(cancellation_token:, deadline:)
-        interruptions.release(ticket)
+        interjections.release(ticket)
         response
       rescue => error
-        interruptions.release(ticket, withdraw: true)
+        interjections.release(ticket, withdraw: true)
         instrument(
-          :agent_interrupt_failed,
-          parent_operation_id: interruptions.operation_id,
-          interruption_id: ticket.id,
-          event_kind: :interrupt,
+          :agent_interjection_failed,
+          parent_operation_id: interjections.operation_id,
+          interjection_id: ticket.id,
+          event_kind: :interjection,
           error_type: error.class.name,
           diagnostic: {exception: diagnostic_exception(error)}
         )
@@ -734,11 +685,11 @@ module LittleGhost
       parent_operation_id: nil,
       checkpoint: nil,
       conversation_id: nil,
-      interruption_metadata: nil,
-      interruption_ids: [],
-      interrupt_ready: nil
+      interjection_metadata: nil,
+      interjection_ids: [],
+      interject_ready: nil
     )
-      if @standalone
+      if standalone?
         raise ArgumentError, "input is required" if input.nil?
 
         return build_run(entrypoint_payload(input, {
@@ -746,7 +697,8 @@ module LittleGhost
           context:,
           settings:,
           template_paths:,
-          deadline_at: deadline
+          deadline_at: deadline,
+          cancellation_token:
         }.compact)).each
       end
 
@@ -765,7 +717,7 @@ module LittleGhost
       end
       settings = @model_settings.merge(settings)
       Enumerator.new do |events|
-        interruptions = AgentInterruptions.new
+        interjections = AgentInterjections.new
         run_context = RunContext.new(
           state: context,
           cancellation_token: cancellation_token,
@@ -773,8 +725,8 @@ module LittleGhost
           metadata: {agent_id: self.class.agent_id},
           checkpoint:,
           conversation_id:,
-          interruption_metadata:,
-          interruption_ids:
+          interjection_metadata:,
+          interjection_ids:
         )
         begin
           with_invocation(run_context) do
@@ -787,81 +739,18 @@ module LittleGhost
               template_paths: invocation_paths,
               events: events,
               parent_operation_id:,
-              interruptions:,
-              interrupt_ready:
+              interjections:,
+              interject_ready:
             )
           end
         rescue => error
-          interruptions.close(error)
+          interjections.close(error)
           raise
         ensure
-          interruptions.close(AgentInterruptError.new("Agent finished before the interruption was delivered"))
-          unregister_interruptions(interruptions)
-        end
-      end
-    end
-
-    # Streams +message+ through the standalone or run-scoped agent.
-    # Standalone +options+ become Invocation fields; run-scoped options are
-    # forwarded to #stream.
-    def stream_ask(message, **options)
-      if @standalone
-        options[:deadline_at] = options.delete(:deadline) if options.key?(:deadline)
-        stream = nil
-        return Enumerator.new do |events|
-          stream ||= build_run(entrypoint_payload(message, options)).each
-          stream.each { |event| events << event }
+          interjections.close(AgentInterjectionError.new("Agent finished before the interjection was delivered"))
+          unregister_interjections(interjections)
         end
       end
-
-      stream(message, **options)
-    end
-
-    # Exposes this agent as a Tool instance.
-    #
-    # By default, each call starts with empty conversational history. Set
-    # <tt>preserve_context: true</tt> to retain history serially between calls.
-    def as_tool(name: self.class.agent_id, description: self.class.description, preserve_context: false)
-      agent = self
-      description = "Delegate a task to #{name}." if description.to_s.empty?
-      mutex = Mutex.new
-      retained_history = []
-      tool_class = Tool.define(
-        name: name,
-        description: description,
-        input_schema: {
-          type: "object",
-          properties: {input: {type: "string"}},
-          required: ["input"],
-          additionalProperties: false
-        }
-      ) do |input, context: nil|
-        invocation = lambda do
-          result = agent.call(
-            input.fetch("input"),
-            history: preserve_context ? retained_history : [],
-            context: context&.state || {},
-            cancellation_token: context&.cancellation_token || Support::CancellationToken.new,
-            interruption_metadata: context&.interruption_metadata,
-            interruption_ids: context&.interruption_ids || [],
-            deadline: context&.deadline,
-            parent_operation_id: run&.operation_id
-          )
-          retained_history.replace(result.messages.reject { |message| message.role == :system }) if preserve_context
-          result.structured? ? result.structured_result.value : result.text
-        end
-        preserve_context ? mutex.synchronize(&invocation) : invocation.call
-      end
-      tool_class.define_method(:close) { agent.close }
-      binding = Tool::Binding.new(
-        agent: self,
-        run:,
-        runtime:,
-        model:,
-        workspace:,
-        sandbox:
-      )
-      tool_class.new(binding:)
     end
 
     # Materializes and freezes the prompt locals declared on the agent class.
@@ -879,21 +768,21 @@ module LittleGhost
     # The materialized tools available during this agent run.
     def tools = tool_registry
 
-    # Closes owned tools, interruptions, sandbox, and workspace resources.
+    # Closes owned tools, interjections, sandbox, and workspace resources.
     # The operation is idempotent and re-raises the first cleanup failure.
     def close
-      resources, interruptions = @close_mutex.synchronize do
+      resources, interjections = @close_mutex.synchronize do
         return if @closed
 
         @closed = true
         [
           [tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
-          @interruptions_mutex.synchronize { @active_interruptions.dup }
+          @interjections_mutex.synchronize { @active_interjections.dup }
         ]
       end
       first_error = nil
-      interruptions.each do |active|
-        active.close(AgentInterruptError.new("Agent was closed"))
+      interjections.each do |active|
+        active.close(AgentInterjectionError.new("Agent was closed"))
       end
       resources.each do |resource|
         resource.close if resource.respond_to?(:close)
@@ -935,45 +824,45 @@ module LittleGhost
       {message: input, **options}
     end
 
-    def register_interruptions(interruptions)
+    def register_interjections(interjections)
       @close_mutex.synchronize do
         raise InvocationError, "Agent is closed" if @closed
 
-        @interruptions_mutex.synchronize { @active_interruptions << interruptions }
+        @interjections_mutex.synchronize { @active_interjections << interjections }
       end
     end
 
-    def unregister_interruptions(interruptions)
-      @interruptions_mutex.synchronize { @active_interruptions.delete(interruptions) }
+    def unregister_interjections(interjections)
+      @interjections_mutex.synchronize { @active_interjections.delete(interjections) }
     end
 
-    def interruption_message(interruption)
-      source = interruption.message
+    def interjection_message(interjection)
+      source = interjection.message
       Message.new(
         role: :user,
         content: [
           Content::Text.new(text: <<~MESSAGE.strip),
-            Agent interruption:
+            Agent interjection:
 
             Respond briefly in ordinary text before any tool calls, then continue the current task unless this
-            interruption asks you to finish.
+            interjection asks you to finish.
           MESSAGE
           *source.content
         ],
-        metadata: source.metadata.merge(interruption.metadata).merge(
-          little_ghost_interruption_id: interruption.id,
-          little_ghost_interruption_batch_key: interruption.batch_key,
-          little_ghost_interruption_metadata: interruption.metadata
+        metadata: source.metadata.merge(interjection.metadata).merge(
+          little_ghost_interjection_id: interjection.id,
+          little_ghost_interjection_batch_key: interjection.batch_key,
+          little_ghost_interjection_metadata: interjection.metadata
         )
       )
     end
 
-    def request_with_interruption(request, interruption)
+    def request_with_interjection(request, interjection)
       ModelRequest.new(
         messages: [
           *request.messages,
-          *interruption.tickets.reject { |ticket| request_contains_interruption?(request, ticket) }
-            .map { |ticket| interruption_message(ticket) }
+          *interjection.tickets.reject { |ticket| request_contains_interjection?(request, ticket) }
+            .map { |ticket| interjection_message(ticket) }
         ],
         tools: request.tools,
         settings: request.settings,
@@ -985,13 +874,24 @@ module LittleGhost
       )
     end
 
-    def request_contains_interruption?(request, interruption)
+    def request_contains_interjection?(request, interjection)
       request.messages.any? do |message|
-        (message.metadata[:little_ghost_interruption_id] ||
-          message.metadata["little_ghost_interruption_id"]) == interruption.id
+        (message.metadata[:little_ghost_interjection_id] ||
+          message.metadata["little_ghost_interjection_id"]) == interjection.id
       end
     end
 
+    def consume_assembly_transition(context)
+      @assembly_transitions_mutex.synchronize { @assembly_transitions.delete(context) }
+    end
+
+    def with_assembly_tool_batch(context, size)
+      @assembly_transitions_mutex.synchronize { @assembly_tool_batch_sizes[context] = size }
+      yield
+    ensure
+      @assembly_transitions_mutex.synchronize { @assembly_tool_batch_sizes.delete(context) }
+    end
+
     def execute(
       input,
       history:,
@@ -1001,15 +901,16 @@ module LittleGhost
       template_paths:,
       events:,
       parent_operation_id:,
-      interruptions:,
-      interrupt_ready:
+      interjections:,
+      interject_ready:
     )
       started_at = monotonic_time
       operation_id = SecureRandom.uuid
       context.bind_agent_operation_id(operation_id)
-      interruptions.bind(operation_id, target_operation_id: parent_operation_id)
-      register_interruptions(interruptions)
-      interrupt_ready&.call
+      @assembly_transitions_mutex.synchronize { @assembly_transition = nil }
+      interjections.bind(operation_id, target_operation_id: parent_operation_id)
+      register_interjections(interjections)
+      interject_ready&.call
       agent_handle = start_instrumentation(
         :agent,
         parent: parent_operation_id || active_instrumentation_parent,
@@ -1040,7 +941,7 @@ module LittleGhost
         )
         begin
           context.check!
-          response, interrupted = invoke_model(
+          response, interjected = invoke_model(
             messages,
             context,
             settings,
@@ -1048,8 +949,9 @@ module LittleGhost
             events,
             parent_operation_id: turn_operation_id,
             structured_result_repair_due:,
-            interruptions:
+            interjections:
           )
+          messages.reject! { |message| tool_companion_message?(message) }
           messages << response.message
           tool_uses = response.message.content.grep(Content::ToolUse)
           result_tool_uses = structured_result_tool_uses(tool_uses)
@@ -1062,12 +964,12 @@ module LittleGhost
             )
             unless validation_error
               messages[-1] = redact_structured_result_message(response.message)
-              unless interruptions.finish
+              unless interjections.finish
                 context.checkpoint(messages)
                 finish_instrumentation(
                   turn_handle,
                   operation_id: turn_operation_id,
-                  outcome: :interrupted,
+                  outcome: :interjected,
                   turn: turn + 1
                 )
                 next
@@ -1122,20 +1024,20 @@ module LittleGhost
               raise OutputLimitError, "The model stopped before completing its response"
             end
 
-            if interrupted || !@structured_output_strategy
-              unless interruptions.finish
+            if interjected || !@structured_output_strategy
+              unless interjections.finish
                 context.checkpoint(messages)
                 finish_instrumentation(
                   turn_handle,
                   operation_id: turn_operation_id,
-                  outcome: :interrupted,
+                  outcome: :interjected,
                   turn: turn + 1
                 )
                 next
               end
             end
 
-            if @structured_output_strategy && !interrupted
+            if @structured_output_strategy && !interjected
               validation_error = if @structured_output_strategy.provider?
                 capture_structured_result(response.message.text, context)
               else
@@ -1143,12 +1045,12 @@ module LittleGhost
               end
               unless validation_error
                 messages[-1] = redact_structured_result_message(response.message)
-                unless interruptions.finish
+                unless interjections.finish
                   context.checkpoint(messages)
                   finish_instrumentation(
                     turn_handle,
                     operation_id: turn_operation_id,
-                    outcome: :interrupted,
+                    outcome: :interjected,
                     turn: turn + 1
                   )
                   next
@@ -1241,17 +1143,61 @@ module LittleGhost
           tool_call_count += tool_uses.length
           raise ProtocolError, "The agent reached its maximum tool calls" if tool_call_count > @max_tool_calls
 
-          tool_results = dispatch_tools(
-            tool_uses,
-            context:,
-            events:,
-            parent_operation_id: turn_operation_id
-          )
+          executed_tools = with_assembly_tool_batch(context, tool_uses.length) do
+            dispatch_tools(
+              tool_uses,
+              context:,
+              events:,
+              parent_operation_id: turn_operation_id
+            )
+          end
           messages << Message.new(
             role: :tool,
-            content: tool_results
+            content: executed_tools.map(&:result)
           )
+          executed_tools.each do |executed_tool|
+            next if executed_tool.companion_content.empty?
+
+            messages << Message.new(
+              role: :user,
+              content: executed_tool.companion_content,
+              metadata: {transient: true, little_ghost_tool_companion: true}
+            )
+          end
           context.checkpoint(messages)
+          transition = consume_assembly_transition(context)
+          if transition
+            result = RunResult.new(
+              message: response.message,
+              stop_reason: :assembly_transition,
+              usage: context.usage,
+              messages: messages.freeze,
+              state: context.state
+            )
+            decision = run_callbacks(:after_invocation, {result:}, context:)
+            apply_cancellation_decision!(decision)
+            result = replacement_value(decision, :result, result)
+            @assembly_transition = transition
+            context.checkpoint(result.messages)
+            finish_instrumentation(
+              turn_handle,
+              operation_id: turn_operation_id,
+              outcome: :completed,
+              turn: turn + 1
+            )
+            metadata = model.details.to_h.merge(model_role: model.role)
+            finish_instrumentation(
+              agent_handle,
+              outcome: :completed,
+              duration_ms: duration_ms(started_at),
+              stop_reason: result.stop_reason,
+              operation_id:,
+              diagnostic: {output: diagnostic_message(result.message)},
+              **usage_attributes(result.usage)
+            )
+            emit(events, :invocation_stop, result:, metadata:)
+            return result
+          end
           finish_instrumentation(
             turn_handle,
             operation_id: turn_operation_id,
@@ -1287,6 +1233,10 @@ module LittleGhost
       end
       raise ProtocolError, "The agent reached its maximum model turns"
     rescue => error
+      @assembly_transitions_mutex.synchronize do
+        @assembly_transitions.delete(context)
+        @assembly_tool_batch_sizes.delete(context)
+      end
       finish_instrumentation(
         agent_handle,
         operation_id:,
@@ -1308,10 +1258,10 @@ module LittleGhost
       turn,
       events,
       parent_operation_id:,
-      interruptions:,
+      interjections:,
       structured_result_repair_due: false,
       recovery_attempt: 0,
-      interruption: nil
+      interjection: nil
     )
       started_at = monotonic_time
       operation_id = SecureRandom.uuid
@@ -1328,9 +1278,9 @@ module LittleGhost
         cancellation_token: context.cancellation_token,
         deadline: context.deadline
       )
-      interruption ||= interruptions.deliver
-      if interruption
-        context.activate_interruption(metadata: interruption.metadata, ids: interruption.interruption_ids)
+      interjection ||= interjections.deliver
+      if interjection
+        context.activate_interjection(metadata: interjection.metadata, ids: interjection.interjection_ids)
       end
       decision = run_callbacks(
         :before_model,
@@ -1339,11 +1289,11 @@ module LittleGhost
       )
       apply_cancellation_decision!(decision)
       request = replacement_value(decision, :request, request)
-      interruption_delivered = interruption&.tickets&.any? do |ticket|
-        !request_contains_interruption?(request, ticket)
+      interjection_delivered = interjection&.tickets&.any? do |ticket|
+        !request_contains_interjection?(request, ticket)
       end
-      if interruption_delivered
-        request = request_with_interruption(request, interruption)
+      if interjection_delivered
+        request = request_with_interjection(request, interjection)
       end
       messages.replace(request.messages)
       context.checkpoint(messages)
@@ -1358,20 +1308,20 @@ module LittleGhost
         model_settings: request.settings,
         **model_attributes
       )
-      if interruption_delivered
-        interruption.tickets.each do |ticket|
+      if interjection_delivered
+        interjection.tickets.each do |ticket|
           instrument(
-            :agent_interrupt_delivered,
+            :agent_interjection_delivered,
             parent_operation_id: operation_id,
-            interruption_id: ticket.id,
-            event_kind: :interrupt
+            interjection_id: ticket.id,
+            event_kind: :interjection
           )
         end
         emit(
           events,
-          :agent_interrupt_delivered,
-          interruption_ids: interruption.interruption_ids,
-          batch_key: interruption.batch_key
+          :agent_interjection_delivered,
+          interjection_ids: interjection.interjection_ids,
+          batch_key: interjection.batch_key
         )
       end
       emit(events, :model_start, turn: turn)
@@ -1409,21 +1359,21 @@ module LittleGhost
       decision = run_callbacks(:after_model, {request: request, response: response, turn: turn}, context: context)
       apply_cancellation_decision!(decision)
       response = replacement_value(decision, :response, response)
-      interruptions.resolve(
-        interruption,
-        AgentInterruptions::Response.new(
+      interjections.resolve(
+        interjection,
+        AgentInterjections::Result.new(
           text: response.message.text,
           tool_calls: response.message.content.any? { |content| content.is_a?(Content::ToolUse) },
-          interruption_ids: interruption&.interruption_ids || [],
-          batch_key: interruption&.batch_key
+          interjection_ids: interjection&.interjection_ids || [],
+          batch_key: interjection&.batch_key
         )
       )
-      interruption&.tickets&.each do |ticket|
+      interjection&.tickets&.each do |ticket|
         instrument(
-          :agent_interrupt_responded,
+          :agent_interjection_responded,
           parent_operation_id: operation_id,
-          interruption_id: ticket.id,
-          event_kind: :interrupt,
+          interjection_id: ticket.id,
+          event_kind: :interjection,
           diagnostic: {output: response.message.text}
         )
       end
@@ -1472,7 +1422,7 @@ module LittleGhost
           repair: structured_result_repair_due
         )
       )
-      [response, !interruption.nil?]
+      [response, !interjection.nil?]
     rescue => error
       finish_instrumentation(
         model_handle,
@@ -1508,8 +1458,8 @@ module LittleGhost
             parent_operation_id:,
             structured_result_repair_due:,
             recovery_attempt: recovery_attempt + 1,
-            interruptions:,
-            interruption:
+            interjections:,
+            interjection:
           )
         end
       end
@@ -1560,7 +1510,7 @@ module LittleGhost
               exception: diagnostic_tool_exception(tool, tool:)
             }
           )
-          next result
+          next ExecutedTool.new(result:, companion_content: [])
         end
 
         context.check!
@@ -1592,7 +1542,7 @@ module LittleGhost
               exception: diagnostic_tool_exception(rejection, tool:)
             }
           )
-          next result
+          next ExecutedTool.new(result:, companion_content: [])
         end
 
         execution_context = ToolExecution.new(
@@ -1639,7 +1589,7 @@ module LittleGhost
             exception: tool_error && diagnostic_tool_exception(tool_error, tool:)
           }.compact
         )
-        result
+        ExecutedTool.new(result:, companion_content: tool_result.companion_content)
       rescue ToolError => error
         result = build_tool_result(tool_use_id: tool_use.id, content: error.message, status: :error)
         finish_instrumentation(
@@ -1655,7 +1605,7 @@ module LittleGhost
             exception: diagnostic_tool_exception(error, tool:)
           }
         )
-        result
+        ExecutedTool.new(result:, companion_content: [])
       rescue => error
         finish_instrumentation(
           tool_handle,
@@ -1671,16 +1621,16 @@ module LittleGhost
       end
       if tools.any?(&:exclusive?)
         pairs.map do |tool_use, tool|
-          result = execution.call(tool_use, tool)
-          emit(events, :tool_stop, tool_use:, result:)
-          result
+          executed_tool = execution.call(tool_use, tool)
+          emit(events, :tool_stop, tool_use:, result: executed_tool.result)
+          executed_tool
         end
       else
         @executor.map(
           pairs,
           cancellation_token: context.cancellation_token,
-          on_result: lambda do |index, result|
-            emit(events, :tool_stop, tool_use: tool_uses.fetch(index), result:)
+          on_result: lambda do |index, executed_tool|
+            emit(events, :tool_stop, tool_use: tool_uses.fetch(index), result: executed_tool.result)
           end
         ) do |tool_use, tool|
           execution.call(tool_use, tool)
@@ -2136,6 +2086,10 @@ module LittleGhost
       value.respond_to?(:role) ? diagnostic_message(value) : value.to_s
     end
 
+    def tool_companion_message?(message)
+      message.metadata[:little_ghost_tool_companion] || message.metadata["little_ghost_tool_companion"]
+    end
+
     def diagnostic_tool_exception(error, tool:)
       diagnostic_exception(error).merge(message: truncated_tool_result(error.message))
     end