samagotchi 0.12.0 → 0.13.0

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../paths"
+require_relative "../hooks/loader"
+require_relative "approval"
+require_relative "protected_paths"
+
+module Samagotchi
+  module Guardrails
+    # What a parent agent may allow on an approval (guardrails.parent_approvals,
+    # config.yml only): off, a deny only; once, "Allow once" too, never a
+    # wider scope. `chi answer` checks it before it posts; the worker checks
+    # it again for an answer marked as chi answer's (CLIENT_ID), with its own
+    # config. A convention for an honest but eager parent, not a security
+    # boundary: any local process can post to the Bridge, with or without
+    # the marker.
+    #
+    # An option allows when Approval.settle would allow it: its index is
+    # below the approval's scopes. The scope is read by index, never by
+    # label. When the scopes are missing or don't fit the options, it fails
+    # closed: only a last option labelled Deny denies.
+    #
+    # Whatever the setting, an approval for a call on chi's own config dir
+    # (config.yml, memories/.bundles' rules), the hooks dir or the approval
+    # store is the user's alone (:protected): "Allow once" on a config.yml
+    # rewrite would be "allow everything" from then on.
+    module ParentApprovals
+      KEY = "guardrails.parent_approvals"
+      # The client id chi answer posts its answers with.
+      CLIENT_ID = "cli:answer"
+      # Set by chi's execute and task_create for the commands they run: a
+      # chi started there answers as a parent (#parent_process?).
+      PARENT_SESSION_ENV = "SAMAGOTCHI_PARENT_SESSION"
+      # Environment variables that say an agent runs this process: Claude
+      # Code's, and chi's own. They survive a PTY wrapper (script, expect).
+      AGENT_MARKERS = ["CLAUDECODE", "AI_AGENT", PARENT_SESSION_ENV].freeze
+      # Rules that ask about chi's own config and hooks: the core
+      # ProtectedPaths asks and the guardrails bundle's shell rule.
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi].freeze
+      # A shell command naming chi's config, hooks or guardrails (the
+      # guardrails bundle's shell-touches-chi, less .git/hooks).
+      CHI_TEXT = %r{\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|memories/\.bundles}
+
+      module_function
+
+      # Whether an answer typed into this process is a parent agent's (so
+      # this setting applies to it): stdin isn't a terminal (a pipe, a file,
+      # /dev/null), or an agent marker is set. A person at chi --attach or
+      # the REPL has a terminal and no marker.
+      def parent_process?(env: ENV, stdin: $stdin)
+        return true if AGENT_MARKERS.any? { |key| !env.fetch(key, "").to_s.strip.empty? }
+
+        !(stdin.respond_to?(:tty?) && stdin.tty?)
+      end
+
+      # This process's setting: "once" or "off" (anything else is off).
+      def setting
+        Config.get(KEY).to_s == "once" ? "once" : "off"
+      end
+
+      # Why a parent may not give this answer, or nil.
+      # @param pending [Hash] the pending question (symbol or string keys)
+      # @param indices [Array<Integer, nil>] the selected options' places
+      # @param setting [String, nil] "off" or "once"
+      # @return [Symbol, nil] :protected (chi's own config: the user's
+      #   alone), :off (no allow at all), :once_only, or nil
+      def refusal(pending, indices, setting:)
+        return nil unless approval?(pending)
+
+        scopes = scopes(pending)
+        allows = Array(indices).reject { |index| deny?(pending, scopes, index) }
+        return nil if allows.empty?
+        return :protected if protected?(pending)
+        return :off unless setting.to_s == "once"
+        return nil if scopes && allows.all? { |index| index.is_a?(Integer) && index >= 0 && scopes[index] == "once" }
+
+        :once_only
+      end
+
+      # Whether +pending+ asks about a call on chi's own config, hooks,
+      # guardrail rules or approvals: by its rule, its paths or its command
+      # (the dirs as this process's environment and config.yml name them).
+      def protected?(pending)
+        facts = fetch(pending, :approval)
+        return false unless facts.is_a?(Hash)
+        return true if PROTECTED_RULES.include?(fetch(facts, :rule).to_s)
+        return true if fetch(facts, :source).to_s == ProtectedPaths::SOURCE
+
+        dirs = chi_dirs
+        paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)
+        return true if paths.any? { |path| dirs.any? { |dir| ProtectedPaths.within?(ProtectedPaths.real(path), dir) } }
+
+        command = fetch(facts, :command).to_s
+        return false if command.empty?
+
+        command.match?(CHI_TEXT) || dirs.any? { |dir| command.include?(dir) || command.include?(ProtectedPaths.real(dir)) }
+      end
+
+      # chi's config dir, the hooks dir and the approval store's dir.
+      def chi_dirs
+        hooks = begin Hooks::Loader.hooks_dir rescue nil end
+        [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails")]
+          .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
+      end
+
+      # The refusal as a line for the parent: deny, and tell the user.
+      # Never how to allow it (the web, chi --attach): that is the user's.
+      # @param reason [Symbol] what #refusal returned
+      # @param typed [Boolean] the answer was typed at a ? prompt (the
+      #   REPL), not given to chi answer
+      def message(reason, typed: false)
+        deny = typed ? "deny it (n; WHY), and tell your user" : "deny it (--option Deny --text WHY), and tell your user"
+        case reason
+        when :protected then "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{deny}"
+        when :off then "allowing a tool call is up to the user: #{deny}"
+        else "only Allow once (#{KEY}: once) can be given here: #{deny}"
+        end
+      end
+
+      # An approval: its kind says so, or it carries approval facts.
+      def approval?(pending)
+        fetch(pending, :kind).to_s == Approval::KIND || !fetch(pending, :approval).nil?
+      end
+
+      # The offered scopes, in option order, or nil when they are missing,
+      # empty, not strings, or leave no option after them for Deny.
+      def scopes(pending)
+        facts = fetch(pending, :approval)
+        scopes = facts.is_a?(Hash) ? fetch(facts, :scopes) : nil
+        return nil unless scopes.is_a?(Array) && !scopes.empty? && scopes.all?(String)
+        return nil unless scopes.size < options(pending).size
+
+        scopes
+      end
+
+      def deny?(pending, scopes, index)
+        return false unless index.is_a?(Integer) && index >= 0
+
+        options = options(pending)
+        return index >= scopes.size && index < options.size if scopes
+
+        index == options.size - 1 && options[index].to_s == Approval::DENY
+      end
+
+      def options(pending) = Array(fetch(pending, :options))
+
+      def fetch(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+    end
+  end
+end

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -4,6 +4,8 @@ require_relative "registry"
 require "digest"
 require_relative "../log"
 require_relative "../memory_bundle/provenance"
+require_relative "../memory_bundle/manifest"
+require_relative "../version"
 
 module Samagotchi
   # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
@@ -28,7 +30,8 @@ module Samagotchi
     # fails to load, or its file's sha256 differs from the one recorded at
     # install, the failure is reported and the gate denies every tool call.
     # Any hook whose sha256 differs is not loaded (reinstall the bundle
-    # after editing a hook by hand).
+    # after editing a hook by hand), nor any of a bundle whose requires_chi
+    # this chi doesn't meet.
     #
     # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
     #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
@@ -48,10 +51,14 @@ module Samagotchi
         # @param settings [Hash] the bundle's section of config.yml
         #   `bundles:` (string keys); a hook class whose initialize takes an
         #   argument gets it
+        # @param requires_chi [String, nil] the bundle's requirement; when
+        #   this chi doesn't meet it no hook loads (each is reported, as the
+        #   plugin loader does)
         # @return [Integer] number of hooks successfully registered
-        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {})
+        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, requires_chi: nil)
           return 0 unless metadata.is_a?(Hash)
 
