samagotchi 0.7.0 → 0.8.1

data/lib/samagotchi/context_status.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "context_usage"
+require_relative "context_window"
+
+module Samagotchi
+  # One turn's context tracking for KernelLoop#run: how full the window is
+  # before each request (the server's last prompt count plus an estimate for
+  # what the turn appended since, else a chars-per-token estimate), the
+  # bucket that puts it in, and what comes of that:
+  #
+  # - the status line's value (#display), every request and again from the
+  #   server's final counts after each generation;
+  # - a :context_status stream event (#observe's return), on a bucket change
+  #   or every context.status_cadence requests;
+  # - the model's own short line (#take_guidance), once per rise into a
+  #   bucket whose guidance asks for a change (the second threshold up).
+  #
+  # The context.* settings are read once, when the tracker is built (one per
+  # run, so a changed setting counts from the next turn).
+  class ContextStatus
+    STATUS_PREFIX = "CONTEXT_STATUS"
+    # The model's own line about its context (a tail system message, kind
+    # LINE_KIND).
+    LINE_PREFIX = "[CONTEXT: "
+    LINE_KIND = "context"
+    GUIDANCE_FROM_RANK = 2
+
+    DEFAULT_CHARS_PER_TOKEN = 4.0
+    DEFAULT_THRESHOLDS = [20, 40, 60, 80].freeze
+
+    def self.enabled?
+      Config.get("context.status") != false
+    end
+
+    # Healthy to critical; the top configured bucket gets the last, the
+    # ones below it the ones before, and the first bucket (and the one
+    # under it) is always healthy.
+    GUIDANCE = [
+      "context healthy — proceed normally",
+      "context moderate — prefer targeted and range reads over full-file dumps",
+      "context elevated — be concise, prefer range reads, avoid re-reading large files",
+      "context critical — summarize aggressively, avoid large outputs, delegate broad work to subagents"
+    ].freeze
+
+    # @param bucket [String] "under<N>" or "<N>plus"
+    # @param thresholds [Array<Integer>] the configured ones, sorted
+    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS)
+      rank = bucket_rank(bucket, thresholds)
+      level = rank < GUIDANCE_FROM_RANK ? 0 : GUIDANCE.size - 1 - (thresholds.size - rank)
+      GUIDANCE[level.clamp(0, GUIDANCE.size - 1)]
+    end
+
+    # 0 for the bucket under the first threshold, then one per threshold.
+    def self.bucket_rank(bucket, thresholds)
+      return 0 if bucket.nil? || bucket.to_s.start_with?("under")
+
+      (thresholds.index(bucket.to_s.delete_suffix("plus").to_i) || -1) + 1
+    end
+
+    # The bucket of the last status line +conversation+ holds: the model's
+    # own line, or a legacy session's injected telemetry.
+    def self.last_bucket(conversation)
+      message = conversation.reverse.find do |entry|
+        content = entry[:content].to_s
+        entry[:role] == "system" && (content.start_with?(STATUS_PREFIX) || content.start_with?(LINE_PREFIX))
+      end
+      return nil unless message
+
+      match = message[:content].match(/\bbucket=([a-z0-9_]+)/)
+      match && match[1]
+    end
+
+    # @param conversation [Array<Hash>] the turn's conversation so far (its
+    #   last status line's bucket is where rises count from)
+    def initialize(conversation: [])
+      @enabled = self.class.enabled?
+      chars_per_token = Config.get("context.chars_per_token").to_f
+      @chars_per_token = chars_per_token.positive? ? chars_per_token : DEFAULT_CHARS_PER_TOKEN
+      parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
+                     .select { |value| value.between?(1, 99) }.uniq.sort
+      @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
+      @cadence = [Config.get("context.status_cadence").to_i, 0].max
+      @last_bucket = self.class.last_bucket(conversation)
+      @server_usage = nil
+      @counted = nil
+      @display = nil
+      @guidance = nil
+    end
+
+    # @return [Hash, nil] the status line's value ({est_pct:, bucket:});
+    #   nil with context.status off or before the first request
+    attr_reader :display
+
+    def enabled? = @enabled
+
+    # Before a request: estimate +prompt+'s usage against +window+ (this
+    # request's ContextWindow::Resolved) and update the status line's
+    # value. A rise into a bucket that asks the model for a change leaves
+    # a line for #take_guidance.
+    # +image_tokens+: the images' estimate (their base64 is not in +prompt+).
+    #
+    # @return [Hash, nil] the :context_status event's fields (without
+    #   :type/:iteration) when the emit gate fires, else nil
+    def observe(prompt, iteration_index:, window:, image_tokens: 0)
+      return nil unless @enabled
+
+      usage = estimate(prompt, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
+      bucket = bucket_for(usage[:estimated_pct])
+      # The status line's value, every iteration; the gate below decides
+      # only the event and the model's guidance line.
+      @display = { est_pct: usage[:estimated_pct], bucket: bucket }
+      emit = emit?(bucket: bucket, iteration_index: iteration_index)
+      previous_bucket = @last_bucket
+      @last_bucket = bucket
+      return nil unless emit
+
+      @guidance = guidance_message(usage: usage, bucket: bucket) if guidance_due?(previous_bucket, bucket)
+      { status: status_message(usage: usage, bucket: bucket), usage: usage, bucket: bucket, source: usage[:source] }
+    end
+
+    # @return [Hash, nil] the model's line from the last #observe (once)
+    def take_guidance
+      line = @guidance
+      @guidance = nil
+      line
+    end
+
+    # A stream payload's counts, kept for the next estimate.
+    # @return [Hash, nil] the payload's normalized counts, when it has any
+    def capture(payload)
+      normalized = ContextUsage.normalize(payload)
+      @server_usage = normalized if normalized
+      normalized
+    end
+
+    # After a generation: +usage+ is its own server counts (nil: none), for
+    # +prompt_chars+/+image_tokens+ as sent. The next estimate adds only
+    # what the turn appended since (answer, tool results), and the status
+    # line's value counts the answer. Without counts the pre-generation
+    # estimate stays.
+    def generation_done(usage, prompt_chars:, image_tokens:, window:)
+      return unless usage
+
+      @counted = { chars: prompt_chars, image_tokens: image_tokens }
+      value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
+      @display = value if value
+    end
+
+    # The status line's value ({est_pct:, bucket:}) for +used_tokens+ of
+    # +window_tokens+; nil without both, or with context.status off.
+    def display_for(used_tokens:, window_tokens:)
+      return nil unless @enabled
+      return nil unless ContextWindow.positive_integer?(used_tokens) && ContextWindow.positive_integer?(window_tokens)
+
+      pct = (used_tokens.to_f / window_tokens) * 100.0
+      { est_pct: pct, bucket: bucket_for(pct) }
+    end
+
+    # `window` is this request's ContextWindow::Resolved. A window the
+    # stream payload reports itself still wins.
+    # +counted+: the prompt the server's prompt_tokens counted ({chars:,
+    # image_tokens:}); what +prompt+ has on top of it (the answer, tool
+    # results since) is added as an estimate, so the value doesn't read low
+    # during a long tool loop. A prompt shorter than that one (trimmed) or
+    # none known: the server's count alone.
+    def estimate(prompt, window:, server_usage: nil, image_tokens: 0, counted: nil)
+      window_source = window.source
+      window_source = :server if server_usage && server_usage[:context_window_tokens]
+
+      if server_usage && server_usage[:prompt_tokens]
+        window_tokens = server_usage[:context_window_tokens] || window.tokens
+        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt, image_tokens, counted)
+        source = "server"
+      else
+        window_tokens = window.tokens
+        used_tokens = (prompt.length / @chars_per_token).ceil + image_tokens
+        source = "estimate"
+      end
+
+      {
+        window_tokens: window_tokens,
+        window_source: window_source,
+        estimated_used_tokens: used_tokens,
+        estimated_remaining_tokens: [window_tokens - used_tokens, 0].max,
+        estimated_pct: (used_tokens.to_f / window_tokens) * 100.0,
+        source: source
+      }
+    end
+
+    private
+
+    # The estimate for what +prompt+ added since the +counted+ one.
+    def appended_tokens(prompt, image_tokens, counted)
+      return 0 unless counted
+
+      chars = prompt.length - counted[:chars]
+      return 0 unless chars.positive?
+
+      (chars / @chars_per_token).ceil + [image_tokens - counted[:image_tokens].to_i, 0].max
+    end
+
+    def bucket_for(estimated_pct)
+      bucket = "under#{@thresholds.first}"
+      @thresholds.each do |threshold|
+        bucket = "#{threshold}plus" if estimated_pct >= threshold
+      end
+      bucket
+    end
+
+    def bucket_rank(bucket) = self.class.bucket_rank(bucket, @thresholds)
+
+    # A rise (never a fall or a cadence tick) into a bucket whose guidance
+    # asks for a change. With no previous bucket (a first turn, a resumed
+    # session with no line yet), the first bucket counts as a rise from 0.
+    def guidance_due?(previous, bucket)
+      rank = bucket_rank(bucket)
+      rank >= GUIDANCE_FROM_RANK && rank > bucket_rank(previous)
+    end
+
+    def emit?(bucket:, iteration_index:)
+      bucket_changed = if @last_bucket.nil?
+                         bucket != "under#{@thresholds.first}"
+                       else
+                         bucket != @last_bucket
+                       end
+      cadence_due = @cadence.positive? && ((iteration_index + 1) % @cadence).zero?
+      bucket_changed || cadence_due
+    end
+
+    def guidance_message(usage:, bucket:)
+      how = usage[:source].to_s == "server" ? "as the server reports" : "estimated"
+      { role: "system", kind: LINE_KIND,
+        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of the context window is in use " \
+                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds)}]" }
+    end
+
+    def status_message(usage:, bucket:)
+      format(
+        "%<prefix>s window_tokens=%<window>d window_src=%<window_src>s est_used_tokens=%<used>d est_remaining_tokens=%<remaining>d est_pct=%<pct>.1f bucket=%<bucket>s thresholds=%<thresholds>s src=%<src>s guidance=%<guidance>s",
+        prefix: STATUS_PREFIX,
+        window: usage[:window_tokens],
+        window_src: usage[:window_source] || "default",
+        used: usage[:estimated_used_tokens],
+        remaining: usage[:estimated_remaining_tokens],
+        pct: usage[:estimated_pct],
+        bucket: bucket,
+        thresholds: @thresholds.join(","),
+        src: usage[:source],
+        guidance: self.class.guidance(bucket, @thresholds)
+      )
+    end
+  end
+end

