samagotchi 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f0638cac2109278f683d0b6caeca1bb633786721471c1f366f2cf3bc459b43f
-  data.tar.gz: 988b05ee21480227d4a1ed814457dd26af11ed71bf21b3d6c62f863e07f18e1a
+  metadata.gz: 2e7f8dcd85ecceeec6695f9ee969633b68c9f4900c597af6ffc87e9b8ee15168
+  data.tar.gz: d26fd005c3e98b1177de659b41e94ae09a22d19159d74215475db6b5e1777ff3
 SHA512:
-  metadata.gz: b7905a2a451c696ca057def8388137bc6a03523bd43a8e9405d2086a99b979f4804fe51c3bb3fd7fc444ade5ea7909339a29c99a3373b9ad3b254d8702210906
-  data.tar.gz: ce71c8a3a069014d738088e50372c9f50553bd9da12613a756c5941498ba2f3024f9954d2bbe672b10b6c0b00cc5c80cd296858ec84a1425e4ef3713e84cf0fd
+  metadata.gz: aeb8f2f124a5c21f0f5a58ea99c8f473bbde98716ee9abb47478697971a079c32dfd7c36097de58702ec2104ecb8f6846f403019eb9ac66a772c6a14c7b89c0c
+  data.tar.gz: 1ae7b930ce05499c42e1d2cea7a140261d6d0240291ecbdd58394fe8da5649452f969ecccc219317b77baaa686dddf77107313d2c469aa4c4c3277aa997873fd

data/CHANGELOG.md

@@ -8,6 +8,93 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-02
+
+### Added
+
+- `chi send --wait --format json` prints one JSON object on stdout however the wait ends: the reply, a question with its
+  options and the `chi answer` command for it, or the status and a detail line, for scripts and parent agents.
+- `chi answer ID --question QID --option N` (or `--text`, `--dismiss`) answers the question a session waits on and
+  waits for what comes next, as `chi send --wait` does, so an agent running chi as a sub-agent can answer chi's
+  questions itself. `chi send --wait -m` to a session waiting for an answer is refused with the `chi answer` command
+  for it.
+- An approval answered with `chi answer` can be denied, not allowed: allowing is the user's (the web, `chi --attach`).
+  `guardrails.parent_approvals: once` in config.yml (no environment variable) lets "Allow
+  once" through, never a wider scope, and never on a call that changes chi's own config, hooks or guardrail rules; an approval whose offered scopes are missing lets only Deny through. The worker
+  checks it again with its own config (`chi answer` marks its answers); the web and `chi --attach` keep every scope.
+- `chi sessions list` shows a session waiting for an answer as `waiting`; `--format json` has `waiting` (`question`,
+  `approval` or `hook`) and `waiting_id`, the question's id for `chi answer --question`.
+- docs/sub-agent.md: running chi as another agent's sub-agent, with instructions to paste into its `CLAUDE.md` /
+  `AGENTS.md`.
+
+### Changed
+
+- The `guardrails` bundle (0.3.0) asks before answering chi's questions around `chi answer`: `chi --attach` / `chi -p`
+  with stdin from a pipe, a here-string or a file, and `curl`/`wget` to a session's `/answer` route.
+- An answer typed into `chi --attach` or the REPL counts as a parent agent's, held to `guardrails.parent_approvals`,
+  when stdin isn't a terminal or `CLAUDECODE`, `AI_AGENT` or `SAMAGOTCHI_PARENT_SESSION` is set: a piped `y` no
+  longer allows an approval at any scope. chi's `execute` and `task_create` export `SAMAGOTCHI_PARENT_SESSION` (the
+  session's id) into the commands they run, and the model's `task_create` env can't set it.
+- `guardrails.enabled` and `guardrails.small_models` are config.yml only: `SAMAGOTCHI_GUARDRAILS_ENABLED=false` no
+  longer switches guardrails off, and a worker unsets every `SAMAGOTCHI_GUARDRAILS_*` it inherits, so a parent agent
+  starting or waking a session can't switch its guardrails off. `XDG_CONFIG_HOME` still picks the config dir.
+- `chi send --wait` exits 4 (not 1) when `--timeout` passes with the turn still running.
+- Attached `chi -p` from a script exits 3 (not 1) when it leaves a question or an approval waiting for an answer,
+  and prints the whole question on stderr with the `chi answer` command for it, as `chi send --wait` does.
+- For an approval, the question block, `answer_with` and the refusal tell a parent agent to deny it and tell its
+  user (`--option Deny --text WHY`), not `--option N` or `chi --attach`; other questions keep their wording.
+- `chi send --wait`'s exit 3 prints the whole question on stderr: its text, numbered options and how to answer it.
+- `delegate` / `delegate_result` on a child waiting for an answer give the whole question: its text, numbered options
+  and the `chi answer` command for it.
+- `chi send --image` with a missing file or one that isn't an image exits 1 (not 2, which is for usage errors), and
+  with `--wait --format json` prints the JSON error line.
+
+### Fixed
+
+- The web no longer notifies about, or draws, a question a chi REPL is asking: the web can't answer it there.
+- `delegate_result` on a child whose worker died says `worker_gone` instead of waiting for, or reporting, a question
+  nobody can answer; `chi send --wait` and `chi answer` no longer report such a question as waiting either.
+- Answers from Splash no longer start with two blank lines (a workaround until Splash drops them itself).
+- An error in chi's work after a turn's answer no longer also reports the answered turn as failed.
+- A Stop while a turn is still starting (chi asking the model server about the model) now ends the turn there: no before-turn hooks run and a due reminder stays due.
+- `recap.model` set to a model id without a host no longer turns the recap off: it asks the host a bare `--model` goes to.
+- AGENT.md is found at the top of the git work tree when chi runs in a subdirectory (one in the current directory still wins).
+- `execute.timeout_sec` in config.yml (or `--execute-timeout-sec`) sets how long an `execute` command may run, like `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC`; it no longer warns as an unknown key.
+- A bundle's `requires_chi` now applies to its hooks too, not only its plugin: on a too-old chi they don't load, with a notice.
+- `chi bundle install` and `chi bundle status` say when a bundle's hooks won't load because chi is older than its `requires_chi`, also for a bundle without a plugin.
+- A model named with a disabled host's prefix (`box:model` where `hosts.box` has `enabled: false`) is refused with "host 'box' is disabled" instead of going to the default host as a model id.
+- A Stop while a turn is still starting no longer uses up the warning about guardrails or plugins that failed to load: the next turn shows it.
+- A plugin or MCP tool call reads the same in logs, rows and hooks' `content` whatever the model format or Ruby version: its arguments as JSON (Qwen calls showed Ruby's Hash#inspect, which changed in Ruby 3.4). A plugin tool returning a Hash or Array gives the model JSON too.
+
+Update with `chi update` (bundles: guardrails 0.3.0).
+
+## [0.12.0] - 2026-10-02
+
+### Added
+
+- `chi models [--format json] [--timeout S] [TEXT]` lists the names `--model` takes from every host (default first,
+  then `host:id`, then aliases), waiting at most 4 s for the hosts; exit 1 when no host listed.
+- The desktop helper chooses the model for a new session: ⌘M (or a click on the new row's model) opens a searchable
+  chooser of every host's models and aliases; the pick and five recent ones are remembered. Run `chi desktop upgrade`.
+
+### Changed
+
+- `chi self --model` prints an alias default as the ref it resolves to (`box:gemma-small`, not `small`).
+
+### Fixed
+
+- A failed turn's messages and its `turn_failed` event reach a joining client together (a snapshot taken in between
+  could show one without the other).
+- A Ctrl-C while an `after_turn` or `session_end` hook runs no longer cancels the turn that already answered: the
+  answer stays in the session (it was replaced with a cancel note and a second end event).
+- A web Stop sent right as a turn starts (while chi asks the model server for its settings, a first turn's /props
+  probe) cancels the turn at once; it used to answer "not running" and the turn ran on. A failed probe there now ends
+  the turn as failed instead of leaving the session marked running.
+- Reminders keep firing on their own while a session is idle. A reminder that a prompt's turn delivered just as the
+  idle check found it due, or a reminder turn that failed before it started, could stop them until the next prompt.
+
+Update with `chi update` (no bundle changes); run `chi desktop upgrade` for the desktop helper's model chooser.
+
 ## [0.11.0] - 2026-10-01
 
 ### Added
