samagotchi 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80a8fec85f3a253ce7f762f3c8881ee0c49d6e73117f205a53cb64482e7a9cc3
-  data.tar.gz: 6e21caec0f46b5a2831382a2c77842e5d3935e363b6b6ea96f5d136a24ffa1eb
+  metadata.gz: 38684442adc7d8b24e225a8219cd4834395744722f027bd5357b3632b2949641
+  data.tar.gz: f7d0537f004a6b2de38762bbf82d37af648e58b4d06e33e2d19f4c240da7899d
 SHA512:
-  metadata.gz: ad7fd8882239bb39478cddc39d48e85c2dedfb782d73da193b7dfd401b40599aaf2385462c911d633ebdf78d2f2841d3c400367c1e6feefc300778e617afa425
-  data.tar.gz: 2104f11e65bfdf5f9b82a92a2e1281cda2c6a1c6c28a58bd7eedc89e34492f47f34f8aec229aba66d6c875b465ae56f181a0d0a539b039c5ed79a4830c1e4cd0
+  metadata.gz: 695b4c2ab0898eb3a6e6ef2981258da778ec43780dbd8b96ebebeb37b3646522ba92df5851b55a10751a07ada0182392658f071c5be435776431f0dc8b85bfa9
+  data.tar.gz: 129ff9e9ca7bafb5d792fb6d578d8f85b935cc45d402bf820bedd69358fa9d064e2873053f4c38d42f85d8b4e4da86a067747ce5149c13b2cacfbb48c88ef9ee

data/CHANGELOG.md

@@ -8,6 +8,92 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-01
+
+### Changed
+
+- Built-in tool calls are built the same way for every model format (Gemma and Qwen native, OpenAI-style chat), so
+  they no longer differ by format. As part of that:
+  - `edit` takes the old and new text as two fields (`old_text`, `new_text`), so old text that contains `</old>` is
+    no longer cut short; `edit` without `new_text` is an error (it deleted the matched text; pass `""` to delete).
+  - `write` without `content` is an error with every model format (Gemma and Qwen emptied the file).
+  - `register_reminder` from a Qwen model without an interval no longer always fails.
+- Plugins: `ctx.notify`, `ctx.ask_user`, `ctx.steer`, `ctx.stop_turn` and `ctx.stop_generation` are the one way a plugin
+  acts; inside a `chi.on` block they act for that event as `event[:x]` does (`ctx.stop_turn` in `:before_tool_call`
+  denies the call, `ctx.steer` from `:after_turn` is false), and as before anywhere else (commands, your own threads).
+  Plain hook files keep `event[:x]`.
+- Attaching to a session mid-turn (`chi --attach`) shows the turn's finished tool calls as they looked live, with
+  what each did and how long it took (`tool> running command (execute …): ok (1.3s)`), when the worker runs this chi.
+- `chi bundle` usage errors (unknown subcommand or flag, a missing argument) exit 2 like every other command, not 1.
+- A config hook with `on_error: log` warns as `[samagotchi:hooks] <file> (config) failed: <error>`, the same shape as a
+  bundle hook's warning; a fail-closed bundle guardrail's deny reason reads `... (bundle <name>) raised <error>`.
+- Bundles (`chi update`):
+  - known-names 0.1.2: corrects a near-miss name only in paths, `cwd` and commands, no longer inside text being
+    written to a file (`write`/`memory_write` content, `edit`'s old and new text, where a correction could stop the
+    edit matching).
+  - loop-guard 0.2.2: tells repeated `edit` calls apart by their old and new text; acts through `ctx`.
+  - skills 0.1.3 and mcp 0.3.2 (mcp now needs chi 0.8.0): write a skill's history and the MCP tool cache through a
+    unique temporary file, so two workers saving at once no longer collide.
+  - check-in 0.1.3 acts through `ctx`; source-links 0.3.1 drops dead code. They behave as before.
+
+### Fixed
+
+- Web: a Gemma model on a native llama.cpp host streams its answer into the reply as it writes (it showed only when the
+  turn ended), with its thoughts in the thinking block; the attached terminal shows them as thinking and the answer as
+  writing.
+- `execute` with a `cwd` now runs in that directory with Gemma and Qwen native tool calls too (the directory was
+  dropped and the command ran in the project root).
+- `/model … --default` and `/model … --alias` keep the comments and layout of `config.yml`: they change one line
+  (or add one) instead of rewriting the whole file.
+- `chi sessions stop` marks the session with a `stopped` file in its folder instead of rewriting its session file, so
+  a worker saving at that moment can no longer undo the stop (or lose its own save); a resume removes the file.
+- The web's answer, dismiss, command and cancel calls fail the same way: a worker that doesn't answer in time is
+  504 ("did not answer, so ... was not ..."; cancel said "not running"), a worker running an older chi is 501 with
+  how to restart it (an answer said "not running").
+- A web page joining (or re-syncing with) a live session gets its status and pending question as of the same moment
+  as the messages; they could be a step newer.
+- The web's `POST /api/sessions/:id/turn` refuses more than 20 images in one message, as a live worker already did.
+- Web: switching sessions no longer briefly shows the previous session's "delegated by" link in the info bar.
+- The terminal's "retrying (1/3 …)" line counts retries as the web does (it said "1/4", counting the first try).
+- `chi self`'s thinking line finds a `models:` entry under the model an alias points at, as a turn does.
+- A `required: true` config hook that raises something other than a StandardError (e.g. `NotImplementedError`) denies
+  the tool call like any other raise, instead of escaping the guardrail check.
+
+Update with `chi update` (bundles: known-names 0.1.2, loop-guard 0.2.2, skills 0.1.3, mcp 0.3.2, check-in 0.1.3,
+source-links 0.3.1).
+
+## [0.9.0] - 2026-10-01
+
+### Changed
+
+- A small change to a memory or skill can go through `edit` on its file instead of rewriting it all with
+  `memory_write`; the prompt, the memory guide and the nudge below say so. `write`/`edit` on a memory's file
+  refresh its line in `index.md` (date, size; the description is kept), and the default guardrails no longer ask
+  before them as "writes outside the repository".
+- The system prompt no longer tells the model to keep `index.md` updated (`memory_write` does it); its result
+  says "Index line refreshed automatically." instead of naming the index file.
+- `skills` bundle 0.1.1 (`chi update`; needs chi 0.9.0): a skill changed some other way (an `execute` running `sed`) counts as
+  updated: you get the usual "skill X updated" line, `/skill diff` has the old text, and the nudge and the turn-end
+  "wasn't updated" line no longer fire for it. The nudge asks to `edit` the changed step rather than rewrite the
+  whole skill.
+
+### Fixed
+
+- `chi bundle install` of a bundle that's already installed no longer says "Skipped X (already exists; use --force
+  to overwrite)" for a file that's the same as the bundle's; it skips it quietly and says once that
+  `chi bundle upgrade NAME` updates the bundle and keeps local edits. A file skipped for a local edit no longer
+  also reports a checksum mismatch.
+- `chi bundle install` and `upgrade` no longer list a bundle's unchanged guardrail rule files as "Installed"; they
+  are skipped as already up to date like its memory files.
+- A memory file you edited, then `chi bundle install` of its bundle again (skipped for the edit), no longer gets
+  overwritten by the next `chi bundle upgrade`: the re-install kept your edit as the bundle's base, so the upgrade
+  took it as unedited.
+- `chi sessions list --sort/--order` is no longer ignored with `--live`, `--cwd` or `--format`.
+- A tool's time in the web's turn timing and the debug log's `tool_call_completed ms:` no longer counts the wait for
+  a guardrail approval; the log line shows the wait as `waited_ms:`.
+
+Update with `chi update` (bundles: `skills` 0.1.1).
+
 ## [0.8.1] - 2026-10-01
 
 ### Added
@@ -481,7 +567,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.8.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/dm1try/samagotchi/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/dm1try/samagotchi/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/dm1try/samagotchi/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/dm1try/samagotchi/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/dm1try/samagotchi/compare/v0.6.0...v0.7.0

data/docs/architecture.md

@@ -115,9 +115,9 @@ bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop ──┬─
 
 ## Session retention & ordering
 
-- **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware).
+- **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped` and `<uuid>/archived` marker files.
 - **Single owner:** the process running a session's Engine (worker or in-process TUI) holds a flock on `owner.lock` (`OwnerLock`); a second owner backs off, and the web answers 409 for a TUI-owned session.
-- **Status:** `status` is turn state (`idle`/`running`); liveness is the lock.
+- **Status:** `status` is turn state (`idle`/`running`); liveness is the lock. A stop is the `<uuid>/stopped` marker (`Session.mark_stopped`; a resume removes it), which `Session.load` and `.summary_from_file` read as status `stopped`, so no other process rewrites a worker's session file.
 - **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner guard, only when `*.json` present; lazy sweep ≤1/24h from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls) & `Dashboard#render_list`, manual via `bin/chi sessions prune --dry-run`.
 - **Ordering:** `Session.list(sort:,order:,limit:,offset:)` and `GET /api/sessions?sort=&order=&limit=&offset=` default `updated_at desc`; Web UI sort/filter/pagination.
 - **Test hygiene:** `test_run` flag when `SAMAGOTCHI_ENV=test`/`RACK_ENV=test`/`CI`, targetable via `prune --test-only` / `clean`.
