samagotchi 0.66.0 → 0.68.0

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 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)
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
@@ -43,11 +44,12 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # 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)
   │
@@ -72,7 +74,7 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │
   └── ensure: release_turn(probe_cancel_before)
         # TurnState#finish! (turn flag off, controller, sink and steers cleared)
-        # GenerationPhase#finished!, WaitingSteer#clear!
+        # SteerCut#finished! (its GenerationPhase finished, its WaitingSteer cleared)
         # probe cancel swapped back
         # the context window cache dropped, so the next turn asks the server again
         # steers left logged as dropped, activity recorded, turn-scoped hooks cleared
@@ -83,7 +85,7 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
 ```
 StandardError in run_turn:
   → if turn.ended (it came from the after_turn/session_end hooks): logged as post_turn_error, re-raised
-  → else: end_turn(turn, "failed", save: true)
+  → else: end_turn(turn, "failed", save: true) (a save that fails there is logged, turn_end_save_failed)
      # Both loops call LLM::FailedTurn.attach(e, conversation) before re-raising, so
      # failed_messages keeps the loop's partial conversation (tool iterations included),
      # else turn.messages, with TurnNote.failed(summary, continued: turn.continue) at the tail.
@@ -118,6 +120,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,13 +141,14 @@ 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
 ```
 
 Both implement the `LLM::ModelBackend` contract (`#complete(messages:, max_iterations:, on_stream_event:,
-cancel_controller:, model_name:, max_tool_output_chars:, pending_input:)`). `NativeBackend#complete` only calls
+cancel_controller:, model_name:, max_tool_output_chars:, pending_input:, reasoning_since:)`; `reasoning_since:` is
+where the run a step-limit Continue resumes started, the Engine's `resume_from`). `NativeBackend#complete` only calls
 `KernelLoop#run` with the same arguments. `ChatLoop` runs its own loop but is built with the same KernelLoop,
 whose tools, hooks, gate and dispatch it uses.
 
@@ -172,17 +185,21 @@ KernelLoop#run(messages, max_iterations:, on_stream_event:, cancel_controller:,
 `turn.conversation` is the loop's own copy, not the Engine's `turn.messages`. A failure attaches it to the error
 (`LLM::FailedTurn.attach`), so `Engine#failed_messages` can keep it; a Ctrl-C does not (see Error paths).
 
-### ChatLoop (the OpenAI chat API)
+### ChatLoop (the chat APIs)
 
-Runs hosts with `api: openai`: remote providers such as OpenRouter (Claude and others) and any OpenAI-compatible
-chat server. The model gets the tools as JSON schemas and returns structured tool calls.
+Runs hosts whose api has a chat adapter (`LLM::Adapters::BY_API`): `api: openai` on `LLM::OpenAIChat` (remote
+providers such as OpenRouter, Claude among others, and any OpenAI-compatible chat server) and `api: anthropic` on
+`LLM::AnthropicMessages` (Anthropic's Messages API; [anthropic.md](anthropic.md)). The Engine sets the adapter per
+turn for the effective model's host (`HostRegistry#adapter_for`). The model gets the tools as JSON schemas and returns
+structured tool calls.
 
 ```
 ChatLoop#complete(messages:, max_iterations:, on_stream_event:, cancel_controller:,
-                  model_name:, max_tool_output_chars:, pending_input:)
+                  model_name:, max_tool_output_chars:, pending_input:, reasoning_since:)
   │
   │ conversation = Array(messages).map(&:dup)   # a shallow copy of each message
-  │ Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input)
+  │ Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input,
+  │         start: reasoning_since)
   │    .call(max_iterations: max_iterations || 1, cap: KernelLoop.resolve_output_char_cap(max_tool_output_chars))
   │
   └──→ LLM::ModelResult(text, conversation, exhausted, canceled, tool_activity, ...)
@@ -191,10 +208,13 @@ 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 conversation is converted to the OpenAI wire format (`wire_messages`).
+- 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
-  as `stable_length:`), where the prompt's stable part ends. For remote Claude, `LLM::PromptCache` puts the
-  first cache breakpoint there; see prompt-caching.md.
+  as `stable_length:`), where the prompt's stable part ends. The adapter puts the first cache breakpoint there:
+  `OpenAIChat` for a Claude model on a remote host (`LLM::PromptCache.mark`), `AnthropicMessages` on every chat
+  request unless its dialect has no breakpoints or the host refused `cache_control` (`AnthropicWire.translate`,
+  `Dialect#cache_breakpoints`); see prompt-caching.md and anthropic.md.
 - Each call's result is its own tool message, paired by `tool_call_id`.
 - A model turn's saved reasoning (`thinking:`) goes back as `reasoning_content` per the turn's
   `TurnSettings#reasoning_history` (`ReasoningHistory.resolve`, the session's own level first:
@@ -208,8 +228,15 @@ The differences from the native loop:
   in `#resumed_run_start`), past a user entry added after that run's last reply (a `!cmd`'s output). Without
   `since:` (`#reasoning_chars` from outside a Run) the boundary is the last query (a `role: "user"` or `turn_start`
   entry). `Run#prompt_chars` counts it (`#reasoning_chars`).