data/lib/samagotchi/desktop/macos.rb

@@ -6,6 +6,7 @@ require "fileutils"
 require "json"
 require "open3"
 require "rbconfig"
+require_relative "../atomic_file"
 require_relative "../version"
 require_relative "../self_report"
 require_relative "../installed_gem"
@@ -298,9 +299,7 @@ module Samagotchi
 
       def write_launch_file(config = launch_config)
         FileUtils.mkdir_p(@support_dir)
-        tmp = "#{launch_path}.tmp"
-        File.write(tmp, JSON.pretty_generate(config) + "\n")
-        File.rename(tmp, launch_path)
+        AtomicFile.write(launch_path, JSON.pretty_generate(config) + "\n")
       end
 
       def register_app

data/lib/samagotchi/engine.rb

@@ -71,10 +71,9 @@ module Samagotchi
     # Used by specs and inspection.
     def self.system_prompt_for(profile)
       profile = ModelProfile.normalize(profile) unless profile.is_a?(ModelProfile)
-      new(mode: :assist, profile: profile, plugins: false).assist_system_prompt
+      new(profile: profile, plugins: false).assist_system_prompt
     end
 
-    # @param mode               [Symbol] :assist (harness is single-mode; memory-reliant; kwarg kept for compat, ignored)
     # @param client             [Client, nil] defaults to Client.new
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
@@ -89,9 +88,8 @@ module Samagotchi
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
-    def initialize(mode: :assist, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
+    def initialize(client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
                    plugins: true, scratch: false)
-      @mode = mode.to_sym
       @scratch = scratch
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
@@ -128,6 +126,7 @@ module Samagotchi
         tools: -> { @tools },
         session: -> { @session },
         model_key: -> { @model_key },
+        model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
         ask: ->(fields) { open_question(fields) }
       )
