samagotchi 0.97.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bec4407abc70e688b17f913e574b7b7968a13941e7d2f0b2599e8ebdcdd5954
-  data.tar.gz: b1f1b5d30b31953901a94849b22da5deeb7ff97b7b57fe17bda2f3c8d40ec41b
+  metadata.gz: '0185e889922200db9f6882d899b3ff17c74d296aa8c7823a7040e45e308edc47'
+  data.tar.gz: addddd537eac6fc703d0e217c7a968446ca44bb53f8ee501e61de86b1163085c
 SHA512:
-  metadata.gz: 8d1d4b749231445533c0526e4fc87052294b70026ec9be742db89b474bb8bdb18079c95f67d77b8c7116f1d18d0c13be9b413eceea5e1f21343ee93925121756
-  data.tar.gz: 7d32ff1ed5d3d7fb3ccb57f304b96bdad8053671a0395db7408852b57a40130ce7fd76492a5048eba5bf7cb6ac7b94ff3b7dd0c178e536a1b9006815c10f07b9
+  metadata.gz: 62a2aaff51d6bbc45cfcc59e3d199444448cd838c229fbe4bda717658b6ba83fc7f273326ea0d8e8cb3e34839bd3c78ba472a5792589dbfe87a5dd1a8df2c5a7
+  data.tar.gz: 8b68d54a05c89461dba2428496111897cf85ca1cc70ac70f2b1621edcce7d70908243e181644b7086557d347fc80c51305a7b3df446c9299a09c2ec8e1cd113b

data/CHANGELOG.md

@@ -8,6 +8,53 @@ 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
+
+- A long question from the model gets room in the web stage: when its reply doesn't fit, the stage grows (up to 85%
+  of the panel) for the turn, the reply reads from its start in one scroll, and an "Answer ↓" pill leads to the card
+  while it is out of view. Approvals, the step limit and hooks' questions keep their layout.
+- A new hook event, `:question_asked`, lets a plugin attach refs to the reply that asks a question or an approval
+  (display only, never in the prompt); the web pairs them in the asking text, on the card and in the history step.
+  A bundle manifest's hook can list `events: [...]` to run one hook for several events. See
+  [docs/hooks.md](docs/hooks.md).
+- source-links 0.6.0 links the issue keys and paths in a waiting question's reply too, not only in answers.
+
+### Changed
+
+- The web's rename ✎ moved from the info bar to the session's title: on the active card and next to the title in
+  the top bar, with the input over the title.
+- A model server's 404 that lists its models puts `did you mean …?` ahead of the (cut) list, and names up to three
+  ids: every nearest typo on a tie, or the listed ids that contain the name asked for (`Qwen3.6-35B` →
+  `mlx-community--Qwen3.6-35B-A3B-4bit` or `…-8bit`).
+
+### Fixed
+
+- A Gemma 4 step on the native loop no longer shows its tool call's body (`call:ask_user_question{…}`) as text in
+  the web history after a reload.
+
+Update with `chi update` (the system bundle 0.98.0, source-links 0.6.0, the dev profile 0.7.1), then restart `chi web`.
+
 ## [0.97.0] - 2026-10-21
 
 ### Added
@@ -3727,7 +3774,9 @@ 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.97.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
 [0.95.0]: https://github.com/dm1try/samagotchi/compare/v0.94.0...v0.95.0

data/docs/architecture.md

@@ -421,7 +421,14 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
   turn's answer). A tail read's timing is always the newest turn's; `recent=1` is accepted and not needed.
   The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
