little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/agent.rb

@@ -10,46 +10,45 @@ module LittleGhost
   # 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.
+  # 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.
+  #
+  # 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:
@@ -66,9 +65,12 @@ module LittleGhost
       before_model after_model after_model_error
       before_tool after_tool
     ].freeze # :nodoc:
-    ExecutedTool = Data.define(:result, :companion_content) do # :nodoc:
+    ExecutedTool = Data.define(:result, :execution_result) do # :nodoc:
       def status = result.status
       def content = result.content
+      def value = execution_result.value
+      def artifacts = execution_result.artifacts
+      def presentation_content = execution_result.presentation_content
     end
 
     extend Support::ClassAttributes
@@ -81,6 +83,7 @@ module LittleGhost
     class_attribute :system_prompt_value
     class_attribute :system_prompt_builder_value
     class_attribute :tool_declarations_value, default: []
+    class_attribute :code_mode_configuration_value
     class_attribute :prompt_local_values, default: {}
     class_attribute :callback_values, default: Support::Callbacks.new(*CALLBACKS)
 
@@ -161,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
 
@@ -250,8 +254,9 @@ module LittleGhost
 
       # Adds tool or provider classes to the agent.
       #
-      # Every declaration must be a class. A provider class can supply tools
-      # dynamically by implementing <tt>tools(binding)</tt>.
+      # Every declaration must be a class. Pass Tool classes directly, or pass
+      # provider classes that supply tools dynamically through
+      # <tt>tools(binding)</tt>. Multiple declarations are cumulative.
       def tools(*values)
         invalid = values.flatten.compact.find { |value| !value.is_a?(Class) }
         if invalid
@@ -265,6 +270,20 @@ module LittleGhost
 
       def tool_declarations = tool_declarations_value # :nodoc:
 
+      # Enables code mode for this agent. +except+ names the application Tools
+      # that remain model-facing; every other application Tool moves into the
+      # engine catalog and is called through the parent-process Broker.
+      # Framework-owned subagent controls remain model-facing automatically.
+      def code_mode(engine: nil, except: nil, **options)
+        unknown = options.keys - %i[sandbox limits]
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+        declaration = options.merge(engine:, except:).compact
+        self.code_mode_configuration_value = declaration.freeze
+      end
+
+      def code_mode_configuration = code_mode_configuration_value # :nodoc:
+
       # Adds a named value or resolver to every prompt rendered for the agent.
       def prompt_local(name, *values, &resolver)
         raise ArgumentError, "Provide a prompt local value or block" if values.empty? && !resolver
@@ -296,8 +315,9 @@ module LittleGhost
       ##
       # Runs before one invocation begins.
       #
-      # The payload may be continued, replaced, or cancelled with a decision
-      # from Support::Callbacks.
+      # The payload is <tt>{messages: Array<Message>}</tt>. A replacement must
+      # contain +:messages+. Cancellation stops the invocation. A callback may
+      # also accept <tt>context:</tt> to receive the current RunContext.
       #
       # :singleton-method: before_invocation
       # :call-seq:
@@ -306,6 +326,10 @@ module LittleGhost
       ##
       # Observes or transforms the terminal invocation payload.
       #
+      # The payload is <tt>{result: RunResult}</tt>. A replacement must contain
+      # +:result+. Cancellation stops result delivery. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: after_invocation
       # :call-seq:
       #   after_invocation(callable = nil, prepend: false) { |payload| ... } -> self
@@ -313,6 +337,11 @@ module LittleGhost
       ##
       # Runs before a model request is sent.
       #
+      # The payload contains +:request+ (ModelRequest), zero-based +:turn+, and
+      # +:parent_operation_id+. A replacement must contain +:request+.
+      # Cancellation stops the invocation. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: before_model
       # :call-seq:
       #   before_model(callable = nil, prepend: false) { |payload| ... } -> self
@@ -320,6 +349,11 @@ module LittleGhost
       ##
       # Observes or transforms a successful model response.
       #
