samagotchi 0.65.0 → 0.67.0

data/docs/internals/anthropic.md

@@ -0,0 +1,156 @@
+# Anthropic Messages (`api: anthropic`)
+
+A host with `api: anthropic` (Anthropic itself, a gateway passing Claude through, a local server such as Splash,
+Fireworks' Anthropic-compatible API) runs the same chat loop as `api: openai`: `LLM::Adapters::BY_API` maps both apis
+to an adapter, `HostRegistry::HostEntry#chat?` is true for either, and `Engine#backend_for` picks `LLM::ChatLoop`
+(engine.md, "The model↔tool loop"). Only the adapter differs: `LLM::AnthropicMessages` instead of `LLM::OpenAIChat`.
+The user-facing settings (`dialect:`, `auth:`, `max_tokens`, the known limits) are in configuration.md.
+
+```
+ChatLoop::Run#generate
+  → ChatLoop#wire_messages                  # the OpenAI-shaped wire every chat host gets,
+                                            # plus anthropic_content on replayed model turns
+  → AnthropicMessages#chat
+      → #request_body                       # options as Messages takes them, breakpoints on or off
+          → AnthropicWire.translate         # system blocks + messages, cache_control placed
+          → AnthropicWire.tools             # function schemas → {name, description, input_schema}
+      → POST {base}/v1/messages             # LLM::HTTP: retries, cancel, first-token limit
+      → AnthropicAssembly#add per SSE event # → ChatResponse (text, reasoning, tool_calls, usage,
+                                            #   finish_reason, provider_content)
+      → a 400 it can fix: #refusal_fix, then the same request again (once per kind)
+```
+
+## Files
+
+Paths are under `lib/samagotchi/llm/`.
+
+| File | Role |
+|---|---|
+| `adapters.rb` | `Adapters::BY_API` (`openai`, `anthropic`), `.for(entry)`, `.build(api:, …)` for side requests (`IdleClient`) |
+| `anthropic_messages.rb` | `AnthropicMessages`: the request body, `#chat` (streamed or not), the 400 fixes, `#list_models`, `#thinking_fields`, `#replays_content?` |
+| `anthropic_wire.rb` | `AnthropicWire`: ChatLoop's wire messages as Messages' `system` and `messages`, the two breakpoints, tool ids and names |
+| `anthropic_assembly.rb` | `AnthropicAssembly`: a response from a whole body (`.from_message`) or stream events (`#add`), its usage in the OpenAI shape |
+| `dialect.rb` | `Dialect` (`STANDARD`, `FIREWORKS`): what a provider's `/v1/messages` does differently |
+| `prompt_cache.rb` | `PromptCache.control`: the `cache_control` a breakpoint carries (`cache.ttl`) |
+| `chat_loop.rb` | `ChatLoop#replay_blocks`, `#reasoning_history`'s floor, `Run#with_thinking` (saves `anthropic_content`) |
+
+## The adapter
+
+`AnthropicMessages.for(entry)` takes the host's API root, key variable, `auth:`, `dialect:` and remoteness;
+`HostRegistry#adapter_for` keeps one per host for the worker's life, so what it learns from a 400 (below) lasts that
+long. Each request posts `{base}/v1/messages` with `anthropic-version: 2023-06-01`, the key in the header the host's
+`auth:` names (else the dialect's: `x-api-key` on the standard one), and `Session-Id` (plus the dialect's
+`session_header`) when the loop has a session id.
+
+`#request_body` builds, in order: `model`, `max_tokens`, `system` (when there is one), `messages`, `stream`, `tools`
+with `tool_choice: {type: "auto"}` (when any), then the loop's options. The options lose chi's OpenAI-only fields
+(`DROPPED_OPTIONS`: `reasoning_effort`, `chat_template_kwargs`, `stream_options`, `prompt_cache_key`, `logprobs`,
+`top_logprobs`, `max_completion_tokens`); configured sampling passes as written. `max_tokens` is the options'
+(`default.max_tokens`), else the model list's `max_tokens` capped at `DEFAULT_MAX_TOKENS` (64000), and never over an
+output cap a 400 named. `#with_budget_room` keeps `max_tokens` above a budget-form `budget_tokens` plus `MIN_BUDGET`.
+
+`#thinking_fields(level)` is the thinking level on this wire: `off` is `thinking: {type: "disabled"}`; `low`, `medium`
+and `high` are `thinking: {type: "adaptive", display: <dialect's>}` with `output_config: {effort: <level>}`; `default`
+sends nothing. `#thinking_off_refused_fields` (low effort) is what `IdleClient` sends a side ask whose model refused
+thinking off.
+
+`#list_models` reads `GET {base}/v1/models` page by page (`limit=1000`, `after_id`, `has_more`/`last_id`, at most
+`AdapterCommon::MAX_MODEL_PAGES`, as OpenAIChat does); `#window_of` takes `max_input_tokens`, else the OpenAI-shaped fields (`ModelListing`).
+
+## Wire translation (`AnthropicWire.translate`)
+
+ChatLoop builds the same OpenAI-shaped wire messages for every chat host (`#wire_messages`); the adapter translates
+them:
+
+- The head system message becomes the top-level `system`, as text blocks: with its `cache_split:` (from
+  `SystemPrompt#stable_length`) two blocks, the stable part first. A later system message (a reminder, a turn note,
+  the CONTEXT line) becomes user text: a mid-conversation system role is model-gated.
+- An assistant message with saved blocks (`anthropic_content`) sends them verbatim, a `tool_use`'s name and id made
+  valid (`#valid_tool_use`); without them, a text block and its `tool_use` blocks (arguments parsed into the `input`
+  object, `{}` with a warning when they aren't a JSON object). An assistant message with neither is dropped.
+- Tool messages become `tool_result` blocks in a user message. Ids are made what Messages takes
+  (`AnthropicWire.tool_id`: invalid characters replaced and a short hash appended, the same on both sides), and tool
+  names too (`.tool_name`), so a malformed one never fails every later request.
+- User parts become text and `image` blocks (a data URL as base64, an http(s) URL as a url source).
+- Consecutive messages of one role merge into one, its `tool_result` blocks first. Blank text blocks are never sent;
+  a user message left empty says `(empty)`. `reasoning_content` and `cache_split` never go out.
+
+## The response (`AnthropicAssembly`)
+
+A stream is read from its `data:` lines alone (a gateway that drops the `event:` lines works), by content-block
+index: `message_start` (served model, usage), `content_block_start` (text, thinking, redacted_thinking, tool_use),
+`content_block_delta` (`text_delta`, `thinking_delta`, `signature_delta`, `input_json_delta`), `message_delta`
+(stop reason, `stop_details`, usage). `AnthropicMessages#chat_streamed` passes every event but `ping` to `on_delta`,
+`message_start` and `message_delta` with the usage so far attached (`#with_usage`); a block's start or delta counts as shown for the first-token limit
+(`.shows?`). A 200 whose body is a JSON error instead of a stream raises that error (`#raise_plain_error`).
+
+`#response` is a `ChatResponse`:
+
+- `provider_content`: the blocks as received (string keys). A blank text block is dropped (Messages refuses one sent
+  back); a `tool_use` input is an object; a thinking block always has a `signature` (`""` when none came).
+- `finish_reason` from `FINISH_REASONS`: `end_turn`/`stop_sequence` → `stop`, `max_tokens` and
+  `model_context_window_exceeded` → `length`, `tool_use` → `tool_calls`, `refusal` → `refusal`; anything else as it is.
+- Usage in the OpenAI shape the rest of chi reads (`TokenUsage`, `SessionMetrics`, `ContextStatus`, the web's
+  `ctx.js`): Messages counts `input_tokens` without the cache, so `prompt_tokens` is input + cache reads + cache
+  writes, with `cached_tokens` and `cache_write_tokens` under `prompt_tokens_details`. Every field is optional and the
+  later value wins; all zeros is no usage (`#usage_payload`: Fireworks' `message_start` carries only zeros).
+
+## Replaying thinking blocks
+
+Messages wants a model turn's blocks back as they came: a thinking block with its signature, in its place among the
+text and `tool_use` blocks (a tool loop with thinking needs the last assistant turn's). So:
+
+- `ChatLoop::Run#with_thinking` saves the response's `provider_content` on the model entry as `anthropic_content`,
+  beside `thinking:` (string keys, so a resumed session sends the same bytes).
+- `AnthropicMessages#replays_content?` is true, and `ChatLoop#replay_blocks` puts those blocks on the wire message,
+  which `AnthropicWire` sends verbatim. Not for an interrupted entry (its partial blocks have no signature) nor for
+  one with an unpaired call (it goes as flattened text). Before the reasoning boundary (`#reasoning_boundary`) the
+  thinking blocks are left out, so only the front of the history loses them; the conversation's last model entry,
+  when it has tool calls, keeps them even there (a run stopped between steps left its `tool_use` last).
+- `ChatLoop#reasoning_history` floors the level at `turn` on a replaying adapter: `drop` would remove the running
+  run's thinking, which Messages needs. For the same reason a reasoning 400 doesn't ask again without reasoning
+  (`Run#generate`: it would resend the same body).
+- A 400 about a thinking block's signature (`BadRequest#thinking_signature?`, a Claude 5.x block bound to a
+  different conversation) fails the turn for now; configuration.md has the known limit.
+
+## Cache breakpoints
+
+`#request_body` asks `AnthropicWire.translate` for breakpoints (`cache: PromptCache.control`, carrying `ttl: "1h"`
+under `cache.ttl: 1h`) only for a chat request (`purpose: "chat"`; a recap, `ctx.ask_model` or a triage sets none),
+on a dialect with `cache_breakpoints`, and until the host refused `cache_control`. Unlike `PromptCache.mark` on the
+OpenAI path, it doesn't look at the model id or remoteness. The two marks:
+
+1. the first `system` block (with `cache_split:`, the stable part; the per-session tail goes after it unmarked), which
+   caches the tools and the system prompt for every session on that prefix;
+2. the last user block that can carry one (`#mark_last`): never a thinking block, nor one that came from a later
+   system message, which moves every request.
+
+The log line's `cache=` says `on`, `1h` or nothing (`#cache_summary`). prompt-caching.md has the cache rules.
+
+## Dialects
+
+`LLM::Dialect` is a host's `dialect:` (`Dialect.parse` warns once on an unknown name or on a host whose api isn't
+`anthropic`): `auth` (the default key header), `thinking_display` (the `display` sent with adaptive or budget
+thinking, nil for none), `cache_breakpoints` and `session_header`.
+
+| Dialect | auth | thinking display | breakpoints | session header |
+|---|---|---|---|---|
+| `STANDARD` (no `dialect:`) | `x-api-key` | `summarized` | yes | none |
+| `FIREWORKS` | Bearer | none | no (an automatic prefix cache) | `x-session-affinity` |
+
+## 400 fallbacks
+
+`AnthropicMessages#chat` handles the 400s it can fix itself, once each per request, and remembers the fix for the
+adapter's life, so ChatLoop's broader paths never see them (`#refusal_fix`, logged under `http`; kept in an
+`LLM::RefusalMemo`, locked, since the turn, side-ask and recap threads share the host's adapter):
+
+| 400 about | Fix | Remembered |
+|---|---|---|
+| `thinking.display` (`DISPLAY_RE`) | no `display` from now on (`#without_display`), the thinking kept | per host (`thinking_display_refused`) |
+| adaptive thinking or its effort (`ADAPTIVE_REFUSED_RE`) | the budget form: `thinking: {type: "enabled", budget_tokens: BUDGETS[level]}`, no effort (`#budget_form`) | per model (`thinking_form_switched`) |
+| `cache_control` | no breakpoints | per host (`cache_control_refused`) |
+| `max_tokens: N > M` (`OUTPUT_CAP_RE`) | `max_tokens` capped at M | per model (`output_cap`) |
+
+The display check comes before the adaptive one: its path (`thinking.adaptive.display`) names adaptive too. A context
+overflow, a refused sampling field, a signature or a binding-controls 400 is not one of these: it goes on as it is,
+to the loop's own handling (ChatLoop's sampling and thinking-fields fallbacks) or to the turn's failure.

data/docs/internals/background-tasks.md

@@ -18,7 +18,7 @@ Recommended workflow:
 Behavior:
 
 - `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
-- Task metadata and output are persisted under `tmp/tasks/`.
+- Task metadata and output are persisted under `tmp/tasks/`: each task's `tmp/tasks/<id>/task.json` is a `TaskRecord` (`lib/samagotchi/tools/task_record.rb`, a value object: `.from_file` reads it, `#to_file` is the JSON object written, an update is a `#with`). Its keys keep their order; `stderr_path` and `handed_over_by` (a handed-over execute) and `stop_requested_by` (a stop under way or done) are left out until set. `bundles/slow-commands` reads these files on its own, so the shape is a contract.
 - A task record keeps its process's pid and start time (`pid_started`). Before `task_stop` signals, the pid must still lead its own process group and must not have started at another time; otherwise the pid was reused by another process, nothing is signalled and the task ends as failed. A start time that can't be read at that moment (a failed `ps`) falls back to the group check, as does a record without `pid_started` (from an older chi). `task_get`, `task_list`, `task_wait`'s polls and the running-task lists (a cancelled turn's note, a worker's idle exit) make the same check, so a task whose pid was reused reads as exited (failed) at once, not as running until a `task_stop`; on macOS that is one `ps` per running task per check (~5 ms).
 - A stop (`task_stop`, the user's Stop of an `execute`, the execute limit in kill mode) TERMs the task's process group, then KILLs it after a grace. The groups its processes started are stopped too: a GNU `timeout N cmd` (without `--foreground`) moves itself and its command to a group of its own. `ProcessGroup.stop` finds them with one `ps -A -o pid=,ppid=,pgid=` (~40 ms on macOS) before the TERM and again before the KILL, walking down from the group's members. A process whose parent already exited (reparented to init, e.g. a setsid'd `cmd &`, or a backgrounded `timeout N cmd &` after its shell exited) is not found and runs on.
 - Task listing is workspace-scoped (current project only).

data/docs/internals/bundles.md

@@ -35,6 +35,8 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
 | `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
 | `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
+| `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
+| `Placeholder` | `{{placeholder}}` patterns left in an installed memory, one line per file from `Installer#detect_placeholders`; a hint, never a gate |
 
 Readers of the installed state: `Hooks::BundleLoader` (Engine), `GuardrailWiring#bundle_rules`, `Plugin::Loader`,
 `ContextProviders` (scripts), `BundleNeeds` (index markers). Each goes through `Provenance.each_installed` / `#record`

data/docs/internals/engine.md

@@ -35,7 +35,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #                      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)
-  │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools
+  │     # 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
   │     #   (a frozen copy of the history, the prompt, and resumed)
   │     # turn_messages: system head + history + due reminders (:reminder_injected) + the user message
@@ -71,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
@@ -82,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.
@@ -134,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.
 
@@ -171,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, ...)
@@ -190,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:
@@ -207,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
@@ -227,6 +243,8 @@ 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
           → 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)
