little_ghost 0.9.0 → 0.11.0

data/docs/guides/getting_started.md

@@ -17,7 +17,8 @@ $ export OPENROUTER_API_KEY="..."
 
 Use your application's secret manager outside a local shell, and never commit provider credentials.
 
-This guide uses OpenRouter to keep setup to one key. Prefer another hosted
+This guide uses OpenRouter, a service that sends requests to your chosen AI
+model. Set `OPENROUTER_API_KEY` to a key from your OpenRouter account. Prefer another hosted
 provider or a local model server? Start with [Provider Support](providers.md).
 
 ## See your first answer
@@ -41,10 +42,11 @@ else
 end
 ```
 
-Run the file and you have a working AI feature:
+`model` selects the service and model to call. `system_prompt` supplies the
+instructions the model follows on each request. Run the file with your bundle:
 
 ```sh
-$ ruby customer_support_agent.rb
+$ bundle exec ruby customer_support_agent.rb
 ```
 
 `CustomerSupportAgent.ask` creates a `LittleGhost::Run` for this request. When the work finishes, the Run holds the outcome and response.
@@ -55,7 +57,9 @@ The selected external provider may receive system instructions, caller input, co
 
 ## Connect the agent to your application
 
-The first agent can answer general questions. A **tool** gives it a focused operation backed by your Ruby code:
+The first agent can answer general questions. A **tool** gives it a focused
+operation backed by your Ruby code. Add this class after the `require` line,
+before `CustomerSupportAgent`:
 
 ```ruby
 class HelpCenterLookupTool < LittleGhost::Tool
@@ -80,7 +84,9 @@ class HelpCenterLookupTool < LittleGhost::Tool
 end
 ```
 
-Make the tool available to the agent and tell the model when to use it:
+`input_schema` describes the arguments the model may supply. Here, `topic` must
+be one of the help center's keys. Replace the Agent definition and the call at
+the end of the file with these:
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
@@ -106,84 +112,48 @@ LittleGhost checks the model's arguments before it calls
 `HelpCenterLookupTool#call`. The Tool's result then becomes context for the
 model.
 
-### Use application context for private data
-
-The schema checks shape, not permission. When a Tool reads private data or
-changes something, use identity and account information established by your
-application rather than asking the model to supply it.
-
-While an Agent is working, LittleGhost binds each Tool instance to the current
-Run. The Tool can read request values through its `run` accessor:
-
-```ruby
-class OrderStatusTool < LittleGhost::Tool
-  ORDER_STATUSES = {
-    ["user-7", "account-2", "481"] => "out for delivery"
-  }.freeze
-
-  description "Look up an order that belongs to the current customer."
-  input_schema(
-    type: "object",
-    properties: {order_number: {type: "string"}},
-    required: ["order_number"],
-    additionalProperties: false
-  )
-
-  def call(input)
-    lookup = [
-      run.invocation.actor_id,
-      run.invocation.context.fetch("account_id"),
-      input.fetch("order_number")
-    ]
-
-    ORDER_STATUSES.fetch(lookup) do
-      raise LittleGhost::ToolError, "Order not found"
-    end
-  end
-end
-
-class CustomerSupportAgent < LittleGhost::Agent
-  tools HelpCenterLookupTool, OrderStatusTool
-end
-
-run = CustomerSupportAgent.ask(
-  "Where is order 481?",
-  actor_id: "user-7",
-  context: {account_id: "account-2"}
-)
-```
-
-Here, `order_number` came from the model. The application supplied `actor_id`
-and `account_id` after authenticating the caller. LittleGhost places those
-request values on `run.invocation`; context keys become strings.
-
-> **Safety note:** Treat model-selected Tool arguments like any other external
-> input. Check permission using the current user and account before returning
-> private data or performing a write.
-
-That is enough to authorize the first Tool safely. [Core Concepts](core_concepts.md) names the request and working-state objects behind `run`, and [Running in Production](production.md) explains what changes when you add saved conversations.
+> **Safety note:** The schema checks arguments, not permission. This example
+> reads a public help center. Before a Tool returns private data or changes
+> anything, check permission using the user and account identified by your
+> application—not values supplied by the model. [Tools](tools.md) shows how to
+> pass that information to a Tool.
 
 ## Stream the same agent
 
