samagotchi 0.23.0 → 0.25.0

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -23,6 +23,7 @@ require_relative "../session_manager"
 require_relative "../session_metrics"
 require_relative "../guardrails/parent_approvals"
 require_relative "../tool_activity"
+require_relative "../tool_view"
 require_relative "../web/message_parts"
 
 module Samagotchi
@@ -1109,7 +1110,8 @@ module Samagotchi
         output = part[:output]
         status = output.nil? ? "no result" : ToolActivity.tool_activity_status(output, part[:tool])
         activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
-                     params: part[:params], status: status }
+                     params: part[:params], status: status,
+                     description: ToolView.description_title(part[:view] || {}) }
         "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
           "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
@@ -1189,7 +1191,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])
@@ -1202,8 +1204,9 @@ module Samagotchi
       def replay_tool_completed(event)
         return @renderer.call({ duration_ms: nil }.merge(event)) if event.dig(:activity, :action)
 
-        activity = event[:activity] || {}
+        activity = EventRenderer.described(event) || {}
         @screen.commit(snapshot_tool_line({ tool: event[:tool], params: activity[:params], status: activity[:status],
+                                            description: activity[:description],
                                             images: event[:images], diff: event[:diff] }))
       end
 

data/lib/samagotchi/terminal_ui/attached_view.rb

@@ -4,6 +4,8 @@ require "monitor"
 require_relative "formatting"
 require_relative "../output_formatter"
 require_relative "../turn_tally"
+require_relative "../tool_view"
+require_relative "event_renderer"
 require_relative "thinking_line"
 
 module Samagotchi
@@ -111,7 +113,8 @@ module Samagotchi
           @retry = nil
           @waiting_since = nil
           @tool = "running #{event[:tool]}"
-          @tally.started(key: tally_key(event), tool: event[:tool], params: event[:params])
+          @tally.started(key: tally_key(event), tool: event[:tool], params: event[:params],
+                         description: ToolView.description_title(event[:view] || {}))
           redraw_status
         end
       end
@@ -119,7 +122,8 @@ module Samagotchi
       def tool_call_feedback_completed(event)
         @lock.synchronize do
           @tally.completed(key: tally_key(event), tool: event[:tool],
-                           status: event.dig(:activity, :status), params: event.dig(:activity, :params))
+                           status: event.dig(:activity, :status), params: event.dig(:activity, :params),
+                           description: EventRenderer.described(event)&.dig(:description))
         end
       end
 

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "formatting"
+require_relative "../tool_view"
 
 module Samagotchi
   class TerminalUI
@@ -70,8 +71,8 @@ module Samagotchi
           @view.tool_call_feedback_completed(event)
           # A replayed row (a join) carries its duration (nil: unknown).
           measured = tool_duration_ms(event)
-          render_streamed_tool_activity(event[:activity], duration_ms: event.fetch(:duration_ms, measured), images: event[:images],
-                                                          diff: event[:diff])
+          render_streamed_tool_activity(self.class.described(event), duration_ms: event.fetch(:duration_ms, measured),
+                                                                     images: event[:images], diff: event[:diff])
         when :generation_completed, :generation_cancelled, :tool_dispatch_started
           @view.generation_feedback_finished
         when :pending_input_merged
@@ -79,6 +80,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
@@ -187,6 +191,17 @@ module Samagotchi
         Array(event[:steers]).each { |steer| @view.print_line(@view.format_steer_line(source: steer[:source], text: steer[:text])) }
       end
 
+      # A tool_call_completed's activity with the command's description:
+      # its own, else its view's (a snapshot's replay carries the view, not
+      # the description). nil for an event without one.
+      def self.described(event)
+        activity = event[:activity]
+        return activity if activity.nil? || activity[:description] || !event[:view].is_a?(Hash)
+
+        description = ToolView.description_title(event[:view].transform_keys(&:to_sym))
+        description ? activity.merge(description: description) : activity
+      end
+
       private
 
       def render_streamed_tool_activity(activity, duration_ms:, images: nil, diff: nil)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -11,11 +11,21 @@ module Samagotchi
     # $stdout is a colour terminal.
     module Formatting
       def format_tool_activity_line(activity, duration_ms: nil)
-        params = activity[:params].to_s.strip
-        params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = activity[:status].to_s
         elapsed_suffix = duration_ms.nil? ? "" : " (#{format_elapsed_duration(duration_ms)})"