@@ -253,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
@@ -314,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
@@ -339,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!`.
@@ -354,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
 
@@ -411,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)
@@ -441,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 |
 |---|---|---|
@@ -548,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
 
@@ -563,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
@@ -573,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 |
@@ -588,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):
 
@@ -22,11 +23,15 @@ right-hand column happens.
 ```
  shared by every session ──────────────────────────────────────────────────  breaks it
 ┌──────────────────────────────────────────────────────────────────────────┐
-│ tools        built-ins, then plugin tools sorted by (bundle, name)       │  a tool added/changed,
-│              (chat: the `tools` field; native: the model's template)     │  /model, a profile change
+│ 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
 ├──────────────────────────────────────────────────────────────────────────┤
 │ SYSTEM, stable part                         SystemPrompt#system_prompt_with_index
 │   [native thinking token] base prompt                                    │
+│   not-loaded line (only when the toolkit leaves tools out)               │
 │   rg guidance                                                            │  /thinking level,
 │   system identity (+ model overlay)                                      │  /model, editing a
 │   model notes (model_notes_* matching the model)                         │  memory / AGENTS.md
@@ -34,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
@@ -46,22 +51,37 @@ 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!`,
+  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.
 - 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
   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.
 
@@ -107,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/memory.md

@@ -270,7 +270,7 @@ profiles, meta bundles that install a set of them:
 | profile | bundles |
 |---|---|
 | `core` | loop-guard, check-in, guardrails, slow-commands, agents-md: the recommended safety set |
-| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer |
+| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing
 install gets neither by itself: `chi bundle install core` (or `dev`).