+          too_old = MemoryBundle::Manifest.requires_chi_failure(requires_chi, Samagotchi::VERSION)
           loaded = 0
           metadata.each do |raw_basename, raw_meta|
             basename = raw_basename.to_s
@@ -72,7 +79,7 @@ module Samagotchi
               failures&.add(what, "the file is missing", required: true) if fail_closed
               next
             end
-            if (mismatch = sha_mismatch(file, meta.(:sha256), required: fail_closed))
+            if (mismatch = too_old || sha_mismatch(file, meta.(:sha256), required: fail_closed))
               Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
               failures&.add(what, mismatch, required: fail_closed)
               next

data/lib/samagotchi/host_registry.rb

@@ -21,7 +21,6 @@ module Samagotchi
   class HostRegistry
     CACHE_TTL_SECONDS = 60
     REMOTE_CACHE_TTL_SECONDS = 600
-    LIST_TIMEOUT_SECONDS = 3
     # Seconds a remote host's stream may take to show something (a queued
     # free model on OpenRouter can send only keep-alives for minutes).
     REMOTE_FIRST_TOKEN_TIMEOUT = 120

data/lib/samagotchi/llm/openai_chat.rb

@@ -245,12 +245,19 @@ module Samagotchi
           function = call["function"] || {}
           ToolCall.new(id: call["id"], name: function["name"].to_s, arguments: self.class.parse_arguments(function["arguments"]))
         end