-  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A file ref outside the
+  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A question's
+  refs (`pending_question.refs`, `:question_asked`) pair the same way (`markdown_place.js` `linkRefsIn`/`pairRefsIn`):
+  `question_requested` (or a snapshot's pending question) keeps them on the asking step's gen
+  (`turn_model.js` `questionRefs`) before the card draws, so the stage's asking slot (`stage_slots.js`
+  `drawAsking(text, refs)`) pairs them on its raw draw and again after its markdown swap; the card pairs its
+  question text and its kept reply (`question_cards.js`); the step's closed `.gen-text` takes them
+  (`turn_view.js`; on a reload its `data-answer-at`, the message's `display_refs`) and `linkTextRefs` pairs it at
+  the turn's end and after a reload. A file ref outside the
   session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
   session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
   file ref is dropped rather than shown unchecked.
@@ -507,7 +514,8 @@ Bridge's stream above): the chat loop's thinking is the
 server's `reasoning_content`; the raw-prompt loop splits each generation's
 stream with a fresh `ThoughtStreamSplitter`, seeded with the prompt's prefill (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
-from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
+from `text:`; a saved step's text, as the web history and the attached terminal's join show it,
+drops both too: `OutputFormatter.strip_markup`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
 `reasoning_content` on the running turn's replies (`reasoning_history`; a step-limit Continue's
 turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt
@@ -604,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/bundle-authoring.md

@@ -51,7 +51,8 @@ plugin:
   sha256: sha256:<hex>       # `chi bundle check --fix` fills it; never compute it by hand
 # files:                     # memories it installs (top-level *.md); without files: every *.md but README & co.
 #   my_notes.md: sha256:<hex>
-# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler)
+# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler), each with event: NAME
+#                            # or events: [a, b] (one instance for both; chi newer than 0.97.0)
 # needs: [gh]                # outside commands it relies on
 ```
 
@@ -64,7 +65,7 @@ time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
 ## What a hook sees
 
 `chi.on(event) { |event, ctx| … }` gets a Hash. The events, in a turn's order: `session_start`, `before_turn`,
-`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `after_tool_call`,
+`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `question_asked`, `after_tool_call`,
 `after_turn`, `session_end` (the fields of each: [hooks.md, Hook Events](hooks.md#hook-events)). A symbol not in
 that list is never fired (`check` warns). The two a bundle wants most, for an `execute`:
 
@@ -116,7 +117,8 @@ end
 
 `bundle.tool_call` runs guarded hooks; `bundle.tool` calls a registered tool. `bundle.steers`, `cards`, `stops` and
 `questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
-`bundle.http.stub` stubs `ctx.http`; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
+`bundle.http.stub` stubs `ctx.http`; `bundle.question_asked(text, question:)` fires `:question_asked` and returns
+the refs; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
 experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.

data/docs/cli.md

@@ -659,8 +659,8 @@ the first message: …)`); `/title TEXT` names the session (whitespace collapsed
 cut at 80 characters), `/title --clear` drops the name (anything after `--clear`
 is refused with the usage line). It is saved at once,
 mid-turn too, and the lists, cards, top bar and tab show it in place of the first
-message; a continue's next link keeps it. The web's info bar has `✎` for it. See
-[Session titles](sessions.md#session-titles).
+message; a continue's next link keeps it. In the web, `✎` next to the session's
+title (its strip card, or the top bar) does it. See [Session titles](sessions.md#session-titles).
 
 A `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
@@ -895,7 +895,12 @@ nudged the model") show ahead of those calls for about 4 s, as their rows
 wait in the closed block. A card that needs you (a question, an approval, check-in)
 sits in the stage too. While a question or approval waits, the stage shows
 the whole text of the reply that asked it (in place of its newest
-sentence) above the card, until you answer. Once answered, the model's
+sentence) above the card, until you answer. A long reply that asks the
+model's own question (one that doesn't fit that slot) gets more room: the
+stage grows to about 85% of the page for the rest of the turn (never above
+the session panel), the reply reads from its start in the stage's one
+scroll, and while the card is out of view a `❓ Answer ↓` pill at the
+stage's bottom edge takes you to it. Once answered, the model's
 question or its own approval keeps that reply (a delegate's relayed
 approval, a hook's question and the step limit don't): two muted lines
 under its `question → answer` line, the whole text when you open the card,

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

@@ -56,6 +56,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N, restarted: true (only on the first fire after a dropped stream was asked again) }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
+| `:question_asked` | A question of the model's own (`ask_user_question`) or an approval of its tool call is about to open, on the turn's thread (not a hook's or plugin's `ask_user`, a relayed delegate approval, the step-limit question, a `--non-interactive` run or a stored approval: none of those fire it) | `{ type: :question_asked, kind: "question" \| "approval", text: "..." (the reply that asks, as the asking slot shows it: no thoughts, no tool-call markup), question: {...} (the question's fields, frozen: question/options/header…, an approval's approval: facts too; no id yet), refs: (see [Refs on a question](#refs-on-a-question-display-only)) }` |
 | `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (the text the model gets: capped at max_tool_output_chars; a cut one has a [cut: …] line, at its end, or for an execute result between its head and its tail, the whole output saved in the session's tool_output/ folder), status: "ok" \| "error" \| "blocked" \| "stopped", call: {...} (the call that ran, as the gate left it), elapsed_ms: N (the tool's own run, without an approval wait; nil for a denied call), result: "..." (the tool's own text: no "[read]" lead, no "ran as:" line, never cut) }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped. Match on `result:`, not `output:`: it is what the tool said (`Error: command timed out after 120s` for an execute killed at its limit in kill mode, `Samagotchi::Tools::Execute::TIMEOUT_PREFIX`; `Still running at the 120s limit: …` for one handed over as a task, `Samagotchi::Tools::Execute::HANDED_OVER`) |
 | `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