-Use `.stream_ask` when a console, HTTP response, or user interface should receive progress as it happens:
+Use `.stream_ask` when a console, HTTP response, or user interface should receive
+the answer as it is written. Replace the `.ask` call with the following code.
+
+Each `:agent_stream` event contains the Agent's progress and a `source` that
+identifies which Agent produced it. The source check below selects the Agent
+you called directly: `/root` with no enclosing assembly steps. `:text_delta`
+contains the next piece of its answer.
 
 ```ruby
 stream = CustomerSupportAgent.stream_ask("Can I get a refund?")
 
 run = stream.each do |event|
   case event.type
-  when :text_delta
-    print event.data.fetch(:text)
+  when :agent_stream
+    source = event.data.fetch(:source)
+    next unless source.agent_path == "/root" && source.assembly_path.empty?
+
+    progress = event.data.fetch(:event)
+    print progress.data.fetch(:text) if progress.type == :text_delta
   when :run_error
     warn event.data.fetch(:message)
   end
 end
 
-puts "\n#{run.response}" if run.completed?
+run.response # The completed answer, separate from live progress.
 warn run.error.class.name if run.failed?
 ```
 
-The stream yields `LittleGhost::StreamEvent` values. Text, tool activity, usage, and completion all look the same across providers. When enumeration finishes, `.each` returns the same `LittleGhost::Run` that now holds the final outcome and response.
+When enumeration finishes, `.each` returns the Run with the final outcome and
+complete response. You can display progress and still read the finished answer.
+
+If you later add other Agents, their progress arrives in the same stream. Keep
+the source check when your audience should see only this Agent's text. See
+[Compose Agents](assemblies.md) to display several participants.
 
 ## Give the code a home
 
