samagotchi 0.54.0 → 0.56.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 143c9195fbbe50c8f8193c76815004f30354a01d2e1ec7d5019e70bc79c376df
-  data.tar.gz: c1047a49f05415f8ea9a2789cf32ecc2f6edbcbf5bbfa432a8b919bd193ae360
+  metadata.gz: 242e670188e9ae58b573c067f949fa0de43e15f6f5f10bcc11ea66a087b16bb8
+  data.tar.gz: e6bddbb6238764a871c1bcce826b92472ea7eb6e814ecdf399eb171ec9260c67
 SHA512:
-  metadata.gz: 12b4e73421655936e2d3183e7839f4a8580b1d2b93633cff098170540e2c98ba61cf02c847a4af8b5e19a59424f15691a81d0b38195640263773bdccf2e8b3d3
-  data.tar.gz: bf03f5dab6f9d7e30d37531127dfb88e48e779eb65f271de703f12566d728bbe869a0d3a935d33932afff4556c09b21bfe4d3d95f4b72c131bfc0521a41bf4b9
+  metadata.gz: bf35534c163ba8eb189e85b72ed03b687f203c5f3423909f46fbc358fda45ef1bde4716dd93c368c8a0eceb13fb5044a12250c23fa89eb8f6ee7ebf72857b614
+  data.tar.gz: f81d67ea98da8dbe42a2553a02a957cc2ecd70129c474fe2295f64881e980792cbc9ea446f11b338c255213f3b52976f1d380e5e3f5835f10ea475fbaa541e4d

data/CHANGELOG.md

@@ -8,6 +8,53 @@ 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
+
+- Web: refs. A file tool's row (read, edit, write) and the lines of its diff open the file in your editor: they look
+  like text until hovered (a dotted underline and `↗`, a diff line's `↗ N`), and a click opens the current file at the
+  line read or edited, the diff line's line or the hunk's start. Only a viewer on this machine gets them (a loopback
+  request, or this machine on its LAN address); the phone sees plain text. `web.editor` picks the editor: `vscode`
+  (the default), `vscode-insiders`, `cursor`, `zed`, `none`, or a URL template with `{path}` and `{line}`. The
+  browser and VS Code each ask once to allow it.
+- For development: `script/affected-specs`, the spec files to run for a change (changed specs, name matches,
+  docs-reading specs, specs naming the changed class), ranked and capped. It isn't part of the gem. See
+  [docs/testing.md](docs/testing.md).
+
+### Fixed
+
+- Web: a page that joins mid-turn (or reloads during one) keeps a grep that found nothing as a muted "no match" row,
+  as it showed live; it used to lose the mark.
+
 ## [0.54.0] - 2026-10-10
 
 ### Changed
@@ -2442,7 +2489,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.54.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
 [0.52.0]: https://github.com/dm1try/samagotchi/compare/v0.51.0...v0.52.0

data/bin/chi

@@ -137,7 +137,7 @@ parser = OptionParser.new do |opts|
           "every session outside a repo) or all") { |v| options[:scope] = v }
   # Accepted values of string entries that the registry doesn't type as enums.
   value_hints = { "status.line" => "on|off", "web.host" => "127.0.0.1|::1|localhost|lan|IP", "recap.sentences" => "N|N-M",
-                  "web.annotate_presets" => "text|text" }
+                  "web.annotate_presets" => "text|text", "web.editor" => "vscode|vscode-insiders|cursor|zed|none|URL" }
   # Universal config flags (implicit convention: ENV SAMAGOTCHI_* ↔ YAML dotted ↔ CLI --kebab)
   # Generated from Samagotchi::Config registry — Option A: snake leaf in YAML, kebab in CLI.
   Samagotchi::Config.cli_entries.each do |entry|
@@ -235,7 +235,8 @@ if options[:web]
   view = Samagotchi::Config.get("web.view")
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
                                       markdown: markdown, view: view, new_token: options[:new_token],