@@ -208,7 +208,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
 - `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
   (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
-  across the HTTP boundary). Inspect results through the read surface, not the turn response.
+  across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
+  `session_id`, is `404 unknown_session`. Inspect results through the read surface, not the turn response.
   An optional `deadline` (epoch seconds; `BridgeClient` sends 5/6 of its read timeout ahead) makes
   a request read after it (a worker frozen by sleep or SIGSTOP) answer `408 deadline_passed` and
   not run: a client that timed out has said the message was not sent. `/answer`,
@@ -216,6 +217,10 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   log held, as a turn is), and the Bridge logs `turn_expired`, `answer_expired`, `dismiss_expired`
   or `command_expired`. The web app answers either kind of timeout with `504 worker_timeout`
   ("… so the command was not run"). `/cancel`, `/recap` and `/exit` take none.
+  The web relays answer, dismiss, command and cancel the same way (`App#relay`): a 408 or a read
+  timeout is `504 worker_timeout`; a Bridge 404 for a route an older worker lacks is
+  `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
+  refused connection is `503 not_live`.
 - `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
   answered first or it is gone, `400` for an invalid selection.
@@ -235,6 +240,10 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   the messages itself, then streams from its `event_seq`).
 - `OPTIONS *` — CORS preflight (`Access-Control-Allow-Origin: *`).
 
+Every route goes through `Bridge#dispatch`: an id other than the bridge's own session is
+`404 unknown_session`, and a handler that raises answers `500 bridge_error` (logged as
+`handler_failed`) rather than dropping the connection.
+
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
 for client discovery. `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
 (503 `not_live` when the worker is not running; full history of any session is served by
@@ -248,15 +257,15 @@ changes to every open tab over `GET /api/events` (SSE: a `snapshot` frame on eve
 then `session` for an upsert and `session_gone` for a removal, `: ping` while idle, no replay).
 Files stay the source of truth and workers don't know the hub. Its watcher is a 1 s tick that
 stats the sessions dir (every session writer goes tmp + rename, which bumps the dir's mtime) and
-each `<id>/` folder (recap.json, bridge.json), re-parsing only the files whose mtime or size
+each `<id>/` folder (recap.json, bridge.json, the stopped and archived markers), re-parsing only the files whose mtime or size
 moved through `Session.summary_from_file`. Liveness is probed, since a killed owner leaves no
 file trace: the owner lock every tick for the sessions the projection believes owned, and every
 session every 10 s, so a `kill -9` shows within a second. The summary (`Web::SessionSummary`,
 shared with `/api/sessions` and the session view) carries `owner`, `project_root` and
 `bridge_up` (the sidecar is there *and* the lock is held: the page attaches its stream on it).
 `POST/DELETE /api/sessions` and `/stop` rescan the session before answering (`SessionHub#touch`).
-Without a hub (`App.new` alone) `/api/events` answers `503 no_hub` and the page falls back to
-fetching the list.
+`GET /api/sessions` is the hub's projection too (its sort, paging and total). `Server` always builds
+a hub; an `App.new` without one answers both routes `503 no_hub`.
 
 ## Model loops and adapters
 
@@ -269,9 +278,15 @@ Engine picks the loop from the effective model's host (`HostRegistry#resolve`):
 
 Both return an `LLM::ModelResult` and emit the same stream events; tool calls in
 both go through `ToolRunner` (events, hooks, veto, output cap) and
-`KernelLoop#dispatch_tool_call`. The chat loop's `generation_chunk` carries
-`thinking:` (the server's `reasoning_content`), `text:` and `content:` (both);
-its model turns keep their `tool_calls` and tool results their `tool_call_id`,
+`KernelLoop#dispatch_tool_call`. Every format's built-in calls (Gemma, Qwen,
+chat `tool_calls`) are built by one table, `Tools::BuiltinCalls`, from the
+parsed `{name, args}` (derived from `TOOL_SCHEMAS`), so a call looks the same to
+hooks and tools whichever model made it. Both loops' `generation_chunk` carries
+`thinking:`, `text:` and `content:` (both): the chat loop's thinking is the
+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
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 

data/docs/cli.md

@@ -21,7 +21,7 @@
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
-- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle))
+- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for every other command
 
 ### First setup
 