@@ -430,6 +429,11 @@ module Samagotchi
     attr_reader :metrics
     attr_reader :default_model_name, :effective_model_name
 
+    # The effective model's key (ModelOverlay.key_for its bare name): memory
+    # overlays, guardrail rules' models:.
+    # @return [String, nil]
+    attr_reader :model_key
+
     # The prompt profile for the effective model (see #profile_resolution).
     # @return [ModelProfile]
     def profile = profile_resolution.profile
@@ -454,6 +458,13 @@ module Samagotchi
       @host_registry.bare_name(full_ref)
     end
 
+    # The effective model's bare name for the guardrails' models: rules;
+    # nil without a model name.
+    def guardrail_model_name
+      name = @effective_model_name && bare_model_name(@effective_model_name)
+      name.to_s.strip.empty? ? nil : name
+    end
+
     # Point the kernel (and a chat backend) at the effective model's host
     # (after /model, --model, resume).
     def sync_kernel_client!
@@ -518,7 +529,7 @@ module Samagotchi
     # The array is replaced, not mutated, and the append and the event
     # happen under the event lock, so a joining UI sees both or neither.
     # The caller saves the session.
-    # @param note [Hash] SessionManager.read_note's shape
+    # @param note [Hash] SessionInbox.read_note's shape
     # @return [Hash, nil] the message, or nil when the conversation already
     #   holds this note (a note file re-read after a crash)
     def add_context_note(session, note)