-        "#{paint("tool>", 36)} #{activity[:action]} (#{activity[:tool]}#{params_suffix}): #{paint(status, status_color(status))}#{elapsed_suffix}"
+        "#{paint("tool>", 36)} #{activity[:action]} (#{activity[:tool]}#{tool_params_suffix(activity)}): " \
+          "#{paint(status, status_color(status))}#{elapsed_suffix}"
+      end
+
+      # What a tool line says the call did: the model's description of a
+      # command (": List the specs") in place of its cut params, else the
+      # params, dim.
+      def tool_params_suffix(activity)
+        description = activity[:description].to_s.strip
+        return ": #{description}" unless description.empty?
+
+        params = activity[:params].to_s.strip
+        params.empty? ? "" : " #{paint(params, 90)}"
       end
 
       # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.
@@ -30,12 +40,22 @@ module Samagotchi
 
       STEER_PREVIEW = 80
 
+      # Who a steer names as its sender: a plugin's own label, chi's sender
+      # ids in words (the web's format.js steerSender agrees;
+      # spec/shared/labels_matrix.json). "": no one named.
+      STEER_SENDERS = { "parent_agent" => "parent agent", "chi_send" => "chi send", "plugin_send" => "plugin" }.freeze
+
+      def steer_sender(source)
+        STEER_SENDERS.fetch(source.to_s, source.to_s)
+      end
+
       # "check-in> nudged: <text>", dim, one line cut: a plugin's steer
       # (Steer) in the running turn or the join's last exchange.
       def format_steer_line(source:, text:)
         first = text.to_s.strip.split("\n").first.to_s
         first = "#{first[0, STEER_PREVIEW - 1]}…" if first.length > STEER_PREVIEW || text.to_s.strip.include?("\n")
-        paint("#{source.to_s.empty? ? "plugin" : source}> nudged: #{first}", 90)
+        sender = steer_sender(source)
+        paint("#{sender.empty? ? "plugin" : sender}> nudged: #{first}", 90)
       end
 
       # "↻ empty answer, asking again (1/1)": the loop retries an empty answer;
@@ -45,6 +65,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)
@@ -110,10 +139,8 @@ module Samagotchi
 
       # A tool call from the snapshot: it has no action text, only the tool.
       def snapshot_tool_line(part)
-        params = part[:params].to_s.strip
-        params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = part[:status].to_s
-        "#{paint("tool>", 36)} #{part[:tool]}#{params_suffix}: #{paint(status, status_color(status))}" \
+        "#{paint("tool>", 36)} #{part[:tool]}#{tool_params_suffix(part)}: #{paint(status, status_color(status))}" \
           "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
 
@@ -376,6 +403,9 @@ module Samagotchi
         lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
         lines << "cancellations:    #{snapshot[:cancellations]}"
         lines << "retries:          #{snapshot[:retries]}"
+        # A looped session: loop-guard's cuts, or thinking that ran to the cap.
+        lines << "thinking cuts:    #{snapshot[:cuts].to_i}"
+        lines << "output cap hits:  #{snapshot[:capped].to_i}"
         context = snapshot[:context] || {}
         if context[:used_tokens]
           pct = context[:window_tokens].to_i.positive? ? format(" (%.1f%%)", context[:used_tokens] * 100.0 / context[:window_tokens]) : ""
@@ -391,14 +421,15 @@ module Samagotchi
         lines.join("\n")
       end
 
-      # ", cached 4864 (93%), reasoning 212" for the tokens line; the counts a
-      # server didn't report are left out.
+      # ", cached 4864 (93%), cache writes 312, reasoning 212" for the tokens
+      # line; the counts a server didn't report are left out.
       def token_breakdown_text(tokens)
         cached = tokens[:cached_sum].to_i
         reasoning = tokens[:reasoning_sum].to_i
         prompt = tokens[:prompt_sum].to_i
         text = +""
         text << ", cached #{cached} (#{(cached * 100.0 / prompt).round}%)" if cached.positive? && prompt.positive?
