samagotchi 0.55.0 → 0.56.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f90692cf867e2bd082f40c2ae576604656d23169163ed5584f9221ccec528ac1
-  data.tar.gz: ac4852809e3ccdc332dd0d052e17671096eb167691cdde6f01fc2ef6e43b9870
+  metadata.gz: 242e670188e9ae58b573c067f949fa0de43e15f6f5f10bcc11ea66a087b16bb8
+  data.tar.gz: e6bddbb6238764a871c1bcce826b92472ea7eb6e814ecdf399eb171ec9260c67
 SHA512:
-  metadata.gz: 541c55286cdad591988db3b43af6c60480061f931b418c83ff44afe3fe62e677df638021f082ce42241bd1f0145ca3a88173f9046341e9d282351cdc92814a1c
-  data.tar.gz: ae24243b3978c3f8f87a655c50d9f446128618b63d6dc5b10923f09eef90d11fcd4bee714692d287157340029f83097476c7d057f27c8ddff98c86f30678758b
+  metadata.gz: bf35534c163ba8eb189e85b72ed03b687f203c5f3423909f46fbc358fda45ef1bde4716dd93c368c8a0eceb13fb5044a12250c23fa89eb8f6ee7ebf72857b614
+  data.tar.gz: f81d67ea98da8dbe42a2553a02a957cc2ecd70129c474fe2295f64881e980792cbc9ea446f11b338c255213f3b52976f1d380e5e3f5835f10ea475fbaa541e4d

data/CHANGELOG.md

@@ -8,6 +8,34 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.56.0] - 2026-10-11
+
+### Added
+
+- `reasoning_history` (`drop`, `turn`, `all`) on a `models:` or `hosts:` entry, and `SAMAGOTCHI_REASONING_HISTORY`
+  for a whole process: which of its own reasoning a chat host's model gets back. `/model` names a configured level
+  and `chi self` shows it.
+- `/reasoning-history drop|turn|all|default` sets a session's own level (saved; continue and fork copy it); `/model`,
+  `/stats` and the web's session bar (a `reasoning` chip, on chat hosts) show it with its source.
+- `/thinking` and `/reasoning-history` ask before a change that makes the server read the conversation again (Gemma,
+  hosted APIs, a change to or from `all`); `--yes` applies at once. The terminal puts the `--yes` line in the next
+  input, the web's reply has an Apply button; `chi send`, `chi -p … --non-interactive` and piped lines apply directly.
+
+### Changed
+
+- A chat host (`api: openai`) now gets the running turn's reasoning back: each of the turn's earlier replies carries its
+  reasoning as `reasoning_content`, as Qwen's, Gemma 4's and DeepSeek's templates and the hosted APIs expect
+  (`reasoning_history: turn`, the default). A local Qwen thought ~8x less per request with it. `drop` sends none (as
+  before), `all` sends every reply's, earlier turns too. A host that refuses it (a 400 about reasoning) gets the step
+  again without it, and that model sends none from then on (a notice says so once). See "Reasoning history" in
+  docs/configuration.md.
+- `/thinking`'s cache note now tells a local chat server (only the tail; the whole prompt for a Gemma model) from a
+  hosted one (the whole conversation). The web's thinking chip sends its level with `--yes`.
+
+### Fixed
+
+- A local llama.cpp turn whose connection dropped mid-answer now restarts that step (up to twice) instead of failing.
+
 ## [0.55.0] - 2026-10-10
 
 ### Added
@@ -2461,7 +2489,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.55.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.56.0...HEAD
+[0.56.0]: https://github.com/dm1try/samagotchi/compare/v0.55.0...v0.56.0
 [0.55.0]: https://github.com/dm1try/samagotchi/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/dm1try/samagotchi/compare/v0.53.0...v0.54.0
 [0.53.0]: https://github.com/dm1try/samagotchi/compare/v0.52.0...v0.53.0

data/docs/architecture.md