@@ -1278,7 +1289,7 @@ module Samagotchi
       return false unless ctrl && !ctrl.cancelled?
 
       hook_notify("stopped the turn: #{reason}", :warn, hook)
-      ctrl.cancel!(:hook)
+      ctrl.cancel!(:hook, { by: hook_source(hook), reason: reason.to_s })
     end
     private :hook_stop_turn
 
@@ -1645,6 +1656,7 @@ module Samagotchi
             conversation << note if conversation
           elsif canceled && conversation
             conversation << TurnNote.cancelled(result.cancellation_reason, seconds: turn_seconds.call,
+                                                                          stopped_by: effective_controller.detail,
                                                                           shown: TurnNote.interrupted_tail?(conversation),
                                                                           running_tasks: Tools::TaskRuntime.running_created_in(conversation))
             replace_session_messages(session, conversation)
@@ -1959,7 +1971,7 @@ module Samagotchi
     def load_hooks_from_bundles
       require_relative "memory_bundle/provenance"
       settings = bundle_settings
-      MemoryBundle::Provenance.each_installed_holding_hooks do |bundle_name, data|
+      MemoryBundle::Provenance.each_installed(holding: :hooks) do |bundle_name, data|
         if data[:error]
           Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{data[:error]}; its hooks are not loaded",
                                                       bundle: bundle_name)

data/lib/samagotchi/guardrail_wiring.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "digest"
 require "yaml"
 
 require_relative "config"
@@ -30,14 +29,16 @@ module Samagotchi
     # @param tools     [#call] → Tools::Registry
     # @param session   [#call] → Session, nil
     # @param model_key [#call] → String, the effective model's overlay key
+    # @param model_name [#call] → String, nil: the effective model's bare name
     # @param cancelled [#call] → Boolean, whether the running turn is cancelled
     # @param ask       [#call] (fields) → the answer; the Engine's question flow
-    def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:)
+    def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {})
       @scratch = scratch
       @hooks_lookup = hooks
       @tools_lookup = tools
       @session_lookup = session
       @model_key_lookup = model_key
+      @model_name_lookup = model_name
       @cancelled_lookup = cancelled
       @ask = ask
       @failures = Guardrails::LoadFailures.new
@@ -79,6 +80,7 @@ module Samagotchi
         -> { @hooks_lookup.call },
         context_lookup: -> { context },
         model_key_lookup: -> { @model_key_lookup.call },
+        model_name_lookup: -> { @model_name_lookup.call },
         approver: ->(verdict) { request_approval(verdict) },
         approvals_lookup: -> { @approvals },
         checks_lookup: -> { checks },
@@ -117,7 +119,7 @@ module Samagotchi
     def bundle_rules
       require_relative "memory_bundle/provenance"
       rules = []
-      MemoryBundle::Provenance.each_installed_with_guardrails do |bundle_name, data|
+      MemoryBundle::Provenance.each_installed(holding: :guardrails) do |bundle_name, data|
         if data[:error]
           Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{data[:error]}", bundle: bundle_name)
           @failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
@@ -130,9 +132,7 @@ module Samagotchi
           begin
             raise Guardrails::Rules::ParseError, "the file is missing" unless File.file?(path)
 
-            expected = (meta.is_a?(Hash) ? meta[:sha256] : nil).to_s.sub(/\Asha256:/, "")
-            actual = Digest::SHA256.hexdigest(File.binread(path))
-            if expected != actual
+            unless MemoryBundle::Provenance.sha_matches?(path, meta.is_a?(Hash) ? meta[:sha256] : nil)
               raise Guardrails::Rules::ParseError, "its sha256 differs from the installed one (edited after install? reinstall the bundle)"
             end
 

data/lib/samagotchi/guardrails/approvals.rb

