samagotchi 0.3.0 → 0.5.0

data/lib/samagotchi/text_diff.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Line-based unified diff (like `diff -u` without the file header), used to
+  # show what chi's edit/write tools change. Pure: strings in, a hash out.
+  #
+  #   TextDiff.unified("a\nb\n", "a\nc\n")
+  #   # => {text: "@@ -1,2 +1,2 @@\n a\n-b\n+c", added: 1, removed: 1, truncated: false}
+  #
+  # The common prefix and suffix are trimmed first (edits are local), then
+  # Myers O(ND) runs on the middle. When the edit distance passes
+  # MAX_EDIT_DISTANCE it gives up on a minimal diff and shows the whole middle
+  # as removed then added: correct, just not minimal. The text is cut at
+  # MAX_LINES / MAX_BYTES with a "… N more lines" line; the counts stay exact.
+  module TextDiff
+    CONTEXT = 3
+    MAX_LINES = 120
+    MAX_BYTES = 8 * 1024
+    MAX_EDIT_DISTANCE = 1000 # D² work: ~0.35 s for a dense 5 000-line edit
+    NO_NEWLINE = "\"
+
+    module_function
+
+    def unified(before, after, context: CONTEXT, max_lines: MAX_LINES, max_bytes: MAX_BYTES)
+      a = clean(before).lines
+      b = clean(after).lines
+      ops = edit_script(a, b)
+      added = ops.count { |op| op[0] == :add }
+      removed = ops.count { |op| op[0] == :del }
+      text, truncated = render(hunks(ops, context), a, b, max_lines, max_bytes)
+      { text: text, added: added, removed: removed, truncated: truncated }
+    end
+
+    def clean(text)
+      text.to_s.dup.force_encoding(Encoding::UTF_8).scrub("�")
+    end
+
+    # Ops are [:eq, ai, bi], [:del, ai, nil] or [:add, nil, bi] in file order.
+    def edit_script(a, b)
+      pre = 0
+      pre += 1 while pre < a.size && pre < b.size && a[pre] == b[pre]
+      suf = 0
+      suf += 1 while suf < a.size - pre && suf < b.size - pre && a[-1 - suf] == b[-1 - suf]
+
+      ops = (0...pre).map { |i| [:eq, i, i] }
+      a_mid = a[pre...(a.size - suf)]
+      b_mid = b[pre...(b.size - suf)]
+      middle = myers(a_mid, b_mid) ||
+               a_mid.each_index.map { |i| [:del, i, nil] } + b_mid.each_index.map { |j| [:add, nil, j] }
+      middle.each { |t, i, j| ops << [t, i && i + pre, j && j + pre] }
+      (0...suf).each { |s| ops << [:eq, a.size - suf + s, b.size - suf + s] }
+      ops
+    end
+
+    # Myers' greedy forward search, keeping one slice of V per round for the
+    # backtrack. Returns nil when the edit distance passes max_d.
+    def myers(a, b, max_d = MAX_EDIT_DISTANCE)
+      ids = {}
+      a = a.map { |l| ids[l] ||= ids.size }
+      b = b.map { |l| ids[l] ||= ids.size }
+      # No line in common (a full rewrite): the fallback is the minimal diff.
+      return nil if ids.size == a.uniq.size + b.uniq.size
+
+      n = a.size
+      m = b.size
+      off = n + m + 1
+      v = Array.new(2 * off + 1, 0)
+      trace = []
+      (0..(n + m)).each do |d|
+        return nil if d > max_d
+
+        # Round d reads k-1 and k+1 for k in -d..d: keep -(d+1)..d+1.
+        trace << v[off - d - 1, 2 * d + 3]
+        k = -d
+        while k <= d
+          x = if k == -d || (k != d && v[off + k - 1] < v[off + k + 1])
+                v[off + k + 1]
+              else
+                v[off + k - 1] + 1
+              end
+          y = x - k
+          while x < n && y < m && a[x] == b[y]
+            x += 1
+            y += 1
+          end
+          v[off + k] = x
+          return backtrack(trace, n, m) if x >= n && y >= m
+
+          k += 2
+        end
+      end
+      []
+    end
+
+    def backtrack(trace, x, y)
+      ops = []
+      (trace.size - 1).downto(0) do |d|
+        vd = trace[d]
+        at = ->(k) { vd[k + d + 1] }
+        k = x - y
+        prev_k = k == -d || (k != d && at.(k - 1) < at.(k + 1)) ? k + 1 : k - 1
+        prev_x = at.(prev_k)
+        prev_y = prev_x - prev_k
+        while x > prev_x && y > prev_y
+          x -= 1
+          y -= 1
+          ops << [:eq, x, y]
+        end
+        break if d.zero?
+
+        if x == prev_x
+          ops << [:add, nil, prev_y]
+        else
+          ops << [:del, prev_x, nil]
+        end
+        x = prev_x
+        y = prev_y
+      end
+      ops.reverse
+    end
+
+    # Groups ops into hunks: runs of changes whose gaps are at most 2*context
+    # unchanged lines, each padded with up to context lines on both sides.
+    def hunks(ops, context)
+      changed = ops.each_index.reject { |i| ops[i][0] == :eq }
+      return [] if changed.empty?
+
+      groups = [[changed.first, changed.first]]
+      changed.drop(1).each do |i|
+        if i - groups.last[1] - 1 <= 2 * context
+          groups.last[1] = i
+        else
+          groups << [i, i]
+        end
+      end
+      groups.map { |first, last| ops[[first - context, 0].max..[last + context, ops.size - 1].min] }
+    end
+
+    def render(hunks, a, b, max_lines, max_bytes)
+      lines = []
+      hunks.each do |hunk|
+        lines << header(hunk)
+        hunk.each do |t, i, j|
+          line = t == :add ? b[j] : a[i]
+          mark = { eq: " ", del: "-", add: "+" }[t]
+          # Only the "\n": chomp("\n") would take a CRLF's "\r" too.
+          lines << mark + (line.end_with?("\n") ? line[0...-1] : line)
+          lines << NO_NEWLINE unless line.end_with?("\n")
+        end
+      end
+      cut(lines, max_lines, max_bytes)
+    end
+
+    # @@ -start,len +start,len @@ with diff -u's conventions: ",1" is left
+    # out. A side with no lines in the hunk is an empty file (any other hunk
+    # has context lines), shown as 0,0.
+    def header(hunk)
+      a_lines = hunk.filter_map { |t, i, _| i unless t == :add }
+      b_lines = hunk.filter_map { |t, _, j| j unless t == :del }
+      "@@ -#{range(a_lines)} +#{range(b_lines)} @@"
+    end
+
+    def range(indexes)
+      return "0,0" if indexes.empty?
+
+      indexes.size == 1 ? (indexes.first + 1).to_s : "#{indexes.first + 1},#{indexes.size}"
+    end
+
+    def cut(lines, max_lines, max_bytes)
+      bytes = 0
+      lines.each_with_index do |line, i|
+        bytes += line.bytesize + 1
+        next unless i >= max_lines || bytes > max_bytes
+
+        rest = lines.size - i
+        return [(lines[0, i] + ["… #{rest} more lines"]).join("\n"), true]
+      end
+      [lines.join("\n"), false]
+    end
+  end
+end