@@ -366,6 +367,58 @@ end
 
 A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:refs].call(…) }`.
 
+## Refs on a question (display only)
+
+`:question_asked` carries `refs:` too, for the reply that asks the question: a
+ticket the model names while it asks is a ref while the question waits, when
+the user needs it.
+
+```ruby
+class JiraQuestionRefs
+  def call(event)
+    return unless event[:type] == :question_asked
+
+    event[:text].scan(/\b[A-Z][A-Z0-9]+-\d+\b/).uniq.each do |key|
+      event[:refs].call(match: key, kind: "issue", target: { id: key }, label: key,
+                        actions: [{ id: "open", label: "Open in Jira", url: "https://jira.example.com/browse/#{key}" }])
+    end
+  end
+end
+```
+
+- The call, its return values, the checks and the `refs_rejected` log are
+  [Refs on the answer](#refs-on-the-answer-display-only)'s, with lower caps:
+  50 refs and 32 KiB per step. `nil`: the turn has no model step to attach to,
+  or the call came after the hooks ran.
+- They are kept as `display_refs` on the step's model message (the one that
+  asks; in the session file after the turn, a cancelled one too) and go on the
+  pending question as its `refs` (the `question_requested` event, the session
+  file while it waits, the saved question card). A second question in the same
+  step adds to the step's list, and its pending question has the whole list.
+  The model never sees them.
+- The web checks them again wherever a saved one reaches it (the pending
+  question, a saved card, the history), as an answer's, and pairs them as an
+  answer's (the three passes above) in: the stage's asking slot while the
+  question waits (its raw text, then again once its markdown is in), the
+  card's question text, the answered card's kept reply (raw, then its
+  markdown when opened; never its one-line summary copy), and that step's
+  text in the history, live (at the turn's end) and after a reload. A ref
+  whose `match` is only in the question's text pairs there alone; the step's
+  text drops it. **Terminals** ignore them.
+- **Its time is the question's wait**: the hooks run before the question
+  opens, so a slow one delays it (and counts in `ask_user_question`'s
+  `elapsed_ms` and an approval's `waited_ms`). A hook that raises is logged and
+  the question opens with the other hooks' refs. With no hook on the event
+  nothing is built.
+- Don't ask from it: `event[:ask_user]` (and `ctx.ask_user` in a `chi.on`
+  block) returns nil at once here.
+- Needs chi newer than 0.97.0: set `requires_chi`.
+
+A plugin gets the same from `chi.on(:question_asked) { |event, ctx| event[:refs].call(…) }`. The bundle test
+kit fires it as chi does: `bundle.question_asked(text, kind:, question:)` returns the refs the step gets
+([plugins.md](plugins.md#testing-a-bundle-experimental)). The shipped source-links bundle subscribes (its
+sources' refs in the reply that asks, and in the question's text and options).
+
 ## Settings
 
 A hook class whose `initialize` takes an argument gets its settings: **one
@@ -557,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)
 
@@ -599,6 +657,12 @@ Notes:
 
 - Hook key = basename (flat under `hooks/`). No subdirs in v1.
 - `event` is required for auto-registration; a hook with no event is skipped.
+- `events: [after_turn, question_asked]` (a list, in place of `event:`) registers the hook for each event it
+  names: **one** instance serves them all (its state is shared), and `#call` tells them apart by
+  `event[:type]`. `event:` and `events:` together, or an `events:` that isn't a non-empty list of event names,
+  is refused at install (`hooks: <file>: …`). `on_error: fail_closed` applies to its `before_tool_call`
+  registration only. Needs chi newer than 0.97.0 (an older chi installs the hook with no event and never loads
+  it): set `requires_chi`.
 - `sha256` is integrity (not authenticity). No signing in v1. Install records the sha256 of the copied file; at `Engine.new` a hook whose file differs is not loaded (reinstall the bundle after editing one by hand).
 - Hook code is the bundle author's source of truth: on upgrade, hooks are overwritten; if the installed file was locally modified, a warning is emitted (`was locally modified; overwriting`).
 - `on_error` defaults to `skip` for every event, `:before_tool_call` included: a raising hook is silent and the call goes ahead. `log` warns. `fail_closed` (only on `:before_tool_call`; on any other event it acts as `skip`) denies the call the hook raised on. Choose `fail_closed` for a hook that is a guardrail, whose failure should stop tool calls rather than let them through.

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/bundles.md