@@ -3,6 +3,7 @@
 require "json"
 require "fileutils"
 require "time"
+require_relative "../atomic_file"
 require_relative "../log"
 require_relative "approval"
 
@@ -163,13 +164,7 @@ module Samagotchi
         with_lock do
           list = read(locked: true)
           yield list
-          tmp = "#{@path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-          begin
-            File.write(tmp, JSON.pretty_generate(list))
-            File.rename(tmp, @path)
-          ensure
-            FileUtils.rm_f(tmp)
-          end
+          AtomicFile.write(@path, JSON.pretty_generate(list))
         end
       end
     end

data/lib/samagotchi/guardrails/gate.rb

@@ -21,7 +21,8 @@ module Samagotchi
       #   the kernel is built.
       # @param context_lookup [#call] returns the Context for this call
       #   (the Engine's: session, interface, origin, per-turn git cache)
-      # @param model_key_lookup [#call] the model key (memory overlays)
+      # @param model_key_lookup [#call] the model key (memory overlays, rules' models:)
+      # @param model_name_lookup [#call] the bare model name (rules' models:)
       # @param approver [#call, nil] settles an ask (Engine#request_approval);
       #   without one an ask is denied
       # @param approvals_lookup [#call] returns the Approvals store (or nil)
@@ -31,12 +32,13 @@ module Samagotchi
       #   hook's stop_turn): the rest of a batch is denied without a vote
       # @param tools_lookup [#call] returns the Tools::Registry (or nil): a
       #   plugin tool's targets: say what its call acts on
-      def initialize(hooks_lookup, context_lookup: -> { Context.new }, model_key_lookup: -> {}, approver: nil,
-                     approvals_lookup: -> {}, checks_lookup: -> { [] }, cancelled_lookup: -> { false },
+      def initialize(hooks_lookup, context_lookup: -> { Context.new }, model_key_lookup: -> {}, model_name_lookup: -> {},
+                     approver: nil, approvals_lookup: -> {}, checks_lookup: -> { [] }, cancelled_lookup: -> { false },
                      tools_lookup: -> {})
         @hooks_lookup = hooks_lookup
         @context_lookup = context_lookup
         @model_key_lookup = model_key_lookup
+        @model_name_lookup = model_name_lookup
         @approver = approver
         @approvals_lookup = approvals_lookup
         @checks_lookup = checks_lookup
@@ -113,7 +115,8 @@ module Samagotchi
       end
 
       def targets_for(call, context)
-        Targets.for(call, context, model_key: @model_key_lookup.call, registry: @tools_lookup.call)
+        Targets.for(call, context, model_key: @model_key_lookup.call, model_name: @model_name_lookup.call,
+                                   registry: @tools_lookup.call)
       end
 
       # Registry#fire_each rescues a raising hook itself.

data/lib/samagotchi/guardrails/model_size.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+
+module Samagotchi
+  module Guardrails
+    # Whether the effective model is a small one, for rules with
+    # `models: small` (guardrails.small_models). Nothing reports a model's
+    # size (llama.cpp's /props has no parameter count), so `auto` reads it
+    # from the bare model name: Qwen3.6-27B → 27, gemma-4-E4B-it → 4,
+    # Ornith-1.5-35B-A3B → 3 (an MoE's active size counts), Mixtral-8x7B
+    # → 56. A name without a size, and no model at all, is not small (fail
+    # open: the rules for small models are extra asks, not the defaults).
+    module ModelSize
+      SETTING = "guardrails.small_models"
+      # The largest auto-small size, in billions of parameters.
+      MAX_SMALL = 32
+      GLOB_FLAGS = File::FNM_CASEFOLD | File::FNM_EXTGLOB
+
+      # A size starts at the name's start or after a separator, and ends at
+      # a separator or the name's end (so 4bit and v4.1 aren't sizes).
+      NUM = '(\d+(?:\.\d+)?)'
+      BEFORE = '(?:\A|[-_/:\s])'
+      AFTER = '(?=[-_:\s]|\z)'
+      ACTIVE = /#{BEFORE}a#{NUM}b#{AFTER}/i
+      EXPERTS = /#{BEFORE}(\d+)x#{NUM}b#{AFTER}/i
+      PLAIN = /#{BEFORE}e?#{NUM}b#{AFTER}/i
+
+      module_function
+
+      # The size the bare model name gives, in billions; nil without one.
+      # @return [Numeric, nil]
+      def billions(name)
+        name = name.to_s
+        if (m = name.match(ACTIVE))
+          number(m[1])
+        elsif (m = name.match(EXPERTS))
+          m[1].to_i * number(m[2])
+        elsif (m = name.match(PLAIN))
+          number(m[1])
+        end
+      end
+
+      def number(text)
+        text.include?(".") ? text.to_f : text.to_i
+      end
+
+      # @param name [String, nil] the bare model name (no host prefix)
+      # @param key [String, nil] its model key (ModelOverlay.key_for)
+      # @param setting [String, nil] guardrails.small_models: "auto", globs
+      #   on the name or the key, "|"-separated ("auto" may be one of them),
+      #   or "" (never)
+      def small?(name, key, setting = self.setting)
+        return false if name.nil? || name.to_s.strip.empty?
+
+        entries = (setting.nil? ? "auto" : setting.to_s).split("|").map(&:strip).reject(&:empty?)
+        entries.any? do |entry|
+          if entry.casecmp?("auto")
+            (size = billions(name)) ? size <= MAX_SMALL : false
+          else
+            [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate.to_s, GLOB_FLAGS) }
+          end
+        end
+      end
+
+      # How /guardrails says it: "small (auto, 27B)", "not small (auto, no
+      # size in the name)", "small (small_models: qwen*)".
+      def describe(name, key, setting = self.setting)
+        return "not small (no model name)" if name.nil? || name.to_s.strip.empty?
+
+        verdict = small?(name, key, setting) ? "small" : "not small"
+        return "#{verdict} (small_models: #{setting.empty? ? "[]" : setting})" unless setting.nil? || setting.strip.casecmp?("auto")
+
+        size = billions(name)
+        "#{verdict} (auto, #{size ? "#{size}B" : "no size in the name"})"
+      end
+
+      # The setting, live (config.yml is re-read on change); auto when it
+      # can't be read.
+      def setting
+        Config.get(SETTING)
+      rescue StandardError
+        "auto"
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/rules.rb

