samagotchi 0.98.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d683d11a3567996b7eb36801581dfa374309207bda22d8bc7d7e4e7f94d1cf2f
-  data.tar.gz: 850af6daff806f5c56e4c5b9cd2294452360c891fca2690367111ff960c721fd
+  metadata.gz: '0185e889922200db9f6882d899b3ff17c74d296aa8c7823a7040e45e308edc47'
+  data.tar.gz: addddd537eac6fc703d0e217c7a968446ca44bb53f8ee501e61de86b1163085c
 SHA512:
-  metadata.gz: c2272a6357f9fe281f36078facc23678c044b1942213bd4e881881c67fbd1ad2332aaf7f55d82cbe354ab558661b6e2fa4883044d7e07897508d6518f51b3a36
-  data.tar.gz: d4e99b1672e12be69e3c36b1b5e29b9a6b3ed1e68d17a7f308e8a33d6e7a41d5790c5b2ea552c796d335e0fba94ff540d3788389b91b252d81b141ba5e38b869
+  metadata.gz: 62a2aaff51d6bbc45cfcc59e3d199444448cd838c229fbe4bda717658b6ba83fc7f273326ea0d8e8cb3e34839bd3c78ba472a5792589dbfe87a5dd1a8df2c5a7
+  data.tar.gz: 8b68d54a05c89461dba2428496111897cf85ca1cc70ac70f2b1621edcce7d70908243e181644b7086557d347fc80c51305a7b3df446c9299a09c2ec8e1cd113b

data/CHANGELOG.md

@@ -8,6 +8,25 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.99.0] - 2026-10-22
+
+### Added
+
+- Sessions on Anthropic's Messages API (`api: anthropic`) can call a tool their toolkit leaves out by its own name:
+  the reachable built-ins (`list_sessions` on `lean`) and the MCP servers' tools (`mcp_fs_read`) go in each request
+  deferred (`defer_loading`), and a direct call runs under the same guardrails, approvals and rows as through
+  `call_tool`. A `find_tools` hit loads its matches by reference, so the model calls them by name and the request
+  after a load reads its whole prompt from the cache. Other hosts are unchanged. See
+  [docs/configuration.md](docs/configuration.md#toolkits).
+- Plugins can load tools for the model with `ctx.load_tools(names)` (built-ins, MCP tools): on an Anthropic host the
+  model then calls them by name; elsewhere nothing is sent. A hint, not access: the guardrails stay. See
+  [docs/plugins.md](docs/plugins.md).
+
+### Changed
+
+- An Anthropic session whose toolkit leaves tools out, or that has MCP tools, may read its prompt again once on its
+  first turn after the upgrade (its request now carries the deferred tools).
+
 ## [0.98.0] - 2026-10-21
 
 ### Added
@@ -3755,7 +3774,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.98.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.99.0...HEAD
+[0.99.0]: https://github.com/dm1try/samagotchi/compare/v0.98.0...v0.99.0
 [0.98.0]: https://github.com/dm1try/samagotchi/compare/v0.97.0...v0.98.0
 [0.97.0]: https://github.com/dm1try/samagotchi/compare/v0.96.0...v0.97.0
 [0.96.0]: https://github.com/dm1try/samagotchi/compare/v0.95.0...v0.96.0

data/docs/architecture.md

@@ -612,7 +612,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
-| Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`) | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). |
+| Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`), `tools/deferred_tools.rb` | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). On `api: anthropic` they also go out deferred, a hit loads its matches and the model calls them by name ([internals/anthropic.md](internals/anthropic.md)). |
 | Tool output cut | `tool_output_cut.rb` (`ToolOutputCut`), `tool_output_files.rb` (`ToolOutputFiles`) | A tool's output over `max_tool_output_chars`, cut by the tool's policy; an execute's whole output saved in the session's `tool_output/` folder ([internals/tool-guardrails.md](internals/tool-guardrails.md)). |
 | Steer delivery | `steer.rb` (`Steer`), `delivery.rb` (`Delivery`), `steer_cut.rb` (`SteerCut`), `generation_phase.rb`, `waiting_steer.rb`, `steer_cut_after.rb` (`SteerCutAfter`), `cut_policy.rb` (`CutPolicy`) | A message for a running turn: at the next boundary, cutting a thinking-only generation, or queued for the turn's end ([internals/engine.md](internals/engine.md)). |
 | Prompt files | `prompt_files.rb` (`PromptFiles`) | The AGENTS.md chain (root → cwd) and the appended files the system prompt carries. |

