samagotchi 0.12.0 → 0.14.0

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -0,0 +1,158 @@
+# 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, the AI_AGENT convention, Codex CLI's (CODEX_THREAD_ID, which
+      # Codex sets on every command its shell tool runs), and chi's own.
+      # They survive a PTY wrapper (script, expect). The docs list them too
+      # (guardrails.md, sub-agent.md).
+      AGENT_MARKERS = ["CLAUDECODE", "AI_AGENT", "CODEX_THREAD_ID", 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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ipaddr"
 require_relative "config"
 require_relative "model_ref"
 require_relative "client"
@@ -21,7 +22,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
@@ -32,9 +32,12 @@ module Samagotchi
     # first_token_timeout: the configured first-token limit (see #first_token_limit);
     # vision: the configured true/false (VisionSupport), nil when unset;
     # sampling: the configured request parameters (SamplingSettings), nil when unset;
-    # thinking: the configured level (Thinking), nil when unset.
+    # thinking: the configured level (Thinking), nil when unset;
+    # remote: the configured true/false (#remote?), nil when unset;
+    # window_tokens: the configured context window (ContextWindow.setting), nil when unset.
     HostEntry = Struct.new(:name, :host, :port, :transport, :client, :api, :scheme, :url, :api_key_env, :profile,
-                           :first_token_timeout, :vision, :sampling, :thinking, keyword_init: true) do
+                           :first_token_timeout, :vision, :sampling, :thinking, :remote, :window_tokens,
+                           keyword_init: true) do
       # Talks the OpenAI chat API (the chat loop); nil and raw apis use the
       # raw-prompt loop.
       def chat? = api == :openai
@@ -46,9 +49,12 @@ module Samagotchi
       # configured, else the root's /v1.
       def openai_base_url = url || "#{root_url}/v1"
 
-      # A provider on the network rather than a local server: it needs a key
-      # or speaks https. Its model list is cached longer.
-      def remote? = !api_key_env.to_s.empty? || scheme == "https"
+      # A provider on the network rather than a local server: hosts.<name>.remote
+      # when set, else by its address (HostRegistry.remote_address?). An API
+      # key doesn't decide: a llama.cpp on the LAN can have one. A remote
+      # host's model list is cached longer, it gets a first-token limit, and
+      # it isn't asked for llama.cpp's /props.
+      def remote? = remote.nil? ? HostRegistry.remote_address?(scheme, host) : remote
 
       def models_ttl = remote? ? REMOTE_CACHE_TTL_SECONDS : CACHE_TTL_SECONDS
 
@@ -90,7 +96,8 @@ module Samagotchi
         entry = HostEntry.new(name: key.to_s.downcase, host: cfg[:host], port: cfg[:port].to_i, transport: transport,
                               api: cfg[:api]&.to_sym, scheme: cfg[:scheme], url: cfg[:url], api_key_env: cfg[:api_key_env],
                               profile: cfg[:profile], first_token_timeout: cfg[:first_token_timeout],
-                              vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking])
+                              vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking],
+                              remote: cfg[:remote], window_tokens: cfg[:window_tokens])
         entry.client = Client.new(host: cfg[:host], port: cfg[:port], transport: transport, scheme: cfg[:scheme],
                                   first_token_timeout: entry.first_token_limit, name: entry.name,
                                   api_key_env: entry.api_key_env, env: env)
@@ -114,6 +121,23 @@ module Samagotchi
       @entries
     end
 
+    # Loopback, private (RFC 1918, IPv6 unique local) and link-local nets.
+    LOCAL_NETS = %w[127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 100.64.0.0/10
+                    ::1/128 fc00::/7 fe80::/10].map { |net| IPAddr.new(net) }.freeze
+
+    # Whether an address is remote: https, or an http IP address outside
+    # the local nets (LOCAL_NETS). An http host named by a name (localhost,
+    # box, mac.local, gpu.lan) counts as local: chi doesn't look names up.
+    def self.remote_address?(scheme, host)
+      return true if scheme.to_s == "https"
+
+      address = IPAddr.new(host.to_s.delete_prefix("[").delete_suffix("]"))
+      address = address.native if address.ipv4_mapped?
+      LOCAL_NETS.none? { |net| net.family == address.family && net.include?(address) }
+    rescue IPAddr::Error
+      false
+    end
+
     # server.first_token_timeout, or nil when unset or unreadable.
     def self.configured_first_token_timeout
       Config.get("server.first_token_timeout")

data/lib/samagotchi/kernel_loop.rb

@@ -271,7 +271,7 @@ module Samagotchi
     def prepare_request(turn)
       prompt, images = format_prompt(turn)
       image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
-      window = ContextWindow.resolve(client: @client, model: turn.model_name)
+      window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: @turn_settings.window_setting)
       emit_context_status_event(turn.on_stream_event, turn.context, prompt, iteration_index: turn.iteration - 1,
                                                                              window: window, image_tokens: image_tokens)
       if (line = turn.context.take_guidance)

data/lib/samagotchi/llm/chat_loop.rb

@@ -172,11 +172,13 @@ module Samagotchi
 
       # The window for +model+: the kernel's client probes the server it
       # points at (Engine keeps it on the effective model's host; a local
-      # llama.cpp answers /props), then the host's model list, config, env
-      # and the default. A remote provider has no /props to probe.
+      # llama.cpp answers /props), then the host's model list, the model's
+      # or host's window_tokens, config, env and the default. A remote
+      # provider has no /props to probe.
       def context_window(model)
         client = @adapter.remote? ? nil : @kernel.client
-        ContextWindow.resolve(client: client, model: model, adapter: @adapter)
+        ContextWindow.resolve(client: client, model: model, adapter: @adapter,
+                              setting: (@kernel.turn_settings&.window_setting if @kernel.respond_to?(:turn_settings)))
       rescue StandardError
         nil
       end

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/llm/turn_settings.rb

@@ -8,12 +8,14 @@ module Samagotchi
     # ChatLoop) and ToolRunner: the turn's VisionContext (nil sends no
     # images, placeholders instead), its request parameters
     # (SamplingSettings.for; empty sends none), its thinking level
-    # (Thinking.resolve) and the bare model id the turn runs on (every
-    # debug dump is tagged with it). The Engine sets them once per turn,
-    # in Engine#generate, after the model's host is synced.
-    TurnSettings = Data.define(:vision, :sampling, :thinking, :model_name) do
+    # (Thinking.resolve), the bare model id the turn runs on (every debug
+    # dump is tagged with it) and the model's or host's configured context
+    # window (ContextWindow.setting, nil for none). The Engine sets them
+    # once per turn, in Engine#generate, after the model's host is synced.
+    TurnSettings = Data.define(:vision, :sampling, :thinking, :model_name, :window_setting) do
       # No vision, no sampling, the default thinking, no model name.
-      def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, model_name: nil)
+      def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, model_name: nil,
+                          window_setting: nil)
     end
   end
 end

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