-        ChatResponse.new(text: message["content"].to_s,
+        ChatResponse.new(text: OpenAIChat.drop_leading_newlines(message["content"].to_s),
                          reasoning: (message["reasoning_content"] || message["reasoning"]).to_s,
                          tool_calls: calls, usage: Usage.from_payload(body) || Usage.none,
                          finish_reason: body.dig("choices", 0, "finish_reason"), model: served_model(body))
       end
 
+      # Workaround for Splash 1.0.2/1.1.0, which keeps the "\n\n" the model
+      # writes after </think> at the start of the answer
+      # (https://github.com/incoai/splash/issues/254). Remove once Splash
+      # strips it; llama.cpp already does. Streamed, it applies to the chunks
+      # until the first text.
+      def self.drop_leading_newlines(text) = text.sub(/\A[\r\n]+/, "")
+
       def self.served_model(payload)
         model = payload.is_a?(Hash) ? payload["model"] : nil
         model.is_a?(String) && !model.strip.empty? ? model : nil
@@ -372,6 +379,7 @@ module Samagotchi
           @finish_reason = choice["finish_reason"] if choice["finish_reason"]
           delta = choice["delta"].is_a?(Hash) ? choice["delta"] : {}
           content = delta["content"].to_s
+          content = OpenAIChat.drop_leading_newlines(content) if @text.empty?
           reasoning = (delta["reasoning_content"] || delta["reasoning"]).to_s
           @text << content
           @reasoning << reasoning

data/lib/samagotchi/memory_bundle/installer.rb

@@ -265,6 +265,7 @@ module Samagotchi
         # ── Plugin: <file> into <bundle_dir>/plugin/ (docs/plugins.md) ────
         # Like the rules, the bundle's plugin replaces an earlier one.
         plugin_file_for_provenance = install_plugin(manifest, normalized_dir, provenance)
+        warn_hooks_requires_chi(manifest, all_hooks_in_bundle)
 
         # Files the previous version shipped and this one doesn't.
         if @upgrade && existing_provenance && existing_provenance[:files]
@@ -467,6 +468,17 @@ module Samagotchi
         end
       end
 
+      # The hook loader skips every hook of a bundle whose requires_chi this
+      # chi doesn't meet (Hooks::BundleLoader); say so at install, as
+      # install_plugin does for the plugin.
+      def warn_hooks_requires_chi(manifest, hook_files)
+        return if manifest.nil? || hook_files.empty?
+
+        if (failure = Manifest.requires_chi_failure(manifest.requires_chi, Samagotchi::VERSION))
+          @warnings << "Bundle #{@name}: its hooks won't load: #{failure}"
+        end
+      end
+
       # Copy the manifest's plugin file into the bundle's plugin/ dir,
       # warning when its sha256 differs from the declared one or this chi
       # doesn't meet requires_chi (the Engine then won't load it).

data/lib/samagotchi/memory_bundle/status.rb

@@ -43,7 +43,15 @@ module Samagotchi
           }
         end
         { provenance: data, scope: scope, target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
-          needs: needs_status(data) }
+          hooks_requires_failure: hooks_requires_failure(data), needs: needs_status(data) }
+      end
+
+      # Why none of the bundle's hooks load (this chi doesn't meet its
+      # requires_chi, Hooks::BundleLoader), or nil: it has no hooks or meets it.
+      def self.hooks_requires_failure(data)
+        return nil if (data[:hooks] || {}).empty?
+
+        Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION)
       end
 
       # The stored needs, each with found: from this process's PATH (the

