samagotchi 0.97.0 → 0.99.0

data/docs/plugins.md

@@ -433,7 +433,9 @@ This is a bundle hook, the same as a `hooks/*.rb` file. See
 [hooks.md](hooks.md#hook-events) for the events; on `:after_turn`,
 `event[:present]` sets how the answer is shown in the web
 ([Presenting the answer](hooks.md#presenting-the-answer-display-only)) and `event[:refs]`
-attaches refs to it ([Refs on the answer](hooks.md#refs-on-the-answer-display-only)). Its label is
+attaches refs to it ([Refs on the answer](hooks.md#refs-on-the-answer-display-only)); on
+`:question_asked`, `event[:refs]` attaches refs to the reply that asks a question
+([Refs on a question](hooks.md#refs-on-a-question-display-only)). Its label is
 `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
 raises, the error is logged and the hook is skipped.
 
@@ -629,6 +631,17 @@ and after a reload. `tool: call_tool` rules see MCP calls and misses only. A
 `call_tool` itself is removed, is refused by its name before the guardrails
 (no hook, no card).
 
+**On a Messages host the model calls them by name too.** With `api:
+anthropic` (not Fireworks' dialect), every tool `call_tool` reaches goes in
+the request's tools deferred (`defer_loading`: its name only, until
+something loads it): a built-in by its name, a source's tool by its
+`acts_as` (`mcp_fs_read`; one with a refusal, an acts_as two tools share, or
+a name another tool has stays out). A direct call of one runs whether
+anything loaded it or not: a built-in as itself (as if declared), a
+source's tool as the `call_tool` call it stands for, so its rules,
+approvals, hooks and row are `call_tool`'s. Elsewhere such a call is
+refused with the `call_tool` route, as before.
+
 ```ruby
 @source = chi.tool_source(label: "mcp", prefix: "mcp_",
                           call: ->(tool, args, ctx) { run(tool, args, ctx) },  # the result, as a tool block's
@@ -757,6 +770,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.toolkit` | the name of the session's toolkit (`full` for a session from before toolkits); nil with no session |
 | `ctx.declared_tools` | the tool names the session's next turn declares (its toolkit resolved, with its own adds and removes): ask this, not the name, whether a tool is there |
 | `ctx.use_toolkit(name)` | put the session on toolkit `name` (yours from `chi.toolkit`, or chi's): saved, applied at the next turn's start and announced (`toolkit> toolkit: NAME from the next turn's start`, the web's tools chip follows). Only before the session's first model reply and outside a turn (the declared tools start every request, and a plugin doesn't ask first); otherwise it returns false and changes nothing: tell the user to run `/toolkit NAME`. An unknown name raises ArgumentError. Needs chi 0.66.0 |
+| `ctx.load_tools(names)` | load tools the session reaches but doesn't declare, so the model calls them by name: built-ins (`"delegate"`, `"chi/delegate"`), MCP tools (`"mcp_fs_read"`, `"fs/read"`). Returns the names it staged (the wire names); a declared tool, one loaded before, a removed or unknown one is skipped (an unknown one logged), so calling it every turn is fine. From a `before_turn` hook it loads for that turn; anywhere else (mid-turn too) from the next turn's start. Call it from a hook: before the session's first turn its toolkit isn't applied yet and nothing resolves. **A hint, not access**: the tools keep their guardrails and approvals, and only a host that takes tool changes (`api: anthropic`, not Fireworks) gets one, as a system message after the user's (`[tools loaded: delegate (your-bundle)]` in the session, a notice line live); elsewhere nothing is sent or saved, and the tools stay reachable with `call_tool`. A hook may switch the model after you call it, so the return value can't promise delivery. Raises ArgumentError for anything but an Array. Needs chi 0.99.0 |
 | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
 
 The Engine itself is never handed to a plugin.
@@ -1159,6 +1173,7 @@ require "samagotchi/testing"
 bundle = Samagotchi::Testing::Bundle.load("path/to/my-bundle", settings: { "every" => 3 },
                                           host: { session_id: "s1", cwd: Dir.pwd })
 bundle.fire(:after_turn, status: "completed")            # → the event, after the hooks
+bundle.question_asked("Fix JIRA-1?", question: { question: "Go?" })   # → the refs, as chi's seams fire it
 event = bundle.before_tool_call_event({ name: "read", path: "a.txt" }, params: "read a.txt")
 bundle.command("/mine stop")                             # → what the command returned
 bundle.tool("my_tool", path: "a.txt")                    # → the text the model reads
@@ -1173,6 +1188,7 @@ bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe"
 bundle.set(running: false)                               # the session's values: cwd:, messages:, cancelled: …
 bundle.set(cost: 2.5)                                    # ctx.cost: reported USD, or { reported:, estimated:, side:, known: }
 bundle.set(session_settings: { "cap" => 1 })             # the session's --set values (Bundle.load takes session_settings: too)
+bundle.tool_loads.last.names                             # ctx.load_tools calls; set(load_tools_staged: [...]) limits what they stage
 bundle.shutdown
 ```
 
@@ -1212,6 +1228,10 @@ bundle.shutdown
   lays them over `settings:` through chi's own `Context#settings`; the plugin's `initialize(settings)` gets
   `settings:` only. `bundle.set(session_settings:)` moves the session to a new id (`test-session-2`, or the
   `session_id:` given beside it): chi never changes them within a session, and builds `ctx.settings` once per id.
+- **`question_asked(text, kind: "question", question: {}, cwd: nil)`** fires `:question_asked` through
+  `QuestionAsked.fire`, as chi's two seams do: a step whose text is `text` asks a question (or `kind: "approval"`)
+  with the `question` fields, and the refs the hooks attach come back checked (the question caps, a file ref under
+  `cwd:`, default the session's folder), as the step and its pending question keep them; `[]` for none.
 - **A hook that raises fails the call** (`Testing::HookFailed`, with the hook's error) where chi would log it and
   go on; `bundle.lenient { … }` collects them in `bundle.errors` instead.
 - **Sandbox.** A test runs with temp config, state, data and cache homes (config.yml, memories, `ctx.data_dir`, the
@@ -1269,7 +1289,9 @@ by one: the bundle publishes them into chi's tool index
 ([chi.tool_source](#chitool_sourcecall-acts_as-label-wait-prefix), a group
 per server), and the model has its two tools, `find_tools` and `call_tool` (~250 tokens in
 every request plus a line per server, whatever the servers have; `/mcp`
-says how many). Stdio servers only, for now.
+says how many). On `api: anthropic` each tool also goes out deferred as
+`mcp_<server>_<tool>`, so a `find_tools` hit loads it and the model calls it
+by that name, as `call_tool` would run it. Stdio servers only, for now.
 
 ```yaml
 # config.yml

data/docs/sessions.md

@@ -221,7 +221,7 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 
 A session is named by its first message until you give it a title: `/title Coordinator` (in the REPL, an attached terminal, the web composer or `chi send -m "/title Coordinator" ID`; a parent agent may name its delegates the same way). The title is saved in the session file (`title`), whitespace collapsed and cut at 80 characters, and runs mid-turn too, at once. `/title` alone shows it (`title: none (shows the first message: hey chi …)` without one); `/title --clear` drops it, and the first message names the session again. A session whose first line was the command itself (`chi send --new -m "/title X"`) takes its preview from its first real message.
 
-The title names the session wherever its first message did: `chi sessions list` (plain, `--live`, tsv and json's `desc`, before the recap; json has `title` too), `chi sessions delete`'s line, the `list_sessions` tool, `chi broadcast`, the desktop helper, a parent's children (the coordinator bundle's `/children` card, `ctx.sessions.children`; `ctx.sessions.read` too), and in the web the cards, the families and chain rows, the top bar and the browser tab, the notifications and the search; the terminal's status row too (the REPL's and an attached one's, first, see [Status Line](cli.md#status-line)). The web's info bar has `✎` (Rename this session): a small input prefilled with the title; Enter or a click elsewhere sends `/title TEXT` when it changed (empty: `/title --clear`), Esc closes it unsent. A session a chi REPL owns has no `✎`. A continue's new link keeps the title (see [Session chains](#session-chains)). An older `chi web` (or any chi from before the field) that saves a session drops its title: restart `chi web` after upgrading.
+The title names the session wherever its first message did: `chi sessions list` (plain, `--live`, tsv and json's `desc`, before the recap; json has `title` too), `chi sessions delete`'s line, the `list_sessions` tool, `chi broadcast`, the desktop helper, a parent's children (the coordinator bundle's `/children` card, `ctx.sessions.children`; `ctx.sessions.read` too), and in the web the cards, the families and chain rows, the top bar and the browser tab, the notifications and the search; the terminal's status row too (the REPL's and an attached one's, first, see [Status Line](cli.md#status-line)). In the web, `✎` (Rename this session) sits next to the session's title, on its active strip card or after the top bar's title: a small input over the title, prefilled with it; Enter or a click elsewhere sends `/title TEXT` when it changed (empty: `/title --clear`), Esc closes it unsent, and so does the title leaving the screen (All sessions opened, the card swiped out of a phone's strip). A session a chi REPL owns has no `✎`, nor one that shows no title yet (`/title` still works from the composer). A continue's new link keeps the title (see [Session chains](#session-chains)). An older `chi web` (or any chi from before the field) that saves a session drops its title: restart `chi web` after upgrading.
 
 ## Session chains
 
@@ -253,6 +253,16 @@ declares every tool (full). The file stores only the name: a kit's tools and pro
 `/toolkit` changes it, saved at once, from the next turn's start. See
 [Toolkits](configuration.md#toolkits).
 
+A `find_tools` result on a chat host saves the tools its hit loads as `loaded: ["list_sessions", "mcp_fs_read"]` on
+its `tool_response` entry (wire names: a built-in's, an MCP tool's `mcp_<server>_<tool>`), whatever the host: a
+later turn on `api: anthropic` (after a `/model` switch, a resume) sends the load as references, any other host
+ignores it. The names stay deferred for the session's life, across respawns, `--resume` and forks.
+
+A plugin's `ctx.load_tools` leaves a system entry `{"role": "system", "kind": "tool_change", "content": "[tools loaded:
+delegate (bundle)]", "tool_change": {"add": ["delegate"], "by": "bundle"}}` after the turn's user message, only on a
+host that takes tool changes (`api: anthropic`). It is never the system head, counts as conversation, is hidden in
+the web and TUI histories, and goes to no other wire; its names stay deferred for the session's life like a load's.
+
 ## Parent answers
 
 A session file's `parent_answers` (`hard`, `standard`, `soft`, or `null` for none) is the session's own

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/answer_refs.rb

@@ -52,7 +52,9 @@ module Samagotchi
   #
   # The target is AnswerDisplay's: the stored conversation's last message
   # when it is the model's. The list starts from the refs it already has
-  # (re-validated), so a later hook run never loses them.
+  # (re-validated), so a later hook run never loses them. QuestionAsked
+  # uses it too, on the step that asks a question (+messages+ that one
+  # step, lower caps).
   class AnswerRefs
     KEY = :display_refs
     MAX_REFS = 200
@@ -63,12 +65,13 @@ module Samagotchi
     # rebuilt and checked again, the caps applied; what isn't valid any
     # more is dropped. Never raises: a reload must show the conversation.
     # A relative file path is dropped (it was stored absolute), and with
-    # +cwd+ (the session's folder) a file outside it.
+    # +cwd+ (the session's folder) a file outside it. +max_refs+ and
+    # +max_bytes+: the caps (a question's are lower, QuestionAsked).
     # @return [Array<Hash>] the refs to send ({match:, kind:, target:, …})
-    def self.for_display(raw, cwd: nil)
+    def self.for_display(raw, cwd: nil, max_refs: MAX_REFS, max_bytes: MAX_BYTES)
       return [] if raw.nil?
 
-      kept = new([{ role: "model", KEY => raw }], cwd: cwd).to_a
+      kept = new([{ role: "model", KEY => raw }], cwd: cwd, max_refs: max_refs, max_bytes: max_bytes).to_a
       dropped = raw.is_a?(Array) ? raw.length - kept.length : 1
       Log.debug(:web, "display_refs_dropped", count: dropped) if dropped.positive?
       kept
@@ -81,10 +84,14 @@ module Samagotchi
 
     # @param messages [Array<Hash>] the conversation the turn stored
     # @param cwd [String, nil] the session's folder, for relative file paths
-    def initialize(messages, cwd:)
+    # @param max_refs [Integer] the list's cap in refs
+    # @param max_bytes [Integer] the list's cap in JSON bytes
+    def initialize(messages, cwd:, max_refs: MAX_REFS, max_bytes: MAX_BYTES)
       last = Array(messages).last
       @target = last if last.is_a?(Hash) && (last[:role] || last["role"]).to_s == "model"
       @roots = RowRefs.roots(cwd)
+      @max_refs = max_refs
+      @max_bytes = max_bytes
       @refs = []
       @seen = {}
       @bytes = 2 # the list's []
@@ -143,10 +150,10 @@ module Samagotchi
 
       entry = AnswerRef.from(value, roots: @roots).to_h
       return true if @seen.key?(entry)
-      return over_cap(hook, "#{MAX_REFS} refs") if @refs.length >= MAX_REFS
+      return over_cap(hook, "#{@max_refs} refs") if @refs.length >= @max_refs
 
       size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
-      return over_cap(hook, "#{MAX_BYTES / 1024} KiB") if @bytes + size > MAX_BYTES
+      return over_cap(hook, "#{@max_bytes / 1024} KiB") if @bytes + size > @max_bytes
 
       push(entry, size)
       @added = true
@@ -160,10 +167,10 @@ module Samagotchi
     # @return [Boolean] kept
     def keep(raw)
       entry = AnswerRef.from(raw, roots: @roots, relative: false).to_h
-      return false if @seen.key?(entry) || @refs.length >= MAX_REFS
+      return false if @seen.key?(entry) || @refs.length >= @max_refs
 
       size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
-      return false if @bytes + size > MAX_BYTES
+      return false if @bytes + size > @max_bytes
 
       push(entry, size)
       true

data/lib/samagotchi/bundle_command.rb

@@ -476,7 +476,7 @@ module Samagotchi
           hooks.each do |hk, hook|
             hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk)
             exists = File.exist?(hook_path) ? "ok" : "missing"
-            @stdout.puts "    #{hk}: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
+            @stdout.puts "    #{hk}: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
           end
           @stdout.puts "    requires_chi: #{st[:provenance].requires_chi}" if st[:hooks_requires_failure]
           @stdout.puts "    not loaded: #{st[:hooks_requires_failure]}" if st[:hooks_requires_failure]
@@ -658,7 +658,7 @@ module Samagotchi
     end
 
     def hook_metadata_line(hook)
-      "--- metadata: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
+      "--- metadata: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
     end
 
     def build(rest)

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.0
+version: 0.7.1
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.72.0"
+requires_chi: ">= 0.98.0"
 includes:
 - known-names
 - mcp

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -4,8 +4,8 @@
 require "open3"
 require "samagotchi/ref"
 
-# An after_turn hook that links the source refs the model's answer
-# mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
+# An after_turn (and question_asked) hook that links the source refs the
+# model's answer mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
 # through event[:present]: display only, the model's text stays as it was,
 # and it survives a reload). Every UI also gets one line right after the
@@ -58,6 +58,14 @@ require "samagotchi/ref"
 # action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
 # markdown link only. The web's ref menu shows the action.
 #
+# The hook is on :question_asked too (the manifest's events:, chi newer than
+# 0.97.0): while a question of the model's (or an approval of its call)
+# waits, the refs in the reply that asks it, and in the question's text and
+# options, are refs on that reply, the same as an answer's. The web pairs
+# them in the stage's asking slot, on the question's card and on that step
+# in the history (a ref only in the question's text pairs there alone). No
+# links in the text and no note line for it: the turn's end has those.
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI with the session's cards (a reload keeps it, after the worker stopped
 # too: cards.json). The links are stored as the answer's display. A ref in
@@ -120,10 +128,20 @@ class SourceLinks
   end
 
   def call(event)
-    return unless event.is_a?(Hash) && event[:type] == :after_turn
-    return unless event[:status].to_s == "completed"
+    return unless event.is_a?(Hash)
     return if @sources.empty?
 
+    case event[:type]
+    when :after_turn then after_turn(event)
+    when :question_asked then question_asked(event)
+    end
+  end
+
+  private
+
+  def after_turn(event)
+    return unless event[:status].to_s == "completed"
+
     text = last_model_text(event[:messages])
     return if text.nil? || text.empty?
 
@@ -141,7 +159,23 @@ class SourceLinks
     event[:notify]&.call(line(found), level: :info, fallback_for: covered ? :display : nil)
   end
 
-  private
+  # A question of the model's (or an approval of its call) is about to
+  # open: the refs in the reply that asks it and in the question's own text
+  # and options, each scanned on its own (a code span never runs from one
+  # into the next), as refs on that reply. No present (a mid-turn text has
+  # no display) and no note line (the after-turn one stays the terminals').
+  def question_asked(event)
+    refs = event[:refs]
+    return unless refs
+
+    question = event[:question].is_a?(Hash) ? event[:question] : {}
+    field = ->(key) { question.key?(key) ? question[key] : question[key.to_s] }
+    parts = [event[:text], field.call(:question), *Array(field.call(:options))]
+    parts.each do |part|
+      text = part.is_a?(String) ? part : ""
+      add_refs(refs, occurrences(text[0, MAX_SCAN])) unless text.empty?
+    end
+  end
 
   # Links the refs in the answer as shown: the model's text unless an
   # earlier hook changed it (then its offsets differ, so it is scanned

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,15 +1,15 @@
 ---
 name: source-links
-version: 0.5.1
+version: 0.6.0
 scope: system
-description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
+description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
-requires_chi: ">= 0.61.0"
+requires_chi: ">= 0.98.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
 hooks:
   source_links.rb:
-    sha256: sha256:c41249ec0bbb708ec7827e1d0f66689dfbbc415c1da5fe33f5d3a8ec8e5eaa2f
-    event: after_turn
+    sha256: sha256:84c0bef064fb1ea76749a61e758eba612662aaf0f05f18a18ab4228497078fa2
+    events: [after_turn, question_asked]
     on_error: log
     priority: 90

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

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

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"
@@ -77,6 +78,7 @@ require_relative "answer_display"
 require_relative "answer_refs"
 require_relative "edit_preview"
 require_relative "question_desk"
+require_relative "question_asked"
 require_relative "child_reports"
 require_relative "relay_desk"
 require_relative "guardrail_wiring"
@@ -276,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
@@ -364,7 +369,8 @@ module Samagotchi
         model_key: -> { @model_key },
         model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
-        ask: ->(fields) { open_question(fields) },
+        # An approval of the model's call: :question_asked first (QuestionAsked).
+        ask: ->(fields) { open_question(question_asked(QuestionAsked::KIND_APPROVAL, fields)) },
         notify: ->(message) { guardrail_notify(message) }
       )
     end
@@ -1576,13 +1582,35 @@ module Samagotchi
 
     # Ask the model's question (ask_user_question): the kernel's
     # question_handler, called on the turn thread with the payload
-    # Tools::AskUserQuestion.validate made (QuestionDesk#request).
+    # Tools::AskUserQuestion.validate made (QuestionDesk#request), after
+    # the :question_asked hooks (QuestionAsked) gave the step its refs; a
+    # --non-interactive run has no one to ask, so they don't fire there.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request_question(payload)
+      payload = question_asked(QuestionAsked::KIND_QUESTION, payload) unless interface == :non_interactive
       @question_desk.request(payload)
     end
 
+    # The :question_asked hooks for a question of the model's about to
+    # open: the fields with the asking step's refs (QuestionAsked.fire).
+    # @return [Hash]
+    def question_asked(kind, fields)
+      QuestionAsked.fire(hooks: @hooks, conversation: live_conversation, kind: kind, fields: fields,
+                         cwd: @session&.working_directory, synchronize: ->(&block) { synchronize_events(&block) },
+                         visible: ->(content) { question_step_text(content) })
+    end
+    private :question_asked
+
+    # A step's text as the asking slot shows it: the native loop's raw
+    # response without its thoughts and tool-call bodies (a chat step has
+    # neither), then the markup's tokens (OutputFormatter.strip_markup).
+    def question_step_text(content)
+      parser = @kernel.parser
+      OutputFormatter.strip_markup(parser.strip_tool_calls(parser.strip_thought(content)))
+    end
+    private :question_step_text
+
     # Open a question for the UIs and wait for its answer
     # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
@@ -2091,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
 
@@ -2113,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
@@ -2122,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,
@@ -2531,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
@@ -2584,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,

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -69,9 +69,9 @@ module Samagotchi
 
             hook = MemoryBundle::BundleHook.parse(raw_meta)
             # A hook with no declared event cannot be auto-registered.
-            next if hook.event.empty?
+            next if hook.events.empty?
 
-            fail_closed = hook.on_error == "fail_closed" && hook.event == "before_tool_call"
+            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
             unless file && File.exist?(file)
@@ -98,9 +98,10 @@ module Samagotchi
           loaded
         end
 
-        # Build one hook file and register it in +registry+ under its
-        # event, priority and error policy (a fail_closed before_tool_call
-        # one denies when it raises). No missing-file, sha or requires_chi
+        # Build one hook file and register it in +registry+ under each of
+        # its events (one instance for all: its state is shared), with its
+        # priority and error policy (a fail_closed before_tool_call one
+        # denies when it raises). No missing-file, sha or requires_chi
         # check: #load makes them; the test kit loads a bundle's source
         # this way.
         # @param hook [MemoryBundle::BundleHook] its manifest entry
@@ -109,17 +110,19 @@ module Samagotchi
         # @raise [Exception] what loading or building the file raised;
         #   nothing is registered then
         def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil)
-          event_sym = hook.event.to_sym
-          fail_closed = hook.on_error == "fail_closed" && event_sym == :before_tool_call
           plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          policy = if fail_closed then :deny
-                   elsif hook.on_error == "log" then :log
-                   else :skip
-                   end
-          label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-          handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                               fields: { bundle: bundle_name }) { |event| plugin.call(event) }
-          registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          hook.events.each do |event_name|
+            event_sym = event_name.to_sym
+            fail_closed = hook.fail_closed?(event_sym)
+            policy = if fail_closed then :deny
+                     elsif hook.on_error == "log" then :log
+                     else :skip
+                     end
+            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
+            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                 fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          end
           nil
         end
 

data/lib/samagotchi/hooks.rb

@@ -24,12 +24,15 @@ module Samagotchi
   #   :before_tool_call   — before a tool is dispatched: vote with event[:guardrail].deny!/ask!
   #                         (or the older event[:blocked]=true + event[:block_reason]); the
   #                         event also has context: and targets: (docs/guardrails.md)
+  #   :question_asked     — a question of the model's (ask_user_question) or an approval of its
+  #                         call is about to open: event[:refs] attaches refs to the asking
+  #                         reply (QuestionAsked)
   #   :after_tool_call    — after tool execution, before result injection
   module Hooks
     # Every event a hook can be registered for, in a turn's order
     # (docs/hooks.md). Plugin::Api#on takes any symbol: `chi bundle check`
     # warns on one not here.
     EVENTS = %i[session_start before_turn before_generation generation_progress after_generation before_tool_call
-                after_tool_call after_turn session_end].freeze
+                question_asked after_tool_call after_turn session_end].freeze
   end
 end

data/lib/samagotchi/kernel_loop.rb

@@ -1139,6 +1139,14 @@ module Samagotchi
     # through call_tool (+via+) of a tool the toolkit declares is told to
     # call it directly: the model's call_tool(tool: "chi/read") with read
     # declared, or a hook's rewrite (a direct call can't carry via:).
+    # The built-in +name+ names when the turn's host loads tools and the
+    # toolkit reaches it (Registry#indexed): a direct call runs it.
+    def loaded_entry(name)
+      return nil unless @turn_settings&.loads_tools && @tools.respond_to?(:indexed)
+
+      @tools.indexed(name, layers: llm_context_layers)
+    end
+
     def unknown_tool_error(name, layers, via: nil)
       names = @tools.names(layers: layers)
       toolkit = @tools.toolkit&.name
@@ -1160,11 +1168,13 @@ module Samagotchi
 
     def dispatch(call)
       # A built-in reached through call_tool runs only while the toolkit
-      # reaches it that way (Registry#indexed); any other call by its name.
+      # reaches it that way (Registry#indexed); any other call by its name,
+      # on a host that loads tools (TurnSettings#loads_tools) a reachable
+      # one too.
       entry = if call[:via]
                 @tools.respond_to?(:indexed) ? @tools.indexed(call[:name], layers: llm_context_layers) : nil
               else
-                @tools.offered(call[:name], layers: llm_context_layers)
+                @tools.offered(call[:name], layers: llm_context_layers) || loaded_entry(call[:name])
               end
       unless entry
         result = unknown_tool_error(call[:name], llm_context_layers, via: call[:via])
@@ -1198,6 +1208,9 @@ module Samagotchi
         dispatched[:ref_path] = result.ref_path
         dispatched[:ref_stderr_path] = result.stderr_path if result.stderr_path
       end
+      # The tools a find_tools hit loads (Tools::ToolIndex::FoundText),
+      # saved with a chat result (ToolResponse.single).
+      dispatched[:loaded] = result.loaded if result.respond_to?(:loaded) && !Array(result.loaded).empty?
       if result.respond_to?(:images) && !Array(result.images).empty?
         dispatched[:images] = Array(result.images)
         dispatched[:image_only] = true if result.respond_to?(:image_only?) && result.image_only?