data/docs/configuration.md

@@ -1408,6 +1408,14 @@ toolkit:
   starts no children). To keep a built-in away from the model, name it under `remove:`. `find_tools` and `call_tool`
   are declared when a toolkit has a reachable built-in (or an MCP server is configured); `full` with no MCP server
   declares neither, and removing them there (`--no-tool call_tool`) leaves nothing out: no prompt line, no chip.
+- **On `api: anthropic`, reachable tools are callable by name.** Every tool `call_tool` reaches (the reachable
+  built-ins, the MCP servers' tools as `mcp_<server>_<tool>`) also goes in the request's tools deferred
+  (`defer_loading`: Messages keeps them out of the model's view until something loads them, at a flat ~100 tokens).
+  A direct call of one (`list_sessions`, `mcp_fs_read`) runs, under the same guardrails, approvals and rows as
+  through `call_tool` (an MCP tool's call is `call_tool`'s). A `find_tools` hit **loads** its matches (up to 5):
+  the model then sees their definitions and calls them by name; only the new result is read uncached. Not on
+  Fireworks' dialect, nor on `api: openai` or a native host, where such a call gets the `call_tool` route and a hit
+  reads as text.
 - **The prompt line.** One line after the base prompt names them: `Not declared in this session (toolkit lean): ….
   Search them with find_tools; call one with call_tool.`, then `Removed (toolkit child): memory_write, …. Only the
   user can load one (/toolkit add <name>).` With `find_tools` removed, the first sentence ends `Call one with

data/docs/guardrails.md

@@ -429,6 +429,14 @@ direct call, and an approval is keyed `delegate:…` either way. `tool:
 call_tool` rules no longer see such calls, only MCP calls and misses. A
 `chi/` name the toolkit removes is refused before the gate, with no card.
 
+On a Messages host (`api: anthropic`) those tools are also callable by their
+own names (they go out deferred): a direct `delegate` call is gated as any
+declared tool's, keyed `delegate:…` (the same approval as through
+`call_tool`); a direct call of an MCP tool's `mcp_<server>_<tool>` name is
+gated as the `call_tool` call it stands for: `mcp_*` rules match it, and its
+approval is `call_tool>mcp_x:…`, the same as the `call_tool` route's. A tool
+the toolkit removes stays refused before the gate.
+
 ```yaml
     - id: mcp-ask
       # every MCP call (call_tool, acting as mcp_<server>_<tool>); not a find_tools search.

data/docs/hooks.md

@@ -610,6 +610,11 @@ A built-in reached through `call_tool` (`chi/delegate`, a tool the session's too
 declare) fires as that built-in, its call built as a direct call's, with `call[:via] == "call_tool"`.
 A hook that drops `via:` or rewrites the call to a tool the toolkit removes gets the call refused
 by its name.
+On a Messages host (`api: anthropic`), the model may call those tools by their own names (they
+go out deferred, [configuration.md](configuration.md#toolkits)): a direct `delegate` fires as a
+declared tool's call, with no `via:`; a direct `mcp_fs_read` fires as the `call_tool` call it
+stands for (`tool: "call_tool"`, `args: {"tool" => "fs/read", "args" => {…}}`), as if the model
+had called `call_tool`.
 
 ## Bundle Hooks (unified workflow bundle)
 

data/docs/internals/anthropic.md

@@ -13,7 +13,8 @@ ChatLoop::Run#generate
   → AnthropicMessages#chat
       → #request_body                       # options as Messages takes them, breakpoints on or off
           → AnthropicWire.translate         # system blocks + messages, cache_control placed
-          → AnthropicWire.tools             # function schemas → {name, description, input_schema}
+          → AnthropicWire.tools             # function schemas → {name, description, input_schema},
+                                            #   a deferred one with defer_loading: true
       → POST {base}/v1/messages             # LLM::HTTP: retries, cancel, first-token limit
       → AnthropicAssembly#add per SSE event # → ChatResponse (text, reasoning, tool_calls, usage,
                                             #   finish_reason, provider_content)
@@ -35,6 +36,7 @@ Paths are under `lib/samagotchi/llm/`.
 | `anthropic_wire.rb` | `AnthropicWire`: ChatLoop's wire messages as Messages' `system` and `messages`, the two breakpoints, tool ids and names |
 | `anthropic_assembly.rb` | `AnthropicAssembly`: a response from a whole body (`.from_message`) or stream events (`#add`), its usage in the OpenAI shape |
 | `dialect.rb` | `Dialect` (`STANDARD`, `FIREWORKS`): what a provider's `/v1/messages` does differently |
+| `../tools/deferred_tools.rb` | `Tools::DeferredTools.list`: the tools a request declares deferred (Deferred tools) |
 | `prompt_cache.rb` | `PromptCache.control`: the `cache_control` a breakpoint carries (`cache.ttl`) |
 | `chat_loop.rb` | `ChatLoop#replay_blocks`, `#reasoning_history`'s floor, `Run#with_thinking` (saves `anthropic_content`), `#settle_dropped_thinking!` |
 
@@ -202,12 +204,76 @@ The log line's `cache=` says `on`, `1h` or nothing (`#cache_summary`). prompt-ca
 
 `LLM::Dialect` is a host's `dialect:` (`Dialect.parse` warns once on an unknown name or on a host whose api isn't
 `anthropic`): `auth` (the default key header), `thinking_display` (the `display` sent with adaptive or budget
-thinking, nil for none), `cache_breakpoints` and `session_header`.
-
-| Dialect | auth | thinking display | breakpoints | session header |
-|---|---|---|---|---|
-| `STANDARD` (no `dialect:`) | `x-api-key` | `summarized` | yes | none |
-| `FIREWORKS` | Bearer | none | no (an automatic prefix cache) | `x-session-affinity` |
+thinking, nil for none), `cache_breakpoints`, `session_header` and `tool_loading` (deferred tools, below).
+
+| Dialect | auth | thinking display | breakpoints | session header | tool loading |
+|---|---|---|---|---|---|
+| `STANDARD` (no `dialect:`) | `x-api-key` | `summarized` | yes | none | yes |
+| `FIREWORKS` | Bearer | none | no (an automatic prefix cache) | `x-session-affinity` | no |
+
+## Deferred tools
+
+A session declares its toolkit's tools; the ones it reaches but doesn't declare (the built-ins its toolkit leaves out
+without removing them, an MCP server's tools in the tool index) are found with `find_tools` and called with
+`call_tool` on every host. On a Messages host they also go in `tools` with `defer_loading: true`, after the declared
+ones: the model sees their names only when something loads them, and the API accepts a call of one by its own name.
+`AnthropicMessages#loads_tools?(model)` says whether a request does this: the dialect's `tool_loading`, unless the
+host refused it for that model.
+
+`ChatLoop#tool_definitions(conversation, model:)` appends them (`Tools::DeferredTools.list`) only on such an
+adapter, and only with at least one tool declared (Messages wants one). The list, per request:
+
+1. the built-ins the toolkit reaches (`Registry#reachable_names`), in registry order;
+2. the tool index's source tools while `call_tool` is declared (`ToolIndex#deferrable`, via
+   `Registry::Index#deferrable`): callable, the only tool with its acts_as, a name Messages takes, no registered
+   tool's name; by acts_as (`mcp_<server>_<tool>`), sorted by name;
+3. every other name the conversation loaded (a find result's `loaded:`, a tool change's `add:`) that isn't declared,
+   as a stub ("Not available right now; find_tools finds it when it is.", an empty object schema): its server is
+   gone or still starting, and the reference in the history must name a tool in `tools`.
+
+A deferred tool never carries `cache_control`, and the list sits after the declared tools, so the cached prefix holds
+(prompt-caching.md). A session with nothing to defer (full, no MCP server) sends the bytes it always did.
+
+### Loading by reference
+
+A `find_tools` keyword hit loads its callable matches (`ToolIndex::FoundText#loaded`, at most `FIND_RESULTS`: a
+built-in by its name, a source tool by its acts_as when it is deferrable; an empty query, a miss or the names listing
+load nothing). `KernelLoop#dispatch` passes them on (`dispatched[:loaded]`), `ToolRun#loaded` carries them and
+`ToolResponse.single` saves them on the result as `loaded:` (every chat host; `ToolResponse.joined` doesn't).
+`ChatLoop#wire_messages` copies them onto the tool message only for an adapter that loads tools.
+`AnthropicWire.translate(wire, cache:, deferred:)` takes the names this request declares deferred and renders a
+result's `loaded:` names among them as a tool_result holding only
+`{"type": "tool_reference", "tool_name": …}` blocks (Messages takes no other content beside a reference), followed by
+a sibling text block: `Loaded: a, b. Call them directly by these names.`, then the result's text without its
+`Call one with call_tool(…)` line (`ToolIndex::CALL_HINT`; the saved result keeps it). With that line and a trailing
+"(call_tool works too)", Sonnet and Haiku 5.5 went through `call_tool` 2/2 live; without, 5/5 called the tool by
+name. A result whose names aren't deferred here (declared since, or no tool loading) goes as plain text. The sibling
+text is never marked; when breakpoint #2 falls on such a tool_result, it goes on its last reference.
+
+### Tool changes (`ctx.load_tools`)
+
+A plugin's `ctx.load_tools(names)` stages wire names (`Engine#load_tools`: `ToolIndex#deferred_name`, idempotent
+against the staged names and the history's earlier changes, `ToolLoads`). `Engine#turn_messages` appends them after
+the turn's user message (on a turn with none, after its trailing results or notes; a conversation ending with a reply
+keeps them staged) as one `ToolLoads.entry` per bundle (`kind: "tool_change"`), only when the turn's host
+`tool_changes?` (`AnthropicMessages#tool_changes?`: `loads_tools?`, unless the host refused changes for the model);
+otherwise the staged names are dropped and logged (`tool_loads_not_sent`). `ChatLoop#wire_messages` sends the entry
+only to such an adapter, `Prompt.format*` skips it. `AnthropicWire.translate` turns it into a `role: "system"` message
+of its own, `{"type": "tool_addition", "tool": {"type": "tool_reference", "name": …}}` per name deferred in this
+request (none: no message; note `name` here, `tool_name` in a result's reference), held until the run of user-role
+messages it sits in ends: before the next assistant message, or last. `AnthropicMessages` adds
+`INLINE_TOOLS_BETA` (`inline-tools-2026-09-15`) to `anthropic-beta` when the body has such a message, comma-joined with
+the binding beta on a drop_block step. A 400 naming `tool_addition`, the beta or a system role (`TOOL_CHANGES_RE`)
+sets `:tool_changes` for the model: the retry and every later request drop the system messages and the beta.
+
+A direct call of a deferred tool runs whether something loaded it or not (the API doesn't check): the Engine sets
+`TurnSettings#loads_tools` from the turn's final model (after the before_turn hooks), and then `ToolRunner#run` and
+`KernelLoop#dispatch` take a reachable built-in by its own name (`Registry#indexed`) through the normal gate, and wrap
+an MCP tool's acts_as into the `call_tool` call it stands for (`ToolIndex#wrap`): `call_tool`'s row, rules and
+approvals. A reload rebuilds that wrapped call from the saved one (`BuiltinCalls.wrap_saved`). Each such call is
+logged (`tool_direct_deferred`, with `loaded:` whether the conversation had loaded it). On `api: openai` and the
+native loop nothing is deferred, and a direct call of a reachable built-in is refused with the `call_tool` route as
+before.
 
 ## 400 fallbacks
 
@@ -225,9 +291,14 @@ client's life only):
 | `cache_control` | no breakpoints | per host (`cache_control_refused`) |
 | `max_tokens: N > M` (`OUTPUT_CAP_RE`) | `max_tokens` capped at M | per model (`output_cap`) |
 | `block_binding` or the binding beta, on a drop_block retry (`thinking_binding_unsupported?`) | the strip instead (Preserved thinking) | per host (`binding_controls_refused`) |
+| `tools.N.input_schema` (`TOOL_SCHEMA_RE`) where tool N is deferred | that tool leaves the deferred list (`call_tool` still reaches it); one fix per tool (the fix value is `[:tool_schema, name]`), at most `MAX_SCHEMA_FIXES` (5) per request; the names kept by `RefusalMemo#add` | per model (`tool_schema_refused`) |
+| `tool_addition`, the inline-tools beta or a system role (`TOOL_CHANGES_RE`) on a request with a tool change | no system messages and no beta from then on (`#tool_changes?` false); the tools stay deferred and callable | per model (`tool_changes_refused`) |
+| `defer_loading` or `tool_reference` (`TOOL_LOADING_RE`) on a request that carries either | no deferred tools from then on (`#loads_tools?` false, loads go as text); a direct call of a reachable tool is refused again from the next turn (`TurnSettings#loads_tools`) | per model (`tool_loading_refused`) |
 
 The display check comes before the adaptive one: its path (`thinking.adaptive.display`) names adaptive too. A context
 overflow, a refused sampling field, a signature or a binding-controls 400 is not one of these (`#refusal_fix` keeps
 excluding them, so `ADAPTIVE_REFUSED_RE` never reads a binding 400's "adaptive" as a form refusal): a signature 400
 goes to the binding recovery above, the rest on as they are, to the loop's own handling (ChatLoop's sampling and
-thinking-fields fallbacks) or to the turn's failure.
+thinking-fields fallbacks) or to the turn's failure. A tool-loading fix's retry that breaks a replayed thinking
+block's binding gets a signature 400 like any other request, and the binding recovery takes it. These refusals come on
+the first request that carries the feature, normally a turn's first.

data/docs/internals/engine.md

@@ -34,7 +34,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #                      resumed: true (only on a step-limit Continue: resumed: given),
   │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
   │     # refresh_profile! (may ask the server's /props once)
-  │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate),
+  │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name, loads_tools … are set in
+  │     #   generate, after the hooks, from the final model),
   │     #   from one EffectiveModel; ThinkingNotices#turn_started keeps the level and says one the host can't do
   │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools,
   │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, ToolIndex#refresh! for find_tools'
@@ -42,6 +43,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
   │     #   (a frozen copy of the history, the prompt, and resumed)
   │     # turn_messages: system head + history + due reminders (:reminder_injected) + the user message
+  │     #   + the plugins' staged tool loads (ctx.load_tools: a kind "tool_change" system entry per bundle,
+  │     #   only when the turn's host takes tool changes; #append_tool_loads)
   │     # Returns false when a Stop came during the probes or the init wait, else true
   │
   ├── generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
@@ -218,7 +221,10 @@ ChatLoop#complete(messages:, max_iterations:, on_stream_event:, cancel_controlle
 
 The differences from the native loop:
 
-- The tools go in each request's `tools` field (`tool_definitions`), not in the system prompt.
+- The tools go in each request's `tools` field (`tool_definitions(conversation, model:)`), not in the system prompt.
+  On an adapter that loads tools (`#loads_tools?`: `AnthropicMessages`), the tools the session reaches but doesn't
+  declare follow, `defer_loading: true` (`Tools::DeferredTools`; anthropic.md, "Deferred tools"); the Run keeps the
+  last request's deferred names and logs a call of one (`tool_direct_deferred`).
 - The conversation is converted to the OpenAI wire format (`wire_messages`), for every chat host;
   `AnthropicMessages` translates that again into Messages' `system` and content blocks (`LLM::AnthropicWire`).
 - The first system message carries `cache_split:` (from `SystemPrompt#stable_length`, which the Engine passes in
@@ -266,11 +272,15 @@ One iteration with tool calls:
       → :tool_dispatch_started {iteration, call_count}
       → for each call: ToolRunner#run(call, iteration:, call_index:, call_count:,
                                       on_stream_event:, max_tool_output_chars:)
+          → under TurnSettings#loads_tools, a direct call of a source tool's acts_as (mcp_fs_read) is wrapped
+            into the call_tool call it stands for (Registry::Index#wrap, ToolIndex#wrap)
           → first, the call's entry unwraps it (Registry::Entry#unwrap: a call_tool of chi/<built-in> becomes
             that built-in's call with via: "call_tool", ToolIndex#unwrap); the rest sees the real call
           → a tool the session's toolkit leaves out (Registry#left_out; with via:, one Registry#indexed doesn't
             reach) skips the gate: no hooks, no card; KernelLoop#dispatch answers it (the call_tool route for a
-            reachable tool, the not-loaded error for a removed one)
+            reachable tool, the not-loaded error for a removed one). Under TurnSettings#loads_tools a reachable
+            built-in called by its own name is no such call: it runs through the gate, and KernelLoop#dispatch
+            takes it (#loaded_entry)
           → Guardrails::Gate#evaluate (the before_tool_call hooks, then the core checks)
           → :tool_call_started
           → an ask verdict: Gate#settle_ask (asks the user, records waited_ms)

data/docs/internals/llm-context-forget.md

@@ -38,7 +38,8 @@ lets the model forget its own tool outputs. The pieces:
 - **Stubs** (`LLMContextView`): `(forgotten) <note>` on the first output of a call's forgets in a row, `(forgotten
   with tN: see its note)` on the rest (a run of the same note, author and stamp, no other output between them),
   ` [restore: tN]` on a non-read with a stored id, then each kept range under `lines A-B kept:`. The entry keeps its
-  role, tool_call_id and images bookkeeping as for stale.
+  role, tool_call_id and images bookkeeping as for stale, and a find_tools result's `loaded:`, so a Messages host
+  still gets the load's references (anthropic.md, "Deferred tools"); only the sibling text is the stub.
 - **Offers**: `ContextStatus` (internals/context-telemetry.md).
 - **Persistence**: the edits ride on the entries (plan D3), so `--resume`, rollbacks and forks keep the stubs and the
   restores; `/stats` counts each applied batch's re-prefill.

data/docs/internals/prompt-caching.md

@@ -99,6 +99,15 @@ right-hand column happens.
   id: every chat request carries them, unless the host's dialect has none (`Dialect#cache_breakpoints`: `fireworks`,
   an automatic prefix cache) or the host refused `cache_control` with a 400 (no breakpoints for that worker's life).
   [anthropic.md](anthropic.md) has the details.
+- On a Messages host the tools a session reaches but doesn't declare go in `tools` deferred (`defer_loading`), after
+  the declared ones, never marked. Their presence is a flat ~93 tokens of the cached prefix, whatever their number
+  or names: a request with none and one with some don't share a prefix (measured 2026-10-22: a full + MCP session
+  read nothing of the prefix main's chi had cached, then read its own), but the list may grow mid-session (an MCP
+  server's `list_changed`, a tool sorted in mid-list) without a re-read. A find_tools hit's load goes in its own
+  tool_result (`tool_reference` blocks) with the text beside it, rendered the same in every later request (a
+  loaded name stays deferred, a stub once its source is gone), so the request after a load reads the whole prefix;
+  the loaded definitions and the new result are the fresh part. A plugin's
+  `ctx.load_tools` only appends (a system `tool_addition` after the user message, never a change to `tools`).
 - Side requests (idle recap, `/btw`) go through `IdleClient` with their own short system prompt. On a current
   llama.cpp they don't evict the session (see the server settings below); chi never pins them to a slot.
 

data/docs/plugins.md

@@ -631,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
@@ -759,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.
@@ -1176,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
 ```
 
@@ -1276,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

@@ -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/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.98.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"
@@ -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,

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?