samagotchi 0.67.0 → 0.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f42be965113cdd1f5736f77b9a5be8e9fbd77088b4a2013f9b7e86ae7ceb12
-  data.tar.gz: a093f0921d62e84c9e6c34ac10482e57e9e041a5a9d21eda41a88052e819cda1
+  metadata.gz: 5ef7820f894e85b932288a38a22e1f312e01b5f4f1d100996acde11443baab19
+  data.tar.gz: 44f15fe12934aa7c56bff657e8b93a1d0165a752bcf0715f71cb04bb17ed7ac6
 SHA512:
-  metadata.gz: d02e8644b724765182cabb9a74eafcfaec94eb13781680e29cc33bfb1ee2bc850f55a7df4117b61d8a2889c7d48bf4792b88ba316676a1fb6be5632cc98d1a3f
-  data.tar.gz: a4397b9a00729a4eb230415e265c834f85f42b8b6ded242dc3c981ad6f3e543f367d7a9df00ed6d516aef12c2e2266a765b0f66c7025f575975c83fd4b556b86
+  metadata.gz: 38d2aebcc7f777a40ceb1f0008c0160fd374541ff97b74b44ba0d61611cf7e2a103a4398571327b26cd7ffa80d564a552166d74ecfca172788483b1b43d166c7
+  data.tar.gz: 64a08c7808f2a9d58cbd5135ebadef7f59157876d738c16a3b6793c9b424f8a6dca90454ea961672ce0e14a71f809026ac49ba51d1db0b1ff4389073a06fbd4e

data/CHANGELOG.md