@@ -223,8 +193,8 @@ The source repository also contains a complete
 [single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
 and a
 [coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness)
-that demonstrates Agents, prompt views, Tools, a Graph, a Workspace, and a
-native Sandbox.
+that shows a larger application with several agents and tools for working
+with files.
 
 You now have the smallest useful LittleGhost application: one Agent, one Tool, and one familiar Ruby call.
 

data/docs/guides/integrations.md

@@ -27,10 +27,22 @@ events = LittleGhost::AGUI::Adapter.new.stream(
 events.each { |event| websocket.write(JSON.generate(event)) }
 ```
 
-The adapter translates the full Run, including model output, Tool activity,
-retries, subagent activity, and the final outcome. It does not keep state between
-calls. Your application owns the connection, backpressure, disconnect behavior,
-and any request state its callbacks need.
+The adapter translates Run lifecycle and final outcomes, plus selected Agent
+progress such as model output, Tool activity, and retries. By default, it selects
+only the root Agent: `agent_path == "/root"` with an empty `assembly_path`.
+Nested Agent progress is not forwarded. The adapter reads Agent progress from
+`:agent_stream` and reports aggregate usage separately.
+
+Pass `source_filter:` to `LittleGhost::AGUI::Adapter.new` to select other
+participants. This application-owned callable receives an `AgentStreamSource`
+and returns a truthy value only for sources the client may see. Match the
+enclosing assembly path as well as the Agent identity when selecting a nested
+participant. Computed assembly answers arrive in `RUN_FINISHED`'s result, not
+as synthetic text deltas.
+
+The adapter does not keep state between calls. Your application owns the
+connection, backpressure, disconnect behavior, and any request state its
+callbacks need.
 
 LittleGhost may emit event types beyond the core AG-UI set. Decide whether the
 client preserves or ignores types it does not recognize. See the [AG-UI event
@@ -38,8 +50,10 @@ documentation](https://docs.ag-ui.com/concepts/events) when implementing the
 client.
 
 > **Safety note:** A Run stream can include model output, Tool arguments and
-> results, errors, and participant activity. Check that the connected user may
-> see the complete Run, then filter fields before sending or storing events.
+> results, errors, and participant activity. Source selection controls which
+> Agent progress is forwarded; it does not redact that progress or filter the
+> final Run result. Check that the connected user may see those values, and
+> filter sensitive fields before sending or storing events.
 
 Calling `each` drives the source stream on the caller's fiber or thread. When a
 client disconnects, stop enumerating and decide whether the application should

data/docs/guides/models_and_providers.md

@@ -74,9 +74,10 @@ application obtains short-lived credentials at runtime, configure a credential
 resolver that returns them for the selected connection.
 
 > **Safety note:** The selected provider may receive system instructions,
-> caller input, conversation history, Tool results, schemas, and attachments.
-> Choose a provider that is appropriate for that data, and keep credentials and
-> provider endpoints under application control.
+> caller input, application state, question text, conversation
+> history, Tool results, schemas, and attachments. Choose a provider that is
+> appropriate for that data, and keep credentials and provider endpoints under
+> application control.
 
 ## Choose a role for each request
 
@@ -155,29 +156,9 @@ Results and Content](structured_outputs_and_content.md) covers strict schemas,
 provider strategies, repair behavior, and the application checks that still
 belong outside the schema.
 
-## Create embeddings
-
-Use `LittleGhost.embed` when your application needs numeric representations for
-search, clustering, or another similarity-based feature:
-
-```ruby
-response = LittleGhost.embed(
-  model: "primary:openai/text-embedding-3-small",
-  inputs: ["Reset a password", "Track a transfer"]
-)
-
-response.vectors.length # => 2
-response.dimensions
-response.usage.input_tokens
-```
-
-The response keeps vectors in the same order as the inputs. LittleGhost rejects
-an incomplete or malformed response instead of returning a partial batch.
-Embedding text is sent to the selected provider, so choose one appropriate for
-that data. [Provider Support](providers.md) identifies adapters with embedding
-support; `LittleGhost::Embeddings::Request` documents settings and request
-bounds.
-
-Continue with [Prompts as Views](prompt_views.md) when an Agent's instructions
-outgrow one string. See [Structured Results and Content](structured_outputs_and_content.md)
-when you need checked result shapes, images, or documents.
+Continue with [Decisions](decisions.md) for typed, structured answers or
+[Embeddings](embeddings.md) for text representations. [Prompts as
+Views](prompt_views.md) moves growing Agent instructions into conventional ERB
+files. See [Structured Results and
+Content](structured_outputs_and_content.md) for checked result shapes, images,
+or documents.

data/docs/guides/production.md

@@ -218,19 +218,32 @@ values as the answer arrives:
 stream = CustomerSupportAgent.stream_ask(question)
 
 run = stream.each do |event|
-  publish(event) if event.type == :text_delta
+  next unless event.type == :agent_stream
+
+  source = event.data.fetch(:source)
+  next unless source.agent_path == "/root" && source.assembly_path.empty?
+
+  progress = event.data.fetch(:event)
+  publish(progress) if progress.type == :text_delta
 end
 
 record_outcome(run.outcome, error_type: run.error&.class&.name)
 ```
 
-Composite assembly streams include intermediate and nested Agent work as `:agent_stream` events. This default also applies to the event consumer passed to `start_execution`. Pass `include_agent_events: false` when only the ordinary public stream is needed.
+Every Run includes live source-tagged `:agent_stream` events from all its Agents,
+including nested assemblies and subagents. This example displays only root Agent
+text. The same contract applies to `start_execution`. Progress is not repeated
+as raw events or replayed when a Workflow selects a result. Read `run.result`
+or the terminal Run event for the complete answer and aggregate usage. Pass
+`include_agent_events: false` to omit all Agent progress without changing work,
+lifecycle events, or final results.
 
 > **Safety note:** Contextual events can include inputs, reasoning, Tool
 > arguments and results, errors, and output from every participant. Check that
 > the destination may see the complete Run, or filter the events before sending
-> or storing them. LittleGhost's AG-UI adapter ignores these events unless the
-> application translates them explicitly.
+> or storing them. LittleGhost's [AG-UI adapter](integrations.md) selects root
+> Agent progress by default; its `source_filter:` option lets the application
+> select permitted assembly participants.
 
 Use `start_execution` when the caller must stay free for other work, or when you want to deliver an interjection to an active response:
 

data/docs/guides/providers.md

@@ -23,17 +23,24 @@ end
 protocol. An Agent can now use a target such as
 `primary:openai/gpt-5.6-luna`.
 
-| Provider or endpoint | Adapter | Generation | Embeddings |
-| --- | --- | --- | --- |
-| OpenRouter | `:openrouter` | Chat Completions | When the model supports it |
-| OpenAI | `:openai` | Responses or Chat Completions | Yes |
-| Compatible API | `:openai_compatible` | Responses or Chat Completions | When the endpoint implements it |
-| Ollama | `:openai_compatible` | Responses or Chat Completions | When the model supports it |
-| Anthropic | `:anthropic` | Messages | No |
-| Gemini | `:gemini` | Gemini API | No |
-| Vertex AI | `:vertex_ai` | Gemini on Vertex AI | No |
-| Bedrock | `:bedrock` | Converse | Titan Text Embeddings V2 |
-| LM Studio | `:lm_studio` | Responses or Chat Completions | Yes |
+| Provider or endpoint | Adapter | Generation | Decisions | Embeddings |
+| --- | --- | --- | --- | --- |
+| OpenRouter | `:openrouter` | Chat Completions | Typed decision endpoints | When the model supports it |
+| TypeSafe | `:typesafe` | No | System One decisions | No |
+| OpenAI | `:openai` | Responses or Chat Completions | No | Yes |
+| Compatible API | `:openai_compatible` | Responses or Chat Completions | No | When the endpoint implements it |
+| Ollama | `:openai_compatible` | Responses or Chat Completions | No | When the model supports it |
+| Anthropic | `:anthropic` | Messages | No | No |
+| Gemini | `:gemini` | Gemini API | No | No |
+| Vertex AI | `:vertex_ai` | Gemini on Vertex AI | No | No |
+| Bedrock | `:bedrock` | Converse | No | Titan Text Embeddings V2 |
+| LM Studio | `:lm_studio` | Responses or Chat Completions | No | Yes |
+
+TypeSafe Jev is a decision model that returns structured answers to typed
+questions. Its API and OpenRouter's Jev routes support the same question
+types.
+These operations return structured answers directly and do not create an Agent
+Run. See [Decisions](decisions.md) for the question and answer model.
 
 Capabilities can vary by model, account, and server version. Handle provider
 failures even when a model is expected to support a feature.
@@ -60,6 +67,46 @@ Use OpenRouter's `publisher/model` form, such as
 The selected model must support embeddings before you call
 `LittleGhost.embed`.
 
+For Jev decisions, OpenRouter supports both decision endpoints. The default
+uses the Decisions API and namespaced model identifiers such as
+`openrouter:~typesafe/jev-latest`:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    openrouter: {
+      adapter: :openrouter,
+      api_key: ENV.fetch("OPENROUTER_API_KEY"),
+      decision_api: :decisions
+    }
+  }
+end
+```
+
+Set `decision_api: :system_one` to use `/api/v1/systemone`; that route
+accepts a bare TypeSafe model identifier such as `jev-latest`, used as
+`openrouter:jev-latest`.
+OpenRouter describes these routes in its [Jev guide](https://openrouter.ai/blog/insights/what-is-jev/).
+
+### TypeSafe
+
+Connect directly to TypeSafe's System One endpoint with a TypeSafe API key:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    typesafe: {
+      adapter: :typesafe,
+      api_key: ENV.fetch("TYPESAFE_API_KEY")
+    }
+  }
+end
+```
+
+Use a Jev identifier such as `typesafe:jev-latest`. This adapter supports
+typed decisions only. See the [TypeSafe API reference](https://docs.typesafe.ai/api)
+for question and answer fields.
+
 ### OpenAI
 
 ```ruby

data/lib/little_ghost/ag_ui/adapter.rb

@@ -18,8 +18,27 @@ module LittleGhost
     # The adapter has no state between #stream calls, so one instance can
     # translate independent runs.
     #
+    # Progress comes from the Run's native +:agent_stream+ events. By default,
+    # only the top-level Agent's progress reaches the interface: its
+    # AgentStreamSource[rdoc-ref:LittleGhost::AgentStreamSource] has +agent_path+
+    # <tt>/root</tt> and an empty +assembly_path+. A composite run's final
+    # response arrives in +RUN_FINISHED+ independently of participant progress.
+    # Unwrapped progress and wrapped invocation usage or terminal events are
+    # ignored; run lifecycle and aggregate usage remain separate.
+    #
     # === Choose what the interface receives
     #
+    # Pass a +source_filter+ callable to select a participant whose progress is
+    # intended for the destination. The callable receives an AgentStreamSource
+    # and replaces the default root selection. Choose it in trusted application
+    # code, not from request or model values.
+    #
+    #   adapter = LittleGhost::AGUI::Adapter.new(source_filter: lambda { |source|
+    #     step = source.assembly_path.first
+    #     source.agent_path == "/root" && source.assembly_path.length == 1 &&
+    #       step.assembly_id == "response_workflow" && step.participant == "response"
+    #   })
+    #
     # Provider plaintext reasoning becomes AG-UI reasoning events. Tool
     # arguments and results, invocation metadata, subagent events, trace context,
     # and selected error text also pass through without redaction. Authorize and
@@ -28,8 +47,32 @@ module LittleGhost
     # continuity artifacts are never exposed here.
     class Adapter
       TERMINAL_EVENTS = %i[run_partial run_cancel run_stop run_error].freeze # :nodoc:
+      PROGRESS_EVENTS = %i[
+        message_start reasoning_delta text_delta message_stop
+        tool_call_start tool_call_delta tool_call_stop tool_stop
+        model_retry agent_interjection_delivered
+      ].freeze # :nodoc:
+
+      # Selects which Agent's progress reaches the interface.
+      #
+      # +source_filter+ is a callable receiving an AgentStreamSource and returning
+      # a truthy value to include its progress. Omit it to include only a root
+      # Agent outside any composite assembly. A shared adapter may call the filter
+      # concurrently for independent streams, so keep its captured state safe for
+      # concurrent use. Filter exceptions propagate to the caller of #stream.
+      # Raises ArgumentError when +source_filter+ is not callable.
+      def initialize(source_filter: nil)
+        if !source_filter.nil? && !source_filter.respond_to?(:call)
+          raise ArgumentError, "source_filter must be callable"
+        end
+
+        @source_filter = source_filter
+      end
 
-      # Lazily translates +events+ for one AG-UI run.
+      # Lazily translates a Run's +events+ into AG-UI hashes for one interface run.
+      #
+      # Returns an Enumerator. Selected Agent progress arrives as it is produced;
+      # +RUN_FINISHED+ carries the run's final response in <tt>result[:response]</tt>.
       def stream(events, thread_id:, run_id:)
         Enumerator.new do |output|
           message_id = nil
@@ -39,6 +82,9 @@ module LittleGhost
           tool_call_ids = {}
 
           events.each do |source|
+            source = selected_event(source)
+            next unless source
+
             superseded_message_id = message_id if source.type == :model_retry && message_started
             if reasoning_id && source.type != :reasoning_delta
               output << event("REASONING_MESSAGE_END", messageId: reasoning_message_id)
@@ -182,6 +228,23 @@ module LittleGhost
 
       private
 
+      def selected_event(event)
+        return unless event.is_a?(StreamEvent)
+        return PROGRESS_EVENTS.include?(event.type) ? nil : event unless event.type == :agent_stream
+
+        source = event.data[:source]
+        progress = event.data[:event]
+        return unless source.is_a?(AgentStreamSource) && progress.is_a?(StreamEvent)
+        return unless PROGRESS_EVENTS.include?(progress.type)
+
+        selected = if @source_filter
+          @source_filter.call(source)
+        else
+          source.agent_path == "/root" && source.assembly_path.empty?
+        end
+        progress if selected
+      end
+
       def event(type, **attributes)
         {type:, **attributes.compact}
       end

data/lib/little_ghost/agent.rb

@@ -2327,7 +2327,7 @@ module LittleGhost
         agent_path:,
         operation_id:,
         parent_operation_id:,
-        assembly_path: agent_stream_path
+        assembly_path: AgentStreamScope.path(run:, path: agent_stream_path)
       )
       AgentStreamSink.new(destination: events, run:, source:, input:)
     end

data/lib/little_ghost/agent_stream_source.rb

@@ -29,7 +29,8 @@ module LittleGhost
 
     ##
     # :attr_reader: assembly_kind
-    # The +:workflow+, +:swarm+, +:graph+, or custom assembly kind.
+    # The +:workflow+, +:swarm+, +:graph+, +:tool+, or custom assembly kind.
+    # A +:tool+ step marks an assembly invoked through a Tool.
 
     ##
     # :attr_reader: participant
@@ -67,7 +68,11 @@ module LittleGhost
   # A +:agent_stream+ StreamEvent carries this value in +data[:source]+ and the
   # Agent's event as a separate frozen StreamEvent in +data[:event]+.
   # +assembly_path+ is empty for a top-level Agent and contains one
-  # AgentStreamStep for each enclosing composite assembly participant.
+  # AgentStreamStep for each enclosing composite assembly participant or
+  # assembly-as-tool boundary. When an Agent invokes the Tool, the boundary's
+  # +assembly_id+ identifies that Agent and +participant+ names the Tool. Tool
+  # boundaries do not change the delegated Agent's authorization or
+  # managed-subagent path.
   class AgentStreamSource < Data # :doc:
     ##
     # :attr_reader: agent_id
@@ -238,7 +243,41 @@ module LittleGhost
     end
   end
 
+  module AgentStreamScope # :nodoc: all
+    module_function
+
+    def with_tool(target:, name:)
+      return yield unless target.run
+
+      execution = ExecutionState[:tool_execution]
+      source = execution.events.source if execution&.events.is_a?(AgentStreamSink)
+      prefix = target.agent_stream_path
+      parent_path = source&.assembly_path || path(run: target.run, path: prefix)
+      boundary = AgentStreamStep.build(
+        assembly_id: source&.agent_id || target.class.assembly_id,
+        assembly_kind: :tool,
+        participant: name,
+        step_id: execution&.operation_id || SecureRandom.uuid
+      )
+      # Prebuilt descendant factories inherit this scope without mutating a
+      # reusable Agent's bound path or its authorization identity.
+      scope = {run: target.run, prefix:, path: (parent_path + [boundary]).freeze}.freeze
+      ExecutionState.with(agent_stream_tool_scope: scope) { yield }
+    end
+
+    def path(run:, path:)
+      scope = ExecutionState[:agent_stream_tool_scope]
+      return path unless run && scope && scope.fetch(:run).equal?(run)
+
+      prefix = scope.fetch(:prefix)
+      suffix = (path.take(prefix.length) == prefix) ? path.drop(prefix.length) : path
+      scope.fetch(:path) + suffix
+    end
+  end
+
   class AgentStreamSink # :nodoc: all
+    attr_reader :source
+
     def initialize(destination:, run:, source:, input:)
       @destination = destination
       @run = run

data/lib/little_ghost/assembly.rb

@@ -58,11 +58,12 @@ module LittleGhost
       #
       # Enumeration yields StreamEvent objects and returns the terminal Run.
       # The same Invocation fields accepted by .ask may be supplied as +options+.
-      # Composite assemblies also emit an +:agent_stream+ event for every
-      # normalized event from every Agent in the run, including intermediate
-      # and nested participants. Set <tt>include_agent_events: false</tt> to
-      # keep only the ordinary public stream. A standalone Agent retains its
-      # ordinary stream by default and accepts +true+ to opt in.
+      # Agent progress arrives once through +:agent_stream+, with source metadata
+      # identifying every Agent in the Run, including nested participants.
+      # Lifecycle and terminal results remain separate events. Filter sources
+      # before forwarding progress to a destination that may see only some
+      # participants. Set <tt>include_agent_events: false</tt> to omit all Agent
+      # progress without changing execution or final results. See Run.
       def stream_ask(message, **options)
         snapshot = definition
         stream = nil
@@ -177,7 +178,7 @@ module LittleGhost
     end
 
     # Builds the top-level Run used by a standalone assembly.
-    def build_run(payload = nil, include_agent_events_by_default: false, **payload_options) # :nodoc:
+    def build_run(payload = nil, **payload_options) # :nodoc:
       payload = entrypoint_payload(payload, payload_options) unless payload_options.empty?
       payload = payload.dup if payload.is_a?(Hash)
       cancellation_token = if payload.is_a?(Hash)
@@ -191,14 +192,14 @@ module LittleGhost
       options[:cancellation_token] = cancellation_token if cancellation_token
       options[:workspace] = workspace if workspace
       options[:sandbox] = sandbox if sandbox
-      options[:include_agent_events_by_default] = true if include_agent_events_by_default
       runtime.build_run(payload, **options)
     end
 
     # Starts +payload+ in the background and returns an Execution.
-    # Composite assemblies include contextual +:agent_stream+ events in the
-    # consumer by default. Set +include_agent_events+ to +false+ in +payload+
-    # to keep only the ordinary public stream.
+    # The consumer receives source-tagged +:agent_stream+ progress from every
+    # Agent in the Run, including nested participants. Filter sources for the
+    # intended destination. Set +include_agent_events+ to +false+ in +payload+
+    # to omit Agent progress while keeping lifecycle and terminal results.
     def start_execution(payload, &event_consumer)
       ensure_standalone!
       Execution.start(build_stream_run(payload), &event_consumer)
@@ -230,10 +231,10 @@ module LittleGhost
     #
     # A standalone stream returns its terminal Run after enumeration. A
     # run-scoped stream finishes with an +invocation_stop+ event containing its
-    # RunResult. A standalone composite Assembly receives contextual
-    # +:agent_stream+ events from every Agent in the Run by default and may set
-    # <tt>include_agent_events: false</tt> to omit them. A standalone Agent may
-    # set the option to +true+ to include its contextual wrapper.
+    # RunResult. Standalone streams include source-tagged +:agent_stream+ events
+    # from every Agent in the Run by default. Applications filter sources before
+    # forwarding progress, or set <tt>include_agent_events: false</tt> to omit
+    # all Agent progress. This option does not change execution or final results.
     def stream_ask(message, **options)
       if standalone?
         options[:deadline_at] = options.delete(:deadline) if options.key?(:deadline)
@@ -259,6 +260,9 @@ module LittleGhost
     # A directly bound Agent remains the target for every call, so overlapping
     # calls raise AgentBusyError. Class-level Agent#agent_as_tool declarations
     # build a fresh Agent per context-free call.
+    # Within the same Run, progress from the target and its descendants carries a
+    # +:tool+ boundary in AgentStreamSource#assembly_path. It cannot be mistaken
+    # for root Agent progress, including when this instance is reused across calls.
     def as_tool(name: self.class.assembly_id, description: self.class.description, preserve_context: false)
       build_tool(name:, description:, preserve_context:, factory: nil)
     end
@@ -321,7 +325,9 @@ module LittleGhost
             options[:interjection_metadata] = context&.interjection_metadata
             options[:interjection_ids] = context&.interjection_ids || []
           end
-          result = target.call(input.fetch("input"), **options)
+          result = AgentStreamScope.with_tool(target:, name:) do
+            target.call(input.fetch("input"), **options)
+          end
           if result.is_a?(Run)
             raise result.error if result.error
 
@@ -406,9 +412,7 @@ module LittleGhost
     private
 
     def build_stream_run(payload) # :nodoc:
-      return build_run(payload) if is_a?(Agent)
-
-      build_run(payload, include_agent_events_by_default: true)
+      build_run(payload)
     end
 
     def run_entrypoint_class # :nodoc: