samagotchi 0.66.0 → 0.67.0

data/docs/internals/engine.md

@@ -72,7 +72,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 +83,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.
@@ -135,7 +135,8 @@ Engine#backend → backend_for(@host_registry.resolve(@effective_model_name))
 ```
 
 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 +173,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 +196,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 +216,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 +271,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
@@ -317,7 +332,8 @@ 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 +358,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
 
-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
+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!`.
+
+`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 +377,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,15 +434,20 @@ 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
+  @turn_state, @steer_cut (SteerCut: its GenerationPhase and WaitingSteer)
   @host_registry, @effective_model_name; @client = @host_registry.resolve(...).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)
@@ -444,7 +469,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 +576,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 +593,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 +604,22 @@ 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 |
+| `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 +629,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

data/docs/plugins.md

@@ -291,7 +291,7 @@ is what `targets:` says:
 - `command:`: a shell command the call runs; `command:` rules match it.
 - `cwd:`: where it runs, for the repo root and relative paths.
 - `acts_as:`: the tool a call stands for, when the tool runs other tools
-  (the mcp bundle's `mcp_call`). Rules keyed by that tool's name match the
+  (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).
 - `args:`: the arguments it acts with (a Hash), when they aren't the call's
@@ -308,7 +308,7 @@ targets: ->(args) { { acts_as: "mcp_#{args["server"]}_#{args["tool"]}", args: ar
 ```
 
 An approval of an `acts_as:` call keys on the tool's own name as well
-(`mcp_call>mcp_github_x:…`), so it never stands in for an approval of the
+(`call_tool>mcp_github_x:…`), so it never stands in for an approval of the
 tool it acts as, nor that one for it. Hooks see the call's own name, and so
 does loop-guard's `ignore_tools`.
 
@@ -548,7 +548,7 @@ end
 - **`provides_tools: true`**: the task provides what the plugin's tools
   need: tools of its own (with `chi.replace_tools`), or what fixed tools
   read (the mcp bundle's index of a first-run server's tools, which
-  `find_mcp_tools` searches). A turn sent while it runs starts at once (the user's
+  `find_tools` searches). A turn sent while it runs starts at once (the user's
   message shows), then waits for it **before its first model request**, so
   the model sees the tools; the UIs keep showing the task meanwhile. The
   wait lasts at most `timeout` seconds from the task's start (default 60).
@@ -579,6 +579,89 @@ tool (full) until it comes back, with a warning at its first turn. See
 chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
 ```
 
+### `chi.tool_source(call:, acts_as:, label:, wait:, prefix:)`
+
+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.
+
+```ruby
+@source = chi.tool_source(label: "mcp", prefix: "mcp_",
+                          call: ->(tool, args, ctx) { run(tool, args, ctx) },  # the result, as a tool block's
+                          acts_as: ->(group, tool) { "mcp_#{group}_#{tool}" }, # what rules match
+                          wait: ->(group) { start_of(group).value })           # a :starting group's start
+index = Samagotchi::Tools::ToolIndex
+@source.publish([index::Group.new(name: "fs", summary: "files in ~/scratch", tools: [
+                   index::Tool.new(group: "fs", name: "read", description: "Read a file.", schema: read_schema,
+                                   acts_as: "mcp_fs_read")
+                 ]),
+                 index::Group.new(name: "chrome", state: :starting)])
+```
+
+- **`publish(groups)`** swaps in the plugin's whole list, from any thread, at
+  any time (a server that started, `list_changed`): a search sees the old
+  list or the new one, never half. A `Group` has a `summary` (its line in
+  `find_tools`' description), a `state` (`:ready`; `:starting`, its tools may
+  still come: a call to it waits on `wait`, a search says "starting, try
+  again"; `:failed` with its `error`) and its tools. A group exists before its
+  tools do. A `Tool`'s `refusal` says why `call_tool` refuses it (nil: it can
+  be called), its `mark` what a search shows beside its name: the plugin
+  decides both (the mcp bundle: a bad schema, a name clash) and publishes
+  them again when they change.
+- **`call`** gets a call chi looked up and checked: the `Tool`, its `args`
+  typed by its `inputSchema`, and the plugin's `ctx`. It returns what a tool's
+  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
+  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
+  one guardrails were given is refused ("the MCP tools changed while the call
+  waited"), so a hook that disagrees refuses every call.
+- **The row** shows `label` (default: the bundle's name) and
+  `<group>/<tool> args…`. `@source.declared_names` and `declared_tokens` say
+  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.
+
+### `chi.peer_source(name, label:)`
+
+Declares a context source as a peer agent's answers: the peer bundles'
+`claude-review` and `codex-review`. Such a source, when it is a pushed source
+of the session's own, wakes the session by the peer loop's rules instead of
+the 10-minute window: up to `context.peer_turns` wake turns in a row, no wake
+for an answer whose verdict is `VERDICT OK`, and a wake line that names the
+peer and keeps the turn within the user's task (see [Waking: peer
+sources](context.md#peer-sources-the-peer-loop)).
+
+```ruby
+chi.peer_source "codex-review", label: "Codex"
+```
+
+- `name`: a context source name (as `chi context add` takes it). Another
+  bundle's is a load error.
+- `label:`: the peer's name, said in chi's own lines ("your peer agent
+  Codex"): a capital letter, then up to 23 letters and spaces.
+
+The declaration lives in the session's process only, like a tool: a source
+file can't make itself a peer's, and uninstalling the bundle ends it.
+Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `REVIEW`
+source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
+
 ### `chi.ctx`
 
 The plugin's context (the `ctx` its handlers get), for `register` itself:
@@ -907,7 +990,9 @@ only against this API (`lib/samagotchi/bundles/btw/plugin.rb`).
 only against this API (`lib/samagotchi/bundles/mcp/plugin.rb`), and gives
 the model the tools of [MCP](https://modelcontextprotocol.io) servers. It
 has no memory file, and the servers' tools aren't declared to the model one
-by one: it has two tools, `find_mcp_tools` and `mcp_call` (~250 tokens in
+by one: the bundle publishes them into chi's tool index
+([chi.tool_source](#chitool_sourcecall-acts_as-label-wait-prefix), a group
+per server), and the model has its two tools, `find_tools` and `call_tool` (~250 tokens in
 every request plus a line per server, whatever the servers have; `/mcp`
 says how many). Stdio servers only, for now.
 
@@ -925,7 +1010,7 @@ bundles:
         env: {NODE_OPTIONS: "--no-warnings"}   # added to chi's environment
         cwd: ~/scratch                         # default: where chi runs
         tools: [read_*, list_directory]        # optional: only these (globs)
-        description: files in ~/scratch        # optional: its line in find_mcp_tools
+        description: files in ~/scratch        # optional: its line in find_tools
         timeout: 120                           # optional: this server's per-call timeout
       chrome:
         command: [npx, -y, "chrome-devtools-mcp@latest", --slim, --headless]
@@ -944,7 +1029,7 @@ bundles:
   one is replaced, and so is what a search finds. The model's tools never
   change, so the prompt cache keeps. The saved file also keeps the first
   sentence of the server's `instructions` (from `initialize`), for its line
-  in `find_mcp_tools`.
+  in `find_tools`.
 - **The first run** (no saved list, or the config changed) starts the
   server in an [init task](#chiinitlabel-provides_tools-false-quiet-false-timeout-nil--ctx--):
   every UI shows `Starting MCP server x (first run, saving its tools)`, and
@@ -977,9 +1062,9 @@ bundles:
     command: [chrome-devtools-mcp, --slim, --headless]   # after npm i -g chrome-devtools-mcp
   ```
 
-- **Tools: search, then call.** The servers' tools are kept in an index;
+- **Tools: search, then call.** The servers' tools are kept in chi's tool index;
   the model has two fixed tools:
-  - `find_mcp_tools(query, server?)` searches it by keywords over the
+  - `find_tools(query, server?)` 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
@@ -995,7 +1080,7 @@ bundles:
     `instructions`, and how many tools it has (`- chrome (26 tools)` with
     neither: tool names there get called blind, without a search; a first
     run's server is just its name until the next session).
-  - `mcp_call(tool, args)` calls one: `tool` is `<server>/<tool>`, and
+  - `call_tool(tool, args)` calls one: `tool` is `<server>/<tool>`, and
     `mcp_<server>_<tool>` works too (looked up, not parsed). Two tools whose
     `mcp_<server>_<tool>` comes out the same (servers `git-hub` and
     `git_hub`, names alike up to the 48-character cut) are both refused,
@@ -1039,18 +1124,18 @@ bundles:
   closed, then TERM and KILL go to the server's process group.
 - **`/mcp`** (anytime) shows a card with the servers, their state (cached
   (not started), running with its pid, failed with its count, stopped) and
-  their tools as `<server>/<tool>`, the name `mcp_call` takes.
+  their tools as `<server>/<tool>`, the name `call_tool` takes.
   A cached or running server's line says roughly how many tokens its tool
   definitions take (`~4,232 tokens`), which only a search's answer carries
-  now; the last line says what every request carries (`find_mcp_tools` and
-  `mcp_call`) and totals the servers'. It is an estimate:
+  now; the last line says what every request carries (`find_tools` and
+  `call_tool`) and totals the servers'. It is an estimate:
   the definitions' JSON as the chat API gets it (`api: openai`), divided by
   4. The native prompts (Gemma, Qwen) render a flatter schema, so there they
   take less. The log records each server's estimate when it changes
   (`mcp_tools_estimated`).
 - The server's stderr goes to the debug log (`plugins` records, bundle=mcp).
 - **Guardrails.** A rule's `tool:` can be a glob, so one rule covers every
-  MCP tool (a search is `find_mcp_tools`, outside `mcp_*`, so it isn't
+  MCP tool (a search is `find_tools`, outside `mcp_*`, so it isn't
   asked about):
 
   ```yaml
@@ -1062,20 +1147,21 @@ bundles:
         reason: an MCP server's tool
   ```
 
-  `mcp_call`'s `targets:` act as the tool it calls, by its
+  `call_tool`'s `targets:` act as the tool it calls, by its
   `mcp_<server>_<tool>` name ([acts_as:](#guardrails)), so `tool:
-  "mcp_github_*"` or `tool: mcp_github_merge_pull_request` match an
-  `mcp_call` to it, as they matched the tool when it was declared by that
+  "mcp_github_*"` or `tool: mcp_github_merge_pull_request` match a
+  `call_tool` to it, as they matched the tool when it was declared by that
   name. A call made before the server's tools are known (a first run
   still starting) is matched by the name the model gave, so the rule fires
   before the call waits; if the tool it then finds isn't that one, the
   call is refused. The question shows the inner arguments under `<server>: <tool>`
   (`everything: get_sum: a=20 b=22`), and "Allow this call for the
   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.)
-  Two things see `mcp_call`, not the tool: hooks (a `before_tool_call`
-  event's `tool:` is `"mcp_call"`, the tool in its args), and loop-guard's
-  `ignore_tools` (`mcp_call` ignores every MCP call; calls to different
+  (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
+  `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).
 
@@ -1653,10 +1739,20 @@ Claude pairs; without one the bundle costs one tool declaration.
   - `/claude last` sends the model's last completed answer as context. Mid-turn
     it is the answer before the running turn, never the turn's partial text;
     a cancelled or failed turn has no answer, so the one before it goes.
+- **The peer loop.** The bundle declares `claude-review` a peer's
+  ([`chi.peer_source`](#chipeer_sourcename-label)), so Claude's answers
+  wake chi by the loop's rules ([Waking: peer
+  sources](context.md#peer-sources-the-peer-loop)): chi fixes what Claude
+  flagged or disagrees and sends again, up to `context.peer_turns` (3) wake
+  turns in a row, and a `VERDICT OK` answer arrives as a note and ends the
+  round. Only a message you type in the web or a TUI starts the count again.
 - **The skill.** `skill_claude_peer` (system scope) tells the model to send
-  only when you ask, to pick the part rather than the session, not to wait
-  or poll, and how to read the `claude-review` answer (a validate ends with
-  `VERDICT: OK`, `CHANGES` or `UNSURE`).
+  only when you ask or to reply in a peer turn, to pick the part rather than
+  the session, not to wait or poll, and how to read the `claude-review`
+  answer (a validate ends with `VERDICT: OK`, `CHANGES` or `UNSURE`): act on
+  it only within your task, and stop and tell you when Claude agrees or after
+  the last turn. Claude's skill ends each answer's summary with its verdict
+  and never answers with `chi send` (which counts as you typing).
 - **Asking first.** The tool has no `targets:`, so guardrails match it by name
   only: to be asked before each send, add a rule ([Rules in
   config.yml](guardrails.md#rules-in-configyml)):
@@ -1680,6 +1776,10 @@ Claude pairs; without one the bundle costs one tool declaration.
   bypasses permissions holds it for approval (in `-p` it expires after 5
   minutes). It is local only (a Unix socket), but it does hand session
   content to another agent: only what the model or you picked.
+- **Needs chi 0.67.0** for the loop (`chi update`): the plugin is built on
+  `Samagotchi::Plugin::Peer` (lib/samagotchi/plugin/peer.rb), the base both
+  peer bundles share (the tool, `/claude`, the cards, payloads), and each
+  bundle sets its strings and transport.
 
 ## The codex-peer bundle
 
@@ -1758,6 +1858,9 @@ skill install card) works the same.
   Codex's names, and on a missing answer points to Codex being mid-turn or
   its sandbox (the `writable_roots` line). To be asked before each send, a
   guardrails rule with `tool: codex_send` (see the claude-peer section).
+- **The peer loop** works as claude-peer's: `codex-review` is declared a
+  peer's, Codex's answers wake chi up to `context.peer_turns` turns in a row,
+  and `VERDICT OK` ends the round. Needs chi 0.67.0.
 
 ## Shutdown