data/lib/samagotchi/thinking.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # How much a model thinks: one level per model, host or run, mapped to each
+  # backend's own switch. The one place that knows the mapping.
+  #
+  #   off      thinking off where the backend can do it
+  #   low, medium, high   the effort a chat host is asked for
+  #   default  chi sends nothing: the provider's or template's own default
+  #
+  # Order (#resolve): --thinking / SAMAGOTCHI_THINKING_LEVEL, then
+  # models.<key>.thinking, hosts.<name>.thinking, thinking.level in
+  # config.yml, then default.
+  module Thinking
+    LEVELS = %i[off low medium high default].freeze
+    EFFORTS = %i[low medium high].freeze
+    DEFAULT = :default
+
+    # Gemma 4 turns thinking on with this token at the start of the system prompt.
+    GEMMA_THINK_TOKEN = "<|think|>\n"
+    # An empty thought after the Qwen assistant cue: the model answers at once
+    # (what the server's own template does with enable_thinking false).
+    QWEN_EMPTY_THOUGHT = "<think>\n\n</think>\n\n"
+
+    # What a native prompt gets for a level: the text before the system
+    # prompt, the text after the assistant cue, and whether the level means
+    # anything there (low/medium/high have no native knob).
+    Native = Data.define(:system_token, :prefill, :honoured)
+
+    module_function
+
+    # A configured value as a level; nil when unset or not a level (that
+    # warns once, naming +where+). YAML reads an unquoted `off` as false,
+    # which is :off; true (`on`) isn't a level.
+    # @return [Symbol, nil]
+    def level(value, where)
+      return nil if value.nil?
+      return :off if value == false || value.to_s.strip.downcase == "false"
+
+      text = value.to_s.strip.downcase
+      return text.to_sym if LEVELS.include?(text.to_sym)
+
+      hint = value == true || %w[true on].include?(text) ? "; `on` isn't one, `default` leaves it to the model" : ""
+      ConfigFile.warn_once "Warning: #{where}: thinking must be one of #{LEVELS.join(', ')}#{hint}; ignored"
+      nil
+    end
+
+    # The level for +target+ and where it came from ("--thinking",
+    # "models: qwen", "hosts.work", "thinking.level"; nil for the default).
+    # @param target [HostRegistry::ModelTarget]
+    # @param names [Array<String>, nil] the model's lookup names (Engine#model_lookup_names)
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @return [Array(Symbol, String|nil)]
+    def resolve(target, names: nil, models: nil)
+      global, origin = global_level
+      return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
+
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      names ||= [target.model, target.bare_model]
+      key, value = ConfigFile.model_setting(names, :thinking, models: models)
+      return [value, "models: #{key}"] if key
+
+      host = target.entry.respond_to?(:thinking) ? target.entry.thinking : nil
+      return [host, "hosts.#{target.entry.name}"] if host
+      return [global, "thinking.level"] if global
+
+      [DEFAULT, nil]
+    end
+
+    # thinking.level as a level and its origin (:cli, :env, :file), or nil.
+    def global_level
+      raw, origin = Config.get_with_origin("thinking.level")
+      return nil if origin == :default
+
+      where = { cli: "--thinking", env: "SAMAGOTCHI_THINKING_LEVEL" }.fetch(origin, "thinking.level")
+      value = level(raw, where)
+      value ? [value, origin] : nil
+    rescue StandardError
+      nil
+    end
+
+    # Request fields for an OpenAI-style chat host. off sends both switches
+    # (the template's enable_thinking and the OpenAI-style reasoning_effort
+    # "none"): llama.cpp, Splash and OpenRouter each honour one of them.
+    # An effort goes as reasoning_effort (llama.cpp ignores it). default
+    # sends nothing.
+    # @return [Hash] frozen
+    def chat_fields(level)
+      case level
+      when :off then { chat_template_kwargs: { enable_thinking: false }.freeze, reasoning_effort: "none" }.freeze
+      when *EFFORTS then { reasoning_effort: level.to_s }.freeze
+      else {}.freeze
+      end
+    end
+
+    # Whether a chat host's /props (+props+, Client::ServerProps) says its
+    # chat template takes no effort (llama.cpp's
+    # chat_template_caps.supports_reasoning_effort: false), so +level+'s
+    # reasoning_effort is ignored. false when it doesn't say.
+    def effort_ignored?(level, props)
+      return false unless EFFORTS.include?(level) && props&.answered? && props.body.is_a?(Hash)
+
+      caps = props.body["chat_template_caps"]
+      caps.is_a?(Hash) && caps["supports_reasoning_effort"] == false
+    end
+
+    # The native prompt's switch for +level+ under +profile+.
+    # @param profile [ModelProfile]
+    # @return [Native]
+    def native(level, profile)
+      off = level == :off
+      honoured = !EFFORTS.include?(level)
+      case profile&.name
+      when "gemma4" then Native.new(system_token: off ? "" : GEMMA_THINK_TOKEN, prefill: "", honoured: honoured)
+      when "qwen36" then Native.new(system_token: "", prefill: off ? QWEN_EMPTY_THOUGHT : "", honoured: honoured)
+      else Native.new(system_token: "", prefill: "", honoured: level == DEFAULT)
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_activity.rb