+      # The payload contains +:request+, +:response+ (ModelResponse), and
+      # zero-based +:turn+. A replacement must contain +:response+.
+      # Cancellation stops the invocation. A callback may accept
+      # <tt>context:</tt>.
+      #
       # :singleton-method: after_model
       # :call-seq:
       #   after_model(callable = nil, prepend: false) { |payload| ... } -> self
@@ -327,6 +361,11 @@ module LittleGhost
       ##
       # Handles a model error before it leaves the agent loop.
       #
+      # The payload contains +:request+, +:error+, zero-based +:turn+, and
+      # +:parent_operation_id+. Replacing +:request+ with a ModelRequest retries
+      # the model call, up to the framework recovery limit. Cancellation stops
+      # the invocation. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: after_model_error
       # :call-seq:
       #   after_model_error(callable = nil, prepend: false) { |payload| ... } -> self
@@ -334,6 +373,11 @@ module LittleGhost
       ##
       # Runs after validation but before a tool call starts.
       #
+      # The payload contains +:tool_use+, the bound +:tool+, +:operation_id+,
+      # and +:parent_operation_id+. Cancellation returns a model-visible Tool
+      # error, so its reason must be safe to disclose. Replacements are not
+      # consumed. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: before_tool
       # :call-seq:
       #   before_tool(callable = nil, prepend: false) { |payload| ... } -> self
@@ -341,6 +385,10 @@ module LittleGhost
       ##
       # Observes or transforms a completed tool result.
       #
+      # The payload contains the before-tool fields plus the normalized
+      # +:result+. A replacement must contain +:result+.
+      # Cancellation is not consumed. A callback may accept <tt>context:</tt>.
+      #
       # :singleton-method: after_tool
       # :call-seq:
       #   after_tool(callable = nil, prepend: false) { |payload| ... } -> self
@@ -466,16 +514,32 @@ module LittleGhost
       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,
@@ -499,8 +563,8 @@ module LittleGhost
         @owns_resources = true
         @closed = false
         @close_mutex = Mutex.new
-        @interruptions_mutex = Mutex.new
-        @active_interruptions = []
+        @interjections_mutex = Mutex.new
+        @active_interjections = []
         return
       end
 
@@ -519,6 +583,7 @@ module LittleGhost
       self.class.tool_declarations.each do |declaration|
         @tool_registry.register(declaration, replace: true)
       end
+      initialize_code_mode
       @structured_output_strategy = StructuredOutput.resolve(
         self.class.result_schema,
         model:,
@@ -535,8 +600,8 @@ 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 = {}
@@ -544,9 +609,13 @@ module LittleGhost
       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
+      @artifact_lifecycle = if runtime&.respond_to?(:runtime_hooks)
+        runtime.runtime_hooks.find { |hook| hook.is_a?(Runtime::Hooks::Artifacts) }
+      end
       apply_cancellation_decision!(run_callbacks(:after_initialize, self))
     rescue
       @tool_registry&.close
+      @code_mode_runtime&.close
       raise
     end
 
@@ -556,7 +625,19 @@ module LittleGhost
     def entrypoint_name = self.class.agent_id # :nodoc:
 
     def dispatch_tools(tool_uses, context:, events:, parent_operation_id:, parent_trace_context: nil) # :nodoc:
-      execute_tools(tool_uses, context, events, parent_operation_id:, parent_trace_context:)
+      counted = tool_uses.count { |tool_use| !code_mode_control_tool?(tool_use) }
+      context.record_tool_calls!(counted, maximum: @max_tool_calls) if counted.positive?
+      execute_tools(
+        tool_uses,
+        context,
+        events,
+        parent_operation_id:,
+        parent_trace_context:
+      )
+    end
+
+    def code_mode_runtime # :nodoc:
+      @code_mode_runtime || raise(ConfigurationError, "code mode is not enabled for this agent")
     end
 
     def request_assembly_transition(value, context:) # :nodoc:
@@ -575,94 +656,69 @@ module LittleGhost
 
     attr_reader :assembly_transition # :nodoc:
 
-    # 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
-
-    # 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)}
         )
@@ -673,9 +729,9 @@ module LittleGhost
     # Streams one invocation as StreamEvent objects.
     #
     # Agents built inside a run accept history, JSON-like context, cancellation,
