samagotchi 0.98.0 → 0.100.0

data/docs/sub-agent.md

@@ -47,7 +47,9 @@ chi answer ID --question QID --dismiss [--timeout S] [--format json]
 
 A child with a bundle setting of its own, such as a $ cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)):
 `chi send --new --wait --format json --set cost-cap.cap=3 -m "task"`. At the cap the wait exits 3 with the cost-cap
-question; `chi answer ID --question QID --option Continue` (or `Stop`) answers it.
+question; `chi answer ID --question QID --option Continue` (or `Stop`) answers it. A cap on the child's work across
+its turns (the [work-cap bundle](plugins.md#the-work-cap-bundle)), the bound a parent that keeps answering the step
+limit's Continue doesn't otherwise have: `--set work-cap.tool_calls=400` (or `work-cap.minutes=60`, active minutes).
 
 `chi answer` waits after answering, the same way `chi send --wait` does, so the
 next question comes back as exit 3 again. What it waits for is the answered
@@ -122,7 +124,10 @@ relayed to the parent's user the way approvals are.
 
 A session at its cost cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)) waits the same way, as a
 question of kind `hook` with header "Cost cap" and options `Continue` and `Stop`: `--option Continue` raises the cap
-by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`.
+by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`. A session at its work cap (the
+[work-cap bundle](plugins.md#the-work-cap-bundle)) asks the same, header "Work cap", the question naming the
+session's totals (`Work cap reached: 412 tool calls of 400 (6 turns, 47 min active, $1.20). Continue raises it to
+800.`); `stopped_by: work-cap` on Stop.
 
 ## Approvals
 

data/docs/testing.md

@@ -219,3 +219,30 @@ each column; `--model GLOB`, `--since DATE` and `--min-steps N` filter, `--json`
 no session text (ids, model names, note names and digests, dates, numbers), and the suite runs it only on small
 synthetic sessions. It is how a note is judged on and off (`chi --mute model_notes_<name>`) for the same kind of
 task: see [memory.md](memory.md) ("Model notes").
+
+## Dependency check
+
+`bundle exec rake deps:check` says what our dependencies did since the last check; `rake "deps:check[json]"` gives
+the same as JSON. It reads only and always exits 0: it informs (a tech-debt audit round runs it first, and its NEW
+lines go into that round's follow-ups), it doesn't gate, and CI doesn't run it. Three sections:
+
+- **Engines:** each `hosts:` entry of your config.yml on a loopback or private address (an IP, `localhost`, a
+  single-label name or `.local`/`.lan`/`.internal`/`.home.arpa`; a public API is never probed) gets `/props`
+  (`build_info`: llama.cpp) and `/status` (`identity` and `chat_template`: Splash), 2 s each. A host that doesn't
+  answer prints "down, skipped"; one that is neither is left out. Each line carries the newest upstream release
+  (GitHub, no auth) with its URL, for a model to read the notes: llama.cpp's newest `b<N>` tag and how many builds
+  behind the host is, Splash's newest release.
+- **Ruby gems:** `bundle outdated --only-explicit` (direct dependencies, with the Gemfile's requirement).
+- **npm:** `npm outdated` (direct) and `npm audit`'s advisories by severity.
+
+A section that can't be read (offline, a GitHub rate limit) says why and the others go on. What a run saw goes to
+`$XDG_STATE_HOME/samagotchi/deps-check.json` (`~/.local/state/...`; `DEPS_CHECK_STATE` overrides it), outside the
+repo since the engines are this machine's; the next run prints `NEW` on each line that changed since (the first run:
+all), NEW lines first in each section.
+
+**The Splash version** isn't in Splash's `/status`, so you record it: read `splash --version` on the engine host,
+then `rake "deps:splash_version[1.3.2]"` (every Splash host) or `rake "deps:splash_version[host:port,1.3.2]"`. It is
+kept with the build id `/status` shows (`identity.cache.build_id`); when that changes, the check asks you to confirm
+the version and record it again. This step goes once a Splash release carries its version in `/status`.
+
+The code is `script/deps/deps_check.rb`; its spec stubs every request and command (`spec/deps_check_spec.rb`).

data/lib/samagotchi/bundles/core/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: core
-version: 0.3.4
+version: 0.4.0
 scope: system
 description: "Recommended safety set"
 trust_level: reviewed
-# Its members' highest floor (cost-cap's)
-requires_chi: ">= 0.92.0"
+# Its members' highest floor (work-cap's: ctx.usage, raised at the release)
+requires_chi: ">= 0.100.0"
 includes:
 - loop-guard
 - check-in
@@ -13,3 +13,4 @@ includes:
 - slow-commands
 - agents-md
 - cost-cap
+- work-cap

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.98.0
+version: 0.100.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/bundles/work-cap/manifest.yml

@@ -0,0 +1,13 @@
+---
+name: work-cap
+version: 0.1.0
+scope: system
+description: "A per-session work cap (tool calls, active minutes) across turns: at a cap the turn pauses on Continue (another cap's worth) / Stop with the session's totals, a warning at 80% goes to the user only; /workcap shows or sets it"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:d4de4b835d1657223517f3d6a5d8a9b089b7c8fad08ed077f72748369323bd65
+# ask_user's effects: are in chi 0.92.0; ctx.usage is new in the next chi
+requires_chi: ">= 0.100.0"
+# chi --set work-cap.tool_calls=400 / work-cap.minutes=60: the session's own caps, a number or off
+session_settings: {tool_calls: number, minutes: number}

data/lib/samagotchi/bundles/work-cap/plugin.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+# The work-cap bundle (docs/plugins.md, The work-cap bundle): a per-session
+# cap on the work a session does across its turns (ctx.usage: tool calls,
+# active minutes), the session-wide bound the per-turn step limit and
+# check-in don't give. Before each generation it compares the work with the
+# caps: at warn_at of a cap the user (only) gets one notice, at a cap the
+# turn pauses on a question, Continue (the cap goes up by a step) or Stop
+# (the turn stops, with a card). With no one to ask it stops. The question
+# names the session's totals, so a parent agent answering it decides on the
+# whole picture. The model never sees any of it: no tool, no steer, no
+# prompt text. cost-cap (the $ cap) is its sibling; the wordings follow it.
+#
+# Settings (config.yml, bundles: work-cap:), from ctx.settings, never at
+# load: the caps are resolved once per session (see State below), so a
+# config change reaches a running session through /workcap or a new
+# session; warn_at and ignore_tools are read at each check.
+#   tool_calls: 400   this session's own tool-call cap (session_settings:,
+#                     chi --set work-cap.tool_calls=400); 0/off: none
+#   minutes: 60       this session's own cap on active minutes, same rules
+#   child: {tool_calls: 500, minutes: 90}   delegates (ctx.delegate?) with
+#                     no own value
+#   default: {}       every other session (and a delegate without child:)
+#   warn_at: 0.8      the share of a cap that warns; 0/off: no warning
+#   ignore_tools: [task_wait, task_get, delegate, delegate_result]
+#                     tools whose calls and time aren't counted (waiting:
+#                     delegate blocks on its child by default)
+# Each meter resolves on its own: its own value, else child:'s for a
+# delegate, else default:'s. A value that doesn't read (tool_calls: many)
+# warns the user once and the next one is used, never a silent "no cap".
+#
+# What counts: ctx.usage's tool calls and active time (generations plus
+# finished tool calls, never a question's wait), less ignore_tools'.
+#
+# State: <data_dir>/sessions/<session id>.json, {"tool_calls": {"cap": 800,
+# "step": 400}, "minutes": {"cap": null}}, written by /workcap and by
+# Continue; a meter's "cap": null is off for the session, over the config;
+# a meter missing from the file comes from the settings. Resolved once per
+# session id (ctx.delegate? parses the session file) and kept until
+# /workcap or Continue writes a new one.
+require "json"
+require "fileutils"
+
+class Plugin
+  USAGE = "usage: /workcap [N | Nm | Nh | off] (N tool calls, Nm or Nh active time; /workcap alone shows the totals)"
+  OPTIONS = %w[Continue Stop].freeze
+  # For a parent agent's answer (guardrails.parent_answers): Continue
+  # spends more, Stop denies; under hard a parent may only Stop.
+  EFFECTS = { "Continue" => :spend, "Stop" => :deny }.freeze
+  WARN_AT = 0.8
+  METERS = %w[tool_calls minutes].freeze
+  DEFAULT_IGNORE = %w[task_wait task_get delegate delegate_result].freeze
+  # A cap as text: 3, 2.5, .5, 1e1, -1 (a negative is none).
+  NUMBER = /\A-?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?\z/i
+  # Minutes as text: a NUMBER, or one with m/min (minutes) or h (hours).
+  DURATION = /\A(?<number>.+?)\s*(?<unit>m|min|mins|minutes|h|hours?)?\z/i
+
+  def initialize(_settings)
+    @mutex = Mutex.new
+    @resolved = nil        # {session:, meters: {meter => {cap:, step:, key:}}, unreadable: {name => value}}
+    @warned = {}           # meter => [session id, cap] the share warning was given for
+    @unread_warned = nil   # the session id the "isn't a number" notice was given for
+  end
+
+  def register(chi)
+    chi.on(:before_generation) { |_event, ctx| check(ctx) }
+    chi.command("/workcap", "see or set this session's work cap: /workcap, /workcap 400, /workcap 90m, /workcap off",
+                anytime: true) do |args, ctx|
+      command(args, ctx)
+    end
+  end
+
+  # A cap (a positive Float) or nil (none, 0, off, false, or a value that
+  # isn't a number: .readable? tells them apart). Minutes take a unit:
+  # 90m, 1.5h.
+  def self.amount(value, meter)
+    number = number(value, meter)
+    number&.positive? ? number : nil
+  end
+
+  # +value+ as a finite Float, else nil. "5." gets its 0 first
+  # (.float_text: Ruby 3.3's Float wants one).
+  def self.number(value, meter)
+    number = case value
+             when Numeric then value.to_f
+             when String then text_number(value.strip, meter)
+             end
+    number if number&.finite?
+  end
+
+  def self.text_number(text, meter)
+    return Float(float_text(text)) if text.match?(NUMBER)
+    return nil unless meter == "minutes" && (match = DURATION.match(text)) && match[:unit]
+    return nil unless match[:number].match?(NUMBER)
+
+    Float(float_text(match[:number])) * (match[:unit].downcase.start_with?("h") ? 60 : 1)
+  end
+
+  # A NUMBER as Float reads it on every Ruby: a bare point ("5.", "5.e1")
+  # gets a 0 after it.
+  def self.float_text(text) = text.sub(/\.(?=e|\z)/i, ".0")
+
+  # Whether +value+ reads as a cap or as none: a number (text too), off,
+  # false or nil; not "many", true or a list.
+  def self.readable?(value, meter)
+    case value
+    when false, nil then true
+    when Numeric then value.finite?
+    when String then value.strip.casecmp?("off") || !number(value, meter).nil?
+    else false
+    end
+  end
+
+  # 400, 2.5: a whole number without its ".0".
+  def self.count(value)
+    rounded = value.round(1)
+    rounded == rounded.to_i ? rounded.to_i.to_s : rounded.to_s
+  end
+
+  private
+
+  def check(ctx)
+    resolved = resolve(ctx)
+    unreadable(ctx, resolved)
+    capped = resolved[:meters].select { |_meter, meter_cap| meter_cap[:cap] }
+    return if capped.empty?
+
+    usage = ctx.usage
+    used = used(ctx, usage)
+    reached = capped.select { |meter, meter_cap| used[meter] >= meter_cap[:cap] }
+    return at_cap(ctx, resolved, reached, usage, used) unless reached.empty?
+
+    share = warn_share(ctx)
+    return unless share
+
+    capped.each do |meter, meter_cap|
+      cap = meter_cap[:cap]
+      next unless used[meter] >= share * cap && first_warning?(meter, [resolved[:session], cap])
+
+      ctx.notify("#{count(used[meter])} of #{count(cap)} #{unit(meter)} (#{(used[meter] / cap * 100).floor}%)",
+                 level: :warn)
+    end
+  end
+
+  # The counted work per meter: tool calls and active minutes, less the
+  # ignored tools' share.
+  def used(ctx, usage)
+    ignored = ignore_tools(ctx)
+    calls = usage.tool_calls - ignored.sum { |tool| usage.tool_calls_by_tool.fetch(tool, 0) }
+    active_ms = usage.active_ms - ignored.sum { |tool| usage.tool_ms_by_tool.fetch(tool, 0) }
+    { "tool_calls" => [calls, 0].max.to_f, "minutes" => [active_ms, 0].max / 60_000.0 }
+  end
+
+  # Once per session: the settings whose cap didn't read, and what is used.
+  def unreadable(ctx, resolved)
+    bad = resolved[:unreadable]
+    return if bad.empty? || !first_time?(:@unread_warned, resolved[:session])
+
+    named = bad.map { |key, value| "#{key}: #{value.inspect}" }.join(" and ")
+    used = resolved[:meters].values.filter_map do |meter_cap|
+      "#{meter_cap[:key]}: (#{count(meter_cap[:cap])})" if meter_cap[:cap]
+    end
+    using = used.empty? ? "no cap" : "using #{used.join(", ")}"
+    ctx.notify("work-cap: #{named} #{bad.size == 1 ? "isn't" : "aren't"} a number or off; #{using}", level: :warn)
+  end
+
+  def at_cap(ctx, resolved, reached, usage, used)
+    raised = reached.to_h do |meter, meter_cap|
+      [meter, raised_cap(meter_cap[:cap], meter_cap[:step] || meter_cap[:cap], used[meter])]
+    end
+    answer = ctx.ask_user(question: "Work cap reached: #{reached_text(reached, used)} (#{totals(ctx, usage, used, reached.keys)}). " \
+                                    "Continue raises #{raised_text(raised)}.",
+                          header: "Work cap", options: OPTIONS, effects: EFFECTS)
+    if continue?(answer)
+      raised.each do |meter, cap|
+        save_meter(ctx, resolved[:session], meter, "cap" => cap, "step" => reached[meter][:step] || reached[meter][:cap])
+      end
+      ctx.notify("#{raised.size == 1 ? "cap" : "caps"} raised to " \
+                 "#{raised.map { |meter, cap| "#{count(cap)} #{unit(meter)}" }.join(" and ")}")
+    else
+      stop(ctx, reached, usage, used)
+    end
+  end
+
+  # "412 tool calls of 400", and "61 active minutes of 60" for the other.
+  def reached_text(reached, used)
+    reached.map { |meter, meter_cap| "#{count(used[meter])} #{unit(meter)} of #{count(meter_cap[:cap])}" }.join(", ")
+  end
+
+  # "it to 800", or "them to 800 tool calls and 120 active minutes".
+  def raised_text(raised)
+    return "it to #{count(raised.values.first)}" if raised.size == 1
+
+    "them to #{raised.map { |meter, cap| "#{count(cap)} #{unit(meter)}" }.join(" and ")}"
+  end
+
+  # The session's totals a reader decides on, the reached meters left out
+  # (already named): turns, tool calls, active minutes and the spend.
+  def totals(ctx, usage, used, skip = [])
+    parts = ["#{usage.turns} #{usage.turns == 1 ? "turn" : "turns"}"]
+    parts << "#{count(used["tool_calls"])} tool calls" unless skip.include?("tool_calls")
+    parts << "#{active_text(used["minutes"])} active" unless skip.include?("minutes")
+    cost = ctx.cost
+    parts << format("$%.2f", cost.total) if cost.known? && cost.total.positive?
+    parts.join(", ")
+  end
+
+  # "47 min", or "<1 min" before a whole minute of work.
+  def active_text(minutes) = minutes < 1 ? "<1 min" : "#{count(minutes.floor)} min"
+
+  # Another step on the cap, as many steps as it takes to pass the work
+  # (a turn that overshot by more than a step asks once, not each step):
+  # Continue always leaves the cap past the work now.
+  def raised_cap(cap, step, used)
+    raised = cap + step
+    raised += step while raised <= used
+    raised.round(6)
+  end
+
+  def continue?(answer)
+    return false unless answer
+
+    Array(answer[:selected]).first == "Continue" || Array(answer[:selected_indices]).first&.zero?
+  end
+
+  def stop(ctx, reached, usage, used)
+    return unless ctx.stop_turn("work cap reached (#{reached_text(reached, used)})")
+
+    ctx.card(title: "work-cap stopped the turn",
+             body: "Used #{reached_text(reached, used)} (#{totals(ctx, usage, used, reached.keys)}).\n\n" \
+                   "`/workcap N` raises the tool-call cap, `/workcap Nm` the active minutes, `/workcap off` removes both.",
+             level: :warn)
+  end
+
+  def command(args, ctx)
+    arg = args.to_s.strip.downcase
+    return show(ctx) if arg.empty?
+
+    session = ctx.session_id
+    return "work-cap: no session yet" unless session
+
+    if %w[off 0].include?(arg)
+      METERS.each { |meter| save_meter(ctx, session, meter, "cap" => nil) }
+      return "work-cap: no cap for this session"
+    end
+    meter = arg.match?(NUMBER) ? "tool_calls" : "minutes"
+    value = self.class.amount(arg, meter)
+    return USAGE unless value
+
+    save_meter(ctx, session, meter, "cap" => value, "step" => value)
+    "work-cap: #{unit(meter)} cap set to #{count(value)} (#{count(used(ctx, ctx.usage)[meter])} so far)"
+  rescue StandardError => e
+    ctx.log.warn(:workcap_command_failed, error: "#{e.class}: #{e.message}")
+    "work-cap: #{e.message}"
+  end
+
+  def show(ctx)
+    usage = ctx.usage
+    used = used(ctx, usage)
+    meters = resolve(ctx)[:meters]
+    return "work-cap: no cap (#{totals(ctx, usage, used)})" if meters.values.none? { |meter_cap| meter_cap[:cap] }
+
+    capped = meters.select { |_meter, meter_cap| meter_cap[:cap] }
+    caps = capped.map { |meter, meter_cap| "#{count(used[meter])} of #{count(meter_cap[:cap])} #{unit(meter)}" }
+    "work-cap: #{caps.join(", ")} (#{totals(ctx, usage, used, capped.keys)})"
+  end
+
+  def unit(meter) = meter == "tool_calls" ? "tool calls" : "active minutes"
+
+  # The session's caps now: per meter the state file's, else the session's
+  # own value (--set), else child:'s for a delegate, else default:'s.
+  # Cached per session id.
+  def resolve(ctx)
+    session = ctx.session_id
+    cached = @mutex.synchronize { @resolved }
+    return cached if cached && cached[:session] == session
+
+    saved = state(ctx, session)
+    configured = configured(ctx)
+    meters = METERS.to_h { |meter| [meter, saved[meter] || configured[:meters][meter]] }
+    resolved = { session: session, meters: meters, unreadable: configured[:unreadable] }
+    @mutex.synchronize { @resolved = resolved }
+  end
+
+  # The state file's meters ({meter => {cap:, step:}}), {} without one.
+  def state(ctx, session)
+    return {} unless session
+
+    saved = JSON.parse(File.read(state_path(ctx, session)))
+    return {} unless saved.is_a?(Hash)
+
+    METERS.each_with_object({}) do |meter, meters|
+      entry = saved[meter]
+      next unless entry.is_a?(Hash) && entry.key?("cap")
+
+      cap = self.class.amount(entry["cap"], meter)
+      meters[meter] = { cap: cap, step: self.class.amount(entry["step"], meter) || cap, key: "/workcap" }
+    end
+  rescue Errno::ENOENT, JSON::ParserError
+    {}
+  end
+
+  # Per meter the first of its own value, child:'s (a delegate's) and
+  # default:'s that is set and reads (.readable?); the ones set that don't
+  # read (and a child:/default: that isn't a mapping) are kept for the
+  # notice (#unreadable).
+  def configured(ctx)
+    settings = ctx.settings
+    unreadable = {}
+    groups = %w[child default].select { |group| settings.key?(group) }
+    groups.delete("child") if groups.include?("child") && !ctx.delegate?
+    groups = groups.select do |group|
+      next true if settings[group].is_a?(Hash)
+
+      unreadable[group] = settings[group] unless settings[group].nil?
+      false
+    end
+    meters = METERS.to_h do |meter|
+      sources = [[meter, settings, meter]] + groups.map { |group| ["#{group}.#{meter}", settings[group], meter] }
+      [meter, first_readable(sources, unreadable)]
+    end
+    { meters: meters, unreadable: unreadable }
+  end
+
+  def first_readable(sources, unreadable)
+    sources.each do |name, values, meter|
+      next unless values.key?(meter)
+
+      value = values[meter]
+      unless self.class.readable?(value, meter)
+        unreadable[name] = value
+        next
+      end
+      cap = self.class.amount(value, meter)
+      return { cap: cap, step: cap, key: name }
+    end
+    { cap: nil, step: nil, key: nil }
+  end
+
+  def ignore_tools(ctx)
+    settings = ctx.settings
+    settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
+  end
+
+  def warn_share(ctx)
+    settings = ctx.settings
+    return WARN_AT unless settings.key?("warn_at")
+
+    share = settings["warn_at"]
+    share.is_a?(Numeric) && share.positive? ? share : nil
+  end
+
+  # Write one meter's cap into the session's state file (the other kept).
+  def save_meter(ctx, session, meter, data)
+    path = state_path(ctx, session)
+    FileUtils.mkdir_p(File.dirname(path))
+    saved = begin
+      JSON.parse(File.read(path))
+    rescue Errno::ENOENT, JSON::ParserError
+      {}
+    end
+    saved = {} unless saved.is_a?(Hash)
+    saved[meter] = data
+    Samagotchi::AtomicFile.write(path, "#{JSON.generate(saved)}\n")
+    # Resolved again at the next use, from the file now holding the meter.
+    @mutex.synchronize { @resolved = nil }
+  end
+
+  def state_path(ctx, session) = File.join(ctx.data_dir, "sessions", "#{session.gsub(/[^A-Za-z0-9_.-]/, "_")}.json")
+
+  def count(value) = self.class.count(value)
+
+  def first_warning?(meter, key)
+    @mutex.synchronize do
+      next false if @warned[meter] == key
+
+      @warned[meter] = key
+      true
+    end
+  end
+
+  # Whether +key+ is new for the once-only notice kept in +ivar+ (and keep it).
+  def first_time?(ivar, key)
+    @mutex.synchronize do
+      next false if instance_variable_get(ivar) == key
+
+      instance_variable_set(ivar, key)
+      true
+    end
+  end
+end

data/lib/samagotchi/engine.rb

@@ -39,6 +39,7 @@ require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
 require_relative "toolkit_binding"
+require_relative "tool_loads"
 require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
@@ -277,6 +278,9 @@ module Samagotchi
       # The tools plugins publish without declaring (chi.tool_source), and
       # the search and call tools that reach them (Tools::ToolIndex).
       @tool_index = Tools::ToolIndex.new
+      # The tools plugins load (ctx.load_tools), staged until a turn's
+      # messages are built (#append_tool_loads).
+      @tool_loads = ToolLoads.new
       # The context sources the peer bundles declare as a peer agent's
       # answers (chi.peer_source); the worker's ContextAbsorber asks it.
       @peer_sources = PeerSources.new
@@ -2115,12 +2119,13 @@ module Samagotchi
         })
       end
 
-      return if turn.continue
-
-      user_message = { role: "user", content: turn.prompt, turn_id: turn.id }
-      user_message[:images] = image_refs unless image_refs.empty?
-      turn.messages << user_message
-      session.last_prompt = turn.prompt
+      unless turn.continue
+        user_message = { role: "user", content: turn.prompt, turn_id: turn.id }
+        user_message[:images] = image_refs unless image_refs.empty?
+        turn.messages << user_message
+        session.last_prompt = turn.prompt
+      end
+      append_tool_loads(turn)
     end
     private :turn_messages
 
@@ -2137,8 +2142,13 @@ module Samagotchi
       # through the kernel without its #run: tag those dumps with this
       # turn's model, not the last native one.
       explained = model.llm_context_explained(@model_settings.llm_context_session_args)
+      model_backend = backend(model)
+      # A host that loads tools runs a direct call of one the session
+      # reaches but doesn't declare (ToolRunner, KernelLoop#dispatch).
+      loads_tools = model_backend.respond_to?(:loads_tools?) && model_backend.loads_tools?(bare_for_backend)
       @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
-                                                 llm_context: explained&.resolved, price: model.price)
+                                                 llm_context: explained&.resolved, price: model.price,
+                                                 loads_tools: loads_tools)
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
@@ -2146,7 +2156,7 @@ module Samagotchi
       # end keeps it, so a Continue resumes this run.
       run_start = turn.messages.length
       reasoning_since = resumed_run_start(turn, run_start)
-      result = backend(model).complete(
+      result = model_backend.complete(
         messages: turn.messages,
         max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller,
@@ -2555,6 +2565,52 @@ module Samagotchi
 
     public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
 
+    # A plugin's ctx.load_tools: stage the reachable tools +names+ names
+    # (Tools::ToolIndex#deferred_name) that the session neither declares
+    # nor loaded with an earlier tool change, for bundle +bundle+. A name
+    # that names no tool at all is logged; a declared or removed one is
+    # skipped quietly.
+    # @return [Array<String>] the wire names staged
+    def load_tools(names, bundle)
+      added = ToolLoads.added(@session&.messages)
+      wanted = names.filter_map do |name|
+        wire = @tool_index.deferred_name(name)
+        Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || @tools.key?(name)
+        wire
+      end
+      @tool_loads.stage(wanted - added, by: bundle)
+    end
+    public :load_tools
+
+    # The staged tool loads, appended to +turn+'s messages (after its user
+    # message, or the trailing results and notes of a turn with none) as
+    # one ToolLoads entry per bundle, when the turn's host takes tool
+    # changes (ChatLoop#tool_changes?). Elsewhere they are dropped, logged.
+    # A conversation that ends with a reply keeps them staged (a system
+    # change must follow a user turn).
+    def append_tool_loads(turn)
+      return unless @tool_loads.any?
+      return if turn.messages.last&.dig(:role).to_s == "model"
+
+      model = effective_model
+      host = backend(model)
+      staged = @tool_loads.take
+      added = ToolLoads.added(turn.messages)
+      unless host.respond_to?(:tool_changes?) && host.tool_changes?(bare_model_name(model.name))
+        Log.info(:plugins, "tool_loads_not_sent", tools: staged.values.flatten.join(","), model: model.name.to_s)
+        return
+      end
+
+      staged.each do |bundle, names|
+        names -= added
+        next if names.empty?
+
+        turn.messages << ToolLoads.entry(names, by: bundle)
+        hook_notify("tools loaded: #{names.join(", ")}", :info, bundle)
+      end
+    end
+    private :append_tool_loads
+
     # A plugin's ctx.use_toolkit (ToolkitBinding#use).
     # @return [Boolean] whether it was staged
     # @raise [ArgumentError] an unknown toolkit
@@ -2608,6 +2664,7 @@ module Samagotchi
         toolkit: -> { @toolkit_binding.name },
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
+        load_tools: ->(names, bundle) { load_tools(names, bundle) },
         cancel_controller: ->(handler: false) { plugin_cancel_controller(handler: handler) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
@@ -2623,7 +2680,8 @@ module Samagotchi
         # returns [] itself: the || keeps a nil builder safe).
         prompt_files: -> { @prompt_builder&.prompt_files || [] },
         frontend: -> { interface },
-        cost: -> { @metrics.cost }
+        cost: -> { @metrics.cost },
+        usage: -> { @metrics.usage }
       )
     end
 

data/lib/samagotchi/hooks/loader.rb

@@ -52,15 +52,21 @@ module Samagotchi
 
         # Load hooks from a config hash and return a Registry with registered plugins.
         #
-        # @param config_hash [Hash, nil] the hooks section from config.yml
+        # @param config_hash [Hash, nil] the parsed config.yml
         # @param env [Hash] environment variables (default: ENV)
         # @param failures [Guardrails::LoadFailures, nil] collects hooks that
         #   failed to load
         # @return [Samagotchi::Hooks::Registry] the registry with all plugins registered
         def load(config_hash, env: ENV, failures: nil)
-          return Hooks::Registry.new unless config_hash&.key?("hooks")
+          hooks_config = config_hash["hooks"] if config_hash.is_a?(Hash)
+          # An empty `hooks:` key is nil in YAML: no hooks, like no key.
+          return Hooks::Registry.new if hooks_config.nil?
+
+          unless hooks_config.is_a?(Hash)
+            Log.warn(:hooks, "hooks_section_invalid", echo: "[samagotchi:hooks] config.yml hooks: must be a mapping of event name to hook entries; ignored")
+            return Hooks::Registry.new
+          end
 
-          hooks_config = config_hash["hooks"]
           hooks_dir = hooks_dir(env, data: config_hash)
 
           registry = Hooks::Registry.new
@@ -92,10 +98,17 @@ module Samagotchi
 
       # Parse hook definitions from the config hooks section.
       # Returns an array of { event_type:, path:, on_error: } hashes.
+      # An event key that holds something other than a list warns and is
+      # skipped; an empty one (nil) is skipped silently.
       def self.parse_definitions(hooks_config)
         definitions = []
         hooks_config.each do |event_type, configs|
-          next unless event_type.to_s != "hooks_dir" && configs.is_a?(Array)
+          next if event_type.to_s == "hooks_dir" || configs.nil?
+
+          unless configs.is_a?(Array)
+            Log.warn(:hooks, "hooks_event_invalid", echo: "[samagotchi:hooks] config.yml hooks.#{event_type}: must be a list of hook entries; ignored", event: event_type.to_s)
+            next
+          end
 
           configs.each do |cfg|
             next unless cfg.is_a?(Hash) && cfg["path"]