data/lib/samagotchi/memory_paths.rb

@@ -51,6 +51,14 @@ module Samagotchi
       File.basename(common) == ".git" ? File.dirname(common) : common
     end
 
+    # The top of the git work tree holding +cwd+: the directory with the
+    # nearest .git (a linked worktree's own checkout, unlike #project_root);
+    # nil outside any repository.
+    def work_tree_root(cwd = Dir.pwd)
+      dot_git = find_dot_git(cwd)
+      dot_git && File.dirname(dot_git)
+    end
+
     # Is +cwd+ inside a git repository (a .git somewhere above it)?
     def in_repo?(cwd = Dir.pwd)
       !find_dot_git(cwd).nil?

data/lib/samagotchi/model_profile.rb

@@ -18,11 +18,18 @@ module Samagotchi
     # so every surface that reports a missing model reports it the same way).
     UnknownHost = Class.new(MissingModel)
 
+    # Gemma 4 thinks in a channel: `<|channel>thought` … `<channel|>`. The
+    # one source for the parser, the stream splitter, the literal guard and
+    # the web's saved-message reader.
+    GEMMA_THOUGHT_CHANNEL_OPEN = "<|channel>thought"
+    GEMMA_THOUGHT_CHANNEL_CLOSE = "<channel|>"
+
     attr_reader :name, :turn_start, :turn_end,
                 :tool_call_open, :tool_call_close,
                 :tool_response_open, :tool_response_close,
                 :string_delim,
                 :thought_open, :thought_close,
+                :thought_channel_open, :thought_channel_close,
                 :system_prefix, :user_prefix, :assistant_prefix,
                 :model_prefix,
                 :stop_sequences, :tool_decl_format,
@@ -39,6 +46,9 @@ module Samagotchi
       @string_delim = config[:string_delim]
       @thought_open = config[:thought_open]
       @thought_close = config[:thought_close]
+      # A thinking block besides thought_open's (Gemma's channel), or nil.
+      @thought_channel_open = config[:thought_channel_open]
+      @thought_channel_close = config[:thought_channel_close]
       @system_prefix = config[:system_prefix]
       @user_prefix = config[:user_prefix]
       @assistant_prefix = config[:assistant_prefix]
@@ -68,6 +78,8 @@ module Samagotchi
         string_delim: '<|"|>',
         thought_open: "<|think|>",
         thought_close: nil,
+        thought_channel_open: GEMMA_THOUGHT_CHANNEL_OPEN,
+        thought_channel_close: GEMMA_THOUGHT_CHANNEL_CLOSE,
         system_prefix: "",
         user_prefix: "",
         assistant_prefix: "",
@@ -131,8 +143,9 @@ module Samagotchi
     # qualified with a host that isn't configured, instead of sending the
     # whole ref to the default host as a model id, and when an alias after
     # a host prefix names another host ("openrouter:tiny" with tiny:
-    # box:…). Where a model comes in (an Engine starting or switching, a
-    # spawned session) calls it.
+    # box:…), or with a host config.yml has with enabled: false. Where a
+    # model comes in (an Engine starting or switching, a spawned session)
+    # calls it.
     # @param hosts [Hash, nil] the hosts a prefix may name (a HostRegistry's
     #   entries); config.yml's by default
     # @return [String] +model_name+
@@ -145,6 +158,9 @@ module Samagotchi
                            "use #{parsed.alias_name} or #{other}:#{parsed.alias_name}"
       end
       ref = parsed.ref
+      if !parsed.host_name && (disabled = disabled_host_prefix(ref, hosts, env))
+        raise UnknownHost, "host '#{disabled}' is disabled (enabled: false in config.yml)"
+      end
       warn_host_slash(ref, hosts) unless parsed.host_name
       host = Samagotchi::ConfigFile.unknown_host_prefix(ref, hosts: hosts)
       return model_name unless host
@@ -155,6 +171,18 @@ module Samagotchi
       raise UnknownHost, "unknown host '#{host}' in model '#{ref}'#{hint}; the configured hosts are #{names.join(', ')}"
     end
 
+    # The prefix of "box:x" when box is a host config.yml has with
+    # enabled: false (left out of +hosts+), else nil.
+    def self.disabled_host_prefix(ref, hosts, env)
+      prefix, rest = ref.to_s.split(":", 2)
+      return nil if rest.to_s.strip.empty?
+
+      prefix = prefix.strip.downcase
+      return nil if hosts.keys.any? { |k| k.to_s.downcase == prefix }
+
+      Samagotchi::ConfigFile.disabled_host_names(env: env).include?(prefix) ? prefix : nil
+    end
+
     # "box/x" named host box until '/' stopped naming a host: a saved
     # session or a hand-written ref says so once, then goes to the default host.
     def self.warn_host_slash(ref, hosts)
@@ -193,10 +221,6 @@ module Samagotchi
       DEFAULT_NAME
     end
 
-    def self.from_env
-      from_model_name(required_model_name(nil))
-    end
-
     # ── Resolution: which profile a model gets ───────────────────────────
 
     NAMES = %w[qwen36 gemma4].freeze
@@ -328,16 +352,6 @@ module Samagotchi
     end
     private_class_method :probe?
 
-    # ── Thought channel support ──────────────────────────────────────────
-
-    def thought_channel_open
-      nil
-    end
-
-    def uses_channel_thoughts?
-      false
-    end
-
     def uses_role_prefixes?
       !system_prefix.empty? && !user_prefix.empty?
     end