-                                      annotate_presets: Samagotchi::Config.get("web.annotate_presets"))
+                                      annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
+                                      editor: Samagotchi::Config.get("web.editor"))
 end
 
 # --resume and --attach take a unique id prefix too, like git.

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.
@@ -1094,6 +1169,34 @@ its own). The first target is a long session such as a day-long coordinator, whe
   turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts
   its saved context against the session's budget.
 
+## Opening files from chi web
+
+In `chi web`, a file tool's row (read, edit, write) and the lines of its diff are refs to that file. They look like
+text until hovered (the title gets a dotted underline and `↗`, a diff line an accent bar and `↗ N`); a click opens the
+file in your editor: a row's title at the lines it read or edited (an edit without a range at its first changed
+line, a write at line 1), a diff line at its line, a hunk header at the hunk's start. A drag that selects text isn't
+a click. `web.editor` picks what opens:
+
+```yaml
+web:
+  editor: vscode     # or vscode-insiders, cursor, zed, none
+  # editor: "idea://open?file={path}&line={line}"   # a template of your own
+```
+
+- A preset, or a URL template with `{path}` (the absolute path, each segment URL-encoded, the slashes kept) and an
+  optional `{line}` (1 when there is none). A value that is neither a preset nor has `{path}` logs a warning and
+  counts as `none`. A change needs a `chi web` restart.
+- A template that puts `{path}` in a query (`?file={path}`) gets the path's slashes unencoded; editors accept that.
+- The first click asks twice, once each: the browser asks to open the editor's links (choose "always allow"; Safari
+  and Chrome ask per origin, so another `chi web` port asks again), and VS Code asks to allow opening local files.
+- It opens the file as it is now, not the agent's copy: after later edits a diff line's number can point elsewhere,
+  and a file in a worktree that was removed won't open. The row's diff and output are what the agent saw.
+- Only a viewer on this machine gets refs: a loopback request, or this machine on its own LAN address
+  (`web.host: lan`, the LAN URL or its QR code opened here). A phone sees plain text. An SSH tunnel or a local
+  reverse proxy (`tailscale serve`) looks like loopback, so a remote viewer behind one gets refs that can't open.
+- `GET /api/sessions/:id` (and its `?tail=1`) carries `capabilities.editor` (true for such a viewer) and
+  `editor_url`, the template (null otherwise).
+
 ## All settings
 
 Every setting below takes the three forms described in
@@ -1171,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". |
@@ -1208,6 +1312,7 @@ described in their own sections.
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
 | `web.view` | `stage` | yes | How `chi web` draws a turn: `stage` (the running turn pinned above the composer) or `turn` (one block per turn in the history). See [CLI](cli.md#web-views). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
+| `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |
 | `no_interrupt` | `false` | `--no-interrupt` | Raise the step limit of a turn to 1000 (or `turn.max_iterations`, when larger); a top-level key. |
 | `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |

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/context-telemetry.md

@@ -22,9 +22,8 @@ Emission behavior:
 - The estimate is emitted on every request (both loops, before each request),
   so the web and the attached TUI get a fresh number each time.
 - The model's own `[CONTEXT: …]` line is still gated: it is left only on a rise
-  into a guidance bucket (from the second threshold up), never on a fall or a
-  cadence tick, and not again for a bucket a resumed session's line already
-  names.
+  into a guidance bucket (from the second threshold up), never on a fall, and
+  not again for a bucket a resumed session's line already names.
 - This is warn-only behavior (no automatic history truncation).
 - When the model server reports real `usage` fields in the stream payload, the
   telemetry uses those actual token counts (prefixed `src=server`) instead of the
@@ -57,6 +56,25 @@ both loops):
 Configuration:
 
 - `SAMAGOTCHI_CONTEXT_STATUS` (`true` by default): set to `false` or `0` to disable telemetry.
-- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when the server doesn't report one. chi asks llama.cpp for its real window first (`/props`, the per-slot `n_ctx`); this setting only fills in when it can't (mlx, oMLX, server down), and 256000 is the last resort.
+- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when neither the server nor the model's or host's config gives one (step 4 of the lookup below).
+- `models.<key>.window_tokens` / `hosts.<name>.window_tokens` (config file only): the window for one model, or for every model on a host (step 3 below).
 - `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (default `4.0`): heuristic ratio for char-to-token estimation.
-- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages. The buckets' guidance still gates the model's own `[CONTEXT: …]` line; nothing else reads `context.status_cadence` (it was removed once the event streamed on every request).
+- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` / `context.status_thresholds` (default `20,40,60,80`): comma-separated threshold percentages. They set the buckets, and the buckets' guidance gates the model's own `[CONTEXT: …]` line. (`context.status_cadence` is gone: the event streams on every request.)
+
+The `context.*` settings are read once, when the turn's `ContextStatus` is built, so a change counts from the next turn.
+
+Context window lookup (`ContextWindow.resolve`, the first that answers wins; the event's `window_source` / the line's
+`window_src` names it):
+
+1. The running server (`Client#context_window`): llama.cpp's `/props`, the per-slot `n_ctx` (`:server`). A remote
+   chat host has no `/props`, so the chat loop and the engine skip this step for it.
+2. The host's model list (the chat adapter's `#context_window`, e.g. a provider's `context_length`; `:model_list`).
+3. The config file's `models.<key>.window_tokens` (by the model's lookup names, as sampling and vision look a model
+   up; `:model_setting`), else `hosts.<name>.window_tokens` (`:host_setting`). `ContextWindow.setting` reads it per
+   turn for the effective model, after the hooks that may switch it.
+4. `context.window_tokens`: CLI, `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` or the config file (`:config` or `:env`).
+5. `ContextWindow::DEFAULT_TOKENS`, 256000 (`:default`).
+
+Settings (3 and 4) only fill in when the server and its list report nothing (mlx, oMLX, a server that is down). A
+window the stream's `usage` reports itself (`n_ctx` / `context_window`) wins over all of these for that request
+(`window_src=server`). `chi self` shows the offline answer (steps 3 to 5) and which setting gave it.

data/docs/internals/engine.md