-    # deadlines, settings, and trusted invocation template paths. An agent
-    # instance may be streamed only according to the lifecycle managed by its
-    # owning run. Every template path must be an application-created TrustedPath;
+    # deadlines, settings, and trusted invocation template paths. An Agent
+    # instance may be streamed only by its owning Run. Every template path must
+    # be an application-created TrustedPath;
     # the wrapper records a trust decision and must never contain unchecked
     # request or model input.
     def stream(
@@ -690,9 +746,9 @@ 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?
         raise ArgumentError, "input is required" if input.nil?
@@ -722,7 +778,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,
@@ -730,8 +786,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
@@ -744,16 +800,17 @@ 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)
+          @code_mode_runtime&.close(context: run_context)
+          interjections.close(AgentInterjectionError.new("Agent finished before the interjection was delivered"))
+          unregister_interjections(interjections)
         end
       end
     end
@@ -770,24 +827,24 @@ module LittleGhost
       end.freeze
     end
 
-    # The materialized tools available during this agent run.
+    # The Tool registry 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 }
+          [@code_mode_runtime, tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
+          @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)
@@ -810,7 +867,15 @@ module LittleGhost
     # Returns the tools exposed to the model for +turn+. Subclasses may override
     # this hook to filter the already-authorized tool list.
     def model_tools(tools, context:, turn:)
-      tools
+      return tools unless @code_mode_runtime
+
+      exceptions = Array(@code_mode_declaration[:except]).map(&:to_s)
+      tools.select do |specification|
+        name = specification.fetch(:name, specification["name"]).to_s
+        tool = tool_registry.fetch(name) if tool_registry.names.include?(name)
+        exceptions.include?(name) || %w[exec wait stop].include?(name) ||
+          tool.is_a?(Subagents::ControlTool) || !tool
+      end
     end
 
     # :doc:
@@ -829,45 +894,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,
@@ -879,10 +944,10 @@ 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
 
@@ -906,16 +971,22 @@ module LittleGhost
       template_paths:,
       events:,
       parent_operation_id:,
-      interruptions:,
-      interrupt_ready:
+      interjections:,
+      interject_ready:
     )
       started_at = monotonic_time
       operation_id = SecureRandom.uuid
+      events = agent_stream_events(
+        events,
+        input:,
+        operation_id:,
+        parent_operation_id:
+      )
       context.bind_agent_operation_id(operation_id)
       @assembly_transitions_mutex.synchronize { @assembly_transition = nil }
-      interruptions.bind(operation_id, target_operation_id: parent_operation_id)
-      register_interruptions(interruptions)
-      interrupt_ready&.call
+      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,
@@ -928,7 +999,6 @@ module LittleGhost
       prompt = rendered_system_prompt(template_locals, template_paths)
       messages.unshift(Message.new(role: :system, content: prompt)) unless prompt.to_s.empty?
       messages << (input.is_a?(Message) ? input : Message.new(role: :user, content: input))
-      tool_call_count = 0
       structured_result_repair_due = false
 
       decision = run_callbacks(:before_invocation, {messages: messages}, context: context)
@@ -946,7 +1016,7 @@ module LittleGhost
         )
         begin
           context.check!
-          response, interrupted = invoke_model(
+          response, interjected = invoke_model(
             messages,
             context,
             settings,
@@ -954,9 +1024,9 @@ module LittleGhost
             events,
             parent_operation_id: turn_operation_id,
             structured_result_repair_due:,
-            interruptions:
+            interjections:
           )
-          messages.reject! { |message| tool_companion_message?(message) }
+          messages.reject! { |message| artifact_presentation_message?(message) }
           messages << response.message
           tool_uses = response.message.content.grep(Content::ToolUse)
           result_tool_uses = structured_result_tool_uses(tool_uses)
@@ -969,12 +1039,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
@@ -1029,20 +1099,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
@@ -1050,12 +1120,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
@@ -1145,9 +1215,6 @@ module LittleGhost
             )
           end
 