data/lib/samagotchi/parent_report.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "json"
+
+require_relative "cli/exit"
+
+module Samagotchi
+  # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
+  # sub-agent: `chi send --wait` and `chi answer`. One JSON object for
+  # --format json, or a line (a block for a question) for stderr, and the
+  # exit status. A question carries everything needed to answer it, so a
+  # parent agent can answer from the output alone. Kept apart from the
+  # commands so a later delegate_answer tool reports the same shape.
+  module ParentReport
+    # The approval facts a parent needs; the rest (preview, branch) is the
+    # card's.
+    APPROVAL_KEYS = %i[tool label command paths args cwd rule source reason scopes].freeze
+
+    # stderr that keeps its last line: with --format json a failure before
+    # any wait is reported from it (#error_line).
+    class LastLine < SimpleDelegator
+      attr_reader :last
+
+      def puts(*lines)
+        @last = lines.last.to_s.chomp unless lines.empty?
+        __getobj__.puts(*lines)
+      end
+    end
+
+    module_function
+
+    # @param result [ReplyWait::Result]
+    # @return [String] answered, question, failed, canceled, no_answer,
+    #   error, worker_gone, stopped or running
+    def status(result)
+      case result.status
+      when :done then "answered"
+      when :waiting_for_answer then "question"
+      when :no_reply
+        case result.outcome
+        when "failed" then "failed"
+        when "canceled" then "canceled"
+        else "no_answer"
+        end
+      when :error then "error"
+      when :worker_gone then "worker_gone"
+      when :stopped then "stopped"
+      # ReplyWait's own :canceled is the caller giving up (its cancelled:),
+      # and :timeout the deadline: the turn goes on either way.
+      else "running"
+      end
+    end
+
+    # @return [Integer] 0 answered, 3 a question waits, 4 still running,
+    #   1 anything else
+    def exit_status(result)
+      case status(result)
+      when "answered" then CLI::Exit::OK
+      when "question" then CLI::Exit::QUESTION
+      when "running" then CLI::Exit::RUNNING
+      else CLI::Exit::FAILED
+      end
+    end
+
+    # @param session_id [String]
+    # @param timeout [Numeric, nil] the wait's --timeout (for the running detail)
+    # @return [Hash] the --format json object
+    def json(result, session_id:, timeout: nil)
+      report = { status: status(result), session_id: session_id }
+      case report[:status]
+      when "answered" then report[:text] = result.text.to_s
+      when "question"
+        question = question(result.question)
+        report[:question] = question
+        report[:answer_with] = answer_with(session_id, question)
+      else report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      end
+      report
+    end
+
+    # @return [String] the JSON object as one line
+    def json_line(result, session_id:, timeout: nil)
+      JSON.generate(json(result, session_id: session_id, timeout: timeout))
+    end
+
+    # Print a wait's end the way the commands do: the JSON object on
+    # stdout, or the reply on stdout and anything else on stderr (a
+    # question in full) after "chi send: ".
+    # @param command [String] "chi send", "chi answer"
+    # @return [Integer] the exit status
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil)
+      if json
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout))
+      elsif result.status == :done
+        stdout.puts(result.text)
+      else
+        stdout.flush
+        text = if result.status == :waiting_for_answer
+                 question_text(result.question, session_id: session_id)
+               else
+                 "#{detail(result, session_id: session_id, timeout: timeout)}\n"
+               end
+        stderr.print("#{command}: #{text}")
+      end
+      stdout.flush
+      exit_status(result)
+    end
+
+    # A failure before any wait (no such session, a busy one, a message
+    # that didn't go in) as the JSON object.
+    # @param session_id [String, nil]
+    def error_line(detail, session_id: nil)
+      JSON.generate({ status: "error", session_id: session_id, detail: detail.to_s })
+    end
+
+    # A pending question (Session#pending_question) as a parent sees it.
+    # kind is "question" for the model's own (the desk stores none),
+    # "hook" or "approval".
+    # @return [Hash]
+    def question(pending)
+      pending ||= {}
+      approval = pending[:approval].is_a?(Hash) ? symbolize(pending[:approval]) : nil
+      {
+        id: pending[:id].to_s,
+        kind: (pending[:kind] || "question").to_s,
+        header: blank(pending[:header]),
+        text: pending[:question].to_s,
+        options: Array(pending[:options]).map(&:to_s),
+        multi_select: !!pending[:multi_select],
+        allow_freeform: !!pending[:allow_freeform],
+        approval: approval&.slice(*APPROVAL_KEYS)
+      }.compact
+    end
+
+    # The command that answers +question+; N is the parent's to fill in.
+    # An approval's is a deny: allowing it is the user's
+    # (Guardrails::ParentApprovals).
+    def answer_with(session_id, question)
+      return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
+
+      "chi answer #{session_id} --question #{question[:id]} --option N"
+    end
+
+    # What a parent does with an approval.
+    DENY_AND_TELL = "deny it, and tell your user"
+
+    def approval?(question)
+      question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "approval"
+    end
+
+    # What a wait that ended without an answer says, one line.
+    def detail(result, session_id:, timeout: nil)
+      attach = "chi --attach #{session_id}"
+      case result.status
+      when :waiting_for_answer
+        if approval?(result.question)
+          "waiting for an approval: #{first_line(result.question[:question])}; #{DENY_AND_TELL}"
+        else
+          "waiting for an answer: #{first_line(result.question&.dig(:question))}; open it: #{attach} or the web"
+        end
+      when :no_reply then "#{no_reply_line(result)}; #{attach} shows it"
+      when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
+      when :worker_gone then "the worker is gone; #{attach} shows what happened"
+      when :stopped then "the session was stopped (chi sessions stop)"
+      else timeout ? "still running after #{format("%g", timeout)} s: #{attach}" : "still running: #{attach}"
+      end
+    end
+
+    # The whole question for stderr: header, text, numbered options, what
+    # else it takes, and the commands that answer it.
+    # @return [String] lines, newline-terminated
+    def question_text(pending, session_id:)
+      q = question(pending)
+      lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
+      text_lines = q[:text].strip.lines.map(&:rstrip)
+      text_lines = text_lines.drop(1) unless q[:header]
+      lines.concat(text_lines.map { |line| "  #{line}" })
+      q[:options].each_with_index { |option, i| lines << "    #{i + 1}. #{option}" }
+      if approval?(q)
+        lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
+        lines << "  deny: #{answer_with(session_id, q)}"
+      else
+        lines << "  more than one allowed: repeat --option" if q[:multi_select]
+        lines << "  free text allowed: --text" if q[:allow_freeform]
+        lines << "  answer: #{answer_with(session_id, q)}"
+        lines << "  or open it: chi --attach #{session_id} or the web"
+      end
+      lines.map { |line| "#{line}\n" }.join
+    end
+
+    def no_reply_line(result)
+      case result.outcome
+      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
+      when "canceled" then "the turn was canceled"
+      when "completed" then "the turn ended with no visible answer"
+      else "the turn ended without a reply (canceled, failed or empty)"
+      end
+    end
+
+    def first_line(text)
+      text.to_s.strip.lines.first.to_s.strip
+    end
+
+    def blank(value)
+      value.to_s.strip.empty? ? nil : value.to_s
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../log"
 require_relative "../hooks/registry"
 require_relative "../tools/args"