@@ -2,6 +2,7 @@
 
 require_relative "verdict"
 require_relative "targets"
+require_relative "model_size"
 
 module Samagotchi
   module Guardrails
@@ -13,6 +14,10 @@ module Samagotchi
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
     #            relative to the repo root, the cwd outside one)
+    #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
+    #            or a glob on the bare model name or the model key, or a
+    #            list of them: the rule only votes for a model that matches
+    #            (no model matches none; missing = every model)
     # verdict ask|deny, reason, scopes (for an ask; default all).
     # `guardrails.disable` switches single rules off (#parse_disable).
     # A rule that doesn't parse raises ParseError: the Engine then denies
@@ -21,13 +26,14 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path verdict reason scopes].freeze
+      KEYS = %w[id tool command path models verdict reason scopes].freeze
       VERDICTS = %w[ask deny].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :verdict, :reason, :scopes, :source, keyword_init: true) do
+      Rule = Struct.new(:id, :tools, :command, :path, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
+          return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
           return false if tools && !tool_matches?(targets.tool)
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
@@ -39,6 +45,21 @@ module Samagotchi
           tools.any? { |tool| Rules.glob?(tool) ? File.fnmatch(tool, name.to_s, File::FNM_EXTGLOB) : tool == name }
         end
 
+        # Whether the rule votes for this model (its models:; without one,
+        # for every model). +small+ says whether the model is a small one.
+        def for_model?(name, key, small = -> { ModelSize.small?(name, key) })
+          return true unless models
+          return false if name.nil? || name.empty?
+
+          models.any? do |entry|
+            if entry == "small"
+              small.call
+            else
+              [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate, ModelSize::GLOB_FLAGS) }
+            end
+          end
+        end
+
         def path_matches?(targets)
           return targets.outside_repo? if path == "outside_repo"
 
@@ -83,7 +104,7 @@ module Samagotchi
         end
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
-                 path: path_of(raw["path"], label), verdict: verdict.to_sym,
+                 path: path_of(raw["path"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
       end
 
@@ -114,6 +135,17 @@ module Samagotchi
         value
       end
 
+      def self.models_of(value, label)
+        return nil if value.nil?
+
+        names = Array(value)
+        unless !names.empty? && names.all? { |n| n.is_a?(String) && !n.strip.empty? }
+          raise ParseError, "#{label}: models must be small, a glob or a list of them"
+        end
+
+        names.map(&:strip)
+      end
+
       def self.scopes_of(value, label)
         return nil if value.nil?