samagotchi 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 236e301c873eb2b96520aeeb3e7668e535f50174b1afb94d28a149cef161d418
-  data.tar.gz: adc3281cace9460e307abe5abc33719041863898e848f10b290d5d2d3e4c93d5
+  metadata.gz: 6abdccc8a805a545ad1e27898b3caf43516d16ef1b7832444bac7b6e0a4b5e63
+  data.tar.gz: 8c0e0f354030f8ad954afdfd9dff96ef54d0b1fdd79d8df190cf494a8a32b18d
 SHA512:
-  metadata.gz: 6e97629a0a1459a7c9b403a495aea87807f4b2570421e369a56a01afd140830b8284e7d25a86132f14ebdab95275913f66caa8aea48680d23b507dec9d57b519
-  data.tar.gz: 284540411644a596492ad2d91c36eecb23f8eb435b95e06781e387b4933a6210680e15b6d79f035b1abd029b726aa9489bdee39816a9d509bfb7a1810b92b00e
+  metadata.gz: 36530955a235e3d73adaa4496545c12f6abea21daf1ff0a40eaba9477c22e1e7007dced1a500912878164c0a9f1a9ec76b45d4d8a34709473d8c496b1d53ce69
+  data.tar.gz: 125d6ab7dd048082ff6296d663803da9d6a8073c7ead520f2264ec4cc27c28d29bdb772addd47f2be39b9aa497308ef09236bd5e3e1bc43854341970fc8e6a6e

data/CHANGELOG.md