@@ -280,7 +280,10 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `404` for an unknown id. A POST with a body because routes match exact paths.
 - `POST /session/:id/command` — a session command (`/model`, `/models`, `!rollback`, `!cmd`,
   `/continue`) for the worker loop; `202` with a `command_id` its `:command_ran` names, `400` when
-  the line isn't one.
+  the line isn't one. A `:command_ran` carries `thinking`, `reasoning_history` and `llm_context`
+  (the summaries the next turn runs under) when the command changed them or the model, and
+  `confirm: {line, text}` when a `/thinking` or `/reasoning-history` change from a `web:` or `tui:`
+  client asks first (`CacheConfirm`; nothing changed, `line` applies it).
 - `POST /session/:id/exit` — ask the worker to exit now (`{client_id:}`). The worker checks with
   the event log held (`WorkerIdleExit#hold_for_request`): `200 {status: "exiting"}` and it leaves
   like an idle exit, or `409 {status: "held", reason:}` with `turn_running`, `input_queued`,
@@ -390,7 +393,8 @@ server's `reasoning_content`; the raw-prompt loop splits each generation's
 stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
 from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
-so later requests and resumed sessions pair them. It has its own system prompt
+so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
+`reasoning_content` on the running turn's replies (`reasoning_history`). It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
 `Engine#build_stream_event_handler` is the one seam both loops' streams pass

data/docs/cli.md