@@ -586,9 +586,10 @@ In interactive assist mode, you can switch the request model without restarting:
 
 Notes:
 
-- The switch updates the request `model` field, routes to the matching host (`HostRegistry`, `lib/samagotchi/host_registry.rb:72`), and resolves the prompt profile again (config, the server's chat template, the name; see "Prompt profile" in configuration.md).
+- The switch updates the request `model` field, routes to the matching host (`HostRegistry#resolve`), and resolves the prompt profile again (config, the server's chat template, the name; see "Prompt profile" in configuration.md).
 - Without `--default` the command is session-scoped and does not rewrite config files.
 - With `--default` the new default is written to `~/.config/samagotchi/config.yml` (honoring `XDG_CONFIG_HOME`) and takes effect for all new sessions; the current session's effective model is also updated immediately. Bare aliases and `host:model` are both valid.
+- `--default` and `--alias` change only their one key's line in `config.yml` (`default.model`, or the alias under `model_aliases:`): comments and the rest of the file stay as written, a symlinked file is written through and keeps its mode. When the edited text wouldn't read back as the expected settings (a flow-style section, anchors), chi writes the whole file out from the parsed data instead, which drops its comments.
 - Worker sessions inherit `hosts:` via `SAMAGOTCHI_HOSTS_JSON`.
 - The idle recap uses the session's current model (a switch counts from the next recap), unless `recap: {host_ref, model}` pins one.
 
@@ -706,7 +707,7 @@ While a turn runs, one row above the prompt says what it is doing, the spinner f
   Qwen `TURN:` prefix and inline markdown are left out.
 - `| waiting for the first token… 5s` after 2 s with nothing streamed.
 - `| running execute…` while a tool runs (its `tool>` line prints when it ends).
-- `| retrying (1/4 in 0.5s): Errno::ECONNREFUSED` while a network error is retried.
+- `| retrying (1/3 in 0.5s): Errno::ECONNREFUSED` while a network error is retried.
 - `| mcp: starting servers…` while a plugin's slow setup (an init task) runs, between turns too;
   `mcp> ✓ …` prints when it is done.
 

data/docs/guardrails.md

@@ -126,6 +126,12 @@ All the fields a rule gives must match. Absolute and `**/` globs match the
 resolved path; other globs match the path relative to the repo root. Paths
 resolve the way the tools resolve them (against the cwd; `~` expanded).
 
+`outside_repo` leaves out a memory's file: a `*.md` right in the project or
+system memories folder (not `index.md`, not a hidden file). `write`/`edit`
+there is what `memory_write` does unasked, and the model is told to `edit` a
+memory for a small change. The memories folder's `index.md`, `.bundles/`, and
+the rest of chi's config folder still count as outside.
+
 To switch off single rules (a bundle's, say) without editing its files, list
 them under `disable:`. A plain id switches off every rule with that id; `bundle:id`
 only that bundle's:
@@ -238,8 +244,9 @@ bundles:
     max_distance: 2           # default: 1 under 10 characters, else 2
 ```
 
-`mode: correct` rewrites the call (whole tokens, everywhere they appear) and
-says so; `mode: ask` shows the call with three choices, *Correct it and
+`mode: correct` rewrites the call (whole tokens, everywhere they appear in
+the command, the `cwd` and the paths; never in file text: a write's content
+or an edit's `old_text`/`new_text`) and says so; `mode: ask` shows the call with three choices, *Correct it and
 run*, *Run as is*, *Deny*; with no one to ask (`--non-interactive`) or a
 dismissed question it rejects. A real near name (a folder `jondoe` next to
 user `johndoe`, a login one letter from another) is caught too: list it under

data/docs/hooks.md

@@ -140,10 +140,10 @@ whole response), and none after the turn or the generation was cancelled.
 A 240k-char thinking gives about 120 fires.
 
 `thinking` holds what the model streamed as thinking: `reasoning_content`
-on the chat path, a Qwen `<think>` block on the raw-prompt path. Some
-thinking arrives as `text` instead: Gemma 4's on the raw-prompt path (it has
-no close marker), and a chat provider's that puts `<think>` inside the
-answer's content. Tool-call bodies are left out of `text`. With streaming off
+on the chat path, a Qwen `<think>` block or a Gemma 4
+`<|channel>thought … <channel|>` block on the raw-prompt path. Some
+thinking arrives as `text` instead: a chat provider's that puts `<think>`
+inside the answer's content. Tool-call bodies are left out of `text`. With streaming off
 (`stream: false` on a chat host) there are no chunks, so no fires.
 
 **Keep it fast.** The hook runs on the turn's thread, inside the HTTP read:
@@ -368,6 +368,43 @@ end
 
 Note: `:before_tool_call` can replace the `:call` hash to change what runs; `tool_call_started` (what the UIs show) and the rules see the final call.
 
+### The call a hook sees
+
+`event[:call]` is the same hash for every model format (Gemma, Qwen, the
+chat path): `name:`, `content:`, `path:`, `scope:`, plus the tool's other
+parameters by their own names (symbol keys). `content:` holds the tool's
+main argument (`""` when it has none), `path:` the parameter named in its
+column, and an argument the model left out is `nil`. Text values are
+stripped of surrounding whitespace, except file text, an edit's
+`old_text`/`new_text`, `env` and `options`.
+
+| Tool | `content:` from | `path:` from | Own fields |
+|------|-----------------|--------------|------------|
+| `execute` | `command` | — | `cwd` |
+| `read` | `path` | — | `start_line`, `end_line` |
+| `write` | — | `path` | `content` |
+| `edit` | — | `path` | `old_text`, `new_text`, `start_line`, `end_line` |
+| `memory_read` | `name` | — | `scope` |
+| `memory_write` | — | `name` | `content`, `scope`, `description`, `current_model_only` |
+| `task_create` | `command` | — | `cwd`, `env` |
+| `task_get` | `id` or `task_id` | — | — |
+| `task_list` | — | — | — |
+| `task_stop` | `id` or `task_id` | — | — |
+| `task_wait` | `id` or `task_id` | — | `timeout`, `tail_lines`, `done_pattern` |
+| `web_fetch` | `url` | — | — |
+| `register_reminder` | `name` | — | `description`, `interval_minutes` |
+| `cancel_reminder` | `name` | — | — |
+| `list_reminders` | — | — | — |
+| `list_sessions` | — | — | `cwd` |
+| `send_note` | `text` | — | `session` |
+| `delegate` | `task` | — | `model`, `session`, `wait`, `timeout` |
+| `delegate_result` | — | — | `session`, `timeout` |
+| `ask_user_question` | `question` | — | `question`, `options`, `header`, `multi_select`, `allow_freeform` |
+
+A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
+`new_text:` (its `content:` is `""`). A plugin or MCP tool's call has its
+arguments whole on `args:` (string keys) instead.
+
 ## Bundle Hooks (unified workflow bundle)
 
 Bundles can ship executable guardrails alongside memories. A bundle with hooks lives as a directory with a `hooks/` subdirectory (flat, basename-keyed):
@@ -393,7 +430,7 @@ hooks:
   guardrails.rb:
     sha256: 1234...
     event: before_tool_call
-    on_error: fail_closed   # default for before_tool_call
+    on_error: fail_closed   # skip (default) | log | fail_closed (before_tool_call only)
     priority: 10
   audit.rb:
     sha256: 5678...
@@ -410,12 +447,12 @@ Notes:
 - `event` is required for auto-registration; a hook with no event is skipped.
 - `sha256` is integrity (not authenticity). No signing in v1. Install records the sha256 of the copied file; at `Engine.new` a hook whose file differs is not loaded (reinstall the bundle after editing one by hand).
 - Hook code is the bundle author's source of truth: on upgrade, hooks are overwritten; if the installed file was locally modified, a warning is emitted (`was locally modified; overwriting`).
-- A raising `:before_tool_call` guardrail respects `on_error`: `fail_closed` denies the call (fail-closed), `log` warns, `skip` is silent.
+- `on_error` defaults to `skip` for every event, `:before_tool_call` included: a raising hook is silent and the call goes ahead. `log` warns. `fail_closed` (only on `:before_tool_call`; on any other event it acts as `skip`) denies the call the hook raised on. Choose `fail_closed` for a hook that is a guardrail, whose failure should stop tool calls rather than let them through.
 - A `fail_closed` `:before_tool_call` hook is required: if it is missing, fails to load or its sha256 differs, chi denies every tool call until it is fixed.
 - A bundle can also ship YAML rules in `guardrails/*.yml`; see [Guardrails](guardrails.md#the-guardrails-bundle).
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
-- A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md).
+- A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
 - Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 

data/docs/internals/gemma4-contract.md

@@ -19,5 +19,6 @@ Thought handling follows the Gemma guidance:
 - Standard multi-turn: prior model thoughts are stripped from conversation history before the next turn.
 - Function/tool-calling exception: during a single turn that includes tool calls, thoughts are not stripped between those tool-call rounds.
 - Final model output returned to the caller is thought-stripped.
+- While a generation streams, the thought channel goes to the stream's `thinking:` lane, not `text:` (`ThoughtStreamSplitter.for_profile`, fresh per generation), so the UIs show it as thinking and `:generation_progress` hooks count it in `thinking_chars`.
 
 In short, raw thought blocks are treated as in-turn transient context, not durable history.

data/docs/memory.md

@@ -12,7 +12,8 @@ Tool behavior:
 - `memory_read`: `scope` is optional.
 - If `scope` is provided (`project` or `system`), only that scope is read.
 - If `scope` is omitted, read falls back from project to system.
-- `memory_write`: `scope` is required (`project` or `system`). The entry name is passed via the `name` parameter (not `path` — the file tools use `path`). On success, the return value includes the full file path, so you can use the `edit` tool directly for targeted updates.
+- `memory_write`: `scope` is required (`project` or `system`). The entry name is passed via the `name` parameter (not `path` — the file tools use `path`). On success, the return value includes the full file path. For a small change to an existing memory (a step, a line) the model is told to `edit` that file rather than rewrite it all with `memory_write`.
+- `write`/`edit` that change a `*.md` right in a scope dir refresh its managed `index.md` line (date, bytes; the description is kept), as `memory_write` does. A memory created with `write` gets a line with no description; any other `.md` written there gets a line too. Model overlays (`<name>.<key>.md` next to `<name>.md`), files in another project's folder and files changed by `execute` are left out.
 
 ## Model-Specific Memory Overlays
 
@@ -51,8 +52,9 @@ chi is told about skills by the system bundle (`identity.md`, every turn, and
   looks unexpected on the way (a failing check, a warning the skill doesn't
   mention), chi stops, says what it saw and asks how to go on.
 - **Updating.** When a step turned out different (a renamed script, an extra
-  step), chi fixes the skill in the same turn: those steps changed, the rest
-  kept, a dated Changelog line added. No confirmation.
+  step), chi fixes the skill in the same turn: those steps changed (with `edit`
+  on its file, so a small fix doesn't resend the whole skill), the rest kept, a
+  dated Changelog line added. No confirmation.
 
 A skill is plain Markdown, no frontmatter:
 

data/docs/plugins.md

@@ -304,18 +304,33 @@ end
 ### `chi.on(event, priority: 100) { |event, ctx| … }`
 
 This is a bundle hook, the same as a `hooks/*.rb` file. See
-[hooks.md](hooks.md#hook-events) for the events and for what `event[:notify]`,
-`event[:ask_user]`, `event[:stop_turn]` and `event[:steer]` do; on `:after_turn`,
+[hooks.md](hooks.md#hook-events) for the events; on `:after_turn`,
 `event[:present]` sets how the answer is shown in the web
 ([Presenting the answer](hooks.md#presenting-the-answer-display-only)). Its label is
 `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
 raises, the error is logged and the hook is skipped.
 
+To act from the block, use `ctx`: `ctx.notify`, `ctx.ask_user`,
+`ctx.steer`, `ctx.stop_turn`, `ctx.stop_generation`. Inside the block they
+act for **this event** (the `event[:notify]`… helpers that plain hooks in
+[hooks.md](hooks.md) get are the same thing, and a plugin doesn't need them):
+
+- `ctx.stop_turn` in a `:before_tool_call` block also denies the call the
+  event is about.
+- From `:after_turn` and `:session_end` there is no turn left:
+  `ctx.steer`, `ctx.stop_turn` and `ctx.stop_generation` do nothing and
+  return false.
+- In a `:generation_progress` block `ctx.ask_user` asks no one (nil).
+
+This holds on the block's own thread while it runs. A thread the block
+starts doesn't inherit the event: there the helpers act as from a command,
+on the session as it is when called ([The context](#the-context-ctx)), so
+`ctx.steer` from it reaches whatever turn is running then.
+
 #### Watching the stream
 
 `chi.on(:generation_progress)` sees a response while it streams, in batches
-(2000 chars or a second), and `event[:stop_generation]` (or
-`ctx.stop_generation`) cuts it while the turn goes on: the model is asked
+(2000 chars or a second), and `ctx.stop_generation` cuts it while the turn goes on: the model is asked
 again. The rules (the thread it runs on, keeping it fast, what a cut does)
 are in [hooks.md](hooks.md#watching-the-stream).
 
@@ -328,7 +343,7 @@ class Plugin
       next if event[:thinking_chars] < LIMIT
 
       # Once per generation: a cut generation fires no more.
-      if event[:stop_generation].call("it thought for over #{LIMIT / 1000}k chars")
+      if ctx.stop_generation("it thought for over #{LIMIT / 1000}k chars")
         ctx.notify("thinking too long (#{event[:elapsed_ms] / 1000} s): cut", level: :warn)
       end
     end
@@ -449,7 +464,14 @@ name order, so the first bundle keeps the name.
 ## The context: `ctx`
 
 Every handler gets the plugin's context. There is one per plugin for the
-session's life, and each read gives the session as it is now.
+session's life, and each read gives the session as it is now. It is a
+plugin's one way to talk to the user and to the turn: the helpers below act
+on the session now from a command, a tool, an init task or your own thread,
+and for the event inside a `chi.on` block (see `chi.on` above).
+
+Everything a plugin shows (notices, nudges, stop notices, questions) is
+named by its bundle in every UI (`my-bundle> …`); the debug log keeps the
+full label, `plugin.rb (bundle my-bundle)`.
 
 | | |
 |---|---|
@@ -461,13 +483,13 @@ session's life, and each read gives the session as it is now.
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
 | `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn |
 | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
-| `ctx.notify(text, level: :info)` | one line to the user, like a hook's `event[:notify]`, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command) |
+| `ctx.notify(text, level: :info)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command) |
 | `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 question, like a hook's `event[:ask_user]` |
+| `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, like a hook's `event[:steer]`: 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, your own |
-| `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason, like a hook's `event[:stop_turn]`; true when it stopped one now |
-| `ctx.stop_generation(reason)` | cut the generation that is streaming, like a hook's `event[:stop_generation]`: 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.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.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) |
 | `ctx.sessions` | fork, send to and read other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 
@@ -915,7 +937,7 @@ with a line and carry on unchanged.
 
 `chi bundle install skills` (or the `dev` profile) installs the bundle shipped with chi
 (`lib/samagotchi/bundles/skills/plugin.rb`): one anytime command, `chi.on`
-hooks, `ctx.sessions.send`, `ctx.notify` and `event[:steer]`. It has no memory
+hooks, `ctx.sessions.send`, `ctx.notify` and `ctx.steer`. It has no memory
 file; skills themselves work without it ([docs/memory.md](memory.md#skills)).
 
 | | |
@@ -940,16 +962,24 @@ skills> skill release updated (+2 −1): 1. Run `scripts/verify.sh`; stop if it
 The line is the file on disk changing, whatever the tool answered; a denied
 write shows nothing.
 
+A skill read in the turn is also watched for changes made another way (an
+`execute` running `sed`, a script): after each other tool call, and at the
+turn's end, its file is compared with the content last seen (at the read, or
+after the last write). A change shows the same line, keeps the content last
+seen as a version (so `/skill diff` has it) and counts as the skill updated.
+A plain read keeps no version.
+
 **The nudge** (`nudge: true`). Some models, finding a skill's step broken,
 skip it and go on without fixing the skill. In a turn that read a skill
 (`memory_read` of a `skill_*` name, or `read` of its file), the first failing
 tool call after it (an `execute` that exited non-zero, a tool error) steers
 the model once: *"A step of skill release failed. Find out why before skipping
-it; if the skill is out of date, fix it now: memory_write the whole skill,
-its title and every section as they were, that step fixed, a Changelog line
-added."* If the turn ends with a failed step and the
-skill not rewritten, one line says so: `skill release was followed, a step
-failed, the skill wasn't updated`. A failure unrelated to the skill (a test
+it; if the skill is out of date, fix it now: edit the step that changed in
+its file (or memory_write the whole skill) and add a Changelog line."* No
+steer once a skill read this turn has changed, by any tool. If the turn ends
+with a failed step and no skill read changed, one line says so: `skill
+release was followed, a step failed, the skill wasn't updated`. A failure
+unrelated to the skill (a test
 meant to fail) can set it off too: once per turn, and only after a skill was
 read.
 

data/docs/sessions.md

@@ -19,7 +19,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
-**Stopping a worker:** `chi sessions stop ID` marks the session stopped, sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal and the web report when a command or a question dismiss gets a 404 (`BridgeClient.stale_worker_message`). The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s.
+**Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s.
 
 **Deleting a session:** `chi sessions delete ID...`, `/exit --delete` in a terminal and the Web UI's delete all go through `SessionManager.delete_session`: it resolves a unique prefix, removes `<id>.json` and the whole `<id>/` dir, and returns what it removed. A session a plain REPL has open (`owner.lock` kind `tui`) is always refused. One a worker runs is refused unless the caller asks to stop it: then it stops the worker as `chi sessions stop` does and deletes once `owner.lock` is free (`--force` on the CLI, 10 s; the web always, 2 s; `/exit --delete` after the worker agreed to exit, 10 s). A worker that outlives the wait leaves the session in place. The web's route is `DELETE /api/sessions/:id` (200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
 

data/lib/samagotchi/bootstrap_command.rb

@@ -6,6 +6,8 @@ require_relative "model_profile"
 require_relative "bootstrap/probe"
 require_relative "bootstrap/config_writer"
 require_relative "bootstrap/bundles"
+require_relative "cli/command"
+require_relative "cli/flags"
 
 module Samagotchi
   # `chi bootstrap [TARGET]`: the first setup. It names a model server, works
@@ -15,6 +17,8 @@ module Samagotchi
   # system bundle and the core profile, and on a terminal asks about dev.
   # Prompts only on a terminal; a script gets the list and exit 2 instead.
   class BootstrapCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--no-test] [--dry-run]
         Finds the model server at TARGET and writes config.yml for it.
@@ -37,6 +41,14 @@ module Samagotchi
         check-in, guardrails), and on a terminal offers the dev bundles.
     TEXT
 
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.value "--name"
+      f.value "--model"
+      f.value "--key-env"
+      f.switch "--no-test"
+      f.switch "--dry-run"
+    end
+
     PICK_SHOWN = 20
     # A test request slower than this says it is waiting (a model loading).
     LOADING_AFTER = 3
@@ -66,8 +78,8 @@ module Samagotchi
     # @return [Integer] 0 written (or already there), 1 failed (a failed
     #   test still writes the config), 2 usage or a choice to make
     def run
-      options = parse or return 2
-      return 0 if options[:help]
+      options = parse
+      return options if options.is_a?(Integer)
 
       key_env = options[:key_env]
       return fail!("#{key_env} is not set; export it first (the API key; chi only writes its name)") if key_env && unset?(key_env)
@@ -85,26 +97,21 @@ module Samagotchi
 
     private
 
+    def command_name = "chi bootstrap"
+    # A usage error's line ends with "(see chi bootstrap --help)".
+    def usage_on_error = nil
+
+    # @return [Hash, Integer] the options, or the exit status after the
+    #   help or a usage error
     def parse
-      options = {}
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "-h", "--help", "help"
-          @stdout.puts(USAGE)
-          return { help: true }
-        when "--name", "--model", "--key-env"
-          options[arg.delete_prefix("--").tr("-", "_").to_sym] = @argv.shift or return usage_error("#{arg} needs a value")
-        when /\A--(name|model|key-env)=(.+)\z/ then options[Regexp.last_match(1).tr("-", "_").to_sym] = Regexp.last_match(2)
-        when "--no-test" then options[:no_test] = true
-        when "--dry-run" then options[:dry_run] = true
-        when /\A-/ then return usage_error("unknown option #{arg}")
-        else
-          return usage_error("one TARGET only (got #{options[:target]} and #{arg})") if options[:target]
+      parsed = parse_flags(FLAGS, @argv)
+      return parsed if parsed.is_a?(Integer)
 
-          options[:target] = arg
-        end
-      end
+      options = parsed.options
+      target, extra = parsed.args
+      return usage_error("one TARGET only (got #{target} and #{extra})") if extra
+
+      options[:target] = target if target
       if options[:key_env] && !options[:key_env].match?(ConfigFile::ENV_NAME_RE)
         return usage_error("--key-env takes the variable's name (e.g. OPENROUTER_API_KEY), not the key")
       end
@@ -119,8 +126,7 @@ module Samagotchi
       candidates = begin
         Bootstrap::Probe.candidates(options[:target])
       rescue ArgumentError => e
-        usage_error(e.message)
-        @exit = 2
+        @exit = usage_error(e.message)
         return nil
       end
       result = @probe.classify_target(candidates, key_env: key_env)
@@ -251,8 +257,7 @@ module Samagotchi
       name = begin
         writer.host_name(Bootstrap::ConfigWriter.derived_name(result.candidate.host), requested: options[:name], model_ids: ids)
       rescue Bootstrap::ConfigWriter::Error => e
-        usage_error(e.message)
-        @exit = 2
+        @exit = usage_error(e.message)
         return nil
       end
       outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
@@ -408,10 +413,5 @@ module Samagotchi
       @exit = 1
       nil
     end
-
-    def usage_error(message)
-      @stderr.puts("chi bootstrap: #{message} (see chi bootstrap --help)")
-      nil
-    end
   end
 end