@@ -8,6 +8,65 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.69.0] - 2026-10-14
+
+### Added
+
+- Web: a new chain link (continue →) shows the model picker in its composer until its first turn, so the next link can
+  start on another model or provider; the continue toast shows the fallback warning when the previous model's host is
+  gone.
+- Built-ins a session's toolkit leaves out are reachable: `find_tools` searches them (group `chi`) beside MCP
+  servers' tools, and `call_tool` runs them through the usual guardrails as the real call. `remove:` /
+  `--no-tool` / `/toolkit remove` stay hard.
+
+### Changed
+
+- find_tools' description and its `server` parameter (now `group`) changed: sessions with MCP servers read their
+  prompt again once. So do sessions on `lean`, `child`, `coordinator` or a kit based on them: they now declare
+  `find_tools` and `call_tool`, and their not-loaded line changed.
+- A toolkit based on `lean` or `child` (a `toolkit.kits` entry, a bundle's `chi.toolkit`) no longer keeps the
+  built-ins its base leaves out from the model: they're reachable through `find_tools` / `call_tool`, guarded as
+  themselves. Name one under `remove:` to keep it out.
+- Guardrail rules on `call_tool` no longer see calls of chi's own tools made through it; they match the tool's own
+  name.
+- Shipped bundles: a change that needs a newer chi marks the manifest `requires_chi_next` instead of raising
+  `requires_chi`; `rake release:bump` raises it to the released version and `rake release:check` fails on a marker
+  left over.
+- `/toolkit remove X` on a tool the toolkit leaves out is saved (it makes X unreachable). `/toolkit add X` then
+  `/toolkit remove X` now removes X (it used to go back to the kit's default), and a remove then an add declares X.
+- The `child` toolkit also removes `delegate` and `delegate_result`: a child on it can't start children, even
+  through call_tool.
+
+### Fixed
+
+- A TLS handshake blip on a gateway (`SSL_connect … unexpected eof`, a reset mid-handshake) is retried like other
+  network errors instead of failing the turn at once; a certificate chi doesn't trust, a certificate for another
+  name, or an `https://` base_url on a plain HTTP port fails at once, saying what to check (`SSL_CERT_FILE`, the
+  host's base_url).
+- A bundle tool named like an MCP tool (`mcp_fs_read`) no longer takes `call_tool` calls of that MCP tool out of
+  `mcp_*` rules.
+- Web: on a phone the start page's model, thinking and LLM context chips wrap instead of being cut short; a toast no
+  longer covers a fresh link's open model panel; the family popover's status dots keep pulsing in step.
+
+## [0.68.0] - 2026-10-14
+
+### Changed
+
+- Web: the settings popovers' selects (thinking level, LLM context strategy and apply) look the same in Safari, Chrome
+  and Firefox: chi's own box and caret instead of each browser's native control.
+- Web: the thinking chip comes before the LLM context chip, on the session bar (think, reasoning, llm ctx, tools) and
+  beside the start page's model picker.
+
+### Fixed
+
+- `/model` while the web or another terminal read `/stats` no longer leaves the new model on the old model's prompt
+  profile (its turns formatted for the wrong family until the next `/model`).
+- Web: the sessions strip no longer blinks when a session updates: a card fades in only when it is new to the list,
+  and a running or waiting card's dot keeps its pulse through the redraw. All sessions no longer re-fades on every
+  update or search keystroke either.
+
+Update with `chi update` (the system bundle 0.68.0), then restart `chi web`.
+
 ## [0.67.0] - 2026-10-14
 
 ### Added
@@ -2937,7 +2996,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.67.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.69.0...HEAD
+[0.69.0]: https://github.com/dm1try/samagotchi/compare/v0.68.0...v0.69.0
+[0.68.0]: https://github.com/dm1try/samagotchi/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/dm1try/samagotchi/compare/v0.66.0...v0.67.0
 [0.66.0]: https://github.com/dm1try/samagotchi/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/dm1try/samagotchi/compare/v0.64.0...v0.65.0

data/docs/architecture.md

@@ -400,7 +400,9 @@ by one pure resolver, `ModelRef.parse` (host prefix, alias), given the configure
 hosts and aliases; `HostRegistry` routes a name that names no host (its model
 index after `/models`) and builds the `ModelTarget`.
 
-Engine picks the loop from the effective model's host (`HostRegistry#resolve`):
+Engine picks the loop from the effective model's host: `EffectiveModel.of` resolves it (`HostRegistry#resolve`)
+on every read, never kept, since config.yml and a model listing can move it without a `/model`
+([internals/engine.md](internals/engine.md), "EffectiveModel"):
 
 | Loop | Class | Host | Talks through |
 |---|---|---|---|
@@ -450,7 +452,7 @@ message (docs/internals/context-telemetry.md).
 `HostRegistry#adapter_for`, built by `LLM::Adapters` from the host's api) share
 `LLM::HTTP`: timeouts, TLS for https, a line reader for streamed bodies, the retry loop (`retry.*`; network errors, 429 and
 500/502/503/504/529, honouring `Retry-After`; never after a stream has produced
-output) and cancel. Cancel closes the in-flight socket from the
+output; a refused connection and a TLS handshake that can't work, `LLM::TLSError`, fail at once) and cancel. Cancel closes the in-flight socket from the
 `CancellationController` listener, so it works on any thread.
 
 `LLM::AnthropicMessages` talks Anthropic's Messages API (`POST {root}/v1/messages`) for the same chat loop:
@@ -496,7 +498,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 
 | Component | Main file(s) | What it is |
 |---|---|---|
-| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). |
+| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources ([plugins.md](plugins.md)). |
@@ -515,7 +517,8 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | 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; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | 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. |
-| Model settings | `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | A model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |
+| Model settings | `effective_model.rb` (`EffectiveModel`, `ModelChoice`), `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | The effective model's settings as one snapshot per read, a model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |
+| Session settings | `session_setting.rb` (`SessionSetting`), `level_setting_command.rb` (`/thinking`, `/reasoning-history`), `llm_context_command.rb`, `toolkit_command.rb`, `thinking_notices.rb` (`ThinkingNotices`) | A session's own llm_context, thinking, reasoning_history and toolkit: their chips (session state, `/stats`, `:command_ran`, the web), the commands that set them, the thinking level's notices. |
 | Dialects | `llm/dialect.rb` (`LLM::Dialect`) | What an `api: anthropic` provider's `/v1/messages` does differently (`dialect: fireworks`) ([internals/anthropic.md](internals/anthropic.md)). |
 | Logging | `log.rb` (`Log`), `log_subscriber.rb` (`LogSubscriber`), `log_path.rb` (`LogPath`), `log_line.rb` | The debug log: tagged records, a session's event trail, where the file goes ([configuration.md](configuration.md#debug-log-file)). |
 | Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |

data/docs/cli.md

@@ -517,7 +517,12 @@ line, the web as the `reasoning` chip. See "Reasoning history" in
 [configuration.md](configuration.md).
 
 `/toolkit` lists the tools the next turn declares (each with its estimated
-tokens), the session's toolkit and the tools it leaves out. `/toolkit NAME` puts
+tokens), the session's toolkit and the tools it leaves out: `reachable
+(find_tools): …` (built-ins the model reaches with find_tools and call_tool)
+and `removed: …` (only `/toolkit add` brings one back), or `not loaded: …` when
+the toolkit removes call_tool. `/toolkit remove TOOL` is hard: a tool the
+toolkit left out reachable becomes unreachable (saved, and asked first once the
+session has a model reply), also after an add. `/toolkit NAME` puts
 the session on another toolkit (dropping its own adds and removes); `/toolkit
 add TOOL` and `/toolkit remove TOOL` change one tool (a tool's name keeps its
 case). The change is saved at once and applies from the next turn's start; a

data/docs/configuration.md

@@ -988,8 +988,8 @@ Transient network failures are retried automatically with exponential backoff.
 
 - Default retries: `5` (up to `6` total attempts including the first call).
 - Default backoff: `0.5s`, `1s`, `2s`, `4s`, `8s`.
-- Retry scope: transient network errors (timeouts, reset connections, EOF/socket reachability failures),
-  HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
+- Retry scope: transient network errors (timeouts, reset connections, broken pipes, EOF/socket reachability
+  failures, a TLS handshake that drops: `SSL_connect … unexpected eof while reading`), HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
   60s is not waited out and the error is reported instead.
 - An HTTP 402 about credit held by in-flight requests (OpenRouter reserves credit for each running request, so
   one session's long request can make another's fail) is retried like a 429, 20s apart unless `Retry-After`
@@ -998,6 +998,11 @@ Transient network failures are retried automatically with exponential backoff.
   budget, so it fails at once (lower `default.max_tokens` or raise the key's limit).
 - A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
   <address> (connection refused) — is the server running?`.
+- Nor is a TLS handshake that can't work, which fails at once saying what to check: a certificate chi doesn't
+  trust (`certificate verify failed (self-signed certificate)`, `unable to get local issuer certificate`, an expired
+  one: set `SSL_CERT_FILE` to a CA bundle that has the gateway's CA), a certificate for another name (`hostname
+  mismatch`: check the host's `base_url`), or a server that doesn't speak TLS there (`wrong version number`: an
+  `https://` base_url on a plain HTTP port; should it be `http://`?).
 - A stream that has already produced output is never retried at the transport (the retry would repeat it). The
   chat loop (an OpenAI-compatible host) drops the partial reply and asks again for the whole step, from the same
   conversation, at most twice (at most `retry.max` times when that is smaller: `retry.max: 0` turns it off), after
@@ -1331,7 +1336,7 @@ toolkit:
 |---|---|
 | `full` | every built-in; the default |
 | `lean` | `execute`, `read`, `write`, `edit`, `memory_read`, `memory_write`, `task_create`, `task_wait`, `task_get`, `task_list`, `task_stop`, `ask_user_question`, `web_fetch`, `context_read` |
-| `child` | `lean` plus `send_note`, without `memory_write` |
+| `child` | `lean` plus `send_note`, without `memory_write`, `delegate`, `delegate_result` |
 | `coordinator` | `lean` plus `delegate`, `delegate_result`, `list_sessions` (declared by the coordinator bundle) |
 
 - **Plugin tools** are declared in every toolkit unless its `remove:` names them, and so is `forget_outputs` under
@@ -1342,9 +1347,26 @@ toolkit:
   for a delegate child, or `chi --toolkit NAME` / `--tool` / `--no-tool` ([cli](cli.md)). Changing `toolkit.default`
   doesn't move existing sessions, not even when their worker is woken again; a session from before toolkits is on
   `full`. A continue and a fork keep the toolkit. `/toolkit` shows and changes it.
-- **Not loaded.** When a toolkit leaves tools out, one line after the base prompt names them (`Not loaded in this
-  session (toolkit lean): …. Only the user can load one (/toolkit add <name>).`). A call to one is refused before
-  the guardrails (no approval card): `Error: delegate isn't loaded in this session (toolkit lean) …`.
+- **Left out: reachable or removed.** A built-in missing from a kit's base list (`lean` has no `delegate`; a
+  `kits:` entry on `base: lean` or `child` inherits that) is left out softly: it is **reachable**. `find_tools` searches it as group `chi` (`chi/delegate`, with its inputSchema) beside
+  the MCP servers' tools, and `call_tool(tool: "chi/delegate", args: {…})` runs it as `delegate` itself, through the
+  usual guardrails, approvals and hooks ([plugins](plugins.md#chitool_sourcecall-acts_as-label-wait-prefix)). A
+  tool in a toolkit's `remove:`, a `--no-tool` or a `/toolkit remove` is **removed**: hard, also after an add, and
+  call_tool can't reach it (`child` removes `memory_write`, `delegate` and `delegate_result`, so a child on it
+  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.
+- **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
+  call_tool(tool: "chi/<name>", args: {…}).` instead. With `call_tool` itself removed, nothing is reachable and one
+  line names them all: `Not loaded in this session (toolkit lean): …. Only the user can load one (/toolkit add
+  <name>).`
+- **Calls by name.** A direct call of a reachable tool is refused before the guardrails (no approval card), with
+  the route: `Error: delegate isn't declared in this session (toolkit lean); call it with call_tool(tool:
+  "chi/delegate", args: {…}) (find_tools gives its inputSchema).` A removed tool's: `Error: memory_write isn't
+  loaded in this session (toolkit child) and can't be loaded from here; only the user can (/toolkit add
+  memory_write).` `/toolkit` lists both kinds, and the web's toolkit chip says them in its tooltip.
 - **Applied at a turn's start.** A change (`/toolkit`, a plugin's `ctx.use_toolkit`) is saved at once and the next
   turn declares it; once the session has a model reply, `/toolkit` asks first ("Changes that restart the prompt
   cache").

data/docs/guardrails.md

@@ -303,7 +303,7 @@ A plugin tool that runs other tools for the model (a dispatcher such as
 and with which arguments (`args:`). A rule's `tool:` then matches the call's
 own name **or** the tool it acts as: `tool: mcp_github_*` fires for a
 `call_tool` that acts as `mcp_github_merge_pull_request`, and `tool: call_tool`
-fires whatever it acts as. The question names the tool it acts as (by the
+fires whatever MCP tool it acts as. The question names the tool it acts as (by the
 `label:` its `targets:` gives, if any: display only) and shows its arguments, and an approval of "this call" is keyed by the real name, the
 alias and those arguments (`/guardrails` lists it as
 `call_tool>mcp_github_merge_pull_request:number=7 …`), so it never covers a
@@ -313,6 +313,28 @@ one of chi's own tools or another bundle's tool: that `acts_as:` is dropped
 name only. Hooks and loop-guard's `ignore_tools` still see the call's own
 name.
 
+chi's `call_tool` is exempt from the "another bundle's tool" drop (not the
+core-tool one): its `acts_as` is always a tool its sources published, so a
+bundle tool that happens to share an MCP tool's `mcp_<server>_<tool>` name
+can't take `call_tool` calls of that MCP tool out of your `mcp_*` rules. The
+trade-off, when such a clash exists:
+- an `allow` or `ask` rule by that name matches both the bundle tool and the
+  MCP call;
+- a `rule`-scope approval ("always for this rule") covers both, because it
+  matches by rule, source and place, not by tool;
+- `session` and `repo` approvals stay distinct (`call_tool>mcp_x:…` vs
+  `mcp_x:…`);
+- deny rules cover both, which is the point.
+
+A `call_tool` of one of chi's own tools (`chi/delegate`: a built-in the
+session's toolkit leaves out, [toolkits](configuration.md#toolkits)) is
+gated **as that tool**: it is turned into the `delegate` call before the
+guardrails run, so every rule on `delegate` (or `execute`'s `command:`, the
+`rm` check, a delegate child's boundary) gives the same verdict as for a
+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.
+
 ```yaml
     - id: mcp-ask
       # every MCP call (call_tool, acting as mcp_<server>_<tool>); not a find_tools search.

data/docs/hooks.md

@@ -536,6 +536,10 @@ A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
 arguments whole on `args:` (string keys) instead, and its `content:` is those
 arguments as JSON. An MCP tool's call is chi's `call_tool` (its tool index's, which the mcp
 bundle runs): `tool: "call_tool"`, with `args: {"tool" => "<server>/<tool>", "args" => {…}}`.
+A built-in reached through `call_tool` (`chi/delegate`, a tool the session's toolkit doesn't
+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.
 
 ## Bundle Hooks (unified workflow bundle)
 

data/docs/internals/bundles.md

@@ -24,7 +24,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 |---|---|
 | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash`; runs the Installer, prints its summary, runs the conflict agent step |
 | `SourceNormalizer` (source.rb) | source → local dir; a git/zip/tar extract is *owned* and removed after the install |
-| `Manifest` | parses/validates `manifest.yml` (files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers) and writes it (`Manifest.write`, for Builder) |
+| `Manifest` | parses/validates `manifest.yml` (files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
 | `Installer` | one install/upgrade/dry run of one bundle (below) |
 | `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` |

data/docs/internals/engine.md

@@ -34,20 +34,23 @@ 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 is set in generate),
+  │     #   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, a prompt rebuild when it changed)
+  │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, ToolIndex#refresh! for find_tools'
+  │     #   chi line, a prompt rebuild when it changed)
   │     # 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
   │     # 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:)
-  │     # sync_kernel_client!, then @kernel.turn_settings = turn.settings with model_name, window_setting,
-  │     #   llm_context (turn_llm_context: the session's, the model's/host's, else llm_context.strategy)
-  │     #   and price (turn_price: hosts.<name>.models.<id>.price), all read per turn
+  │     # one EffectiveModel (after the hooks, which may switch the model): sync_kernel_client!, then
+  │     #   @kernel.turn_settings = turn.settings with model_name, window_setting, llm_context (the
+  │     #   session's, the model's/host's, else llm_context.strategy) and price
+  │     #   (hosts.<name>.models.<id>.price), all read per turn
   │     # turn.limit = max_iterations or IterationLimit.for
-  │     # backend.complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
+  │     # backend(model).complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
   │     # Returns LLM::ModelResult (text, conversation, canceled?, exhausted?, tool_activity,
   │     #                          context_status, empty_steps, empty_retries)
   │
@@ -118,6 +121,16 @@ A worker's TERM, HUP or INT (WorkerSignals, trapped by a spawned worker only):
      loop left brings only that hard exit, and run_session_loop restores the default handlers
   → run_session_loop: exit 0, no discard; input queued behind the stopped turn wakes a new worker
 
+The effective model doesn't resolve (a broken host config, HostRegistry#resolve raising):
+  → the rescued readers give their fallback (Engine#model_setting) and log effective_model_unresolved;
+     a setting that fails on a resolved model gives its fallback and logs <setting>_unresolved
+     (sampling, thinking, reasoning_history, steer_cut_after, llm_context, window, price, served,
+     vision_adapter); served_probe_failed when asking the server for its served model fails;
+     alias_note_failed, thinking_notice_failed likewise
+  → WARN once per process for an (event, model, error class), DEBUG after (EffectiveModel::Unresolved)
+  → session_state_snapshot never raises (its model fields are nil); a turn, stats_snapshot,
+     chat_model? and system_prompt raise, as before
+
 Stopped before the model was asked (prepare_turn returned false):
   → stopped_before_model(turn) → end_turn(turn, "canceled")
   → nothing kept, :turn_canceled {cancellation_reason, cancelled_by, duration_ms}
@@ -129,7 +142,7 @@ Stopped before the model was asked (prepare_turn returned false):
 The Engine does not talk to models directly. `Engine#backend` picks the loop the effective model's host speaks:
 
 ```
-Engine#backend → backend_for(@host_registry.resolve(@effective_model_name))
+Engine#backend → backend_for(effective_model)    # EffectiveModel.of(@host_registry, @model_choice)
   → host entry chat? (an api in LLM::Adapters::BY_API: openai, anthropic): LLM::ChatLoop (one per Engine, built on first use)
   → else:                                                     LLM::NativeBackend wrapping the Engine's KernelLoop
 ```
@@ -243,8 +256,11 @@ 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:)
-          → a tool the session's toolkit leaves out (Registry#left_out) skips the gate: no hooks, no card;
-            KernelLoop#dispatch answers it with the not-loaded error
+          → 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)
           → 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)