@@ -31,13 +31,63 @@ module Samagotchi
     module_function
 
     # @param registry [Tools::Registry, nil] the session's tools
-    def tool_activity_event(tool_name, call, result, registry: nil)
-      {
+    # @param cwd [String, nil] what a file tool's title is relative to (the
+    #   worker runs in its session's working directory)
+    def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd)
+      event = {
         action: tool_activity_action(tool_name, registry: registry),
         tool: tool_name,
         params: tool_activity_params(tool_name, call, registry: registry),
         status: tool_activity_status(result, tool_name)
       }
+      title = tool_title(tool_name, call, cwd: cwd)
+      event[:title] = title if title
+      event
+    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).
+    def tool_title(tool_name, call, cwd: nil)
+      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]
+             when Tools::Execute::NAME, Tools::TaskCreate::NAME then command_title(call[:content])
+             end
+      text = text.to_s.strip
+      return nil if text.empty?
+
+      case tool_name
+      when Tools::Read::NAME, Tools::Write::NAME, Tools::Edit::NAME
+        path = relative_path(text, cwd)
+        path.length > TOOL_ACTIVITY_PREVIEW_LIMIT ? "…#{path[-(TOOL_ACTIVITY_PREVIEW_LIMIT - 1)..]}" : path
+      else
+        text = text.gsub(/\s+/, " ")
+        text.length > TOOL_ACTIVITY_PREVIEW_LIMIT ? "#{text[0, TOOL_ACTIVITY_PREVIEW_LIMIT - 1]}…" : text
+      end
+    end
+
+    # A leading "cd <dir> &&" / "cd <dir>;" goes: the model's habit, and it
+    # eats the line.
+    LEADING_CD = /\Acd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/
+
+    def command_title(command)
+      line = command.to_s.lines.map(&:strip).find { |l| !l.empty? }.to_s
+      line.sub(LEADING_CD, "")
+    end
+
+    # +path+ relative to +cwd+ when it is inside it, compared by path
+    # components ("/p/app-2" is not inside "/p/app"); else as given.
+    def relative_path(path, cwd)
+      return path if cwd.to_s.empty? || !path.start_with?("/")
+
+      parts = File.expand_path(path).split("/")
+      base = File.expand_path(cwd).split("/")
+      return path unless parts.length > base.length && parts[0, base.length] == base
+
+      parts.drop(base.length).join("/")
     end
 
     def tool_activity_action(tool_name, registry: nil)