+        text << ", cache writes #{tokens[:cache_write_sum].to_i}" if tokens[:cache_write_sum].to_i.positive?
         text << ", reasoning #{reasoning}" if reasoning.positive?
         text
       end

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/thinking_tails.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+
+module Samagotchi
+  # The thinking a session would otherwise lose: a SessionObserver
+  # subscriber (next to SessionMetrics) that keeps the tail of a generation
+  # cut mid-stream (a plugin's stop_generation, loop-guard's cut, a steer's
+  # cut), stopped with its turn by a plugin (stop_turn), or ended at the
+  # provider's output cap (finish_reason length). A cut generation's
+  # thinking is dropped from the conversation, and a looping one is what a
+  # fixture needs.
+  #
+  # The tails go to <session dir>/thinking_tails.jsonl, one JSON record a
+  # line, the newest MAX_RECORDS kept: next to the session's analytics.json,
+  # so an archived session (and a copied session dir) keeps them. Not in the
+  # session's messages (nothing there can reach the model, hooks or the
+  # web's reload by accident) and not in the turn records (the live snapshot
+  # carries those on every /state frame).
+  class ThinkingTails
+    FILE = "thinking_tails.jsonl"
+    # The last chars of a generation's thinking kept: a loop's cycle and
+    # some of its lead-in.
+    TAIL_CHARS = 20_000
+    MAX_RECORDS = 10
+
+    # @param session_dir [#call] the current session's directory, or nil
+    #   (no session yet: nothing is written)
+    def initialize(session_dir:, clock: -> { Time.now })
+      @session_dir = session_dir
+      @clock = clock
+      @turn_id = nil
+      reset
+    end
+
+    # The saved records of +dir+, oldest first (empty without a file).
+    # @return [Array<Hash>] string-keyed
+    def self.read(dir)
+      File.readlines(File.join(dir, FILE), chomp: true).filter_map do |line|
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    rescue SystemCallError
+      []
+    end
+
+    def call(event)
+      case event[:type]
+      when :turn_started then @turn_id = event[:turn_id]
+      when :generation_started, :generation_retrying then reset
+      when :generation_chunk then add(event[:thinking].to_s)
+      when :generation_completed then completed(event)
+      when :generation_cancelled
+        # A plugin's stop_turn mid-generation; a user's Stop is not kept.
+        keep(event, finish_reason: "cancelled", stopped_by: "hook") if event[:reason].to_s == "hook"
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def reset
+      @tail = +""
+      @chars = 0
+    end
+
+    def add(thinking)
+      return if thinking.empty?
+
+      @chars += thinking.length
+      @tail << thinking
+      @tail = @tail[-TAIL_CHARS..] if @tail.length > 2 * TAIL_CHARS
+    end
+
+    def completed(event)
+      stopped_by = event[:stopped_by]
+      return reset unless stopped_by || event[:finish_reason].to_s == "length"
+
+      keep(event, finish_reason: event[:finish_reason].to_s, stopped_by: stopped_by&.to_s, stop_reason: event[:stop_reason])
+    end
+
+    # Writes the record and forgets the generation (the native loop's cut
+    # with no retry left reports :generation_cancelled after it too).
+    def keep(event, **fields)
+      return reset if @chars.zero?
+
+      record = { at: @clock.call.utc.iso8601(3), turn_id: @turn_id, iteration: event[:iteration], **fields,
+                 thinking_chars: @chars, tail: @tail.length > TAIL_CHARS ? @tail[-TAIL_CHARS..] : @tail }.compact
+      reset
+      dir = @session_dir.call
+      return unless dir
+
+      FileUtils.mkdir_p(dir)
+      lines = self.class.read(dir).last(MAX_RECORDS - 1).map { |kept| JSON.generate(kept) }
+      AtomicFile.write(File.join(dir, FILE), (lines + [JSON.generate(record)]).join("\n") << "\n")
+    end
+  end
+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/token_usage.rb

@@ -12,15 +12,16 @@ module Samagotchi
   # The last chunk can say more: llama.cpp adds a `timings` block with exact
   # speeds and `cache_n` (its native `tokens_cached` counts the new tokens too,
   # so it is not read); OpenRouter adds `usage.cost` (USD) and the
-  # `prompt_tokens_details.cached_tokens` / `completion_tokens_details.reasoning_tokens`
-  # breakdowns. Those fields are nil when a payload doesn't carry them.
+  # `prompt_tokens_details.cached_tokens` / `cache_write_tokens` /
+  # `completion_tokens_details.reasoning_tokens` breakdowns (cache writes:
+  # Anthropic models, prompt caching's first request). Those fields are nil when a payload doesn't carry them.
   #
   # from_payload returns nil when no server token counts are present, so a
   # caller can fall back to a chars/4 heuristic. The reported values are
   # cumulative per request, so callers should take the running MAX across
   # chunks (see SessionMetrics).