@@ -489,14 +489,34 @@ from (`session`, `--thinking` / `SAMAGOTCHI_THINKING_LEVEL`, `models: <key>`,
 session's own level, which comes first; `/thinking default` unsets it. It is
 saved with the session (a `--resume`, a continue and `/model` keep it) and
 applies from the next turn's start; the reply says what the change costs the
-prompt cache: the whole prompt on native Gemma 4 (its `<|think|>` starts the
-prompt), only the tail on native Qwen, and other request fields on a chat host
-(a local llama.cpp or Splash server keeps its cache; a hosted API such as
-OpenRouter → Claude or OpenAI may restart its own). `/thinking` alone answers
+prompt cache: the whole prompt on Gemma 4 (native, or a local chat server whose
+model name says gemma: `<|think|>` starts the prompt), only the tail on Qwen
+(native, or a local llama.cpp or Splash server), and the whole conversation on a
+remote chat host (OpenRouter, a hosted API). `/thinking` alone answers
 mid-turn too; a change sent while a turn runs waits for the turn's end, and
 skips that turn's warm-up. `/stats` shows the level on its `thinking:` line.
 See "Thinking" in [configuration.md](configuration.md).
 
+`/reasoning-history` shows which of its own reasoning a chat host's model gets
+back from the next turn on, and where that came from (`session`,
+`SAMAGOTCHI_REASONING_HISTORY`, `models: <key>`, `hosts.<name>`, the default
+`turn`). `/reasoning-history drop|turn|all` sets the session's own level, which
+comes first; `/reasoning-history default` unsets it. It is saved and carried as
+`/thinking`'s is, and a native host ignores it (the reply says so). A change to
+or from `all` once an earlier reply has thinking rewrites the earlier replies;
+`drop` ↔ `turn` costs nothing. `/stats` shows it on its `reasoning history:`
+line, the web as the `reasoning` chip. See "Reasoning history" in
+[configuration.md](configuration.md).
+
+A `/thinking` or `/reasoning-history` change that restarts the prompt cache
+asks first: the reply says what it costs, changes nothing, and names the line
+that applies it (`/thinking low --yes`). `--yes` (or `-y`) applies it at once.
+The terminal puts that line in the next input (Enter applies it); the web's
+reply has an Apply button. `chi send ID "/thinking low"`,
+`chi -p "/thinking low" --non-interactive` and lines piped into the REPL apply
+without asking (a plain `chi -p` opens the REPL, which asks). See "Changes that
+restart the prompt cache" in [configuration.md](configuration.md).
+
 ### Typing during a turn
 
 The prompt stays open while a turn runs, in an attached terminal and in the plain
@@ -525,9 +545,10 @@ REPL alike:
   - At once, beside the turn: `/stats`, `/recap`, `/help`, `/context`, a
     plugin's anytime command (`/btw`), and the commands that only show
     something: `/models` (with a filter too), and `/model`, `/llm-context`,
-    `/thinking` and `/guardrails` alone.
+    `/thinking`, `/reasoning-history` and `/guardrails` alone.
   - After the turn: the ones that change something (`/model X`, `/model clear`,
-    `/llm-context strategy …`, `/thinking LEVEL`, `/guardrails revoke N`) and `!cmd`, whose output
+    `/llm-context strategy …`, `/thinking LEVEL`, `/reasoning-history LEVEL`, `/guardrails revoke N`) and
+    `!cmd`, whose output
     joins the conversation. `(queued: runs after this turn)` says so at once (the
     web draws the command's bubble dashed, with the same words, until it ran);
     when the turn ends they run in the order sent, a prompt sent before one
@@ -698,7 +719,8 @@ as you toggled them. A reloaded session shows the same block
 from the saved messages (each step's thinking, narration, tool parameters
 and output, the output capped at 2000 characters) and the timing records
 (status and duration per row). On an `api: openai` host the model's
-reasoning is saved with each step for this (never sent back to the model);
+reasoning is saved with each step for this (and sent back to the model
+within the turn: see "Reasoning history" in [Configuration](configuration.md));
 steps saved before that have none, so they show no thinking. An `edit` or
 `write` row has a closed `diff +3 −1` under it that opens to the change it
 made (up to 120 lines or 8 KB), live and after a reload (see

data/docs/configuration.md

@@ -487,15 +487,15 @@ models:
   (`chi web`'s, say) wakes it later: use `chi send --new --thinking low`.
 - A level is fixed for a turn: a change takes effect at the next turn's start. `/thinking LEVEL` sent while a turn
   runs waits for its end (as `/model X` does), and holds off that turn's warm-up. What a change costs the prompt cache,
-  which `/thinking` says:
+  which `/thinking` says (and asks before the costly ones: "Changes that restart the prompt cache"):
 
-  | Backend | A level change |
-  |---|---|
-  | native Qwen (`qwen36`) | only the prompt's tail (the empty thought after the cue) |
-  | native Gemma 4 (`gemma4`) | the whole prompt is read again: `<\|think\|>` starts the system prompt |
-  | chat host, local llama.cpp or Splash | other request fields; the server keeps its cache (a Gemma template re-reads it all) |
-  | chat host, OpenRouter → Claude | thinking params are part of the cached prefix: the cache restarts |
-  | chat host, OpenRouter → OpenAI reasoning | an effort change rewrites hidden instructions: the prefix is lost |
+  | Backend | A level change | Asks |
+  |---|---|---|
+  | native Qwen (`qwen36`) | only the prompt's tail (the empty thought after the cue) | no |
+  | native Gemma 4 (`gemma4`) | the whole prompt is read again: `<\|think\|>` starts the system prompt | yes |
+  | chat host, local (llama.cpp, Splash), a model name with `gemma` | the whole prompt: the template writes the same token | yes |
+  | chat host, local, any other model | other request fields; the server keeps its cache, only the tail changes | no |
+  | chat host, remote (OpenRouter, a hosted API) | Claude's thinking params are part of the cached prefix, an OpenAI effort change rewrites hidden instructions: the conversation is read again | yes |
 
 - `models:` levels and `thinking.level` in the file are read every turn; a host's `thinking:` reaches a worker when
   it starts, as its `sampling:` does (`chi sessions stop` to change it).
@@ -539,6 +539,81 @@ hosts:
 A different level changes a native model's system prompt (Gemma's token, Qwen's turn preamble), so the next turn
 reads the whole context again once; on a chat host only the end of the prompt changes.
 
+## Reasoning history
+
+Which of its own reasoning a chat host's model (`api: openai`) gets back. chi saves each step's reasoning; with it
+sent back, the model goes on from its own plan between tool calls instead of working it out again (in one test a local
+Qwen thought about 8x less per request and finished a small task about 40% sooner). One level, set per model or per host:
+
+```yaml
+hosts:
+  deepseek-api:
+    url: https://api.deepseek.com/v1
+    api: openai
+    api_key_env: DEEPSEEK_API_KEY
+    reasoning_history: all   # its API wants every earlier reply's reasoning when tools are sent
+models:
+  some-model:
+    reasoning_history: drop
+```
+
+- `turn` (the default) sends the running turn's reasoning: each reply since the last user message carries its
+  reasoning as `reasoning_content`, which is what Qwen's, Gemma 4's and DeepSeek's chat templates and the hosted APIs
+  (OpenRouter takes it for DeepSeek, Qwen and other text-reasoning models) expect. The running turn starts at the
+  last message you sent (a prompt, or a steer: as the chat template counts it) and never before the turn's own start,
+  so a turn that goes on by itself (a reminder, a context wake, a continue after a stop) sends nothing of the one
+  before it, an interrupted reply's partial thought included.
+- `drop` sends none (what chi did before this setting).
+- `all` sends every reply's reasoning, earlier turns too. It sends only the field: a local template that leaves out
+  earlier turns' reasoning (Qwen's) needs `sampling: {chat_template_kwargs: {preserve_thinking: true}}` as well.
+- Order, first set wins: the session's own level, `SAMAGOTCHI_REASONING_HISTORY` (the whole process; for A/B runs),
+  the `models:` entry (found the way `profile:` is), the `hosts:` entry, then `turn`. Anything else than a level warns
+  once and counts as unset. A host's level reaches a worker when it starts, as its `sampling:` does.
+- **A session's own level** (`drop`, `turn` or `all`; an explicit `turn` counts as its own) is saved in the session
+  (its file's `"reasoning_history"`), so a `--resume`, a respawned worker, a continue and `/model` keep it; a plugin's
+  fork copies it, a delegate child starts without it. Set it with `/reasoning-history LEVEL` in the session
+  (`/reasoning-history default` unsets it, `/reasoning-history` alone shows the level and where it came from) or the
+  web's `reasoning` chip in the session bar (shown on chat hosts only). There is no start flag: a fresh session runs
+  the command before its first turn at no cost. A change takes effect at the next turn's start; sent while a turn runs
+  it waits for its end.
+- What a change costs the prompt cache (`/reasoning-history` says so, and asks first when it costs: "Changes that
+  restart the prompt cache"):
+
+  | Change | Cost |
+  |---|---|
+  | `drop` ↔ `turn` | none: a turn's first request carries no reasoning under either |
+  | to or from `all`, once an earlier reply has thinking | every earlier reply gains or loses its reasoning: a server that renders it (hosted APIs, llama.cpp's default template) reads the conversation again from the first earlier thought |
+  | nothing thought yet, the same level, or a native host | none |
+
+- The native loop (`/completion`) ignores it: it always keeps the running turn's reasoning, a mid-turn steer included
+  (the chat loop starts again after a steer).
+- When a host answers a request that sent reasoning back with an HTTP 400 about reasoning, chi asks again without it,
+  sends none to that model from then on (until the worker restarts) and says so once. If the request without it is
+  refused too, the thinking fields get the same fallback ("Thinking") and the reasoning goes back on the next step.
+- `/model` names a level that isn't the default (`reasoning history: drop (models: some-model)`, `all (session)`),
+  `/stats` shows it on its `reasoning history:` line (chat hosts only), and `chi self` on its `reasoning history` row
+  (a session's own level first when run from its commands).
+- Claude via OpenRouter signs its reasoning (`reasoning_details`), which chi doesn't keep: it gets the plain text,
+  and the fallback above covers a refusal.
+
+## Changes that restart the prompt cache
+
+`/thinking` and `/reasoning-history` ask before a change that makes the server read the conversation again: Gemma's
+thinking switch, a remote chat host's thinking fields ("Thinking"), and a change to or from `all` once an earlier reply
+has thinking ("Reasoning history"). They ask only when the level the next turn runs under really changes and the
+session has a model reply.
+
+- The reply says what it costs and changes nothing yet: `Nothing changed yet: send /thinking low --yes to apply.`
+- `--yes` (or `-y`, anywhere after the command) applies it at once.
+- The terminal (the REPL and an attached TUI) puts the `--yes` line in the next input: Enter applies it.
+- The web's reply bubble has an **Apply (restarts the cache)** button. The session bar's chips are already an explicit
+  choice: their Set sends the `--yes` line, and their form says what a change costs. Command bubbles are page-only, so
+  the button is gone after a reload.
+- Only a person at a web tab or a chi TUI is asked. `chi send ID "/thinking low"`,
+  `chi -p "/thinking low" --non-interactive`, lines piped into the REPL, a delegate, a plugin and a card's action
+  apply directly, since nobody would see the question; so do the start flags (`chi --thinking` on a resumed or
+  attached session sends `/thinking LEVEL --yes`). A plain `chi -p` opens the REPL, which asks.
+
 ## Llama HTTP Timeouts
 
 Long-running llama.cpp completions can exceed Ruby's default HTTP read timeout.
@@ -1199,6 +1274,7 @@ described in their own sections.
 | `context.every_seconds` | `300` | | How often an attached context source's command runs when it has no `--every` (seconds, at least 30). See [Attached context](context.md). |
 | `context.wake` | `true` | yes | A source whose update says `wake: true` may start a turn in a live, idle session (one per source per 10 minutes, within `session.max_wakes`); `false`: updates wait as notes for the next turn. See [Waking](context.md#waking). |
 | `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |
+| `reasoning_history` | `turn` | | Which of its reasoning a chat host's model gets back: `drop`, `turn`, `all`; environment only (`SAMAGOTCHI_REASONING_HISTORY`), below a session's own level (`/reasoning-history`), above the `models:`/`hosts:` entries. See "Reasoning history". |
 | `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't; a session's own level outranks them all, and `--thinking` sets it on a session run (on `chi web` it sets this). See "Thinking". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
 | `hosts.<name>.models` | none | | The model ids a host serves whatever its `/v1/models` lists: a map of ids, or a plain list. See "Models a host serves but doesn't list". |

data/docs/internals/background-tasks.md

@@ -24,6 +24,6 @@ Behavior:
 - `task_get` returns metadata and `output_path`; use `read` for output contents.
 - `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).
 - `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.
-- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) and `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none). `chi self` reads the last two for its model and thinking level. The three are `TaskRuntime::MARKER_ENV_KEYS` (and `SessionManager::SESSION_MARKER_ENV`, which a spawned worker unsets). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
+- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none) and `SAMAGOTCHI_SESSION_REASONING_HISTORY` (its own reasoning_history level, the same way). `chi self` reads the last three for its model, thinking level and reasoning history. The four are `TaskRuntime::MARKER_ENV_KEYS` (and `SessionManager::SESSION_MARKER_ENV`, which a spawned worker unsets). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 
 Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/engine.md

@@ -174,6 +174,19 @@ The differences from the native loop:
   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.
 - 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:
+  `Session#reasoning_history`, `/reasoning-history`): `all` on every model message, `turn` past
+  `ChatLoop#reasoning_boundary`: the later of the last query (a `role: "user"` entry: a prompt, a steer, merged input,
+  the chat template's `last_query_index`; or a `turn_start` entry) and the Run's start (`Run`'s `@start`, the
+  conversation length at `#complete`), so a continue turn (reminder, context wake, continue after a stop) replays
+  nothing of the run before. `Run#prompt_chars` counts it (`#reasoning_chars`). The native loop differs on a steer:
+  `KernelLoop#inject_pending_input!` doesn't re-sanitize, so native keeps the turn's reasoning across a mid-turn
+  steer, where the chat loop starts again (as the template does).
+- 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
+  `: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.
 
 ### Shared: ToolResponse (per batch) and ToolRunner (per call)
 
@@ -320,6 +333,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:empty_answer_retry` | an empty, cut or malformed answer is asked again | `{iteration, attempt, of, finish_reason, thinking_chars, stopped_by?, malformed?}` |
 | `:steer_cut` | a steer cut the generation | `{iteration, source}` |
 | `:llm_context_edited` | the apply rule applied a batch of LLM context edits (a request, a forget_outputs call, turn end; never the warm-up) | `{moment, why, freed_tokens, tail_tokens, staged, text, groups}` (`LLMContextNotice`) |
+| `:thinking_refused` / `:reasoning_history_refused` | the chat loop asked a step again without the thinking fields / the reasoning sent back; the Engine logs it and makes a once-per-session-and-host `:hook_notice` of it, the event itself never reaches the sink | `{iteration, model, level, detail}` |
 | `:pending_input_merged` | queued input joined the conversation | `{iteration, count, content, steers?, answer}` |
 | `:tool_dispatch_started` / `:tool_dispatch_completed` | around a batch | `{iteration, call_count}` |
 | `:tool_call_started` | before a call runs | see ToolRunner |

data/docs/internals/prompt-caching.md

@@ -135,6 +135,14 @@ is prefilled once. The native and the chat loop use the same plan.
    on its `generation_completed` log line. `/stats` shows "cached N (P%)" and "cache writes". A change that
    drops `cached=` on the second fresh session is a regression. Update the prompt snapshot fixtures with
    `UPDATE_PROMPTS=1` and read the diff: a cache-friendly change moves sections, it doesn't reorder per run.
+6. **Ask before a setting change that restarts the cache.** A session setting whose change makes the server read
+   the conversation again asks a person at a web tab or a TUI first (`CacheConfirm`: the reply carries the
+   `--yes` line, `SessionCommands::Result#confirm` and the `command_ran` event's `confirm`). Each setting has a
+   classifier: `Thinking.cache_cost` (`:full` for Gemma, `:provider` for a remote chat host, `:tail` otherwise) and
+   `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking).
+   `CacheConfirm.needed?` asks only for `:full`, `:provider` and `:history`, when the effective level changes and
+   the session has a model reply. A new setting with a cost (a `/model` across templates, `/llm-context` turning
+   forget on) adds its classifier and goes through the same step.
 
 ## Server-side settings worth knowing
 

data/docs/sessions.md

@@ -68,7 +68,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`), and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`), and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
 - The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `day N` chip and rows, the info bar's ← → links, a refused continue), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, the actions per kind, one delegated click). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -58,7 +58,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
 - `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
-- `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
+- `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.55.0
+version: 0.56.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:45064ac6b19863e1646d15891d0e9cc7a8f10ab981a0d25d6e13891591538b8a
+  config_modification_protocol.md: sha256:d908921b5988244fb2a03fe04e693d0e7a1dfadf8cd77704e9232826db7eb2d7
   memory_guide.md: sha256:15cd3b24eda853cc458371c6c75809a2d4b5352311d075aaa4384926b5221c27
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/cache_confirm.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The confirm step before a session setting change that restarts the
+  # prompt cache (/thinking, /reasoning-history): such a change, sent
+  # without --yes from a person at a web tab or a chi TUI, changes nothing
+  # and replies with what it costs and the line that applies it. Two steps,
+  # no stored state: the reply carries a Confirm (SessionCommands::Result,
+  # the worker's command_ran), the TUI prefills its line, the web draws an
+  # Apply button that sends it.
+  module CacheConfirm
+    YES_FLAGS = %w[--yes -y].freeze
+    # The costs worth asking about (Thinking.cache_cost,
+    # ReasoningHistory.cache_cost); :tail and nil are not.
+    COSTLY = %i[full provider history].freeze
+
+    # The line that applies a change, and the question the reply ends with.
+    Confirm = Data.define(:line, :text) do
+      # The plain form the worker's command_ran carries.
+      # @return [Hash] symbol keys
+      def to_h = { line: line, text: text }
+    end
+
+    module_function
+
+    # A command's argument words with --yes / -y (anywhere) taken out.
+    # @param args [String] what follows the command name
+    # @return [Array(String, Boolean)] the rest, stripped and downcased, and
+    #   whether --yes was there
+    def split(args)
+      words = args.to_s.strip.downcase.split
+      yes = words.any? { |word| YES_FLAGS.include?(word) }
+      [(words - YES_FLAGS).join(" "), yes]
+    end
+
+    # Whether a change must ask first: the effective level changes, the
+    # cost is one of COSTLY, and the session has a model reply (a cache to
+    # restart at all).
+    def needed?(cost:, history:, changed:)
+      changed && history && COSTLY.include?(cost)
+    end
+
+    # The Confirm for +name+ set to +word+: the line with --yes, and the
+    # question naming it.
+    # @return [Confirm]
+    def confirm(name, word)
+      line = "#{name} #{word} --yes"
+      Confirm.new(line: line, text: "Nothing changed yet: send `#{line}` to apply.")
+    end
+  end
+end

data/lib/samagotchi/client_id.rb

@@ -39,8 +39,20 @@ module Samagotchi
     HUMAN_PREFIXES = [WEB_PREFIX, TUI_PREFIX].freeze
     HUMAN_IDS = [CLI_SEND].freeze
 
+    # A person at a screen that shows a command's reply and can answer it
+    # (#interactive?): a web tab, an attached chi TUI.
+    INTERACTIVE_PREFIXES = [WEB_PREFIX, TUI_PREFIX].freeze
+
     module_function
 
+    # Whether +client_id+ is a web tab or a chi TUI, which see a command's
+    # reply and can send the line it asks for (CacheConfirm); chi send, a
+    # delegate, a plugin, chi itself and nil are not.
+    def interactive?(client_id)
+      id = client_id.to_s
+      INTERACTIVE_PREFIXES.any? { |prefix| id.start_with?(prefix) }
+    end
+
     # Whether +client_id+ (a turn's or a line's origin) is a human's input.
     def human?(client_id)
       return true if client_id.nil?

data/lib/samagotchi/config.rb

@@ -187,6 +187,10 @@ module Samagotchi
       # is bin/chi's own --thinking; models: and hosts: entries rank below
       # the flag and the env, above config.yml's value.
       Entry.new(key: "thinking.level",           yaml_path: %w[thinking level],           type: :string, default: "default",       expose: %i[env config]),
+      # Which of its reasoning a chat host's model gets back (ReasoningHistory):
+      # the environment only, for A/B runs; models: and hosts: entries are
+      # the config surface.
+      Entry.new(key: "reasoning_history",        yaml_path: %w[reasoning_history],        type: :string, default: nil,              expose: %i[env]),
 
       Entry.new(key: "default.max_tokens",       yaml_path: %w[default max_tokens],       type: :integer, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli]),
@@ -269,9 +273,9 @@ module Samagotchi
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
     MAP_ENTRY_KEYS = {
-      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking enabled
-                    remote window_tokens llm_context_strategy llm_context_apply llm_context_budget_tokens models].freeze,
-      "models" => %w[profile vision sampling thinking window_tokens llm_context_strategy llm_context_apply
+      "hosts" => %w[host port url transport api api_key_env profile first_token_timeout vision sampling thinking
+                    reasoning_history enabled remote window_tokens llm_context_strategy llm_context_apply llm_context_budget_tokens models].freeze,
+      "models" => %w[profile vision sampling thinking reasoning_history window_tokens llm_context_strategy llm_context_apply
                      llm_context_budget_tokens].freeze
     }.freeze
     # The keys a hosts.<name>.models entry may hold (HostModel.parse_map).