data/lib/samagotchi/tool_runner.rb

@@ -4,6 +4,8 @@ require_relative "tool_activity"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
+require_relative "edit_preview"
+require_relative "tools/tool_path"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -17,6 +19,10 @@ module Samagotchi
     # that returns many screenshots can't flood the context).
     MAX_IMAGES_PER_RESULT = 4
 
+    # file_before for a call that isn't an edit/write, or won't run.
+    NOT_AN_EDIT = Object.new.freeze
+    private_constant :NOT_AN_EDIT
+
     # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
     #   the kernel is built.
     def initialize(kernel)
@@ -29,7 +35,9 @@ module Samagotchi
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
     #   (the loops save them with the result, so a reload without the plugin
-    #   shows the same row)
+    #   shows the same row), and diff: what an edit/write changed in its
+    #   file (EditPreview.change; also on tool_call_completed, never in the
+    #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
@@ -40,12 +48,17 @@ module Samagotchi
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
                   tool: call[:name], call: call.dup, params: params }
       started[:label] = label if label
+      # The worker runs in its session's working directory.
+      title = ToolActivity.tool_title(call[:name], call, cwd: Dir.pwd)
+      started[:title] = title if title
       emit(on_stream_event, started)
 
       # The ask comes after tool_call_started: the UI shows the tool line,
       # then the approval under it.
       settle_ask(verdict) if verdict.ask?
+      before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
+      diff = file_change(call, before)
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -61,17 +74,40 @@ module Samagotchi
       completed = { type: :tool_call_completed, iteration: iteration, call_count: call_count, call_index: call_index,
                     tool: call[:name], output: capped, output_truncated: truncated, activity: result[:activity] }
       completed[:images] = images if images&.any?
+      completed[:diff] = diff if diff
       emit(on_stream_event, completed)
 
       run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
       run[:images] = images if images&.any?
       run[:shown_params] = params if params && plugin_tool?(call[:name])
       run[:shown_label] = label if label
+      run[:diff] = diff if diff
       run
     end
 
     private
 
+    # edit/write only: the file just before the call runs. The row diffs it
+    # with the file after, whatever the result says, so an edit that fails
+    # after writing still shows its change and one that wrote nothing shows
+    # none.
+    def file_before(call)
+      return NOT_AN_EDIT unless EditPreview.tool?(call[:name])
+
+      EditPreview.snapshot(Tools::ToolPath.normalize(call[:path]))
+    rescue StandardError
+      NOT_AN_EDIT
+    end
+
+    def file_change(call, before)
+      return nil if before.equal?(NOT_AN_EDIT)
+
+      EditPreview.change(before, EditPreview.snapshot(Tools::ToolPath.normalize(call[:path])))
+    rescue StandardError => e
+      Log.warn(:turn, "edit_diff_failed", tool: call[:name], error: "#{e.class}: #{e.message}")
+      nil
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/ask_user_question.rb