+- On an adapter that sends its blocks back (`#replays_content?`: `AnthropicMessages`), a model turn's saved blocks
+  (`anthropic_content`, the response's `provider_content`, saved by `Run#with_thinking`) go back verbatim, thinking
+  blocks with their signatures (`#replay_blocks`): not for an interrupted entry or one with an unpaired call, and
+  without the thinking blocks before the reasoning boundary (the last model entry with tool calls keeps them).
+  `#reasoning_history` floors `drop` at `turn` there, since Messages needs the running run's thinking blocks.
 - A 400 about reasoning (`BadRequest#reasoning_refused?`) for a request that sent reasoning back asks the step again
-  without it; when that goes through, `#reasoning_history_refused!` marks the model (worker lifetime) and
+  without it (not on a replaying adapter, where the body would be the same); when that goes through,
+  `#reasoning_history_refused!` marks the model (worker lifetime; the loop's `LLM::RefusalMemo`, as for the thinking
+  and sampling refusals) and
   `:reasoning_history_refused` goes out. When it is refused too, the thinking-fields fallback (`#thinking_refused!`,
   `:thinking_refused`) runs on it, still without reasoning. Up to three requests per step. A 400 about a thinking
   block's signature (`BadRequest#thinking_signature?`) or a refused binding control
@@ -256,7 +283,7 @@ One iteration with tool calls:
   `EVENT_FIELDS`) copy them by these lists, so a new row field is added there. `ref` is `FileRef.for` (a
   read/write/edit's file against the cwd, `{kind: "file", path, line?, end_line?}`); the web opens it in the editor
   that `Web::Editor` (web.editor) names, for a local viewer only (`App#viewer_capabilities`).
-  `refs` is a plugin tool's row refs: its registry entry's `refs` (chi.tool's `refs:` lambda, `Api.per_call`), run
+  `refs` is a plugin tool's row refs: its registry entry's `refs` (chi.tool's `refs:` lambda, `ToolSpec#per_call`), run
   once per call by `RowRefs.for` (never raises: a raise or a non-list gives none, `tool_refs_failed`; each entry a
   `Ref`, a bad one dropped, `tool_refs_rejected`; a relative file resolved against the session's folder
   (`KernelLoop#session_cwd`, else the process's), one outside it (its spelling or its real path) dropped, a kept one
@@ -311,13 +338,46 @@ 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):
 
 ```ruby
 Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                  :settings, :id, :limit) do
+                  :settings, :id, :limit, :resumed, :resume_from) do
+  def resumed? = resumed ? true : false                           # a step-limit Continue
   def tag(event) = origin ? event.merge(origin: origin) : event   # boundary events carry the origin
   def elapsed = ...                                               # seconds since started_at
 end
@@ -342,10 +402,14 @@ end
   running turn's record so far as a killed turn's (canceled, `worker_stopped`), which the next worker loads; the
   turn's end writes over it.
 
-### GenerationPhase
+### SteerCut, GenerationPhase and WaitingSteer
+
+The Engine holds one `SteerCut` (`@steer_cut`), which owns a `GenerationPhase` and a `WaitingSteer`: the Bridge and
+the TUI ask it (`Engine#cut_for_steer`, `#input_epoch`, `#generation_snapshot`), the Engine's stream handler feeds it
+(`SteerCut#observe`), a drain that took input calls `#delivered!`, and `release_turn` calls `#finished!`.
 
-What the running generation streams, fed by the Engine's stream handler: whether a steer sent as a cut (delivery
-`cut`: `/cut TEXT`, `chi send --cut`) may cut it. `SteerCut#cut_for_steer` answers `:now`, `:waits` or `:off`; the
+`GenerationPhase` is what the running generation streams, fed through `SteerCut#observe`: whether a steer sent as a
+cut (delivery `cut`: `/cut TEXT`, `chi send --cut`) may cut it. `SteerCut#cut_for_steer` answers `:now`, `:waits` or `:off`; the
 Bridge acks it as `cut`.
 A generation is cuttable while it has streamed only thinking, is still thinking, and has thought for at least
 the model's cut wait (`SteerCutAfter.resolve`: `steer_cut_after` per models:/hosts: entry, else `steer.cut_after`) seconds (`cuttable?(min_age)`). It has `started!`, `chunk!`, `retrying!` and `finished!`.
@@ -357,8 +421,8 @@ line and tell whether "cut in now" can land.
 ### WaitingSteer
 
 A message that may cut the generation but came too early (the generation hadn't been thinking long enough). It
-waits until the thinking passes the model's cut wait (the Engine checks on each thinking chunk), until a drain hands
-the message to the model at a boundary, or until the turn ends (`clear!` in `release_turn`).
+waits until the thinking passes the model's cut wait (`SteerCut#observe` rechecks it on each thinking chunk), until a
+drain hands the message to the model at a boundary, or until the turn ends (`SteerCut#finished!` clears it).
 
 ## Events
 
@@ -414,22 +478,28 @@ hook registry (`@hooks.fire`), not on the sink or the observers. The other hook
 
 ```
 Engine initialization (in this order, among other things):
-  @turn_state, @generation_phase, @waiting_steer
-  @host_registry, @effective_model_name; @client = @host_registry.resolve(...).client
+  @turn_state, @steer_cut (SteerCut: its GenerationPhase and WaitingSteer)
+  @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)
+  @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)
   wire_kernel: @kernel = KernelLoop.new(client:, profile:, hooks:, reminder_store:, tools:)
   @kernel.guardrail_gate = @guardrail_wiring.gate; @kernel.warmup = PromptWarmup.new
-  @hooks.runtime = hook_runtime
+  @hooks.runtime = @hook_routes.runtime (HookRoutes, built first: what a hook or plugin does reaches the UIs)
   @native_backend = LLM::NativeBackend.new(kernel: @kernel)
   @prompt_builder = SystemPrompt.new(...)
   @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
@@ -444,7 +514,7 @@ Model probes (per turn):
 
 Plugins and hook files register hooks on hook points (see "Hook points" above, and docs/hooks.md). Every fire
 puts the hook runtime on the event: `event[:hook]` (the hook's label) and five helpers, which call the Engine's
-`Hooks::Runtime`. A plugin's `ctx` has the same ones (`ctx.notify`, `ctx.steer`, ...).
+`Hooks::Runtime` (built by `HookRoutes`, `hook_routes.rb`, which routes each to the UIs). A plugin's `ctx` has the same ones (`ctx.notify`, `ctx.steer`, ...).
 
 | Helper | What it does | Used by |
 |---|---|---|
@@ -551,8 +621,10 @@ Both loops:
 - **The same events**: generation events, tool dispatch and tool call events, and the before/after generation
   and tool call hooks.
 
-Native loop only: the Qwen open-block recovery, and the thinking prefill (Qwen with thinking off gets an empty
-thought after the cue, kept in the model message so the next prompt starts with what the server has cached).
+Native loop only: the Qwen open-block recovery, and the thinking prefill (`Thinking.native`: with thinking off, Qwen
+gets an empty thought after the cue, `QWEN_EMPTY_THOUGHT`, and Gemma 4 its empty thought channel,
+`GEMMA_EMPTY_THOUGHT`, with no `<|think|>` token before the system prompt; kept in the model message so the next
+prompt starts with what the server has cached).
 
 ## Key design principles
 
@@ -566,8 +638,9 @@ thought after the cue, kept in the model message so the next prompt starts with
    persistent.
 5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine, keyed by
    `[chat, thinking, layers]` (chat/native, the thinking level, the turn's LLM context layers), and is reset
-   only on a model switch, a tools change or a profile change. The stable part (base prompt, identity,
-   memories, AGENTS.md, memory indexes) comes before the volatile tail (model, working directory, session).
+   only on a model switch, a tools change, a profile change or a toolkit change (`Engine#apply_toolkit!`). The
+   stable part (base prompt, the toolkit's not-loaded line, rg guidance, identity, model notes, preloaded memories,
+   AGENTS.md, appended files, memory indexes) comes before the volatile tail (model, working directory, session).
    prompt-caching.md covers this in detail.
 
 ## Key files
@@ -576,12 +649,26 @@ Paths are under `lib/samagotchi/`.
 
 | File | Role |
 |---|---|
-| `engine.rb` | Engine: turn lifecycle, event emission, hooks runtime, plugins, model switching |
+| `engine.rb` | Engine: turn lifecycle, event emission, plugins, model switching |
 | `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) |
-| `llm/chat_loop.rb` | Chat loop: `#complete` (tool schemas per request, wire conversion) |
+| `llm/chat_loop.rb` | Chat loop: `#complete` (tool schemas per request, wire conversion, block replay) |
+| `llm/adapters.rb` | `LLM::Adapters::BY_API`: which chat adapter a host's api gets |
+| `llm/openai_chat.rb` | `LLM::OpenAIChat`, the `/v1/chat/completions` adapter |
+| `llm/adapter_common.rb` | `LLM::AdapterCommon`: what both chat adapters share (the HTTP layer and its timeouts, the paged model list, the SSE line loop, JSON errors) |
+| `llm/anthropic_messages.rb`, `llm/anthropic_wire.rb`, `llm/anthropic_assembly.rb`, `llm/dialect.rb` | The `/v1/messages` adapter, its wire translation, its response, its dialects ([anthropic.md](anthropic.md)) |
+| `llm/prompt_cache.rb` | Cache breakpoints on the OpenAI path, and the `cache_control` both adapters send |
+| `llm/turn_settings.rb` | `LLM::TurnSettings`, what a turn runs under (vision, sampling, thinking, reasoning history, …) |
+| `llm/native_tool_normalizer.rb`, `llm/stream_drops.rb` | A chat adapter's tool calls as chi's call hashes (`Tools::BuiltinCalls`); asking again for a step whose stream dropped (both loops) |
+| `reasoning_history.rb` | `ReasoningHistory`: the levels, `.resolve`, `.run_start` |
 | `llm/backend.rb` | The `LLM::ModelBackend` contract (`#complete(...)`) |
 | `llm/native_backend.rb` | Wraps KernelLoop as a backend (`#complete` calls `#run`) |
 | `llm/model_result.rb` | `LLM::ModelResult`, what a backend returns |
@@ -591,7 +678,11 @@ Paths are under `lib/samagotchi/`.
 | `prompt_warmup.rb` | The turn-end warm-up |
 | `tools/registry.rb` | The tools a session offers: schemas, handlers, order |
 | `system_prompt.rb` | System prompt construction (stable part, volatile tail) |
+| `prompt_files.rb`, `model_notes.rb` | The AGENTS.md chain and appended files; the model notes the prompt loads |
+| `toolkit.rb`, `toolkit_command.rb` | A session's toolkit (`Toolkit#resolve`, what `Registry` declares); `/toolkit` |
+| `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 |
 | `extension_load.rb` | What an Engine loads at start: config.yml and bundle hooks, plugins, `bundles:` settings; events held while plugins load |
 | `guardrail_wiring.rb`, `guardrails/gate.rb` | The gate's context and approvals; the verdict per call |
 | `events.rb` | Event type sets shared by the Worker, the Bridge, the TUI and the web |

data/docs/internals/gemma4-contract.md

@@ -14,7 +14,7 @@ XML tool tags and declaration-echo parsing are intentionally not supported.
 
 Thought handling follows the Gemma guidance:
 
-- Include `<|think|>` in the system instruction to activate thinking mode.
+- Include `<|think|>` in the system instruction to activate thinking mode. With thinking off (`/thinking off`) chi leaves the token out and prefills Gemma's empty thought channel after the model cue (`Thinking::GEMMA_EMPTY_THOUGHT`, `Thinking.native`, `Prompt.prefill_for`), as Gemma's chat template does with `enable_thinking` false.
 - When thinking mode is active, the model may emit internal reasoning as `<|channel>thought ... <channel|>`.
 - Standard multi-turn: prior model thoughts are stripped from conversation history before the next turn.
 - Function/tool-calling exception: during a single turn that includes tool calls, thoughts are not stripped between those tool-call rounds.

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

@@ -75,9 +75,9 @@ The proxies are the context-edit spike's (lexical and lenient: a basename mentio
   stale's stubs, every output led by its `[#tN]` id (`LLMContextView`), the `[CONTEXT: …]` line chi's `ContextStatus`
   adds at a turn's start under `--budget N` (default 64000; no line below its guided buckets, so a small case may get
   none), and the chat messages and tools of chi's `ChatLoop`, `forget_outputs` with its real description. The model
-  (`--forget-model MODEL`, a chi model ref on an `api: openai` host) answers once; a `forget_outputs` call among its
-  calls runs through chi's `LLMContextForget` (refusals, `protect_steps`, `keep`), and the row scores stale's stubs
-  plus the forgets. Each answer is saved in `--out DIR` (`<case>.forget_offer.json`) and read back, so a rerun asks
+  (`--forget-model MODEL`, a chi model ref on a chat host: `api: openai` or `api: anthropic`) answers once; a
+  `forget_outputs` call among its calls runs through chi's `LLMContextForget` (refusals, `protect_steps`, `keep`),
+  and the row scores stale's stubs plus the forgets. Each answer is saved in `--out DIR` (`<case>.forget_offer.json`) and read back, so a rerun asks
   only for the rest (an error isn't saved); `--out` alone scores saved answers; `--max-cost USD` stops the asking
   once the costs the server reports reach it (exit 1, the answers so far kept). The row's notes give the call rate
   (`called`, `no_call`, `error`, `unasked`), the ids chi refused and the notes' mean length. Ids in this row cost
@@ -96,7 +96,8 @@ ruby script/llm_context_bench.rb "$SESSIONS" --picks deepseek=picks/deepseek --p
 ## Live picks (the D7 tool-name A/B)
 
 The one part that calls a model, and only with `--live MODEL`: at each case it asks the model which of its tool
-outputs to forget, through chi's own chat client (the model must be on an `api: openai` host), and saves each
+outputs to forget, through chi's own chat client (the model must be on a chat host, `api: openai` or `api: anthropic`:
+`LivePick.chat_adapter` takes any `HostEntry#chat?` host), and saves each
 answer under `--out DIR` for `--picks` to score. A saved pick is never asked for again. The request is the
 session's conversation up to the turn's end (thinking dropped, every tool result led by its id `[#tN]`), chi's
 built-in chat tools plus the forget tool, and the policy's tail line; a model that doesn't call the tool is asked

data/docs/internals/prompt-caching.md

@@ -3,8 +3,9 @@
 A model server reuses work only for the **exact token prefix** it has already seen. Change one token and
 everything after it is computed again (prefill). The local models we run (hybrid Qwen 3.6 / Ornith on llama.cpp
 and Splash) can only resume from a **restore point near the end** of an earlier prompt, not from any shared
-prefix. Anthropic (Claude via OpenRouter) caches only up to an explicit `cache_control` breakpoint. So the order
-of what chi sends decides what a new turn, or a new session, has to pay for.
+prefix. Anthropic (Claude via OpenRouter, or over the Messages API, `api: anthropic`) caches only up to an explicit
+`cache_control` breakpoint. So the order of what chi sends decides what a new turn, or a new session, has to pay
+for.
 
 Measured with prompt-cache slice 1 (2026-10-04, fresh sessions, ~7.7k-token prompt):
 
@@ -23,6 +24,8 @@ right-hand column happens.
  shared by every session ──────────────────────────────────────────────────  breaks it
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ 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)      │
 │              those the session's toolkit declares (per toolkit)          │  /model, a profile change,
 │              (chat: the `tools` field; native: the model's template)     │  a toolkit change
 ├──────────────────────────────────────────────────────────────────────────┤
@@ -36,7 +39,7 @@ right-hand column happens.
 │   AGENTS.md (root → cwd)                                                 │  (picked up by a new
 │   appended files (append_system_prompt:, --append-system-prompt)         │  process or a rebuild)
 │   project + system memory indexes                                        │
-│                         ◄── remote Claude: cache_control breakpoint #1   │
+│                ◄── remote Claude / Messages: cache_control breakpoint #1 │
 ├──────────────────────────────────────────────────────────────────────────┤
 │ SYSTEM, volatile tail (per session, least → most changing)               │
 │   Model: this session runs on …                                          │  another session
@@ -48,17 +51,19 @@ right-hand column happens.
 ┌──────────────────────────────────────────────────────────────────────────┐
 │ history      user / assistant / tool messages, APPEND-ONLY               │  !rollback, a failed or
 │              (images: up to the newest N, cut in batches; ImagePlan)     │  cancelled turn's tail,
-│                         ◄── remote Claude: breakpoint #2 on the last     │  the image cut moving
-│                             non-system message                           │  a batch, history
+│                ◄── remote Claude / Messages: breakpoint #2 on the last   │  the image cut moving
+│                    non-system message (Messages: its last user block)    │  a batch, history
 ├──────────────────────────────────────────────────────────────────────────┤  sanitizing (thinking
 │ tail notes   reminders, turn notes, steers (system/user messages)        │  stripped per spec)
 │ new prompt   this turn's user message                                    │
 └──────────────────────────────────────────────────────────────────────────┘
 ```
 
-- The system prompt is built **once per loop** and rebuilt only on `@prompt_builder.reset!`: a model switch
-  (`Engine#switch_model!`), a plugin's `tools_changed!`, or a profile change. A per-turn rebuild would
-  break everything below it.
+- The system prompt is built **once per key** and kept (`SystemPrompt#build`, keyed by `[chat, thinking, layers]`:
+  the loop, the thinking level, the turn's LLM context layers; a `/thinking` change builds under another key). All
+  of them are dropped only on `@prompt_builder.reset!`: a model switch (`Engine#switch_model!`), a plugin's
+  `tools_changed!`, a profile change, or a toolkit change (`Engine#apply_toolkit!`). A per-turn rebuild would break
+  everything below it.
 - The tools layer is shared **per toolkit** (configuration.md, "Toolkits"): sessions on the same toolkit share it,
   and a chain's links keep theirs. A session's toolkit is saved when it is created and never resolved again from
   config. A change (`/toolkit`, `ctx.use_toolkit`) is applied only at a turn's start (`Engine#apply_toolkit!`,
@@ -69,7 +74,14 @@ right-hand column happens.
   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
   a breakpoint. The split point comes from `SystemPrompt#stable_length` via the message's `cache_split:`, which
-  never goes on the wire.
+  never goes on the wire. `PromptCache.mark` keys on the model id (`claude`) and runs only for a remote host's chat
+  requests (`OpenAIChat#cache_breakpoints`).
+- On a Messages host (`api: anthropic`), `AnthropicWire.translate` sets the same two breakpoints on the translated
+  request: the first `system` block (the stable part, when `cache_split:` splits it) and the last user block that
+  can carry one (never a thinking block, never one from a mid or tail system message). It doesn't look at the model
+  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.
 - 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.
 
@@ -115,14 +127,17 @@ is prefilled once. The native and the chat loop use the same plan.
   one provider. `cache.key: session` also sends the session id as `prompt_cache_key` in the body, the field
   OpenAI's API routes and caches by (OpenRouter honours it too); the log line shows `cache_by=session`. Only
   `api.openai.com` and OpenRouter get it, and only the session's own chat requests (not recap or `/btw`): a local
-  llama.cpp, Splash or another gateway may reject an unknown field. Off by default.
+  llama.cpp, Splash or another gateway may reject an unknown field. Off by default. A Messages host never gets
+  `prompt_cache_key` (`AnthropicMessages::DROPPED_OPTIONS`); its dialect may add a header of its own beside
+  `Session-Id` (`Dialect#session_header`: `x-session-affinity` under `dialect: fireworks`, which keeps a session on
+  the replica that has its cache).
 
 ## Reading the numbers
 
 - The debug log's `generation_completed` line: `prompt=` (the request's prompt tokens), `cached=` (read from the
   server's cache), `cache_write=` (written to it, where the provider reports writes) and `reprefill=` (of the last
   request's prompt on the same model, what was prefilled again). The `http` line of a
-  remote Claude request shows `cache=on` (or `cache=1h`) when it carried breakpoints.
+  remote Claude or Messages request shows `cache=on` (or `cache=1h`) when it carried breakpoints.
 - The warm-up logs `model warmup` with `cached=`, `prefilled=` and `prefill_ms=`.
 - `/stats`: "cached N (P%)", "cache writes" and "re-prefilled" for the session.
 - A healthy session: from the second request on `cached=` is close to `prompt=`; a second fresh session in the