@@ -16,14 +16,14 @@ Engine#run_turn → backend.complete(...) → KernelLoop#run (native) or ChatLoo
 
 ```
 Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:, max_tool_output_chars:,
-                pending_input:, continue:, origin:, images:)
+                pending_input:, continue:, origin:, images:, id:)
   │
-  ├── begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:)
+  ├── begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id:)
   │     # @session = session, session.status = RUNNING, used memories absorbed,
   │     # TurnState#begin!(controller:, sink:) (a new CancellationController when none is given),
   │     # a recap in flight invalidated, GuardrailWiring#begin_turn(origin)
   │     # Returns a Turn {session, prompt (nil on a continue), continue, on_event, controller,
-  │     #                 origin, started_at, id}
+  │     #                 origin, started_at, id (the caller's id:, else a new uuid)}
   │
   ├── Client.swap_probe_cancel(turn.controller)   # a Stop cuts this turn's /props probes
   │
@@ -39,7 +39,9 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # Returns false when a Stop came during the probes or the init wait, else true
   │
   ├── generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
-  │     # sync_kernel_client!, then @kernel.turn_settings = turn.settings with model_name and window_setting
+  │     # sync_kernel_client!, then @kernel.turn_settings = turn.settings with model_name, window_setting,
+  │     #   llm_context (turn_llm_context: the session's, the model's/host's, else llm_context.strategy)
+  │     #   and price (turn_price: hosts.<name>.models.<id>.price), all read per turn
   │     # turn.limit = max_iterations or IterationLimit.for
   │     # backend.complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
   │     # Returns LLM::ModelResult (text, conversation, canceled?, exhausted?, tool_activity,
@@ -172,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)
 
@@ -181,6 +196,7 @@ Both loops run a batch of calls the same way:
 One iteration with tool calls:
   KernelLoop#dispatch_calls / ChatLoop::Run#dispatch
     → ToolResponse.run_batch(runner, calls, iteration:, emit:, on_stream_event:, cap:)
+       # chat passes a block, called with each run as it finishes
       → :tool_dispatch_started {iteration, call_count}
       → for each call: ToolRunner#run(call, iteration:, call_index:, call_count:,
                                       on_stream_event:, max_tool_output_chars:)
@@ -192,15 +208,24 @@ One iteration with tool calls:
           → returns {output:, capped_output:, truncated:, activity:, images:, shown_params:,
                      shown_label:, diff:}
       → :tool_dispatch_completed {iteration, call_count}
-    → native: ToolResponse.joined(runs), one entry with the capped outputs
-      chat:   ToolResponse.single(run, tool_call_id:) per call, with the capped output
+    → native: ToolResponse.joined(runs, ids:), one entry with the capped outputs
+      chat:   ToolResponse.single(run, tool_call_id:, ids:) as each call finishes (the block), with the
+              capped output
+      ids: ToolIds.next_ids, chi's own ids for the outputs ("t41"), saved on the entry as tool_ids
+      (one per call of the batch for native, one for chat); LLM context edits name outputs by them
 ```
 
 **ToolRunner** (`ToolRunner#run`):
 - Runs the gate first, so `:tool_call_started` shows the call that will run (a before_tool_call hook may
   replace it; known-names corrects a misspelled name this way, and the model gets one line saying what ran).
 - Emits `:tool_call_started` {iteration, call_count, call_index, tool, call, params, label (plugin tools),
-  title, view}.
+  title, called_as, view, ref}. The row fields (title, called_as, view, ref) come from `ToolRowFields.for`, which the
+  reload (`Web::MessageParts#tool_part`) calls too. `ToolRowFields::ACTIVITY_KEYS` (title, called_as) travel
+  inside `activity` on the completed event; `EVENT_KEYS` (view, ref) go top-level on both events.
+  `Bridge::TurnAccumulator` (snapshot and replay) and the web (`activity.js` `ACTIVITY_FIELDS` /
+  `EVENT_FIELDS`) copy them by these lists, so a new row field is added there. `ref` is `FileRef.for` (a
+  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`).
 - Settles an ask verdict after `:tool_call_started`, so a UI shows the tool line and then the approval.
 - Dispatches through `KernelLoop#dispatch_tool_call`, or writes the denial text. Unknown tools are answered in
   `KernelLoop#dispatch` ("Error: no such tool ...", never repeating the wrong name).
@@ -211,7 +236,7 @@ One iteration with tool calls:
   with `[cut: N of M chars; read it in parts]` (N kept of M, the whole within the cap unless the cap is shorter
   than that line). The model (both loops), the event and the after_tool_call hook get that text.
 - Emits `:tool_call_completed` {iteration, call_count, call_index, tool, output, output_truncated, activity,
-  images, diff, waited_ms, view}, then fires `:after_tool_call` {iteration, tool, output, status}.
+  images, diff, waited_ms, view, ref}, then fires `:after_tool_call` {iteration, tool, output, status}.
 - The activity's status (`ToolActivity#tool_activity_status`): `error` for an `Error:` result and for an
   execute that exited non-zero, except a grep-family search that found nothing (`ToolActivity.no_match?`:
   exit 1, no stderr block, the last step is grep/egrep/fgrep/rg/ag/pgrep, no `&&` after a step that can fail
@@ -299,8 +324,8 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 |---|---|---|
 | `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, images?}` |
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
-| `:context_status` | every request, the current estimate before it | `{iteration, ...}` |
-| `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source}` (native adds `profile`, `profile_source`) |
+| `:context_status` | every request (unless `context.status` is off), the current estimate before it | `{iteration, status, usage, bucket, source}` (internals/context-telemetry.md) |
+| `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price}` (`price`: the turn's `ModelPrice#to_h`, nil without one; native adds `profile`, `profile_source`) |
 | `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` |
 | `:generation_retrying` | the transport retries the request, or the chat loop asks again for a step whose stream dropped mid-answer (`restarted: true`: what the step streamed is void, and the web's live step, the TUI's activity line, the Bridge's TurnAccumulator and the stream hooks' watch start it over) | `{iteration, attempt, max_retries, next_delay, error_class, error_message, status, restarted?}` |
 | `:generation_completed` | a generation ended, or was cut | `{iteration, content_length, thinking_chars, served_model, requested_model, finish_reason, ...}`; a cut adds `stopped_by`, `stop_reason`; the Engine adds `speed`, `tokens` |
@@ -308,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 |
@@ -368,7 +394,7 @@ puts the hook runtime on the event: `event[:hook]` (the hook's label) and five h
 
 | Helper | What it does | Used by |
 |---|---|---|
-| `event[:notify].call(text, level:)` | One line to the user (`:hook_notice`) | mcp (a server didn't start), loop-guard |
+| `event[:notify].call(text, level:, fallback_for:)` | One line to the user (`:hook_notice`); `fallback_for: :display` marks a line that stands in for the answer's display, which a UI that renders the display's links leaves out | mcp (a server didn't start), loop-guard |
 | `event[:ask_user].call(question:, options:, header:, allow_freeform:)` | A single-select question through the question flow; nil when there is no one to ask | known-names (a near-miss name: correct it?) |
 | `event[:stop_turn].call(reason)` | Cancel the running turn (reason `:hook`), with a warn notice | loop-guard (repeated calls), check-in (`/checkin stop`) |
 | `event[:stop_generation].call(reason)` | Cut the streaming generation; the turn goes on | loop-guard (thinking repeats itself) |
@@ -394,9 +420,18 @@ From `:after_turn` and `:session_end` there is no turn left: `stop_turn` and `st
 `ToolRunner` asks the kernel's `Guardrails::Gate` (set by the Engine from `GuardrailWiring`) before each call;
 the gate is not itself a hook. `Gate#evaluate` fires the `:before_tool_call` hooks (the voters, e.g. the
 known-names bundle or a config hook), which vote through `event[:guardrail]` (`deny!`, `ask!`) or the legacy
-`event[:blocked]` flag. A deny stays a deny for the hooks after it. Then the core checks run on the final call:
-protected paths, then the rules (config and bundles, e.g. the guardrails bundle's `rules.yml`; a rule can match
-the tool, its targets and the model). A gate that raises denies the call.
+`event[:blocked]` flag. A deny stays a deny for the hooks after it. Then the core checks run on the final call,
+in `GuardrailWiring#checks` order:
+
+1. load failures (`Guardrails::LoadFailures`): a required hook or rule file that failed to load denies every call;
+2. `rules.hook_asks`: with guardrails disabled, a hook's ask is dropped (a deny still applies);
+3. protected paths;
+4. `ScratchWrites` (a `chi scratch` session only): write and edit under the memories folder are denied;
+5. `ChildBoundary` (a delegate child only): a change outside its folder asks;
+6. the rules (config and bundles, e.g. the guardrails bundle's `rules.yml`; a rule can match the tool, its
+   targets and the model).
+
+A gate that raises denies the call.
 
 The verdict is one of:
 
@@ -457,10 +492,11 @@ thought after the cue, kept in the model message so the next prompt starts with
    `FailedTurn.attach`; after a Ctrl-C, only `turn.messages`.
 4. **Events are the contract.** UIs read events, not internal state. `on_event` is per turn; observers are
    persistent.
-5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine (per chat/native
-   and thinking level) and is reset only on a model switch, a tools change or a profile change. The stable part
-   (base prompt, identity, memories, AGENT.md, memory indexes) comes before the volatile tail (model, working
-   directory, session). prompt-caching.md covers this in detail.
+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, AGENT.md, memory indexes) comes before the volatile tail (model, working directory, session).
+   prompt-caching.md covers this in detail.
 
 ## Key files
 

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