@@ -19,30 +19,50 @@ module Samagotchi
 
       def self.name        = NAME
 
-      # Direct invocation (used in specs / headless fallback).
-      # When a blocking handler is not injected, return an instructional error so the
-      # model falls back to plain text rather than hanging.
-      def self.call(question, options: nil, header: nil, multi_select: nil, allow_freeform: nil)
-        question = question.to_s.strip
-        return "Error: question is required" if question.empty?
-
-        opts = normalize_options(options)
-        return "Error: options must be an array of 2-8 non-empty strings" if opts.nil?
-
-        header = header.to_s.strip
-        header = nil if header.empty?
-        ms = to_bool(multi_select)
-        af = to_bool(allow_freeform)
-
-        payload = {
+      QUESTION_REQUIRED_ERROR = "Error: ask_user_question requires 'question'"
+
+      # The tool result for a wrong number of options.
+      def self.options_count_error(count)
+        "Error: ask_user_question requires 2-8 options (got #{count}). Provide e.g. options=[\"Cats\",\"Dogs\"]"
+      end
+
+      # The one check of a model's ask_user_question call (the kernel runs it
+      # before the question opens). Dumb-model tolerant: options may be a JSON
+      # string or bracket noise, a single option is salvaged, missing options
+      # are read from the call's content, booleans may be strings; wire control
+      # tokens are stripped from the question and header.
+      # @param call [Hash] the tool call (question:/content:, options:, header:,
+      #   multi_select:, allow_freeform:)
+      # @return [Hash, String] the payload {question:, options:, header:,
+      #   multi_select:, allow_freeform:} (no header key when empty), or the
+      #   plain-text error the model gets as the tool result
+      def self.validate(call)
+        question = strip_wire_tokens(call[:question] || call[:content])
+        return QUESTION_REQUIRED_ERROR if question.empty?
+
+        options = normalize_options_lenient(call[:options])
+        options = normalize_options_lenient(call[:content].to_s) if options.empty? && call[:content]
+        return options_count_error(options.size) if options.empty? || options.size > 8
+
+        header = strip_wire_tokens(call[:header])
+        {
           question: question,
-          options: opts,
-          header: header,
-          multi_select: ms,
-          allow_freeform: af
+          options: options,
+          header: (header unless header.empty?),
+          multi_select: to_bool(call[:multi_select]),
+          allow_freeform: to_bool(call[:allow_freeform])
         }.compact
+      end
+
+      # Booleans the way models send them (Gemma passes "true"/"false").
+      def self.to_bool(value)
+        return value if value == true || value == false
 
-        JSON.pretty_generate(payload)
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+
+      def self.strip_wire_tokens(text)
+        text.to_s.gsub(/<\|[^|]*\|>/, "").gsub(/<\||\|>/, "").strip
       end
 
       # Normalize options param: accept Array or JSON string; strip, reject empty.
@@ -135,18 +155,6 @@ module Samagotchi
 
         arr.map { |v| sanitize_option(v) }.reject { |v| v.nil? || v.empty? }
       end
-
-      def self.to_bool(v)
-        return nil if v.nil?
-        return v if v == true || v == false
-
-        s = v.to_s.strip.downcase
-        return true if %w[1 true yes on].include?(s)
-        return false if %w[0 false no off].include?(s)
-
-        nil
-      end
-      private_class_method :to_bool
     end
   end
 end

data/lib/samagotchi/tools/edit.rb

@@ -22,9 +22,25 @@ module Samagotchi
 
       def self.call(content, path:, start_line: nil, end_line: nil)
         path = ToolPath.normalize(path)
+        result = apply(content, path: path, start_line: start_line, end_line: end_line)
+        return result if result.is_a?(String)
+
+        updated, message = result
+        File.write(path, updated)
+        message
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      # The edit without the write: [updated, message] or "Error: …", with
+      # exactly the strings call returns. +read+ reads the file, so a dry run
+      # (EditPreview) can reuse a copy it already has; each mode keeps its own
+      # check order (exact: tags first; range: file not found first).
+      def self.apply(content, path:, start_line: nil, end_line: nil, read: ->(p) { File.read(p) })
+        path = ToolPath.normalize(path)
 
         if range_requested?(start_line, end_line)
-          return call_range_mode(content, path: path, start_line: start_line, end_line: end_line)
+          return apply_range_mode(content, path: path, start_line: start_line, end_line: end_line, read: read)
         end
 
         old_text = extract_tag(content, "old")
@@ -35,7 +51,7 @@ module Samagotchi
         return "Error: <old> block is empty" if old_text.empty?
         return "Error: file not found: #{path}" unless File.exist?(path)
 
-        source = File.read(path)
+        source = read.(path)
         count  = count_occurrences(source, old_text)
 
         return "Error: old text not found in #{path}" if count == 0
@@ -43,13 +59,12 @@ module Samagotchi
 
         idx     = source.index(old_text)
         updated = source[0, idx] + new_text + source[idx + old_text.length..]
-        File.write(path, updated)
-        "Edited #{path}: replaced #{old_text.bytesize} bytes with #{new_text.bytesize} bytes"
+        [updated, "Edited #{path}: replaced #{old_text.bytesize} bytes with #{new_text.bytesize} bytes"]
       rescue => e
         "Error: #{e.message}"
       end
 
-      def self.call_range_mode(content, path:, start_line:, end_line:)
+      def self.apply_range_mode(content, path:, start_line:, end_line:, read:)
         return "Error: file not found: #{path}" unless File.exist?(path)
 
         new_text = extract_tag(content, "new")
@@ -59,7 +74,7 @@ module Samagotchi
         return start_num if start_num.is_a?(String)
         return "Error: start_line must be provided for range edits" if start_num.nil?
 
-        source = File.read(path)
+        source = read.(path)
         lines = source.lines
         total_lines = lines.length
 
@@ -102,15 +117,14 @@ module Samagotchi
         # first suffix line isn't concatenated onto the last replacement line.
         normalized = (!new_text.empty? && !suffix.empty? && !new_text.end_with?("\n")) ? new_text + "\n" : new_text
         updated = prefix + normalized + suffix
-        File.write(path, updated)
 
         replaced_lines = (end_value - start_num) + 1
         new_line_count = new_text.lines.length
-        "Edited #{path}: replaced lines #{start_num}-#{end_value} (#{replaced_lines} lines) with #{new_line_count} lines#{clamp_note}"
+        [updated, "Edited #{path}: replaced lines #{start_num}-#{end_value} (#{replaced_lines} lines) with #{new_line_count} lines#{clamp_note}"]
       rescue => e
         "Error: #{e.message}"
       end
-      private_class_method :call_range_mode
+      private_class_method :apply_range_mode
 
       # Count non-overlapping literal occurrences of +needle+ in +haystack+.
       def self.count_occurrences(haystack, needle)

data/lib/samagotchi/tools/execute.rb

@@ -195,8 +195,8 @@ module Samagotchi
       def self.output_block(label, content)
         return nil if content.nil? || content.empty?
 
-        truncate_at_bytes = OutputGuardrails.env_positive_int("SAMAGOTCHI_EXECUTE_TRUNCATE_AT_BYTES", OutputGuardrails::DEFAULT_TRUNCATE_AT_BYTES)
-        preview_bytes = OutputGuardrails.env_positive_int("SAMAGOTCHI_EXECUTE_PREVIEW_BYTES", OutputGuardrails::DEFAULT_PREVIEW_BYTES)
+        truncate_at_bytes = OutputGuardrails.config_positive_int("execute.truncate_at_bytes", OutputGuardrails::DEFAULT_TRUNCATE_AT_BYTES)
+        preview_bytes = OutputGuardrails.config_positive_int("execute.preview_bytes", OutputGuardrails::DEFAULT_PREVIEW_BYTES)
         bytes = content.bytesize
         return "#{label}:\n#{content}" if bytes <= truncate_at_bytes
 
@@ -220,7 +220,7 @@ module Samagotchi
       def self.telemetry_lines_for(content)
         OutputGuardrails.telemetry_lines_for(
           content: content,
-          threshold_env: "SAMAGOTCHI_EXECUTE_TELEMETRY_THRESHOLD_PCT",
+          threshold_key: "execute.telemetry_threshold_pct",
           threshold_default: OutputGuardrails::DEFAULT_TELEMETRY_THRESHOLD_PCT,
           token_key: "estimated_tokens_for_command_output",
           pct_key: "estimated_window_pct_for_command_output"