@@ -261,11 +277,13 @@ One iteration with tool calls:
 ```
 
 **ToolRunner** (`ToolRunner#run`):
+- Unwraps a call_tool of a built-in first (`Registry::Entry#unwrap`), so `original`, the params and the label
+  are the built-in's and no "ran as:" line follows.
 - Runs the gate first, so `:tool_call_started` shows the call that will run (a before_tool_call hook may
   replace it; known-names corrects a misspelled name this way, and the model gets one line saying what ran).
 - Emits `:tool_call_started` {iteration, call_count, call_index, tool, call, params, label (plugin tools),
-  title, called_as, view, ref, refs}. The row fields (title, called_as, view, ref) come from `ToolRowFields.for`, which the
-  reload (`Web::MessageParts#tool_part`) calls too. `ToolRowFields::ACTIVITY_KEYS` (title, called_as) travel
+  title, called_as, via, view, ref, refs}. The row fields (title, called_as, via, view, ref) come from `ToolRowFields.for`, which the
+  reload (`Web::MessageParts#tool_part`, after `BuiltinCalls.unwrap_saved`) calls too. `ToolRowFields::ACTIVITY_KEYS` (title, called_as, via) travel
   inside `activity` on the completed event; `EVENT_KEYS` (view, ref, refs) go top-level on both events.
   `Bridge::TurnAccumulator` (snapshot and replay) and the web (`activity.js` `ACTIVITY_FIELDS` /
   `EVENT_FIELDS`) copy them by these lists, so a new row field is added there. `ref` is `FileRef.for` (a
@@ -326,6 +344,38 @@ TurnState
 
 The lock is a leaf: nothing is called out while it is held.
 
+### EffectiveModel (a snapshot per read)
+
+`EffectiveModel.of(registry, choice)` resolves the model once (`HostRegistry#resolve`: host, client, the id
+sent) with its lookup names, and reads each setting from them (sampling, thinking, reasoning history, steer cut,
+LLM context, window, price, served model, vision, profile). It is built per read and never kept: config.yml is
+read live, a model listing can move a bare id to another host, and another process's saved model lists change
+what a resolve gives, all without a `/model`. Frozen, so any thread may hold one.
+
+- The Engine's readers take one (`Engine#effective_model`); those whose fallback always covered the resolve go
+  through `#model_setting`. A turn takes one in `turn_settings` (before the hooks) and one in `generate` (after
+  them); `system_prompt`, `steer_cut_after` (at `:turn_started`) and the turn-end warm-up take their own;
+  `stats_snapshot` and `session_state_snapshot` take one each (the latter nil-tolerant).
+- Never resolved (they hold on a broken resolve): `effective_model_ref`, `bare_model_name`,
+  `guardrail_model_name`, `sync_model_key!`, `served_model(probe: false)` (`HostRegistry#model_ref`/`#bare_name`).
+- Readers on other threads: the Bridge (`/state`, `/stats`, the SSE reset, a steer's cut wait), the worker's
+  command thread, the recap thread and plugin threads (`session_model_recap_target`), the REPL.
+- `ModelChoice` (`@model_choice`) holds the name and the typed name as one value, so a reader on another thread
+  never pairs one model's name with another's typed name.
+- `EffectiveModel.of_session` builds a saved session's (no worker): `Web::App`, `LLMContextStrategy.for_session`.
+
+`SessionSetting` names the four per-session settings (llm_context, thinking, reasoning_history, toolkit): the
+session's own value, the commands that move each chip, its chip from an EffectiveModel or from the Engine's
+readers, a saved session's chip, and how the web takes a worker snapshot's. The session state, `/stats` (no
+toolkit), a `:command_ran` and the web's session JSON list them from it.
+
+### ThinkingNotices
+
+What a turn's thinking level leads to, said once per session and host (`thinking_notices.rb`): an effort the
+host can't do, off the model didn't honour, a host refusing the thinking fields or the reasoning sent back. It
+keeps the turn's `[level, ModelTarget]` and whether the generation thought; `turn_settings` and the stream handler
+call it. Turn thread only.
+
 ### Turn (Engine::Turn)
 
 The turn as the Engine sees it (the KernelLoop has its own `Turn` struct):
@@ -435,16 +485,17 @@ hook registry (`@hooks.fire`), not on the sink or the observers. The other hook
 ```
 Engine initialization (in this order, among other things):
   @turn_state, @steer_cut (SteerCut: its GenerationPhase and WaitingSteer)
-  @host_registry, @effective_model_name; @client = @host_registry.resolve(...).client
+  @host_registry, @model_choice (ModelChoice: the name and the name as typed); @client = effective_model.client
   @given_profile = profile or nil (resolved on first need, so building an Engine makes no network call)
   @hook_routes (HookRoutes: notices, hook questions, stop_turn/stop_generation, steer attribution)
   @guardrail_wiring, @question_desk
   @toolkit_binding (ToolkitBinding: the kits, the plugins' among them, and the turn-start apply)
   @extension_load = ExtensionLoad.new; @hooks = @extension_load.hooks (config.yml's, then the bundles')
   @tools = Tools::Builtins.registry; the bundles' plugins load (load_plugins → ExtensionLoad#load_plugins),
-    then @tool_index.declare(@tools): find_tools + call_tool (source "index", not core) when a plugin
-    registered a chi.tool_source (Tools::ToolIndex: the index's groups, search, call checks; the source runs
-    the call with its own plugin Context)
+    then (plugins or not) @tool_index.declare(@tools): find_tools + call_tool (source "index", not core),
+    declared per toolkit by Registry#declared? (a source registered at load, or a reachable built-in) and
+    sets call_tool's unwrap (Tools::ToolIndex: the chi group from Registry#reachable_names, the sources'
+    groups, search, call checks, the unwrap; a source runs the call with its own plugin Context)
   wire_kernel: @kernel = KernelLoop.new(client:, profile:, hooks:, reminder_store:, tools:)
   @kernel.guardrail_gate = @guardrail_wiring.gate; @kernel.warmup = PromptWarmup.new
   @hooks.runtime = @hook_routes.runtime (HookRoutes, built first: what a hook or plugin does reaches the UIs)
@@ -453,8 +504,9 @@ Engine initialization (in this order, among other things):
   @session_observer with the metrics, the log subscriber and the thinking tails subscribed (subscribe_session_observers)
 
 Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
-  → checks the host (ModelProfile.check_host!), sets @effective_model_name
-  → drops the given profile and the profile resolution (resolved again on first need)
+  → checks the host (ModelProfile.check_host!), sets @model_choice (name and typed name in one assignment)
+  → drops the given profile and the profile resolution (resolved again on first need; one that another
+    thread finishes for the old model is neither kept nor applied: #store_profile)
   → sync_model_key!, @prompt_builder.reset! (the system prompt is built again)
   → sync_kernel_client! (the kernel talks to the new host), the context window cache dropped
   → the kernel is never rebuilt; the next turn's backend follows the new host's api
@@ -608,6 +660,10 @@ Paths are under `lib/samagotchi/`.
 | `turn_state.rb` | Cross-thread turn state (running, controller, sink, steers, activity clock) |
 | `steer_cut.rb` | `SteerCut`: the Engine's seam for a message cutting the generation |
 | `generation_phase.rb`, `waiting_steer.rb` | Whether a steer may cut the running generation, and the steer that waits to |
+| `effective_model.rb` | `EffectiveModel` (the effective model's settings, a snapshot per read; `.of_session`), `ModelChoice`, the fallbacks' log lines (`Unresolved`) |
+| `session_setting.rb` | `SessionSetting`: the per-session settings' descriptors (own value, chips, the web's fallback) |
+| `level_setting_command.rb`, `thinking_command.rb`, `reasoning_history_command.rb` | `/thinking` and `/reasoning-history` (`LevelSettingCommand` and its two Specs) |
+| `thinking_notices.rb` | `ThinkingNotices`: the notices a turn's thinking level leads to |
 | `steer_cut_after.rb`, `cut_policy.rb` | The model's cut wait (`SteerCutAfter.resolve`); the loops' cut path (`CutPolicy`) |
 | `steer.rb` | Queued input and steers at iteration boundaries |
 | `kernel_loop.rb` | Native loop: `#run` (format, generate, parse, dispatch, iterate) |

data/docs/internals/prompt-caching.md

@@ -25,13 +25,14 @@ right-hand column happens.
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ tools        built-ins, then plugin tools sorted by (bundle, name),      │  a tool added/changed,
 │              the tool index's find_tools/call_tool as bundle "index"     │
-│              (declared once at load; publishes change only results)      │
+│              (per toolkit; MCP lines from load, the chi line per toolkit)│
 │              those the session's toolkit declares (per toolkit)          │  /model, a profile change,
 │              (chat: the `tools` field; native: the model's template)     │  a toolkit change
 ├──────────────────────────────────────────────────────────────────────────┤
 │ SYSTEM, stable part                         SystemPrompt#system_prompt_with_index
 │   [native thinking token] base prompt                                    │
-│   not-loaded line (only when the toolkit leaves tools out)               │
+│   not-loaded line (only when the toolkit leaves tools out:               │
+│     not declared / removed)                                              │
 │   rg guidance                                                            │  /thinking level,
 │   system identity (+ model overlay)                                      │  /model, editing a
 │   model notes (model_notes_* matching the model)                         │  memory / AGENTS.md
@@ -70,6 +71,12 @@ right-hand column happens.
   beside `apply_staged_tools!`, then `reset!`): the chat loop builds `tools:` per request, so a mid-turn change
   would differ from the turn's prompt. Under `full` nothing is filtered and no line is added: the bytes are what
   they were before toolkits.
+- find_tools' description is a function of the toolkit and the source groups **at load**: `ToolIndex#declare`
+  snapshots the MCP groups' lines (name, summary, callable count) and `ToolIndex#refresh!` (from
+  `ToolkitBinding#apply!`) rebuilds only the `chi` line, the built-ins the toolkit reaches. An MCP server that
+  finishes booting between load and the first turn changes search answers only, so two sessions on the same
+  toolkit with the same MCP cache send the same bytes. Whether find_tools/call_tool are declared at all reads the
+  same two things (`Registry#index_needed?`), never live groups.
 - On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
   breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint
   #2, so the **next request in the session** reads everything up to it. Mid and tail system messages never take

data/docs/plugins.md

@@ -25,6 +25,8 @@ plugin:
   file: plugin.rb
   sha256: sha256:6a1a7022…   # shasum -a 256 plugin.rb
 requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2"); the bundle's hooks/ check it too
+# requires_chi_next: true    # shipped bundles only, ignored by chi: rake release:bump raises requires_chi
+                             # to the chi being released (docs/releasing.md)
 needs: [gh]                  # optional: outside commands it relies on (see memory.md#bundles-that-need-outside-commands)
 ```
 
@@ -294,6 +296,8 @@ is what `targets:` says:
   (chi's `call_tool`, which calls a tool a [source](#chitool_sourcecall-acts_as-label-wait-prefix) published). Rules keyed by that tool's name match the
   call too, as well as rules on the tool's own name. It can't be one of
   chi's own tools or another bundle's tool: that is dropped (and logged).
+  The "another bundle's tool" drop doesn't apply to chi's `call_tool`: its
+  `acts_as` is always a tool its sources published.
 - `args:`: the arguments it acts with (a Hash), when they aren't the call's
   own (a dispatcher's inner arguments). A call with no `command:` or
   `paths:` is asked about with them, and "allow this call" is keyed by them.
@@ -583,15 +587,32 @@ chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
 
 Tools the model reaches through a search instead of declaring them one by
 one: the plugin publishes them into chi's **tool index**, and chi declares
-two tools in all, whatever the number of sources: `find_tools` (a keyword
-search that answers each match's `inputSchema`) and `call_tool` (calls one as
-`<group>/<tool>`; its row label is the first source's `label`). They
-are declared once, after the plugins load, and only when a plugin registered
-a source: a session without one declares neither. Nothing a source publishes
-later changes the request's tools, only what a search answers, so the prompt
-cache keeps (the search tool's description lists the groups as they were at
-load). The mcp bundle is the only source so far (a group per server), and the
-texts speak of MCP servers.
+two tools in all, whatever the number of sources: `find_tools(query,
+group?)` (a keyword search that answers each match's `inputSchema`) and
+`call_tool(tool, args)` (calls one as `<group>/<tool>`; its row label is the
+first source's `label`). The index has one group of its own, **`chi`**: the
+built-ins the session's toolkit leaves out but doesn't remove
+([toolkits](configuration.md#toolkits)), each with its registered schema.
+The two tools are registered once, after the plugins load, and declared per
+toolkit: when a plugin registered a source then, or when the toolkit has a
+reachable built-in (`full` with no source declares neither). Nothing a
+source publishes later changes the request's tools, only what a search
+answers, so the prompt cache keeps: the search tool's description lists the
+source groups as they were at load, and a `chi` line first, per toolkit.
+The mcp bundle is the only source so far (a group per server). A source's
+group named `chi`, or named like an earlier group, is left out of search,
+lookup and the description, with one warning per name.
+
+**A built-in through `call_tool` runs as that built-in.** `call_tool(tool:
+"chi/delegate", args: {…})` (or a bare `delegate` while it's reachable) is
+turned into the `delegate` call itself before the guardrails, so rules on
+`delegate`, approvals (keyed `delegate:…`, the same as a direct call's),
+`before_tool_call`/`after_tool_call` hooks and the row see `delegate`, with
+`call[:via] == "call_tool"`; the row reads "delegate (via call_tool)", live
+and after a reload. `tool: call_tool` rules see MCP calls and misses only. A
+`chi/` name the toolkit removes or declares, or any built-in once
+`call_tool` itself is removed, is refused by its name before the guardrails
+(no hook, no card).
 
 ```ruby
 @source = chi.tool_source(label: "mcp", prefix: "mcp_",
@@ -621,7 +642,8 @@ index = Samagotchi::Tools::ToolIndex
   block returns (a String, a `ToolResult` with images).
 - **Guardrails** see a `call_tool` as the tool it calls: its `acts_as`, its
   arguments and `"<group>: <tool>"` as the question's label
-  ([acts_as:](#guardrails)). A call made before its tool is published is
+  ([acts_as:](#guardrails)), even when another bundle has a tool of that
+  name (only the core-tool drop applies). A call made before its tool is published is
   named by `acts_as` from the names alone; a bare name with `prefix` is
   taken as an `acts_as` as given. The `acts_as:` hook must give exactly the
   `acts_as` the source publishes for that tool: a call whose tool isn't the
@@ -632,11 +654,11 @@ index = Samagotchi::Tools::ToolIndex
   what the two tools take in every request (none when other tools had both
   names). A `Group` in a state other than the three, holding another group's
   tool, or a `Tool` with a blank `acts_as` raises `ArgumentError`.
-- `find_tools` and `call_tool` aren't chi's own tools: every toolkit declares
-  them (unless its `remove:` names them), as it does plugin tools. A bundle
-  that declares tools of those names itself (an mcp bundle before 0.7.0 has
-  `find_mcp_tools` and `mcp_call`) keeps them, and with no source chi
-  declares neither.
+- `find_tools` and `call_tool` aren't chi's own tools: a toolkit that needs
+  them declares them (unless its `remove:` names one; `call_tool` stays
+  usable with `find_tools` removed). A bundle that declares tools of other
+  names itself (an mcp bundle before 0.7.0 has `find_mcp_tools` and
+  `mcp_call`) keeps them; with no source, `full` declares neither of chi's.
 
 ### `chi.peer_source(name, label:)`
 
@@ -1064,7 +1086,7 @@ bundles:
 
 - **Tools: search, then call.** The servers' tools are kept in chi's tool index;
   the model has two fixed tools:
-  - `find_tools(query, server?)` searches it by keywords over the
+  - `find_tools(query, group?)` searches it by keywords over the
     server's name, the tool's name and its description, and answers up to 5
     tools, each with its name `<server>/<tool>`, its description and its
     whole `inputSchema`. A word counts more the fewer tools have it (a word
@@ -1089,7 +1111,7 @@ bundles:
     `args` are typed by the tool's
     `inputSchema` (numbers and booleans given as text, JSON text for an
     object). A name it doesn't know answers the closest ones (`Error: no
-    MCP tool chrome/open_url. Closest: chrome/new_page, …`). Its row shows
+    tool chrome/open_url. Closest: chrome/new_page, …`). Its row shows
     `mcp chrome/take_screenshot fullPage=true`.
   - A tool turn takes a few more steps than when every tool was declared
     (the P1 spike: about 1.5 more on a 30-tool server), and each request is
@@ -1159,8 +1181,9 @@ bundles:
   session" (or in this repo) allows that tool with those arguments only.
   (Approvals stored before 0.6.0, under the old name, don't carry over, nor
   ones stored before 0.7.0 under `mcp_call`: each MCP tool is asked about once more.)
-  Two things see `call_tool`, not the tool: hooks (a `before_tool_call`
-  event's `tool:` is `"call_tool"`, the tool in its args), and loop-guard's
+  Two things see `call_tool`, not the MCP tool: hooks (a `before_tool_call`
+  event's `tool:` is `"call_tool"`, the tool in its args; a built-in reached
+  through `call_tool` is the exception, it fires as that built-in), and loop-guard's
   `ignore_tools` (`call_tool` ignores every MCP call; calls to different
   tools, or with different args, stay distinct, since the tool is in the
   args).