@@ -642,7 +729,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.11.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/dm1try/samagotchi/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/dm1try/samagotchi/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/dm1try/samagotchi/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/dm1try/samagotchi/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/dm1try/samagotchi/compare/v0.9.0...v0.10.0

data/README.md

@@ -14,9 +14,16 @@ command.
 ## Requirements
 
 - Ruby 3.3+
-- A model server: [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server`
-  by default; mlx-lm, oMLX and OpenAI-compatible servers also work
-  (see [Configuration](docs/configuration.md#model-server-transport))
+- A model server: any OpenAI-compatible chat completions server, or
+  [llama.cpp](https://github.com/ggml-org/llama.cpp)'s `llama-server` through
+  its own API (the native path, and the default)
+
+Tested: llama.cpp native (Qwen, Gemma 4), [Splash](https://github.com/incoai/splash)
+over the OpenAI API, and [OpenRouter](https://openrouter.ai) (remote, OpenAI API
+with `api_key_env`). vLLM, LM Studio, Ollama, mlx-lm, oMLX and other
+OpenAI-compatible servers should work over the OpenAI API but are not tested;
+mlx-lm and oMLX also have native transports, see
+[Configuration](docs/configuration.md#model-server-transport).
 
 ## Install
 
@@ -59,7 +66,7 @@ Point chi at your model server; it works out the rest and writes
 
 ```sh
 chi bootstrap 192.168.1.29:8081          # llama.cpp on another machine
-chi bootstrap localhost:11434            # Ollama (any OpenAI-compatible server)
+chi bootstrap localhost:11434            # any OpenAI-compatible server
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
 chi bootstrap                            # look on this machine's usual ports
 ```
@@ -86,9 +93,8 @@ server:
   port: 8080
 ```
 
-`server:` is a llama.cpp `llama-server`. For any other OpenAI-compatible
-server (vLLM, LM Studio, Ollama, a gateway), name it under `hosts:` with
-`api: openai` instead:
+`server:` is a llama.cpp `llama-server`. For an OpenAI-compatible server,
+name it under `hosts:` with `api: openai` instead:
 
 ```yaml
 default:
@@ -145,6 +151,12 @@ stdin plus `-m` puts the stdin above the message as a `>` quote. `chi send --new
 starts a session with the message instead (it shows in the web at once), and
 `--wait` blocks and prints the answer.
 
+Another agent (Claude Code, Codex) can run chi as a sub-agent the same way:
+`chi send --new --wait --format json` returns chi's reply, or the question chi
+stopped on, which the agent answers with `chi answer`. See
+[chi as a sub-agent](docs/sub-agent.md) for a snippet to paste into its
+`CLAUDE.md` / `AGENTS.md`.
+
 ### Send to chi (macOS)
 
 `chi desktop install` builds a small native helper: select text in any app →
@@ -173,6 +185,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Configuration](docs/configuration.md): `config.yml`, hosts, model server transports, timeouts, retries, logs
 - [Memory](docs/memory.md): scopes and model-specific overlays
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
+- [chi as a sub-agent](docs/sub-agent.md): `chi send --wait --format json`, `chi answer`, instructions for a parent agent
 - [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks

data/bin/chi

@@ -23,13 +23,13 @@ if ARGV[0] == "self"
   if %w[-h --help help].include?(ARGV[1])
     puts "Usage: chi self [--model]"
     puts "  Print version, source dir, config/memory/session paths, model/host and bundles."
-    puts "  --model  print only the model a new session starts on (exit 1 when none is configured)"
+    puts "  --model  print only the model a new session starts on, an alias resolved (exit 1 when none is configured)"
     exit 0
   end
   require "samagotchi/self_report"
   # The desktop helper's hint for its "New session" row: offline and quick.
   if ARGV[1] == "--model"
-    model = Samagotchi::SelfReport.model_name
+    model = Samagotchi::SelfReport.model_ref_name
     puts model if model
     exit(model ? 0 : 1)
   end
@@ -45,10 +45,14 @@ SUBCOMMANDS = {
   "note" => ["samagotchi/note_command", "NoteCommand"],
   # a message into sessions as the user's (-m)
   "send" => ["samagotchi/send_command", "SendCommand"],
+  # answer the question a session waits on, then wait (--question, --option)
+  "answer" => ["samagotchi/answer_command", "AnswerCommand"],
   # find a model server and write config.yml (--model, --name)
   "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
   # bring an installed chi up to date
   "update" => ["samagotchi/update_command", "UpdateCommand"],
+  # the models --model takes, from every host (--format, --timeout)
+  "models" => ["samagotchi/models_command", "ModelsCommand"],
   # the native "Send to chi" helper
   "desktop" => ["samagotchi/desktop_command", "DesktopCommand"],
   # install, upgrade, uninstall, status, diff, list, build (--scope, --force, …)
@@ -92,8 +96,10 @@ parser = OptionParser.new do |opts|
            chi sessions <list|stop|archive|unarchive|delete|prune|clean>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
            chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
+           chi answer ID --question QID --option N   answer a question a session waits on
            chi bundle <install|upgrade|uninstall|status|diff|list|build>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
+           chi models [--format json] [TEXT]   the models --model takes, from every host
            chi self                         version, paths, model and bundles
            chi update [--dry-run]           update this chi, its bundles and the desktop helper
     (each subcommand takes --help)
@@ -103,7 +109,7 @@ parser = OptionParser.new do |opts|
   opts.on("--resume SESSION_ID", "Resume a previous session by its ID (or a unique prefix of it)") { |s| options[:resume] = s }
   opts.on("--attach SESSION_ID", "Attach to a session's worker, waking one if it has exited; ID or a unique prefix") { |s| options[:attach] = s }
   opts.on("--[no-]shared", "Run the session in a background worker and attach to it, so `chi web` can share it (the default, config session.shared; with --resume: that session); --no-shared runs a plain in-process REPL") { |v| options[:shared] = v }
-  opts.on("--model NAME", "Model selector (runtime only, overrides --resume) [alias for --default-model]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
+  opts.on("--model NAME", "Model for this run, not saved (overrides --resume's; config default.model) [env SAMAGOTCHI_DEFAULT_MODEL]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
   opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
           "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join('|')}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
   opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "How much the model thinks this run: off|low|medium|high|default (outranks config.yml; " \
@@ -308,7 +314,7 @@ if launch == :attached
     warn "Error: #{e.message}"
     exit 1
   end
-  exit(ended == :detached ? 0 : 1)
+  exit Samagotchi::TerminalUI::AttachLauncher.exit_status(ended)
 end
 
 begin

data/docs/architecture.md

@@ -156,10 +156,10 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 #### Using the core
 
 ```ruby
-engine = Samagotchi::Engine.new(mode: :assist, model_name: "gemma4", memories: [])
+engine = Samagotchi::Engine.new(model_name: "gemma4", memories: [])
 session = Samagotchi::Session.new_session(mode: "assist", model_name: "gemma4", working_directory: Dir.pwd)
 
-engine.run_turn(session, "hello", on_event: nil)   # => KernelLoop::Result (`.output`)
+engine.run_turn(session, "hello", on_event: nil)   # => LLM::ModelResult (`.output`)
 ```
 
 #### The `on_event` seam
@@ -169,7 +169,7 @@ forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds
 higher-level events so UIs get clean turn boundaries without inferring them:
 
 - `:turn_started` — `{ session_id:, prompt: }`
-- `:turn_completed` — `{ result: }` (the final `KernelLoop::Result`)
+- `:turn_completed` — `{ result: }` (the final `LLM::ModelResult`)
 - `:turn_canceled` — `{ cancellation_reason: }`
 
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
@@ -223,7 +223,9 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   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.
+  answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
+  (`chi answer`, a parent agent) an allow on an approval beyond the worker's
+  `guardrails.parent_approvals` is `403 parent_approval_refused`, the question still open.
 - `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
   `200`, or `409` when it is no longer pending.
 - `POST /session/:id/command` — a session command (`/model`, `/models`, `!rollback`, `!cmd`,
@@ -330,8 +332,8 @@ conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
 `summary:`, which the REPL, the attached TUI and the web show.
 
-**Usage and models.** `ModelResult#usage` is an `LLM::Usage` (server counts, else
-a chars/4 estimate, else zeros; never nil). Model lists are `LLM::ModelInfo`
+**Usage and models.** A turn's token counts are `SessionMetrics`', read from the
+stream events (server counts, else a chars/4 estimate). Model lists are `LLM::ModelInfo`
 (`HostRegistry#list_all_models`); the context window comes from the running
 server (`/props`), then the host's model list, then config.
 

data/docs/cli.md

@@ -17,18 +17,20 @@
 - `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
 - `chi sessions list|stop|archive|unarchive|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). A usage error (an unknown subcommand or flag, a flag missing its value, `stop` or `delete` with no ids, a bad `list --format` or `--scope`) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
-- `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
-- `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 send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; `--format json` prints one JSON object instead; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
+- `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
+- `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
+- `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
+- `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, an alias resolved to its target (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)). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for every other command
+- `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 the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument
 
 ### First setup
 
 `chi bootstrap TARGET` names the model server and writes the config for it:
 
 ```sh
-chi bootstrap 192.168.1.29:8081          # host:port (port 8080 when none)
+chi bootstrap 192.168.1.29:8081          # host:port (an IP or localhost: port 8080 when none; a domain: https 443, then http 80)
 chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
 chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
 ```
@@ -66,6 +68,29 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   A bundle that fails to install makes the exit 1. `--dry-run` says what it
   would install.
 
+### Listing the models
+
+`chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and
+`chi send --new --model`, `/model`) takes, one per line:
+
+```sh
+$ chi models
+gemma-4                          # the default (default.model), first
+splash:incoai/Qwen3.8-27B-Splash # another host's id: host:id
+openrouter:qwen/qwen3.8-27b
+small -> box:gemma-small         # an alias and the ref it resolves to
+$ chi models qwen                # only the names containing "qwen" (any case)
+```
+
+- A default-host id is bare, except one with a `:` (`qwen3:8b`), which is written `<host>:qwen3:8b` so it can't
+  read as a host name. An id that an alias of the same name hides is left out.
+- Each run lists anew (no cache); `--timeout S` caps the wait for the hosts (default 4 s). A host that fails or doesn't
+  answer in time is noted on stderr (`chi models: box: no answer in 4 s`).
+- `--format json` prints one object: `default` (and `default_typed` when it was set as an alias), `default_host`,
+  `models` (`name`, `host`, `id`), `aliases` (`name`, `ref`, `host`) and `warnings`. The desktop helper's model
+  chooser reads it.
+- Exit 0 when any host listed its models, 1 when none did (the default is still printed), 2 on a usage error.
+
 ### Updating
 
 `chi update` brings an installed chi up to date and prints one table:
@@ -155,7 +180,8 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 
 Every setting in the config registry (`lib/samagotchi/config.rb`) that exposes a CLI
 flag also works as `--kebab-case VALUE`, e.g. `--server-host`, `--server-port`,
-`--read-truncate-at-bytes`. `chi --help` lists them all.
+`--read-truncate-at-bytes`; an on/off setting is `--[no-]kebab-case` with no value
+(`--context-status`, `--no-context-status`). `chi --help` lists them all.
 
 **Which loop runs.** There is no backend flag: the model's host decides. A host with
 `api: openai` in config.yml is driven through the OpenAI chat API (streamed; a remote
@@ -180,11 +206,22 @@ as an unknown key).
 
 Notes:
 
+- Attached `chi -p …` with stdin not a terminal (a script, an agent's shell)
+  leaves when its input ends and the turn is done. Exit status: 0 the turn
+  ended, 3 a question or an approval waits for an answer (stderr gets the
+  whole question as `chi send --wait` prints it, with the
+  `chi answer ID --question QID --option N` command; the worker keeps it
+  open, and `chi answer` or the web answers it), 1 the turn failed or the
+  worker went away. For a
+  script, `chi send --new --wait` is the better entry point: stdout holds the
+  answer alone (see [Starting a session](sessions.md#starting-a-session)).
 - `-p` always feeds **and** runs the prompt; there is no feed-and-edit variant. To
   prefill (edit, not execute) the first REPL line, use the
   `SAMAGOTCHI_DEFAULT_INPUT` environment variable instead.
-- Prompt history is persisted per session; `--resume` preserves prior messages as
-  turn context (a `-p` run on a resumed session never clobbers existing history).
+- Prompt history (↑) is one file shared by every session (see [Persistent Prompt
+  History](#persistent-prompt-history)); `--resume` preserves the session's prior
+  messages as turn context (a `-p` run on a resumed session never clobbers its
+  conversation).
 - Non-interactive runs (`-p` with `--non-interactive`, or bare `--non-interactive`)
   print only the final result output — no spinner, status line, or REPL.
 
@@ -333,6 +370,16 @@ file and index line stay as they are; only this session doesn't see it.
 - The `read` tool on `memories/<name>.md` is not refused (a guardrails rule
   can protect the path if wanted).
 
+### Session commands
+
+`/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, generation latency, cancellations, retries, context used and window,
+the prompt profile and the model the server says it ran. `/recap` is in
+[Session recap](#session-recap), `/model` and `/models` in [Runtime Model
+Switch](#runtime-model-switch-assist-mode).
+
 ### Typing during a turn
 
 The prompt stays open while a turn runs, in an attached terminal and in the plain
@@ -344,7 +391,8 @@ REPL alike:
   A line that comes after the turn's last step runs as the next turn, and so
   does one sent after Ctrl-C: it doesn't merge into the turn being cancelled.
   Reminder turns take merged lines too.
-- `/stats` and `/recap` answer at once. Other commands (`!cmd`, `/model`,
+- `/stats` and `/recap` answer at once, and in an attached terminal so do `/help`
+  and a plugin's anytime command (`/btw`). Other commands (`!cmd`, `/model`, `/models`,
   `!rollback`, `/continue`, `/guardrails`) say `busy: wait for the turn to end`
   and go back into the prompt, so Enter runs them once the turn ends.
 - A question (`ask_user_question`, a guardrails approval) turns the prompt into
@@ -577,7 +625,7 @@ In interactive assist mode, you can switch the request model without restarting:
 
 - `/model <name>`: set a session-scoped model override.
 - `/model host:model` or `/model host:alias`: qualified host routing (only `:` names a host; `openai/gpt-4o` is a model id). `host:alias` applies the alias; an alias whose target names another host is refused (`alias 'tiny' names host 'box', not 'openrouter'`). Aliases apply once: an alias pointing to another alias sends that name as written.
-- `/model --default <name>`: set session model and persist as new default in `config.yml` (also updates `SAMAGOTCHI_DEFAULT_MODEL` for future sessions; supports `host:model` full ref).
+- `/model --default <name>`: set session model and persist as new default (`default.model`) in `config.yml` for future sessions (supports `host:model` full ref). It writes only the file: an exported `SAMAGOTCHI_DEFAULT_MODEL` (or `--model`) still wins over it.
 - `/model <name> --alias <alias>`: create alias for current effective model (alias value may be bare or `host:model`).
 - `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
@@ -700,7 +748,7 @@ A long, tool-heavy turn says what it has been doing. From the turn's 3rd tool ca
 a dim row under the activity row tallies its calls, with no model call:
 
 ```
-12 tool calls (2 failed) · execute ×7 · read_file ×3 · edit_file ×2 · last: execute command=bundle exec rspec
+12 tool calls (2 failed) · execute ×7 · read ×3 · edit ×2 · last: execute command=bundle exec rspec
 ```
 
 It lists the top 3 tools by count (ties go to the tool used first), the failed calls

data/docs/configuration.md

@@ -49,8 +49,9 @@ hosts:
 # url:, else http://host:port/v1) with its api_key_env; base_url is an OpenAI API
 # base as given (e.g. http://h:8081/v1). model is a model ref like any other: an
 # alias is applied, and its host:/the alias's host picks the host when host_ref
-# is left out (a model naming another host than host_ref turns recap off with a
-# warning). recap: false turns it off.
+# is left out; a model naming no host goes where a bare --model goes (the
+# default host). A model naming another host than host_ref turns recap off with
+# a warning. recap: false turns it off.
 recap:
   # host_ref: small-box
   # model: your-small-model-id
@@ -114,8 +115,9 @@ any per-run `--memory` values (config baseline first, deduped). A per-run
 
 ### Environment variables
 
-Every setting has an environment variable: `SAMAGOTCHI_` plus its dotted
-name in upper case, with `_` for each dot. `default.model` is
+Every setting has an environment variable (except the ones the table marks
+config.yml only): `SAMAGOTCHI_` plus its dotted name in upper case, with `_`
+for each dot. `default.model` is
 `SAMAGOTCHI_DEFAULT_MODEL`, `server.read_timeout` is
 `SAMAGOTCHI_SERVER_READ_TIMEOUT`. Use them to override the file for one run or
 one shell (`SAMAGOTCHI_LOG_LEVEL=debug chi`); keep lasting choices in the file.
@@ -230,6 +232,18 @@ hosts:
     api_key_env: BOX_LLAMA_KEY
 ```
 
+A host without `port:` (and without `url:`) uses port 8080. `enabled: false`
+turns an entry off without deleting it: chi skips it as if it weren't there
+(not in `chi models`, never the default host; `box:model` then counts as an
+unknown host prefix, see [Llama Model Routing](#llama-model-routing)):
+
+```yaml
+hosts:
+  box:
+    host: 192.0.2.20
+    enabled: false
+```
+
 For models on that host, chi uses the chat loop (its own OpenAI chat adapter): it
 takes the OpenAI base (`url:`, else `http://HOST:PORT/v1`) and streams messages plus
 function schemas from `/v1/chat/completions`; the model's reasoning (`reasoning_content`)
@@ -741,6 +755,10 @@ The helper reads these from its launch file: after editing them run
 
 If an AGENT.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
+The project root is the top of the git work tree chi runs in (a linked
+worktree's own checkout), or the current directory outside a repository. An
+AGENT.md in the current directory is read instead when there is one; only one
+file is read.
 
 To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
 `config.yml` (env `SAMAGOTCHI_SKIP_AGENT_MD=true`).
@@ -749,7 +767,8 @@ To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
 
 Every setting below takes the three forms described in
 [Environment variables](#environment-variables): a nested key in
-`config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment and, where the CLI
+`config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment (not for one
+marked config.yml only) and, where the CLI
 column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 `model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`) are
 described in their own sections.
@@ -767,7 +786,7 @@ described in their own sections.
 | `server.read_timeout` | `600` | yes | Read timeout, seconds. |
 | `server.first_token_timeout` | 120 remote, off local | | Seconds to the first token; `0` = off. `hosts.<name>.first_token_timeout` wins. |
 | `recap.enabled` | on | | `false` (or `recap: false`) turns the idle recap off. |
-| `recap.model` | session's | yes | Model that writes the recap: an id, alias or `host:model` (the host then picks where to ask). |
+| `recap.model` | session's | yes | Model that writes the recap: an id, alias or `host:model` (the host then picks where to ask; a bare id goes where a bare `--model` goes). |
 | `recap.host_ref` | session's | yes | A `hosts:` name to ask (`host:` is accepted too, also a host name, not a model ref). |
 | `recap.base_url` | none | yes | An OpenAI API base to ask instead (`http://h:8081/v1`). |
 | `recap.inactivity` | `180` | yes | Idle seconds before a recap. |
@@ -785,8 +804,9 @@ described in their own sections.
 | `image.max_side` | `1568` | | See "Images". |
 | `image.max_bytes` | `3750000` | | See "Images". |
 | `image.max_per_request` | `20` | | See "Images". |
-| `guardrails.enabled` | `true` | | See [Guardrails](guardrails.md). |
-| `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. See [Guardrails](guardrails.md#rules-for-some-models). |
+| `guardrails.enabled` | `true` | | `false`: no rules, and hooks' asks are dropped (a deny still applies). config.yml only: a worker unsets any `SAMAGOTCHI_GUARDRAILS_*` it inherits. See [Guardrails](guardrails.md). |
+| `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. config.yml only. See [Guardrails](guardrails.md#rules-for-some-models). |
+| `guardrails.parent_approvals` | `off` | | What `chi answer` lets a parent agent allow on an approval: `off` (deny only) or `once` ("Allow once", never a wider scope). config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `log.file` | state dir | yes | See "Debug Log File". |
 | `log.disable` | `false` | yes | No file logging. |
 | `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
@@ -817,6 +837,7 @@ described in their own sections.
 | `execute.truncate_at_bytes` | `65536` | yes | The same for `execute` output. |
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
+| `execute.timeout_sec` | `30` | yes | Seconds one `execute` command may run before it is stopped. |
 | `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/desktop.md

@@ -35,8 +35,30 @@ The first row, **New session in <folder>** (⌘0), starts a session with the mes
 that of the most recently updated live session, else of the newest recent one, else your home folder. It is ticked
 alone (ticking it clears the sessions and the reverse) and is preselected when no session is live. ⌘⏎ on it beeps: a
 note needs a session. After the send the panel shows `started <id>…` for 3 s. On its right, in grey, the row names
-the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override); it
-is left out when none is configured.
+the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override; an
+alias as the model it names).
+
+### Choosing the model
+
+Click the model on the new row, or press **⌘M**, to choose another one for the new session. The chooser takes the
+place of the session list: a search field (focused), then **Default (<model>)** (`Default (small → box:gemma-small)`
+for an alias), your recent picks and every host's
+models and aliases (from [`chi models`](cli.md#listing-the-models)), at most nine at a time.
+
+- Type to search: every word must match the host or the id; names starting with what you typed rank first. A name
+  no host lists is offered at the bottom as "not listed" and sent as typed (a host that is down, a model just added).
+- ↑/↓ and ⏎, a click, or ⌘1…⌘9 pick; Esc (or ⌘M) closes the chooser only, a second Esc the panel. While an input
+  method is composing, ⏎, the arrows and Esc are its own.
+- The row then shows the pick in the accent colour, and ⏎ sends `chi send --new --model <name>`, the name exactly as
+  the chooser shows it; Default sends no `--model`. An existing session keeps its model (switch it there with `/model`).
+- The pick is remembered for the next open (and the last five in the recent list), for every folder. A remembered
+  model no host lists any more falls back to the default, with a note in the panel.
+- The list is fetched again at each open; the previous one shows meanwhile ("Loading models…" the first time after
+  the helper starts). Hosts that failed or took over 4 s are named under the list; the default and the recent picks
+  still work.
+
+The chooser needs a chi with `chi models`: an older helper works with a newer chi, not the reverse
+(`chi desktop upgrade` after updating chi).
 
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 
@@ -83,8 +105,9 @@ off until you set it up:
    `kitty.agents` picks the programs listed (default `claude|codex|gemini|aider|opencode|cursor-agent|amp|goose`, a
    YAML list works too; `"*"` lists every window, shells too), `kitty.binary` the kitty to run (default
    `/Applications/kitty.app/Contents/MacOS/kitty`). See [Configuration](configuration.md#desktop-helper-agents-in-kitty).
-3. Run `chi desktop upgrade` (or `chi update`): the helper reads these from its launch file, so **after every edit of
-   `kitty:`** run it again. No rebuild when only the settings changed.
+3. Run `chi update` (or `chi desktop upgrade`): the helper reads these from its launch file, so **after every edit of
+   `kitty:`** run it again. `chi update` only rewrites the launch file when only the settings changed (no rebuild);
+   `chi desktop upgrade` always rebuilds.
 
 The helper finds the sockets itself: kitty adds `-<pid>` to a `listen_on` path from kitty.conf (and fills in
 `{kitty_pid}`), `~` and variables the helper knows are expanded, others (`${KITTY_PID}`) stay as written, as kitty
@@ -166,12 +189,15 @@ using it. `status` prints the baked dirs.
 The helper uses only these commands, so it could ship on its own later:
 
 - `chi sessions list --live --scope=all --format json` and `chi sessions list --limit 20 --scope=all --format json` →
-  `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap}]` (it uses `id`, `desc`, `cwd`, `busy`, `updated_at`;
+  `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (it uses `id`, `desc`, `cwd`, `busy`, `updated_at`;
   "recent" = rows of the second call that aren't live and have `owner: null`; only UUID-shaped ids go on to chi).
-- `chi send [-m LINE] ID...` with the text on stdin (or none) and `chi note --source NAME ID...` with the text on
-  stdin → one line per session on stdout; exit 0 means all sent or queued, 1 means some were refused or failed.
+- `chi send [-m LINE] [--image PATH]... ID...` and `chi send --new --dir DIR [--model NAME] [-m LINE] [--image PATH]...`
+  with the text on stdin (or none), and `chi note [--source NAME] ID...` with the text on stdin → one line per session
+  on stdout; exit 0 means all sent or queued, 1 means some were refused or failed.
+- `chi self --model` → the model a new session starts on (the panel's hint).
+- `chi models --format json` → the models the hosts offer (the new-session model picker).
 
-Each call is stopped after 10 s. A stopped `chi note` says the note may be partly delivered.
+Each call is stopped after 10 s, a send with images after 30 s. A stopped `chi note` says the note may be partly delivered.
 
 ## Troubleshooting