-          tool_call_count += tool_uses.length
-          raise ProtocolError, "The agent reached its maximum tool calls" if tool_call_count > @max_tool_calls
-
           executed_tools = with_assembly_tool_batch(context, tool_uses.length) do
             dispatch_tools(
               tool_uses,
@@ -1158,15 +1225,16 @@ module LittleGhost
           end
           messages << Message.new(
             role: :tool,
-            content: executed_tools.map(&:result)
+            content: executed_tools.map(&:result),
+            metadata: artifact_message_metadata(executed_tools)
           )
           executed_tools.each do |executed_tool|
-            next if executed_tool.companion_content.empty?
+            next if executed_tool.presentation_content.empty?
 
             messages << Message.new(
               role: :user,
-              content: executed_tool.companion_content,
-              metadata: {transient: true, little_ghost_tool_companion: true}
+              content: executed_tool.presentation_content,
+              metadata: {transient: true, little_ghost_artifact_presentation: true}
             )
           end
           context.checkpoint(messages)
@@ -1263,10 +1331,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
@@ -1283,9 +1351,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,
@@ -1294,11 +1362,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)
@@ -1313,26 +1381,27 @@ 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)
       response = nil
       time_to_first_token = nil
       buffered_events = strategy ? [] : nil
+      code_mode_control_indexes = {}
 
       model.stream(request).each do |event|
         context.check!
@@ -1353,7 +1422,9 @@ module LittleGhost
             **model_attributes
           )
         end
-        buffered_events ? buffered_events << event : events << event
+        unless code_mode_control_event?(event, code_mode_control_indexes)
+          buffered_events ? buffered_events << event : events << event
+        end
         response = event.data[:response] if event.type == :message_stop
       end
       raise ProtocolError, "The model stream ended without a response" unless response
@@ -1364,21 +1435,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
@@ -1427,7 +1498,7 @@ module LittleGhost
           repair: structured_result_repair_due
         )
       )
-      [response, !interruption.nil?]
+      [response, !interjection.nil?]
     rescue => error
       finish_instrumentation(
         model_handle,
@@ -1463,8 +1534,8 @@ module LittleGhost
             parent_operation_id:,
             structured_result_repair_due:,
             recovery_attempt: recovery_attempt + 1,
-            interruptions:,
-            interruption:
+            interjections:,
+            interjection:
           )
         end
       end
@@ -1476,7 +1547,8 @@ module LittleGhost
         raise ProtocolError, "The model returned duplicate tool use ids"
       end
 
-      tool_uses.each { |tool_use| emit(events, :tool_start, tool_use: tool_use) }
+      tool_uses.each { |tool_use| emit(events, :tool_start, tool_use: tool_use) unless code_mode_control_tool?(tool_use) }
+      presentation_budget = Artifacts::PresentationBudget.new
       pairs = tool_uses.map do |tool_use|
         [tool_use, tool_registry.fetch(tool_use.name)]
       rescue ToolError => error
@@ -1515,7 +1587,8 @@ module LittleGhost
               exception: diagnostic_tool_exception(tool, tool:)
             }
           )
-          next ExecutedTool.new(result:, companion_content: [])
+          execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error: tool)
+          next ExecutedTool.new(result:, execution_result:)
         end
 
         context.check!
@@ -1547,7 +1620,8 @@ module LittleGhost
               exception: diagnostic_tool_exception(rejection, tool:)
             }
           )
-          next ExecutedTool.new(result:, companion_content: [])
+          execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error: rejection)
+          next ExecutedTool.new(result:, execution_result:)
         end
 
         execution_context = ToolExecution.new(
@@ -1560,20 +1634,36 @@ module LittleGhost
           parent_trace_context:
         )
         invoke = lambda do
-          with_tool_execution(execution_context) do
-            invoke_tool(
-              tool_use, tool, context,
-              operation_id:, parent_operation_id:
-            )
+          ExecutionState.with(tool_execution: execution_context) do
+            with_tool_execution(execution_context) do
+              invoke_tool(
+                tool_use, tool, context,
+                operation_id:, parent_operation_id:
+              )
+            end
           end
         end