@@ -298,14 +299,26 @@ module Samagotchi
           schema: spec[:schema], label: spec[:label],
           handler: lambda { |call, _kctx|
             result = block.call(Api.args_of(call, parameters), context)
-            # A String (a ToolResult too, with its images) as it is.
-            result.is_a?(String) ? result : result.to_s
+            Api.result_text(result)
           },
           preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
           targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
         }
       end
 
+      # A tool's result as the model reads it: a String (a ToolResult too,
+      # with its images) as it is, a Hash or Array as JSON (its #to_s is
+      # Hash#inspect, which changes with the Ruby version), else #to_s.
+      def self.result_text(result)
+        case result
+        when String then result
+        when Hash, Array then JSON.generate(result)
+        else result.to_s
+        end
+      rescue JSON::GeneratorError
+        result.to_s
+      end
+
       # A tool call's arguments as a plugin sees them: the parsers' args:
       # (a call built without one, in a spec say: the call without its
       # name), string keys, typed by +parameters+, frozen.

data/lib/samagotchi/prompt_literal_guard.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "model_profile"
+
 module Samagotchi
   # Escapes literal control-token text when arbitrary source/output is embedded
   # inside prompts, then restores those placeholders when model text is used.
@@ -13,8 +15,8 @@ module Samagotchi
       ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_CLOSE]]", "<tool_response|>"],
       ["[[SAMAGOTCHI_LITERAL_GEMMA_STRING_DELIM]]", '<|"|>'],
       ["[[SAMAGOTCHI_LITERAL_THINK_OPEN]]", "<|think|>"],
-      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_OPEN]]", "<|channel>thought"],
-      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_CLOSE]]", "<channel|>"]
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_OPEN]]", ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN],
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_CLOSE]]", ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE]
     ].freeze
 
     QWEN_TOKEN_PAIRS = [