@@ -37,7 +37,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
 | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
 | `Provenance` | the `.bundles/<name>/` dir: `#write` the record + bases, `#record` → `InstalledBundle`, `.each_installed`, `.claimants` (which bundles own a file) |
-| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty) |
+| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty). `BundleHook#events` is the manifest's `event:` or its `events:` list (written back as `event:` for one, as an older chi reads it); `Hooks::BundleLoader#load_hook_file` builds the hook once and registers it under each |
 | `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
 | `Profile` | meta bundles (`includes:`): install the members, record which; `InstallResult#kept_own` names a new member's memory files the user already had, with other bytes (`kept_own_line`, printed by `chi bundle`, `chi update` and `chi bootstrap`); a dry run runs each member's Installer as a dry run too, so it names them as well |
 | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |

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)
@@ -594,6 +604,23 @@ logged). Both are display only: `AnswerDisplay::DISPLAY_ONLY` lists `display`, `
 after_generation), while `KernelLoop#sanitize_history` and `ChatLoop#plain` copy them so the stored conversation keeps
 them across turns. `Web::App#messages_for_display` sends `display_refs` re-validated (`AnswerRefs.for_display`).
 
+`:question_asked` (`QuestionAsked`, `question_asked.rb`) fires from the two Engine seams where a question of the
+model's opens, never from `QuestionDesk`: `Engine#request_question` (the kernel's `question_handler`, after
+`AskUserQuestion.validate`; not with `interface == :non_interactive`) and the guardrail wiring's `ask:` lambda
+(`GuardrailWiring#request_approval`, after a stored approval and the non-interactive deny). So `ask_for_hook`, a
+relayed approval (`EnginePeers#open_question` → `Engine#open_question`) and `post` (the step-limit question) never
+fire it. `QuestionAsked.fire` is a no-op without a subscriber (`Registry#any?`); else it finds the live
+conversation's last `role: "model"` entry (`Engine#live_conversation`, one lookup for both loops: a ChatLoop batch may
+end in a tool result), builds an `AnswerRefs` on that step alone with the question caps (50 / 32 KiB), fires with the
+step's text (`Engine#question_step_text`: the parser's thought and tool-call strip, then
+`OutputFormatter.strip_markup`), a frozen copy of the fields and a no-op `ask_user`, then sets `display_refs` on
+the step **in place** under the event lock (the loops and the forget layer hold entries by identity) and returns the
+fields with `refs:`. `QuestionDesk#request` forwards `refs` past its slice; `PendingQuestion#refs` carries them to
+`:question_requested`, the session file and the cards. `Web::App#with_question_refs` re-validates them (the pending
+question, `cards_for_display`) with the same caps; the page pairs them in the asking slot, on the card and on the
+step's text ([architecture.md](../architecture.md), the `display_refs` paragraph). The kit's
+`Testing::Bundle#question_asked` calls `QuestionAsked.fire` with a one-step conversation.
+
 ### Hook lifecycle
 
 - **Bundle hooks** (`Registry#register_bundle`) and **config hooks** (`register_persistent`, from config.yml)
@@ -756,6 +783,7 @@ Paths are under `lib/samagotchi/`.
 | `toolkit_binding.rb` | `ToolkitBinding`: the Engine's toolkit seam (the kits, `#explained`, `ctx.use_toolkit`, the turn-start `#apply!` behind `Engine#apply_toolkit!`) |
 | `hooks/registry.rb` | Hook registry, fire order, `Hooks::Runtime` |
 | `hook_routes.rb` | `HookRoutes`: the Engine's routes for a hook's or plugin's notice (`:hook_notice`, `fallback_for:`), question, stop and steer, and the guardrails' after-load line |
+| `question_asked.rb` | `QuestionAsked`: the `:question_asked` fire, the asking step's refs (`display_refs` in place, the pending question's `refs`) |
 | `question_desk.rb`, `pending_question.rb`, `question_answer.rb` | `QuestionDesk`: the one open question (ask, post, answer, cancel, relay mark); `PendingQuestion` and `QuestionAnswer`, its values (Hashes only in events, Bridge JSON, the session file and the hook/plugin `ask_user` result) |
 | `hook_question.rb` | `HookQuestion`: a hook's or plugin's `ask_user` question as one value, from the runtime/host edge to `QuestionDesk#ask_for_hook` |
 | `event_routes.rb` | `EventRoutes`: where a card (`Engine#show_card`), a notice (`HookRoutes#notify`) and a guardrails line (`#guardrail_notify`, turn or between turns only) go: held while the plugins load, an anytime command's, an init task's, a running turn's event, else announced or held for `holding_announcements` |

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.