-        tool_result = tool.exclusive? ? synchronize_exclusive_tools(&invoke) : invoke.call
+        tool_result = if tool.exclusive? && !code_mode_control_tool?(tool_use)
+          synchronize_exclusive_tools(&invoke)
+        else
+          invoke.call
+        end
         after_decision = run_callbacks(
           :after_tool,
           callback_payload.merge(result: tool_result),
           context: context
         )
         tool_result = replacement_value(after_decision, :result, tool_result)
+        if @artifact_lifecycle
+          tool_result = @artifact_lifecycle.prepare_tool_result(
+            tool_result,
+            tool_use:,
+            run: @run,
+            workspace:,
+            context:
+          )
+        end
+        tool_result = bound_artifact_presentation(tool_result, presentation_budget)
         result = build_tool_result(
           tool_use_id: tool_use.id,
           content: tool_result.content,
@@ -1594,7 +1684,7 @@ module LittleGhost
             exception: tool_error && diagnostic_tool_exception(tool_error, tool:)
           }.compact
         )
-        ExecutedTool.new(result:, companion_content: tool_result.companion_content)
+        ExecutedTool.new(result:, execution_result: tool_result)
       rescue ToolError => error
         result = build_tool_result(tool_use_id: tool_use.id, content: error.message, status: :error)
         finish_instrumentation(
@@ -1610,7 +1700,8 @@ module LittleGhost
             exception: diagnostic_tool_exception(error, tool:)
           }
         )
-        ExecutedTool.new(result:, companion_content: [])
+        execution_result = Tool::ExecutionResult.new(content: result.content, status: :error, error:)
+        ExecutedTool.new(result:, execution_result:)
       rescue => error
         finish_instrumentation(
           tool_handle,
@@ -1627,7 +1718,7 @@ module LittleGhost
       if tools.any?(&:exclusive?)
         pairs.map do |tool_use, tool|
           executed_tool = execution.call(tool_use, tool)
-          emit(events, :tool_stop, tool_use:, result: executed_tool.result)
+          emit(events, :tool_stop, tool_use:, result: executed_tool.result) unless code_mode_control_tool?(tool_use)
           executed_tool
         end
       else
@@ -1635,7 +1726,8 @@ module LittleGhost
           pairs,
           cancellation_token: context.cancellation_token,
           on_result: lambda do |index, executed_tool|
-            emit(events, :tool_stop, tool_use: tool_uses.fetch(index), result: executed_tool.result)
+            tool_use = tool_uses.fetch(index)
+            emit(events, :tool_stop, tool_use:, result: executed_tool.result) unless code_mode_control_tool?(tool_use)
           end
         ) do |tool_use, tool|
           execution.call(tool_use, tool)
@@ -1643,10 +1735,82 @@ module LittleGhost
       end
     end
 
+    def bound_artifact_presentation(result, budget)
+      accepted = budget.accept(result.presentation_content)
+      return result if accepted.equal?(result.presentation_content) || accepted == result.presentation_content
+
+      fallback = result.artifacts.reject do |artifact|
+        artifact.metadata[:complete_result] || artifact.metadata["complete_result"]
+      end
+      references = artifact_references(fallback)
+      content = if references.empty?
+        result.content
+      else
+        "#{result.content}\n\nArtifacts:\n#{references.join("\n")}"
+      end
+
+      Tool::ExecutionResult.new(
+        value: result.value,
+        content:,
+        status: result.status,
+        error: result.error,
+        artifacts: result.artifacts,
+        presentation_content: accepted
+      )
+    end
+
+    def artifact_references(artifacts)
+      artifacts.filter_map do |artifact|
+        next unless artifact.reference.is_a?(String) && artifact.bytes
+
+        details = [artifact.media_type, "#{artifact.bytes} bytes"].compact.join(", ")
+        "- #{artifact.reference} (#{details})"
+      end
+    end
+
+    def artifact_message_metadata(executed_tools)
+      artifacts = executed_tools.flat_map(&:artifacts).select do |artifact|
+        artifact.reference.is_a?(String) && artifact.bytes
+      end
+      return {} if artifacts.empty?
+
+      {
+        "little_ghost_artifacts" => artifacts.map do |artifact|
+          {
+            "reference" => artifact.reference,
+            "name" => artifact.name,
+            "media_type" => artifact.media_type,
+            "bytes" => artifact.bytes
+          }.compact
+        end
+      }
+    end
+
     def invoke_tool(tool_use, tool, context, operation_id:, parent_operation_id:)
       tool.execute(tool_use.input, context:)
     end
 
