samagotchi 0.23.0 → 0.24.0

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -5,13 +5,23 @@ module Samagotchi
     # A small shell lexer for the guardrails' text checks (ShellGitDirs
     # and the rules' shell matchers): words with quotes and
     # backslashes undone, operators apart, comments dropped, and $(…) or
-    # backticks (quoted or not) as one opaque SUBST marker inside a word. It never runs
-    # anything, and it does its best on odd input (an unbalanced quote).
+    # backticks (quoted or not) as one opaque SUBST marker inside a word. A
+    # heredoc's body (<<EOF, <<'EOF', <<-EOF) is one word after its <<TAG
+    # word and lexing goes on after the terminator line: HEREDOC when cat or
+    # tee read it as data, SUBST when an unquoted tag's body holds $(…) or
+    # backticks, else the body text itself (a script, as sh -c '…' gives).
+    # An unterminated heredoc is no heredoc: the rest is lexed as commands.
+    # It never runs anything, and it does its best on odd input (an
+    # unbalanced quote).
     module ShellLex
       # Longest first: "&&" before "&", ";;" before ";".
       OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "\n", "(", ")"].freeze
       # What a $(…) or `…` becomes inside a word.
       SUBST = "\0SUBST"
+      # What a heredoc body that cat or tee read as data becomes.
+      HEREDOC = "\0HEREDOC"
+      # Commands that read a heredoc as data (when not piped on).
+      DATA_SINKS = %w[cat tee].freeze
       # A word that is a redirection (>, >>, 2>&1, <).
       REDIRECT = /\A\d*[<>]/
 
@@ -50,6 +60,7 @@ module Samagotchi
           @word = +""
           @specials = +""
           @in_word = false
+          @heredocs = []
         end
 
         def tokens
@@ -139,8 +150,12 @@ module Samagotchi
           @i = @s.index("\n", @i) || @s.size
         end
 
-        # >, >>, 2>&1, &>, <, <<: kept in the word (the walk drops them).
+        # >, >>, 2>&1, &>, <, <<<: kept in the word (the walk drops them).
+        # << starts a heredoc.
         def redirection
+          return add("<<<", 3) if @s[@i, 3] == "<<<"
+          return if @s[@i, 2] == "<<" && heredoc
+
           special(@s[@i])
           add(@s[@i], 1) while @i < @s.size && @s[@i].match?(/[&\d>-]/) && @word.end_with?(">")
         end
@@ -156,8 +171,101 @@ module Samagotchi
             flush
             @tokens << [:op, op]
             @i += op.size
+            bodies if op == "\n" && !@heredocs.empty?
           end
         end
+
+        # <<TAG, <<-TAG, <<'TAG', << "TAG": its own word, the body noted to
+        # be read after the line ends. False (nothing read) without a tag.
+        def heredoc
+          dash = @s[@i + 2] == "-"
+          j = @i + (dash ? 3 : 2)
+          j += 1 while [" ", "\t"].include?(@s[j])
+          tag, quoted, stop = heredoc_tag(j)
+          return false if tag.empty?
+
+          flush unless @word.match?(/\A\d*\z/)
+          special("<")
+          @word << "<" << (dash ? "-" : "") << tag
+          @i = stop
+          flush
+          @heredocs << { tag: tag, dash: dash, quoted: quoted, at: @tokens.size }
+          true
+        end
+
+        # The tag starting at +j+ with quotes and backslashes undone, whether
+        # any were there, and where it ends.
+        def heredoc_tag(j)
+          tag = +""
+          quoted = false
+          while j < @s.size && !@s[j].match?(/[\s;&|<>()]/)
+            if ["'", '"'].include?(@s[j])
+              close = @s.index(@s[j], j + 1) or return ["", false, j]
+              tag << @s[(j + 1)...close]
+              j = close + 1
+              quoted = true
+            elsif @s[j] == "\\"
+              tag << @s[j + 1].to_s
+              j += 2
+              quoted = true
+            else
+              tag << @s[j]
+              j += 1
+            end
+          end
+          [tag, quoted, j]
+        end
+
+        # After a line with heredocs: each body in order, up to its
+        # terminator line, as one word in its command. Unterminated: none
+        # are, and the rest is lexed as commands.
+        def bodies
+          heredocs = @heredocs
+          @heredocs = []
+          pos = @i
+          read = []
+          heredocs.each do |doc|
+            body, pos = body(doc, pos)
+            break unless body
+
+            read << [doc, body]
+          end
+          return if read.size < heredocs.size
+
+          read.reverse_each { |doc, body| @tokens.insert(doc[:at], [:word, body_word(doc, body), ""]) }
+          @i = pos
+        end
+
+        # The body from +pos+ and where lexing goes on, or nil.
+        def body(doc, pos)
+          start = pos
+          while pos < @s.size
+            eol = @s.index("\n", pos) || @s.size
+            line = @s[pos...eol]
+            line = line.sub(/\A\t+/, "") if doc[:dash]
+            return [@s[start...pos], [eol + 1, @s.size].min] if line == doc[:tag]
+
+            pos = eol + 1
+          end
+          nil
+        end
+
+        def body_word(doc, body)
+          return SUBST if !doc[:quoted] && body.match?(/\$\(|`/)
+          return HEREDOC if data_sink?(doc[:at])
+
+          body
+        end
+
+        # Whether the command the heredoc at token +at+ is in is cat or tee
+        # and not piped into another command.
+        def data_sink?(at)
+          start = at
+          start -= 1 while start.positive? && @tokens[start - 1][0] == :word
+          verb = @tokens[start...at].map { |t| t[1] }.find { |w| !w.match?(/\A[A-Za-z_]\w*=/) && !w.match?(REDIRECT) }
+          next_op = @tokens[at..].find { |t| t[0] == :op }
+          DATA_SINKS.include?(File.basename(verb.to_s)) && !["|", "|&"].include?(next_op&.dig(1))
+        end
       end
     end
   end

data/lib/samagotchi/guardrails/shell_paths.rb

@@ -114,7 +114,7 @@ module Samagotchi
 
         # An absolute path for +word+ against +dir+, or nil.
         def resolve(word, dir)
-          return nil if word.include?(ShellLex::SUBST) || word.match?(SCRIPT)
+          return nil if word.include?(ShellLex::SUBST) || word == ShellLex::HEREDOC || word.match?(SCRIPT)
 
           word = expand(word) or return nil
           return nil if word.match?(GLOB)

data/lib/samagotchi/idle_recap.rb

@@ -63,8 +63,10 @@ module Samagotchi
 
           case message["role"]
           when "user"
-            # A plugin's steer is a prod to the model, not what the user said.
-            next nil if Steer.steer?(message)
+            # A plugin's steer is a prod to the model, not what the user said;
+            # a continue steer from the user or the parent agent is an
+            # instruction, kept.
+            next nil if Steer.steer?(message) && !Steer.person?(message)
 
             # An image is a line naming it (refs only, never its bytes), unless
             # the text is only the web's placeholder naming it already.

data/lib/samagotchi/kernel_loop.rb

@@ -355,8 +355,12 @@ module Samagotchi
       generation.streamed_thinking += split[:thinking].to_s.length
       return unless turn.on_stream_event
 
-      emit(turn, type: :generation_chunk, iteration: turn.iteration, content: chunk[:content], text: split[:text],
-                 thinking: split[:thinking], payload: chunk[:payload])
+      event = { type: :generation_chunk, iteration: turn.iteration, content: chunk[:content], text: split[:text],
+                thinking: split[:thinking], payload: chunk[:payload] }
+      # A chunk of a tool call (its bytes are dropped from both lanes): a
+      # steer doesn't cut this generation (Engine#cut_for_steer).
+      event[:tool_call] = true if split[:tool]
+      emit(turn, **event)
     end
 
     # The cut stream's visible text goes with it: the buffer as it was
@@ -386,18 +390,24 @@ module Samagotchi
                                      messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
     end
 
-    # A generation a plugin cut is an empty answer made early: asked again
-    # with its own nudge while the retry budget lasts (queued input goes in
-    # place of the nudge), else the turn ends as cancelled (hook), with
-    # nothing salvaged and without the spent nudge. A Stop that came right
-    # after the cut is a plain cancel. Returns :next or the turn's result.
+    # A generation a plugin cut is an empty answer made early. Queued input
+    # (a user's line, a plugin's steer) goes in first, with or without a
+    # retry left, and spends no attempt: the model answers it. A steer's cut
+    # (Engine#cut_for_steer) with nothing queued (its message was taken at
+    # a boundary already) is asked again as is. Else it is asked again with
+    # its own nudge while the retry budget lasts, else the turn ends as
+    # cancelled (hook), with nothing salvaged and without the spent nudge.
+    # A Stop that came right after the cut is a plain cancel. Returns :next
+    # or the turn's result.
     def after_cut(turn, generation)
       cut = generation.cut
       raise Client::RequestCancelled, turn.cancel_controller.reason if turn.cancel_controller.cancelled?
 
-      if turn.empty_retry.left?
-        return :next if inject_pending_input!(turn)
+      # The row under the cut step, above the message it was cut for.
+      emit(turn, type: :steer_cut, iteration: turn.iteration, source: cut[:source].to_s) if cut[:steer]
+      return :next if inject_pending_input!(turn) || cut[:steer]
 
+      if turn.empty_retry.left?
         turn.empty_retry.nudge!(turn.conversation, TurnNote.cut_retry(cut[:by], cut[:reason]),
                                 emit: turn.emit, iteration: turn.iteration, finish_reason: "stopped",
                                 thinking_chars: generation.streamed_thinking, stopped_by: cut[:by])

data/lib/samagotchi/llm/chat_loop.rb

@@ -107,7 +107,9 @@ module Samagotchi
           when "system"
             wire << { role: "system", content: entry[:content].to_s }
           when "user"
-            wire << { role: "user", content: parts(entry[:content], items) }
+            # A steer or merged input (always a String) goes with its header.
+            content = Steer.header(entry) ? Steer.wire_text(entry, entry[:content].to_s) : entry[:content]
+            wire << { role: "user", content: parts(content, items) }
           when "model"
             wire << assistant_message(entry, paired)
           when "tool_response"
@@ -381,17 +383,22 @@ module Samagotchi
         end
 
         # A generation a plugin cut (stop_generation) is an empty answer made
-        # early: asked again with its own nudge while the retry budget lasts
-        # (queued input goes in place of the nudge), else the turn ends as
-        # cancelled (hook), with nothing salvaged and without a spent nudge.
-        # A Stop that came right after the cut is a plain cancel. Returns
-        # :retry, or the turn's result.
+        # early. Queued input (a user's line, a plugin's steer) goes in
+        # first, with or without a retry left, and spends no attempt. A
+        # steer's cut (Engine#cut_for_steer) with nothing queued is asked
+        # again as is. Else it is asked again with its own nudge while the
+        # retry budget lasts, else the turn ends as cancelled (hook), with
+        # nothing salvaged and without a spent nudge. A Stop that came right
+        # after the cut is a plain cancel. Returns :retry, or the turn's
+        # result.
         def after_cut(iteration, response)
           return canceled(iteration, @cancel_controller.reason) if @cancel_controller.cancelled?
 
-          if @empty_retry.left?
-            return :retry if inject_pending_input(iteration)
+          # The row under the cut step, above the message it was cut for.
+          emit(type: :steer_cut, iteration: iteration, source: response.cut[:source].to_s) if response.cut[:steer]
+          return :retry if inject_pending_input(iteration) || response.cut[:steer]
 
+          if @empty_retry.left?
             @empty_retry.nudge!(@conversation, TurnNote.cut_retry(response.cut[:by], response.cut[:reason]),
                                 emit: method(:emit), iteration: iteration, finish_reason: response.finish_reason,
                                 thinking_chars: response.reasoning.to_s.length, stopped_by: response.cut[:by])
@@ -478,8 +485,11 @@ module Samagotchi
             on_delta: lambda { |content:, reasoning:, payload:|
               streamed << content
               thought << reasoning
-              emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
-                   thinking: reasoning, payload: payload)
+              event = { type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
+                        thinking: reasoning, payload: payload }
+              # A tool call streaming: a steer doesn't cut it (Engine#cut_for_steer).
+              event[:tool_call] = true if OpenAIChat.tool_call_delta?(payload)
+              emit(event)
             },
             on_retry: ->(**retry_event) { emit({ type: :generation_retrying, iteration: iteration }.merge(retry_event)) }
           )

data/lib/samagotchi/llm/openai_chat.rb

@@ -69,6 +69,9 @@ module Samagotchi
             **)
       end
 
+      # true when a streamed +payload+ carries a tool-call delta.
+      def self.tool_call_delta?(payload) = Assembly.tool_call_delta?(payload)
+
       # true when +url+ is OpenRouter's API (openrouter.ai or a subdomain).
       def self.openrouter?(url)
         host = URI(url.to_s).host.to_s.downcase

data/lib/samagotchi/log_subscriber.rb

@@ -109,8 +109,9 @@ module Samagotchi
                                         stopped_by: event[:stopped_by])
       return unless event[:stopped_by]
 
-      # A plugin cut this generation (stop_generation); the turn goes on.
-      log(:info, :generation_stopped, iteration: event[:iteration], bundle: event[:stopped_by],
+      # A plugin (stop_generation) or a steer (Engine#cut_for_steer, by
+      # "steer") cut this generation; the turn goes on.
+      log(:info, :generation_stopped, iteration: event[:iteration], by: event[:stopped_by],
                                       reason: event[:stop_reason].to_s[0, 200], thinking_chars: event[:thinking_chars], ms: ms)
     end
 

data/lib/samagotchi/prompt.rb

@@ -4,6 +4,7 @@ require_relative "model_profile"
 require_relative "prompt_literal_guard"
 require_relative "vision_context"
 require_relative "tool_response"
+require_relative "steer"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -168,7 +169,9 @@ module Samagotchi
       # peer session), and a turn note carries an error's text: escaped like
       # user content so it can't close its turn.
       role = ESCAPED_KINDS.include?(message[:kind].to_s) ? "user" : message[:role]
-      PromptLiteralGuard.escape(message[:content], profile: profile, role: role)
+      # A steer or merged input is led by a header naming its sender (added
+      # after the escape: the header has no literals to guard).
+      Steer.wire_text(message, PromptLiteralGuard.escape(message[:content], profile: profile, role: role))
     end
 
     private_class_method :image_lines, :format_with_turn_markers, :ends_in_tool_response?, :tool_response_blocks,

data/lib/samagotchi/steer.rb

@@ -10,20 +10,41 @@ module Samagotchi
   #
   # The user's own lines merged into a running turn are marked kind:
   # "input": they are part of that turn, not a turn of their own, so a
-  # reloaded history keeps the turn in one piece.
+  # reloaded history keeps the turn in one piece. A line can be a Line
+  # naming who sent it (a worker's input from chi send, a delegating parent,
+  # a plugin); its input message then carries that source:. The user's own
+  # lines carry none, so their saved bytes are as they always were.
   module Steer
     KIND = "steer"
     INPUT_KIND = "input"
 
+    # A drain item for an input line with its sender (source nil = the user).
+    # A plain String is still a valid item: the user's line.
+    Line = Data.define(:text, :source)
+
+    # The client ids whose input is not the user's own words. Literals, not
+    # SendCommand::CLIENT_ID / Tools::Delegate::CLIENT_PREFIX, so this file
+    # needs no requires (a spec pins them equal).
+    CHI_SEND_CLIENT = "cli:send"
+    DELEGATE_CLIENT_PREFIX = "delegate:"
+    PLUGIN_CLIENT = "plugin"
+
     # What one drain brought: the merged user text (nil when none) and how
-    # many lines made it, and the steers in order.
-    Merge = Struct.new(:content, :count, :steers, keyword_init: true) do
+    # many lines made it, the input messages' text grouped by sender
+    # (consecutive lines from one sender form one group), and the steers in
+    # order.
+    Merge = Struct.new(:content, :count, :inputs, :steers, keyword_init: true) do
       def empty? = content.nil? && steers.empty?
 
-      # The messages it appends: the user's first (marked merged input),
-      # then each steer.
+      # The messages it appends: the merged input first (one message per
+      # sender run, marked kind input, source: when not the user's), then
+      # each steer.
       def messages
-        list = content ? [{ role: "user", kind: INPUT_KIND, content: content }] : []
+        list = inputs.map do |input|
+          message = { role: "user", kind: INPUT_KIND }
+          message[:source] = input[:source] if input[:source]
+          message.merge(content: input[:content])
+        end
         list + steers.map { |steer| Steer.message(**steer) }
       end
 
@@ -36,8 +57,50 @@ module Samagotchi
       end
     end
 
+    # The one line the model reads above a steer or merged input (the wire
+    # only; the saved content stays raw): who sent it, and that it should
+    # follow it or, if it asks for nothing, carry on.
+    HEADER_TAIL = "mid-task. Follow it; if it asks for nothing, carry on with the task.]"
+    SENDERS = {
+      "user" => "from the user",
+      "parent_agent" => "from the parent agent that started this session",
+      "chi_send" => "sent with chi send",
+      "plugin_send" => "sent by a plugin"
+    }.freeze
+    USER_HEADER = "[Steer #{SENDERS["user"]}, #{HEADER_TAIL}".freeze
+
     module_function
 
+    # The saved source of a worker input line from +client_id+: nil for the
+    # user (no client id, the web, an attached TUI, anything unknown).
+    def source_for_client(client_id)
+      id = client_id.to_s
+      if id == CHI_SEND_CLIENT then "chi_send"
+      elsif id.start_with?(DELEGATE_CLIENT_PREFIX) then "parent_agent"
+      elsif id == PLUGIN_CLIENT then "plugin_send"
+      end
+    end
+
+    # The header for a steer or merged input message, else nil. No source
+    # (or "") is the user's; an input with an unknown source too; a steer
+    # with an unknown source is a plugin's (its bundle or hook label).
+    def header(message)
+      kind = (message[:kind] || message["kind"]).to_s
+      return unless [KIND, INPUT_KIND].include?(kind)
+
+      source = (message[:source] || message["source"]).to_s
+      source = "user" if source.empty?
+      sender = SENDERS[source] || (kind == KIND ? "from the #{source} plugin" : SENDERS["user"])
+      "[Steer #{sender}, #{HEADER_TAIL}"
+    end
+
+    # The text a steer or merged input goes out as: its header, a newline,
+    # then +text+ (the message's content by default). Other messages: +text+.
+    def wire_text(message, text = (message[:content] || message["content"]).to_s)
+      header = header(message)
+      header ? "#{header}\n#{text}" : text
+    end
+
     def message(text:, source:)
       { role: "user", kind: KIND, source: source.to_s, content: text.to_s }
     end
@@ -46,6 +109,24 @@ module Samagotchi
       (message[:kind] || message["kind"]).to_s == KIND
     end
 
+    # The sources of a steer a person sent (a continue card's text, from the
+    # user or a parent agent's chi answer), not a plugin's prod.
+    PERSON_SOURCES = %w[user parent_agent].freeze
+
+    # The senders whose message may cut a generation that has only been
+    # thinking (Engine#cut_for_steer): the user (no source), chi send, a
+    # parent agent. A plugin's never does.
+    CUT_SOURCES = ["", "user", "chi_send", "parent_agent"].freeze
+
+    def cuts?(source)
+      CUT_SOURCES.include?(source.to_s)
+    end
+
+    # A steer a person sent: what a recap and a side question keep.
+    def person?(message)
+      steer?(message) && PERSON_SOURCES.include?((message[:source] || message["source"]).to_s)
+    end
+
     # A user message that is a prompt or the user's steering, not a steer:
     # what "the last prompt" and "user turns" count.
     def prompt?(message)
@@ -105,8 +186,22 @@ module Samagotchi
         text = (item[:text] || item["text"]).to_s.strip
         { source: (item[:source] || item["source"]).to_s, text: text } unless text.empty?
       end
-      content = lines.map { |line| line.to_s.strip }.reject(&:empty?).join("\n\n")
-      Merge.new(content: content.empty? ? nil : content, count: content.empty? ? 0 : lines.length, steers: steers)
+      inputs = input_groups(lines)
+      content = inputs.map { |input| input[:content] }.join("\n\n")
+      Merge.new(content: content.empty? ? nil : content, count: content.empty? ? 0 : lines.length,
+                inputs: inputs, steers: steers)
+    end
+
+    # Non-blank input lines as [{content:, source:}], one per run of lines
+    # from the same sender.
+    def input_groups(lines)
+      pairs = lines.filter_map do |line|
+        text = (line.is_a?(Line) ? line.text : line).to_s.strip
+        [text, line.is_a?(Line) ? line.source : nil] unless text.empty?
+      end
+      pairs.chunk_while { |a, b| a[1] == b[1] }.map do |run|
+        { content: run.map(&:first).join("\n\n"), source: run.first[1] }
+      end
     end
   end
 end

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1189,7 +1189,7 @@ module Samagotchi
           # hook's notice, a retry's line), as they were drawn live.
           # Questions are left out: the pending one is asked after the
           # replay, answered ones showed no line.
-          when :turn_started, :pending_input_merged, :hook_notice, :empty_answer_retry then @renderer.call(event)
+          when :turn_started, :pending_input_merged, :hook_notice, :empty_answer_retry, :steer_cut then @renderer.call(event)
           end
         end
         @view.resume(tail: tail, lane: lane, tool: running_tool, parts: turn[:parts])

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -79,6 +79,9 @@ module Samagotchi
         when :empty_answer_retry
           @view.finish_thinking_spinner
           @view.print_line(@view.format_empty_retry_line(event))
+        when :steer_cut
+          @view.finish_thinking_spinner
+          @view.print_line(@view.format_steer_cut_line(event))
         when :turn_completed
           render_turn_summary(event[:turn_summary]) if event[:turn_summary]
         when :turn_canceled

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -45,6 +45,15 @@ module Samagotchi
         paint("↻ #{what}, asking again (#{event[:attempt]}/#{event[:of]})", 90)
       end
 
+      # "↪ cut in for your message": a message for the running turn cut a
+      # generation that was only thinking (Engine#cut_for_steer); an empty
+      # or unknown source is the user's.
+      STEER_CUT_FOR = { "chi_send" => "a message sent with chi send", "parent_agent" => "the parent agent's message" }.freeze
+
+      def format_steer_cut_line(event)
+        paint("↪ cut in for #{STEER_CUT_FOR.fetch(event[:source].to_s, "your message")}", 90)
+      end
+
       # "no answer: the model returned nothing (after 1 retry)", dim like the
       # retry row: a turn that ended with no answer (TurnNote.empty_answer_line).
       def format_empty_answer_line(retries)

data/lib/samagotchi/terminal_ui/one_shot_sink.rb

@@ -29,6 +29,7 @@ module Samagotchi
       def call(event)
         case event[:type]
         when :empty_answer_retry then line(format_empty_retry_line(event))
+        when :steer_cut then line(format_steer_cut_line(event))
         when :generation_retrying then line(format_generation_retry_line(event))
         when :turn_completed, :turn_canceled then @turn_over = true
         when :hook_notice

data/lib/samagotchi/terminal_ui.rb

@@ -1007,7 +1007,12 @@ module Samagotchi
       # Steering merges text only: a line with images runs as the next turn.
       return image_line_waits if ImageInput.extract(line).any?
 
+      epoch = @engine.input_epoch
       @pending_input_queue.push(line.strip)
+      # The user's line cuts a generation that has streamed only thinking
+      # for long (steer.cut_after), now or once it has: the model starts the
+      # step again with it.
+      @engine.cut_for_steer(nil, epoch: epoch)
       true
     end
 

data/lib/samagotchi/thought_stream_splitter.rb

@@ -46,12 +46,16 @@ module Samagotchi
       @active = nil
     end
 
-    # Feed one raw chunk. Returns the newly-routed deltas for this chunk only.
-    # @return [Hash{ text: String, thinking: String }]
+    # Feed one raw chunk. Returns the newly-routed deltas for this chunk
+    # only, and +tool+: whether the chunk opened, streamed into or closed a
+    # tool_call block (its bytes are dropped, but a steer must not cut a
+    # generation that writes a tool call: Engine#cut_for_steer).
+    # @return [Hash{ text: String, thinking: String, tool: Boolean }]
     def feed(chunk)
       @carry << chunk.to_s
       text = +""
       thinking = +""
+      tool = false
       loop do
         if @state == :normal
           hit = earliest_open
@@ -64,9 +68,11 @@ module Samagotchi
           @carry = @carry[hit[:pos]..]
           @active = hit[:block]
           @state = :in_block
+          tool ||= @active[:lane] == :drop
           # Drop the open marker itself; its body follows.
           @carry = @carry[@active[:open].length..].to_s
         else
+          tool ||= @active[:lane] == :drop && !@carry.empty?
           close_pos = @carry.index(@active[:close])
           if close_pos.nil?
             flush_in_block(thinking)
@@ -79,7 +85,7 @@ module Samagotchi
           @state = :normal
         end
       end
-      { text: text, thinking: thinking }
+      { text: text, thinking: thinking, tool: tool }
     end
 
     # Flush any residual state at end of stream (e.g. an unterminated thinking

data/lib/samagotchi/tool_runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "tool_activity"
+require_relative "tool_view"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
@@ -55,6 +56,9 @@ module Samagotchi
       # The worker runs in its session's working directory.
       title = ToolActivity.tool_title(call[:name], call, cwd: Dir.pwd)
       started[:title] = title if title
+      # The full command for a richer UI (params stays cut at 80).
+      view = ToolView.for(call[:name], call)&.to_h
+      started[:view] = view if view
       emit(on_stream_event, started)
 
       # The ask comes after tool_call_started: the UI shows the tool line,
@@ -95,6 +99,9 @@ module Samagotchi
       completed[:images] = images if images&.any?
       completed[:diff] = diff if diff
       completed[:waited_ms] = waited_ms if waited_ms
+      # Also here: a UI that missed the start (a replay gap) builds its row
+      # from this event.
+      completed[:view] = view if view
       emit(on_stream_event, completed)
       # After the completed event: a hook's card (check-in, skills) prints
       # under the call's tool row, not before it.

data/lib/samagotchi/tool_view.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "tools/execute"
+require_relative "tools/task_create"
+
+module Samagotchi
+  # What a richer UI shows of a tool call beyond its one-line params: the
+  # full command of an execute / task_create (whitespace kept), and the
+  # call's own cwd: argument. Built by the server on every path (the live
+  # tool_call_started, the bridge's snapshot and replay, a reload from the
+  # saved call), so the UIs never parse the call themselves. params and its
+  # 80-char cut stay as they are (the guardrails, "ran as:", the TUI).
+  #
+  # +truncated+: the command was longer than COMMAND_LIMIT and is cut to it;
+  # +chars+ is then its full length.
+  ToolView = Data.define(:command, :cwd, :truncated, :chars) do
+    def to_h = super.compact.reject { |_key, value| value == false }
+  end
+
+  class ToolView
+    # The longest command a view carries (the spike's longest was 3,799).
+    COMMAND_LIMIT = 8_000
+
+    TOOLS = [Tools::Execute::NAME, Tools::TaskCreate::NAME].freeze
+
+    # @return [ToolView, nil] nil for a tool without a view and for an
+    #   empty command
+    def self.for(tool_name, call)
+      return nil unless TOOLS.include?(tool_name) && call.is_a?(Hash)
+
+      command = call[:content].to_s
+      return nil if command.strip.empty?
+
+      cwd = call[:cwd].to_s.strip
+      truncated = command.length > COMMAND_LIMIT
+      new(command: truncated ? command[0, COMMAND_LIMIT] : command, cwd: cwd.empty? ? nil : cwd,
+          truncated: truncated, chars: truncated ? command.length : nil)
+    end
+  end
+end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.23.0"
+  VERSION = "0.24.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end