-  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :reasoning_tokens, :cost,
-                                 :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
+  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
+                                 :reasoning_tokens, :cost, :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
     CHARS_PER_TOKEN = 4.0
 
     class << self
@@ -41,11 +42,12 @@ module Samagotchi
         )
         return nil unless prompt_tokens || completion_tokens
 
+        details = hash_at(usage, :prompt_tokens_details)
         new(
           prompt_tokens: prompt_tokens,
           completion_tokens: completion_tokens,
-          cached_tokens: first_positive(*both(hash_at(usage, :prompt_tokens_details), :cached_tokens),
-                                        *both(timings, :cache_n)),
+          cached_tokens: first_positive(*both(details, :cached_tokens), *both(timings, :cache_n)),
+          cache_write_tokens: first_positive(*both(details, :cache_write_tokens)),
           reasoning_tokens: first_positive(*both(hash_at(usage, :completion_tokens_details), :reasoning_tokens)),
           cost: number(*both(usage, :cost)),
           predicted_per_second: positive_number(*both(timings, :predicted_per_second)),
@@ -55,6 +57,16 @@ module Samagotchi
         )
       end
 
+      # A request's prompt-cache counts as a :generation_completed event
+      # carries them (the log line too): the prompt, the part of it the
+      # server reused from its cache, and the part it wrote to it (nil when
+      # none: only some remote servers report writes).
+      # @return [Hash] {prompt_tokens:, cached_tokens:, cache_write_tokens:}
+      def cache_fields(prompt:, cached:, cache_write:)
+        { prompt_tokens: prompt.to_i, cached_tokens: cached.to_i,
+          cache_write_tokens: cache_write.to_i.positive? ? cache_write.to_i : nil }
+      end
+
       # Estimate token count from raw text length using the chars/4 heuristic.
       # @param text [String]
       # @return [Integer]

data/lib/samagotchi/tool_activity.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require_relative "log"
+require_relative "command_steps"
+require_relative "tool_view"
 require_relative "tools/execute"
 require_relative "tools/read"
 require_relative "tools/write"
@@ -42,15 +44,34 @@ module Samagotchi
       }
       title = tool_title(tool_name, call, cwd: cwd)
       event[:title] = title if title
+      # The model's own words for a command, which the TUI's tool line
+      # shows in place of the cut params.
+      description = command_description(tool_name, call)
+      event[:description] = description if description
       event
     end
 
+    # An execute's description, cut as a row's title; nil for the rest.
+    def command_description(tool_name, call)
+      return nil unless call.is_a?(Hash) && ToolView::TOOLS.include?(tool_name)
+
+      ToolView.description_title(call)
+    end
+
     # What the call did, for a web row's one line ("edit lib/a.rb", the
     # command without its "cd … &&"): a file tool's path relative to +cwd+
-    # when it is under it, a command's first line, a memory's name; nil for
-    # the other tools (a plugin's row keeps its preview, the params).
-    # +params+ stays the full key=value line (the TUI, the guardrails).
+    # when it is under it, a command's description (the model's few words),
+    # else its first step and how many more (CommandSteps; its first line
+    # when it has no steps), a memory's name;
+    # nil for the other tools (a plugin's row keeps its preview, the
+    # params). +params+ stays the full key=value line (the TUI, the
+    # guardrails).
     def tool_title(tool_name, call, cwd: nil)
+      if [Tools::Execute::NAME, Tools::TaskCreate::NAME].include?(tool_name)
+        title = command_description(tool_name, call) || steps_title(call[:content])
+        return title if title
+      end
+
       text = case tool_name
              when Tools::Read::NAME, Tools::MemoryRead::NAME then call[:content]
              when Tools::Write::NAME, Tools::Edit::NAME, Tools::MemoryWrite::NAME then call[:path]
@@ -73,6 +94,19 @@ module Samagotchi
     # eats the line.
     LEADING_CD = /\Acd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/
 
+    # "<first step> +N" (N the steps after it), cut to fit
+    # TOOL_ACTIVITY_PREVIEW_LIMIT; nil when the command has no steps.
+    def steps_title(command)
+      steps = CommandSteps.parse(command)&.steps
+      return nil unless steps
+
+      first = steps.first.text.gsub(/\s+/, " ")
+      more = steps.size > 1 ? " +#{steps.size - 1}" : ""
+      room = TOOL_ACTIVITY_PREVIEW_LIMIT - more.length
+      first = "#{first[0, room - 1]}…" if first.length > room
+      "#{first}#{more}"
+    end
+
     def command_title(command)
       line = command.to_s.lines.map(&:strip).find { |l| !l.empty? }.to_s
       line.sub(LEADING_CD, "")