+    def code_mode_control_tool?(tool_use)
+      @code_mode_runtime && %w[exec wait stop].include?(tool_use.name)
+    end
+
+    def code_mode_control_event?(event, indexes)
+      return false unless @code_mode_runtime
+
+      index = event.data[:index]
+      case event.type
+      when :tool_call_start
+        indexes[index] = true if %w[exec wait stop].include?(event.data[:name])
+        indexes.key?(index)
+      when :tool_call_delta
+        indexes.key?(index)
+      when :tool_call_stop
+        indexes.delete(index)
+      else
+        false
+      end
+    end
+
     def parent_trace_attributes(trace_context)
       return {} unless trace_context.is_a?(Hash) && !trace_context.empty?
 
@@ -1943,19 +2107,39 @@ module LittleGhost
 
     def rendered_system_prompt(locals, invocation_paths)
       prompt = self.class.system_prompt
-      return prompt.call(locals) if prompt.respond_to?(:call)
-      return prompt if prompt
+      prompt = prompt.call(locals) if prompt.respond_to?(:call)
+      return append_code_mode_instructions(prompt) if prompt
       template = self.class.system_template
-      return DEFAULT_SYSTEM_PROMPT if instance_of?(Agent) && run && !template
+      return append_code_mode_instructions(DEFAULT_SYSTEM_PROMPT) if instance_of?(Agent) && run && !template
 
       template ||= "#{self.class.logical_path}/system" if run
       return nil unless template
 
-      @template_resolver.render(
+      append_code_mode_instructions(@template_resolver.render(
         template,
         locals: locals,
         invocation_paths: invocation_paths
-      )
+      ))
+    end
+
+    def initialize_code_mode
+      declaration = self.class.code_mode_configuration
+      return unless declaration
+
+      defaults = @runtime.respond_to?(:code_mode_configuration) ? @runtime.code_mode_configuration : nil
+      @code_mode_declaration = (defaults || {}).merge(declaration).transform_keys(&:to_sym).freeze
+      unknown = @code_mode_declaration.keys - %i[engine except sandbox limits]
+      raise ConfigurationError, "Unknown code-mode option: #{unknown.first.inspect}" unless unknown.empty?
+      @code_mode_runtime = CodeMode::AgentRuntime.new(agent: self, declaration: @code_mode_declaration)
+      @tool_registry.register(CodeMode::ExecTool)
+      @tool_registry.register(CodeMode::WaitTool)
+      @tool_registry.register(CodeMode::StopTool)
+    end
+
+    def append_code_mode_instructions(prompt)
+      return prompt unless @code_mode_runtime
+
+      [prompt, @code_mode_runtime.instructions].compact.reject(&:empty?).join("\n\n")
     end
 
     def default_template_resolver(paths)
@@ -1981,6 +2165,19 @@ module LittleGhost
       events << StreamEvent.build(type, **data)
     end
 
+    def agent_stream_events(events, input:, operation_id:, parent_operation_id:)
+      return events unless run&.include_agent_events?
+
+      source = AgentStreamSource.build(
+        agent_id: self.class.agent_id,
+        agent_path:,
+        operation_id:,
+        parent_operation_id:,
+        assembly_path: agent_stream_path
+      )
+      AgentStreamSink.new(destination: events, run:, source:, input:)
+    end
+
     def instrument(name, **attributes)
       attributes.delete(:diagnostic) unless self.class.capture_diagnostics
       values = correlation_attributes.merge(attributes.compact)
@@ -2091,8 +2288,8 @@ 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"]
+    def artifact_presentation_message?(message)
+      message.metadata[:little_ghost_artifact_presentation] || message.metadata["little_ghost_artifact_presentation"]
     end
 
     def diagnostic_tool_exception(error, tool:)