@@ -8,6 +8,96 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-04
+
+### Added
+
+- The web shows an `execute` command as the steps a person reads: `cd X &&` becomes an "in X" tag, `| head -20` a
+  chip, `echo "=== x ==="` a label, a heredoc a collapsed "EOF · N lines" chip; the collapsed row's title is the
+  first step `+N`. A `raw` toggle shows the whole command; anything the parser can't read shows as before.
+- `execute` takes an optional `description` ("what the command does, in a few words"), written by the model; it
+  becomes the tool row's title in the web and replaces the cut command in the terminal's tool line. Turn it off
+  with `execute.description: false`.
+- Every generation logs its prompt-cache counts (`prompt=`, `cached=`, `cache_write=`), and `/stats` shows cache
+  writes next to cached tokens.
+- A generation cut mid-thinking (loop-guard, a plugin's stop, a steer) or ended at the provider's output cap keeps
+  the last 20k chars of its thinking in the session's folder, `thinking_tails.jsonl`, so an archived session holds
+  the loop it was archived for. The model never sees it.
+- Turn records count `cuts` (generations a plugin cut) and `capped` (generations that hit the output cap), and
+  `/stats` shows them as "thinking cuts" and "output cap hits": `retries` counts network retries only.
+
+### Changed
+
+- On macOS, `execute`, `task_create` and `!cmd` run commands in `/bin/zsh` emulating sh (with bash's `{1..3}`,
+  `[[ =~ ]]` groups and echo escapes kept) instead of `/bin/sh`, which is bash 3.2 there and failed on an apostrophe
+  in a heredoc inside `"$( )"`: `git commit -m "$(cat <<'EOF' … it's … EOF )"` now works. Linux keeps
+  `/bin/sh`; see [background tasks](docs/internals/background-tasks.md).
+- loop-guard's cut notice (bundle 0.3.3) quotes the looping sentence: `thinking repeats itself ("Let me write the
+  tool call.", one sentence ×8, 33k chars, 63 s): cut`.
+- The system prompt puts what every session shares first and the per-session lines (model, working directory,
+  session) last, and plugin tools come in a fixed order, so a new session reuses the server's prompt cache: on a
+  local llama.cpp or Splash server its first answer starts in about 0.5 s instead of 4–6 s, and on Claude via
+  OpenRouter a new session reads the shared part from the cache (about 7× cheaper to start).
+- Chat hosts (`api: openai`) are no longer asked for `temperature: 0.0`: chi sends no temperature unless one is
+  configured, so each model runs at its provider's default (as native llama.cpp hosts already did). Greedy decoding
+  made DeepSeek v4.1-flash loop in its thinking. The idle recap and `/btw` follow suit. Set `sampling: {temperature:
+  …}` on a `hosts:` or `models:` entry to pin one; the empty-answer retry still runs at 0.6 unless one is set.
+
+### Fixed
+
+- loop-guard (bundle 0.3.3) cuts thinking that loops in a cycle of 7 or 8 short sentences, or with a longer
+  sentence ("I'll write the spec file now.") in the cycle: 48 sentences in a row with 12 or fewer different ones are
+  a loop. New settings `thinking.window_sentences` (48) and `thinking.window_distinct` (12).
+- A steer row names chi's senders in words: the web's row and trail flash and the terminal's nudged line say
+  `parent agent`, `chi send` and `plugin` instead of the raw `parent_agent` / `chi_send` / `plugin_send`.
+- Thinking off on Gemma 4 no longer warns that off wasn't honoured: its empty thought (whitespace alone) is not
+  counted as thinking.
+- An OpenRouter 402 whose `metadata.reason` is `weight_exceeds_budget` (the request alone is larger than the
+  key's credit budget) fails at once as `request too large for the credit budget on host <name>: …; lower
+  max_tokens (default.max_tokens) or raise the key's credit limit`, instead of being retried as credit held by
+  in-flight requests. Other 402s are unchanged.
+
+Update with `chi update`: loop-guard moves to 0.3.3 (the window rule and the quoted cut notice). Restart `chi web`
+and running sessions afterwards (`chi sessions restart ID`).
+
+## [0.24.0] - 2026-10-04
+
+### Added
+
+- `steer.cut_after` (default 20 s, `0` = never): a message for a running turn from you, `chi send` or a parent
+  agent cuts a generation that has streamed only thinking for that long (counted from its first thinking token;
+  a message that came earlier cuts once the thinking gets there).
+  The model starts the step again with the message, and a `↪ cut in for your message` row marks it. Plugins'
+  steers never cut. Only the cut thinking is lost (llama.cpp re-reads the few tokens after its cached prompt).
+
+### Changed
+
+- The web shows an `execute` / `task_create` call's full command: an expanded tool row has it as a block above the
+  output (whitespace kept, a copy button, `in <cwd>` when the call gave one), and the row's and the stage's hovers
+  show the whole command instead of the 80-character `command="…"` line. The terminal is unchanged.
+- A message that joins a running turn (a line typed in the terminal or the web, `chi send -m`, a delegate's
+  follow-up, `chi answer --option Continue --text`, a plugin's `ctx.steer`) reaches the model with a one-line
+  header naming its sender and asking it to follow the message, or carry on if it asks for nothing, so the model
+  can tell who is steering it. Sessions keep the raw text.
+- The `generation_stopped` log line names who cut the generation as `by=` (was `bundle=`), as a message can cut
+  it now too.
+
+### Fixed
+
+- Guardrails read heredocs (`cat <<'EOF' … EOF`): a heredoc's body no longer asks needlessly (an `rm -rf` or
+  `git push` written into a file by `cat`/`tee`), and an apostrophe in a body no longer hides the commands after it
+  from the strict-mode check for git outside the repo. A body fed to `bash`, `sh` and the like still counts.
+- A `chi send -m` or delegate follow-up merged into a running turn is saved with its sender (`source: chi_send` /
+  `parent_agent`) instead of reading as the user's own words.
+- The idle recap keeps the text of a `chi answer --option Continue --text` (or a continue card answered with
+  text); it was dropped as a plugin's prod.
+- check-in no longer says a nudge was not sent when a user line was merged after it (bundle check-in 0.2.3).
+- A plugin's cut of a generation (loop-guard) with a message or a plugin's steer waiting now delivers it even after
+  `retry.empty_answer`'s budget is spent; the turn used to end cancelled and drop a waiting plugin steer.
+
+Update with `chi update`: check-in moves to 0.2.3 (the nudge-not-sent fix). Restart `chi web` and running sessions
+afterwards (`chi sessions restart ID`).
+
 ## [0.23.0] - 2026-10-04
 
 ### Changed
@@ -1304,7 +1394,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.23.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/dm1try/samagotchi/compare/v0.24.0...v0.25.0
+[0.24.0]: https://github.com/dm1try/samagotchi/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/dm1try/samagotchi/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/dm1try/samagotchi/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/dm1try/samagotchi/compare/v0.20.0...v0.21.0

data/docs/architecture.md

@@ -184,12 +184,18 @@ engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
 
-The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance,
-AGENT.md, the working directory, **the model** (`Model: this session runs on
-<ref> (host …; model key …)` and a line telling the model to answer "which model
-are you" from it, not from training), the session id and log, the memory indexes,
-the identity and the preloaded memories. It is built once per loop and rebuilt only
-by a model switch (or changed tools), so the model line costs no KV churn.
+The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance, the
+identity and the preloaded memories, AGENT.md, the memory indexes, and last **the
+model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
+the model to answer "which model are you" from it, not from training), the working
+directory and the session id and log (Gemma's native tool declarations still follow).
+The order is for the servers' prompt caches, which reuse only an exact token prefix:
+what every session shares first, what changes least before what changes more, the
+per-session lines last, so a new session reuses everything above them. It is built
+once per loop and rebuilt only by a model switch (or changed tools), so the model
+line costs no KV churn.
+The full request layout, what breaks the cache and the rules for changes:
+[internals/prompt-caching.md](internals/prompt-caching.md).
 
 #### Subscribing to the live stream (and the bridge)
 
@@ -275,11 +281,12 @@ The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` fr
 newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
 calls and the running turn's finished ones. The full history is the session's `analytics.json`,
 which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
-The totals' `tokens` block adds the cached and reasoning sums, the cost, the decode time and tokens
+The totals' `tokens` block adds the cached, cache-write and reasoning sums, the cost, the decode time and tokens
 behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
 `last_prefill_tps`, `tps_source`: `server` or `estimate`). Each `generation_completed` event
-carries the generation's `speed` (`{decode_tps, source}`, null without one) and those running
-`tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
+carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
+counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
+those running `tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
 it, so the web's info bar updates per generation without parsing chunk payloads.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:

data/docs/cli.md

@@ -274,7 +274,12 @@ Plain `chi` runs the session in a background worker and attaches the terminal
 to it (`session.shared`, default `true`). A worker's session can have any number
 of UIs at once: the Web UI and attached terminals (`chi`, `--resume`,
 `--attach`). They all see the same turns as they happen, and any of them can send
-a prompt, also while a turn runs (it merges into that turn as steering). The
+a prompt, also while a turn runs (it merges into that turn as steering: the model
+is told it is a steer and who sent it). Steering waits for the model's next step,
+unless the model has streamed only thinking for `steer.cut_after` seconds (default
+20), now or while your message waits: then that generation is cut and the step starts again with your message, marked
+`↪ cut in for your message` (see
+[configuration.md](configuration.md#llama-network-retry-behavior)). The
 first answer to an `ask_user_question` wins; the other UIs close their widget.
 An empty answer dismisses the question in every UI. The model is then told
 not to go ahead with what it asked about, or change anything else, and to wait.
@@ -415,9 +420,10 @@ file and index line stay as they are; only this session doesn't see it.
 `/help` lists the commands this session takes, the installed bundles' too, each
 with a line on what it does. `/stats` shows the session's numbers: turns, tool
 calls (by tool, with errors), iterations, tokens in/out summed over every
-request (with the cached and reasoning tokens when the server reports them),
-the decode speed, generation latency, cancellations, retries, context used
-and window, the prompt profile and the model the server says it ran, and the
+request (with the cached tokens, the cache writes and the reasoning tokens when the server reports them),
+the decode speed, generation latency, cancellations, retries (the network's),
+thinking cuts (generations a plugin such as loop-guard cut) and output cap hits
+(generations that ended at the provider's cap), context used and window, the prompt profile and the model the server says it ran, and the
 cost when the provider reports one (OpenRouter's `usage.cost`; no prices are
 guessed). The speed line is the last generation's and the session's average
 (weighted by tokens): llama.cpp reports it exactly (`87 tok/s out, 1.9k tok/s

data/docs/configuration.md

@@ -369,9 +369,9 @@ after an idle exit) gets that process's environment, so put a lasting choice in
 
 ## Sampling
 
-chi asks chat hosts (`api: openai`) for greedy decoding (`temperature: 0.0`) and sends native hosts no sampling
-fields, so their server's defaults apply (llama.cpp: temperature 0.8). `sampling:` on a `hosts:` entry or a `models:`
-entry sets request fields for the model's turns:
+chi sends no sampling fields by default, to chat hosts (`api: openai`) or native ones, so each model runs at its
+provider's defaults (llama.cpp: temperature 0.8; vLLM takes them from the model's `generation_config.json`).
+`sampling:` on a `hosts:` entry or a `models:` entry sets request fields for the model's turns:
 
 ```yaml
 hosts:
@@ -394,15 +394,16 @@ models:
 - A `models:` entry's fields win over its host's, field by field (the host can set a penalty and the model move only
   the temperature). The entry is found the way `profile:` is (the name as typed, alias-resolved or without its host
   prefix).
-- `temperature: null` (or `~`) sends no temperature, so the provider's default applies (vLLM takes it from the
-  model's `generation_config.json`).
+- `temperature: null` (or `~`) in a model's entry takes back a host's temperature, so the provider's default applies;
+  it also keeps the empty-answer retry (below) at that default.
 - Fields chi sets itself are refused with a warning: `model`, `messages`, `prompt`, `stream`, `stream_options`,
   `tools`, `tool_choice`, `stop`, `n_predict`, `max_tokens`, `n`, `parallel_tool_calls`, `response_format`,
   `cache_prompt`. A `sampling:` that isn't a map warns and is skipped.
-- Greedy decoding can make a heavily quantized thinking model loop in its reasoning ("Let me write the reply…"
-  for minutes) or end with an empty answer. Qwen's own advice for its thinking models is `temperature: 0.6,
-  top_p: 0.95` (not greedy), with `presence_penalty` between 0 and 2 against endless repetition.
-- The idle recap and side questions keep their own short, deterministic settings.
+- Greedy decoding (`temperature: 0`) can make a thinking model loop in its reasoning ("Let me write the reply…"
+  for minutes) or end with an empty answer; set it only for a model you have watched. Qwen's own advice for its
+  thinking models is `temperature: 0.6, top_p: 0.95`, with `presence_penalty` between 0 and 2 against endless
+  repetition.
+- The idle recap and side questions don't use `sampling:`; they send their own short output cap and no temperature.
 
 `/model` shows what applies (`sampling: temperature=0.6 presence_penalty=1.5 (hosts.work)`), and each request's
 `stream` line in the debug log carries a `sampling=` field with what was sent. The fields are read every turn, so a
@@ -514,10 +515,14 @@ gateway that spreads requests over several providers can key on it to keep one c
 prompt caches hit and every turn is answered by the same model. Servers that don't know the header ignore it.
 
 Chat requests for a Claude model (an id containing `claude`, such as `anthropic/claude-sonnet-5.5`) on a remote
-OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system message and on the last
-message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again; the debug
+OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system prompt and on the last
+message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again. The system
+prompt goes as two text parts, the breakpoint after the first: everything sessions share, then the model, working
+directory and session lines, so a new session reads the shared part from the cache as well; the debug
 log's line shows `cache=on`. Nothing to configure. A provider behind a gateway may still not cache: check the
-cached tokens in `/stats`.
+cached tokens in `/stats`. Each request's own counts are in the debug log's `generation_completed` line:
+`prompt=` (its prompt tokens), `cached=` (read from the server's cache) and `cache_write=` (written to it, when the
+server reports writes); recap and side requests log theirs as `recap request_usage`.
 
 ## Llama Model Routing
 
@@ -616,6 +621,8 @@ Transient network failures are retried automatically with exponential backoff.
 - An HTTP 402 about credit held by in-flight requests (OpenRouter reserves credit for each running request, so
   one session's long request can make another's fail) is retried like a 429, 20s apart unless `Retry-After`
   says otherwise: with the default `retry.max` that is about 100s. With `retry.max: 0` it fails at once.
+  Not when its `metadata.reason` is `weight_exceeds_budget`: that request alone is larger than the key's credit
+  budget, so it fails at once (lower `default.max_tokens` or raise the key's limit).
 - A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
   <address> (connection refused) — is the server running?`.
 - A stream that has already produced output is never retried (the retry would repeat it); it fails the turn.
@@ -646,6 +653,14 @@ no made-up answer is saved.
 A generation a plugin cuts while it streams (loop-guard's thinking watch, or any `stop_generation`,
 [hooks.md](hooks.md#watching-the-stream)) uses the same budget: `↻ cut by loop-guard, asking again (1/1)`, and with
 none left the turn ends as cancelled (hook).
+A message for a running turn waits for the next step, unless the model's generation has streamed only thinking for
+`steer.cut_after` seconds (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`, `0` = never; counted from its first
+thinking token, so the wait for a busy server doesn't count) and still does: then a message from you (the terminal,
+the web), `chi send` or a parent agent cuts that generation, and the model starts the step again with the message
+(`↪ cut in for your message`). A message that comes earlier cuts once the thinking passes `steer.cut_after`, unless
+the step ends first and the message goes in there. Such a cut spends no `retry.empty_answer` attempt and sends no
+hidden note; only the cut thinking is lost. A generation that has streamed visible text or a tool call is never cut,
+and a plugin's steer (`ctx.steer`, `ctx.sessions.send`) never cuts.
 
 Assist-mode UX:
 
@@ -663,7 +678,7 @@ message (before, a failed llama.cpp `/completion` ended the turn as
 | connection | reset, timed out, dropped mid-stream; refused | yes (network retry), not mid-stream; refused: no |
 | rate limited | HTTP 429 | yes, honouring `Retry-After` |
 | credits held | HTTP 402 "… in-flight requests" | yes, after 20s (or `Retry-After`) |
-| credits | any other HTTP 402: out of credits | no |
+| credits | any other HTTP 402: out of credits; one whose `metadata.reason` is `weight_exceeds_budget` (the request alone is over the key's budget: lower `default.max_tokens`) | no |
 | server | HTTP 5xx, llama.cpp's mid-stream `error:` event | 500/502/503/504/529 only |
 | auth | HTTP 401/403 | no |
 | bad request | other 4xx; a prompt larger than the context window, whatever the status | no |
@@ -887,6 +902,7 @@ described in their own sections.
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
+| `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message for the running turn (yours, `chi send`'s, a parent agent's) cuts it; `0` = never. See "Llama Network Retry Behavior". |
 | `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
 | `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
@@ -903,6 +919,7 @@ described in their own sections.
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
 | `execute.timeout_sec` | `120` | yes | Seconds one `execute` command may run before it is stopped. |
+| `execute.description` | `true` | | `execute` offers the model an optional `description` (a few words on what the command does), shown as the tool row's title in `chi web` and in place of the command in the TUI's tool line. `false`: the parameter isn't declared, and rows show the command's first step. |
 | `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |

data/docs/hooks.md

@@ -115,10 +115,16 @@ known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
 A steer is saved in the session as `{role: "user", kind: "steer", source:
-"<bundle>", content: "…"}`; the model reads only its text, as a user turn.
+"<bundle>", content: "…"}`, its text raw. The model reads it as a user turn
+led by one line naming the sender: `[Steer from the <bundle> plugin,
+mid-task. Follow it; if it asks for nothing, carry on with the task.]`.
 Its `source` is the hook's bundle (a config or turn hook's label otherwise).
-The user's own lines typed into a running turn are saved as `{role: "user",
-kind: "input", content: "…"}`: part of that turn, not a turn of their own.
+Lines typed into a running turn are saved as `{role: "user", kind: "input",
+content: "…"}`: part of that turn, not a turn of their own. They carry a
+`source` when they are not the user's own: `chi_send` (`chi send -m`),
+`parent_agent` (a delegate's follow-up) or `plugin_send` (`ctx.sessions.send`).
+The model reads them with the same kind of header (`[Steer from the user, …]`,
+`[Steer sent with chi send, …]`, and so on).
 
 Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
 end line. A question from `:before_tool_call` shows **before** the tool
@@ -172,19 +178,27 @@ What a cut is, in detail:
 
 - It is an empty answer made early: it uses the `retry.empty_answer` budget
   ([configuration.md](configuration.md#llama-network-retry-behavior)). With
-  no retry left (`retry.empty_answer: 0`, or already used), the turn ends
-  cancelled (hook): "✕ turn canceled (hook)".
+  no retry left (`retry.empty_answer: 0`, or already used) and nothing
+  queued, the turn ends cancelled (hook): "✕ turn canceled (hook)".
 - It shows nothing by itself: post your own notice (`event[:notify]`) to say
   why. The bundle and the reason go into the note the model reads and the
   log (`generation_stopped`).
 - Queued input (the user's line, or a hook's `steer`) goes in place of the
-  hidden note, as for an empty answer; then there is no `↻` line.
+  hidden note, also once the retry budget is spent, and spends no retry;
+  then there is no `↻` line.
 - The cut generation is not kept: its thinking and any visible text it had
   streamed go with it (the retry answers anew). `:after_generation` doesn't
   fire for it, and its token usage is lost (the stream never sent its last
   chunk). A client that joins the running turn still sees its thinking in
   the turn so far until the turn ends.
 - A Stop from the user right after a cut is a plain cancel.
+- A cut for a message (a user's, `chi send`'s or a parent agent's line into
+  a generation that has streamed only thinking for `steer.cut_after` seconds)
+  is not a plugin's cut: it sends no hidden note and spends no retry; the
+  message goes in and the UIs print `↪ cut in for your message`. The
+  stream's `generation_completed` says `stopped_by: "steer"`, and
+  `stop_generation` returns false for a generation a message already cut.
+  A plugin's `steer` never cuts.
 
 ## Presenting the answer (display only)
 
@@ -385,7 +399,7 @@ stripped of surrounding whitespace, except file text, an edit's
 
 | Tool | `content:` from | `path:` from | Own fields |
 |------|-----------------|--------------|------------|
-| `execute` | `command` | — | `cwd` |
+| `execute` | `command` | — | `description`, `cwd` |
 | `read` | `path` | — | `start_line`, `end_line` |
 | `write` | — | `path` | `content` |
 | `edit` | — | `path` | `old_text`, `new_text`, `start_line`, `end_line` |

data/docs/internals/background-tasks.md

@@ -17,6 +17,7 @@ Recommended workflow:
 
 Behavior:
 
+- `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
 - Task metadata and output are persisted under `tmp/tasks/`.
 - Task listing is workspace-scoped (current project only).
 - `task_get` returns metadata and `output_path`; use `read` for output contents.

data/docs/internals/prompt-caching.md

@@ -0,0 +1,94 @@
+# Prompt caching: how a request is laid out, and how to keep it cache-friendly
+
+A model server reuses work only for the **exact token prefix** it has already seen. Change one token and
+everything after it is computed again (prefill). The local models we run (hybrid Qwen 3.6 / Ornith on llama.cpp
+and Splash) can only resume from a **restore point near the end** of an earlier prompt, not from any shared
+prefix. Anthropic (Claude via OpenRouter) caches only up to an explicit `cache_control` breakpoint. So the order
+of what chi sends decides what a new turn, or a new session, has to pay for.
+
+Measured with prompt-cache slice 1 (2026-10-04, fresh sessions, ~7.7k-token prompt):
+
+| Server | Before | After |
+|---|---|---|
+| Ornith on llama.cpp | 0 tokens reused, 6.4 s prefill per session | 94% reused, 0.5 s |
+| Splash Qwen 3.6 | 3.8 s | 97% reused from the 3rd session, 0.27 s |
+| Sonnet via OpenRouter | full cache write, $0.024 per session | reads the stable part, $0.0035 |
+
+## The layers of a request
+
+From the first token to the last. Every layer is a prefix of the next request's layers, unless something in the
+right-hand column happens.
+
+```
+ shared by every session ──────────────────────────────────────────────────  breaks it
+┌──────────────────────────────────────────────────────────────────────────┐
+│ tools        built-ins, then plugin tools sorted by (bundle, name)       │  a tool added/changed,
+│              (chat: the `tools` field; native: the model's template)     │  /model, a profile change
+├──────────────────────────────────────────────────────────────────────────┤
+│ SYSTEM, stable part                         SystemPrompt#system_prompt_with_index
+│   [native thinking token] base prompt                                    │
+│   rg guidance                                                            │  /thinking level,
+│   system identity (+ model overlay)                                      │  /model, editing a
+│   explicit (preloaded) memories                                          │  memory / AGENT.md
+│   AGENT.md                                                               │  (picked up by a new
+│   project + system memory indexes                                        │  process or a rebuild)
+│                         ◄── remote Claude: cache_control breakpoint #1   │
+├──────────────────────────────────────────────────────────────────────────┤
+│ SYSTEM, volatile tail (per session, least → most changing)               │
+│   Model: this session runs on …                                          │  another session
+│   working directory (location)                                           │  (expected: only
+│   session id + log                                                       │  this tail differs)
+│   [Gemma 4 native only: tool declarations after all of it]               │
+└──────────────────────────────────────────────────────────────────────────┘
+ shared by every turn of this session ─────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────┐
+│ history      user / assistant / tool messages, APPEND-ONLY               │  !rollback, a failed or
+│              (images: the newest N, ImagePlan)                           │  cancelled turn's tail,
+│                         ◄── remote Claude: breakpoint #2 on the last     │  the image window
+│                             non-system message                           │  sliding, history
+├──────────────────────────────────────────────────────────────────────────┤  sanitizing (thinking
+│ tail notes   reminders, turn notes, steers (system/user messages)        │  stripped per spec)
+│ new prompt   this turn's user message                                    │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+- The system prompt is built **once per loop** and rebuilt only on `@prompt_builder.reset!`: a model switch
+  (`Engine#switch_model!`), a plugin's `tools_changed!`, or a profile change. A per-turn rebuild would
+  break everything below it.
+- On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
+  breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint
+  #2, so the **next request in the session** reads everything up to it. Mid and tail system messages never take
+  a breakpoint. The split point comes from `SystemPrompt#stable_length` via the message's `cache_split:`, which
+  never goes on the wire.
+- Side requests (idle recap, `/btw`) go through `IdleClient` with their own short system prompt. On a
+  single-slot local server they can push the session's prefix out of the cache. Fixing that is slice 2 of the
+  plan (R4 `id_slot`, R2 turn-end warm-up).
+
+## Rules for changes
+
+1. **Stable first, volatile last.** Anything that differs between sessions or turns (ids, paths, times, the
+   model line, counters) goes at the very end of the system prompt, ordered by how often it changes. Never put
+   a per-session value in the stable part. A guard spec checks that model, location and session are the last
+   sections (`spec/system_prompt_model_spec.rb`).
+2. **History is append-only.** Never rewrite an earlier message. Add a note at the tail instead. If a model's
+   spec forces a rewrite (e.g. stripping previous-turn thinking), accept the re-prefill and note it.
+3. **Deterministic order.** Tools, memory lists and anything else that's rendered from a hash or a set needs a
+   fixed sort. Plugin tools are sorted by (bundle, name) whatever order their plugins finished starting in
+   (R5a).
+4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`).
+5. **Measure.** Every generation logs `prompt=`, `cached=` and, where the provider reports it, `cache_write=`
+   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.
+
+## Server-side settings worth knowing
+
+- **Splash:** `--persistent-cache` (with `--max-cache-disk`) keeps restore points across restarts. Splash learns
+  a new branch point on the 2nd session, so the 3rd one gets the full reuse.
+- **llama.cpp:** a single slot is shared by everything sent to it. `--parallel N` and `--cache-ram` give side
+  requests room without evicting the session. `--ctx-checkpoints` controls how many restore points a hybrid
+  model keeps.
+- **OpenRouter / Anthropic:** the default cache TTL is 5 minutes. Provider routing (which upstream serves a
+  request) also decides whether a cache is there to hit.
+
+Still to come: side requests on their own slot, a turn-end warm-up, image-window batches and longer remote TTLs.

data/docs/plugins.md

@@ -490,7 +490,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
 | `ctx.ask_user(question:, options:, header: nil, allow_freeform: false)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options) |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
-| `ctx.steer(text)` | put text into the running turn: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook (false from `:after_turn`), your own |
+| `ctx.steer(text)` | put text into the running turn: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. The model reads it with a header naming your bundle (`[Steer from the my-bundle plugin, mid-task. …]`); the session keeps the raw text. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook (false from `:after_turn`), your own |
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
@@ -847,14 +847,20 @@ stream](hooks.md#watching-the-stream)) and cuts it:
   thinking has short sentences too ("Hmm.", "Fine."), but spread out or all
   different (code lines); a longer sentence ends the run, and lines inside a
   ```` ``` ```` code block don't count.
+- Any `window_sentences` sentences in a row, short or long, holding at most
+  `window_distinct` different ones are a loop too: a cycle of 7 or 8 short
+  sentences, or one where a longer sentence ("I'll write the spec file
+  now.") keeps ending the short run. Real thinking holds 40 or more
+  different sentences in any 48; DeepSeek's write loops hold 4 to 9.
 - Nothing triggers before `min_chars` of thinking. The watch sees a loop
   within one batch (2000 chars, or a second) of its third cycle.
 
 What happens (`action: retry`, the default):
 
 1. The first loop in a turn: the generation is cut and the model asked
-   again, with a hidden note that it was cut off. The user sees
-   `loop-guard> thinking repeats itself (3 sentences ×3, 4k chars, 8 s): cut`
+   again, with a hidden note that it was cut off. The user sees the loop's
+   first sentence quoted,
+   `loop-guard> thinking repeats itself ("Wait, the count of the letter r…", 3 sentences ×3, 4k chars, 8 s): cut`,
    and `↻ cut by loop-guard, asking again (1/1)`.
 2. If the retry loops too, the turn is stopped ("stopped the turn: …", "✕
    turn stopped by loop-guard") with a card that quotes the repeated
@@ -869,6 +875,12 @@ the first loop ends the turn as stopped by loop-guard, with the notice and
 no card. `action: stop` stops the turn at the first loop; `action: notify` only
 warns, once per generation.
 
+The cut thinking never goes back to the model, but its last 20k chars are kept
+in the session's folder, `thinking_tails.jsonl` (with a generation that ran to
+the provider's output cap, or that a stop_turn ended): an archived session
+keeps them. A turn's record counts its cuts and cap hits (`cuts`, `capped` in
+`analytics.json`; `/stats` shows "thinking cuts" and "output cap hits").
+
 ```yaml
 bundles:
   loop-guard:
@@ -885,6 +897,8 @@ bundles:
       min_words: 5            # shorter sentences only count toward a short run
       short_run: 24           # this many short sentences in a row…
       short_distinct: 6       # …with at most this many different ones is a loop
+      window_sentences: 48    # any this many sentences in a row…
+      window_distinct: 12     # …with at most this many different ones is a loop
       forget_after: 10        # good steps in a row that forget a loop; 0: never
 ```
 

data/docs/sub-agent.md

@@ -60,9 +60,10 @@ answers waits as a question of kind `continue` (`"limit": 100`, options
 `Continue` and `Stop`). `answer_with` continues it:
 `chi answer ID --question QID --option Continue`, and the continued turn's
 reply (or its next question) comes back on that same wait. With
-`--text "…"` the text joins the continued turn as a steer (as a `chi send -m`
-into a running turn does, marked as coming from the parent agent), so one
-answer continues and redirects it. To stop it:
+`--text "…"` the text joins the continued turn as a steer, labelled for the
+model as coming from the parent agent that started the session, so one answer
+continues and redirects it. (A `chi send -m` into a running turn joins it too,
+labelled as sent with chi send.) To stop it:
 `--option Stop`, with `--text "why"` for the model;
 that wait ends with `status: not_continued`, exit 0, and the turn's work so far
 stays in the session. A message instead (`chi send ID -m "…"`) drops the

data/docs/testing.md

@@ -15,6 +15,18 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
+## Worktrees
+
+Each fix or feature gets its own worktree next to the main checkout:
+
+```sh
+script/worktree NAME [-b BRANCH]   # ../samagotchi-NAME off main, branch NAME unless -b; prints the path
+```
+
+It runs `git worktree add ../samagotchi-NAME -b BRANCH main`, then `npm ci --prefer-offline` in it, so
+`npm test` and `npm run e2e` work there right away (Ruby gems and Playwright's browsers are shared: nothing else
+to install). It refuses when the folder or the branch already exists.
+
 ## Integration specs
 
 Examples tagged `:integration` (`spec/integration/`, the "with LLM access" part of `spec/hooks/integration_spec.rb`)

data/lib/samagotchi/bridge/card_store.rb

@@ -16,7 +16,7 @@ module Samagotchi
     # iteration started before it (a before_tool_call hook's notice comes
     # before its call's row, so the web puts it above row calls + 1). The
     # loop's "asking again" row (:empty_answer_retry, after an empty or cut
-    # answer) is kept the same way, and so is a question the turn asked
+    # answer) and a steer's cut row (:steer_cut) are kept the same way, and so is a question the turn asked
     # (:question_requested), with how it was answered or cancelled, so a
     # reload draws the resolved card where it was.
     #
@@ -46,11 +46,11 @@ module Samagotchi
     # onto a new worker doesn't print those again).
     class CardStore
       CAPACITY = 20
-      NOTICE_TYPES = %i[hook_notice guardrail_warning empty_answer_retry].freeze
+      NOTICE_TYPES = %i[hook_notice guardrail_warning empty_answer_retry steer_cut].freeze
       FILE = "cards.json"
       # The events after which the file is written again: the ones that
       # change an entry or the turn count.
-      SAVED_ON = (%i[card hook_notice empty_answer_retry question_requested question_answered question_cancelled
+      SAVED_ON = (%i[card hook_notice empty_answer_retry steer_cut question_requested question_answered question_cancelled
                      question_relay turn_failed] + Events::TURN_KEPT).freeze
 
       # What a session's saved file lists, as a store started from it lists
@@ -167,6 +167,7 @@ module Samagotchi
         when :guardrail_warning then push({ type: :guardrail_warning, message: event[:message], label: event[:label] }
                                             .compact.merge(in_turn: false, turns: @turns_done))
         when :empty_answer_retry then add_turn_row(event.slice(:type, :attempt, :of, :stopped_by)) if @running
+        when :steer_cut then add_turn_row(event.slice(:type, :source)) if @running
         when :question_requested
           add_turn_row({ type: :question, pending_question: Marshal.load(Marshal.dump(event[:pending_question])) }) if @running
         when :question_answered then resolve_question(event[:id], answer: event[:answer])

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -158,7 +158,8 @@ module Samagotchi
         call = { iteration: part[:iteration], call_index: part[:call_index], tool: part[:tool] }
         call[:label] = part[:label] if part[:label]
         title = part[:title] ? { title: part[:title] } : {}
-        events = [{ type: :tool_call_started, **call, params: part[:params], **title }]
+        view = part[:view] ? { view: part[:view] } : {}
+        events = [{ type: :tool_call_started, **call, params: part[:params], **title, **view }]
         if part[:status] == "running"
           events.first[:elapsed_ms] = part[:elapsed_ms] unless part[:elapsed_ms].nil?
           return events
@@ -170,6 +171,7 @@ module Samagotchi
                       activity: activity }
         completed[:duration_ms] = part[:duration_ms] unless part[:duration_ms].nil?
         completed[:diff] = part[:diff] if part[:diff]
+        completed.merge!(view)
         events << with_images(completed, part[:images])
       end
       private_class_method :tool_replay_events
@@ -253,6 +255,7 @@ module Samagotchi
                    tool: event[:tool], params: event[:params], status: "running" }
           part[:label] = event[:label] if event[:label]
           part[:title] = event[:title] if event[:title]
+          part[:view] = event[:view] if event[:view]
           parts << part
           @tool_started_at[[event[:iteration], event[:call_index]]] = @clock.call
         when :tool_call_completed

data/lib/samagotchi/bridge/turn_notice.rb

@@ -12,6 +12,7 @@ module Samagotchi
       FIELDS = {
         hook_notice: %i[hook text level],
         empty_answer_retry: %i[iteration attempt of stopped_by],
+        steer_cut: %i[iteration source],
         question_requested: %i[pending_question],
         question_answered: %i[id answer],
         question_cancelled: %i[id reason]