data/lib/samagotchi/tool_declarations.rb

@@ -26,6 +26,10 @@ module Samagotchi
               type: "string",
               description: "The shell command to run"
             },
+            description: {
+              type: "string",
+              description: "Optional: what this command does, in a few words (what, not why)"
+            },
             cwd: {
               type: "string",
               description: "Optional working directory to run in (defaults to the project root). Relative paths are resolved against the project root."
@@ -425,6 +429,16 @@ module Samagotchi
 
     module_function
 
+    # +schema+ without execute's description property: what a session
+    # with execute.description off declares (the parameter isn't offered
+    # at all). Any other schema as given.
+    def without_command_description(schema)
+      return schema unless schema[:name] == "execute"
+
+      parameters = schema[:parameters]
+      schema.merge(parameters: parameters.merge(properties: parameters[:properties].except(:description)))
+    end
+
     # Gemma 4 <|tool>declaration:NAME{…}<tool|> blocks for every tool, back
     # to back, as Gemma 4's chat template declares tools.
     # @param schemas [Array<Hash>] a Tools::Registry's schemas

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,76 @@
+# frozen_string_literal: true
+
+require_relative "command_steps"
+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. +cd+ and +steps+: the command as
+  # CommandSteps reads it (its leading cd, its steps), both nil when it
+  # can't (the fallback: the UI shows the command itself) or the command
+  # is cut. +description+: what the model said the command does (execute's
+  # optional description), whitespace collapsed, a trailing period gone;
+  # nil when it gave none.
+  ToolView = Data.define(:command, :cwd, :truncated, :chars, :cd, :steps, :description) do
+    def to_h = super.merge(steps: steps&.map(&:to_h)).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
+
+    # The longest description a view carries; a row's title shows the
+    # first TITLE_LIMIT characters of it.
+    DESCRIPTION_LIMIT = 300
+    TITLE_LIMIT = 60
+
+    # @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
+      parsed = truncated ? nil : CommandSteps.parse(command)
+      new(command: truncated ? command[0, COMMAND_LIMIT] : command, cwd: cwd.empty? ? nil : cwd,
+          truncated: truncated, chars: truncated ? command.length : nil, cd: parsed&.cd, steps: parsed&.steps,
+          description: description(call))
+    end
+
+    # The call's description as a view shows it, nil for none.
+    def self.description(call)
+      text = call[:description]
+      return nil unless text.is_a?(String)
+
+      text = text.gsub(/\s+/, " ").strip.sub(/(?<!\.)\.\z/, "")
+      return nil if text.empty?
+
+      text.length > DESCRIPTION_LIMIT ? "#{text[0, DESCRIPTION_LIMIT - 1]}…" : text
+    end
+
+    # A row's title from the call's description: cut to TITLE_LIMIT, at a
+    # word when one ends in its second half. nil for none.
+    def self.description_title(call)
+      text = description(call)
+      return text if text.nil? || text.length <= TITLE_LIMIT
+
+      cut = text[0, TITLE_LIMIT - 1]
+      space = cut.rindex(" ")
+      cut = cut[0, space] if space && space >= TITLE_LIMIT / 2
+      "#{cut.sub(/[\s,;:.-]+\z/, "")}…"
+    end
+  end
+end

data/lib/samagotchi/tools/builtins.rb

@@ -142,11 +142,14 @@ module Samagotchi
         -> { !!peers&.cancelled? }
       end
 
+      # @param command_description [Boolean] false: execute declares no
+      #   description parameter (execute.description off)
       # @return [Registry] a new registry with the built-ins, in
       #   TOOL_SCHEMAS order (an Engine's own, which bundles add to)
-      def registry
+      def registry(command_description: true)
         by_name = CLASSES.to_h { |klass| [klass::NAME, klass] }
         ToolDeclarations::TOOL_SCHEMAS.each_with_object(Registry.new) do |schema, registry|
+          schema = ToolDeclarations.without_command_description(schema) unless command_description
           klass = by_name.fetch(schema[:name])
           handler = HANDLERS.fetch(klass::NAME) { ->(call, _kctx) { klass.call(call[:content]) } }
           registry.register(klass::NAME, schema: schema, handler: handler)