samagotchi 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9668c1088aa3739aa60890e07c7d04cf41fb87debf9683b6cd42b6e6e61ee265
-  data.tar.gz: ecfd58cc93c0dee8d867936c75754f854da34cf436dce28fcbc442e7f61c6ec2
+  metadata.gz: 2e7f8dcd85ecceeec6695f9ee969633b68c9f4900c597af6ffc87e9b8ee15168
+  data.tar.gz: d26fd005c3e98b1177de659b41e94ae09a22d19159d74215475db6b5e1777ff3
 SHA512:
-  metadata.gz: cd2b82ad80038fb47d35a7b76177312521548a61764963697bebe2cb3b5389fd2d604debba118a87bca43077f2f350b7a0c5f63878df73c5ad75382951246ca0
-  data.tar.gz: ef64847c760b05f8b6ee084fcd39b0ffc2595de21538c388ee7dc8c37f59a952bf4f55b2cf8db8df8187cf4600dd890e996bb94473a9af4e3e99a8cef8ed48af
+  metadata.gz: aeb8f2f124a5c21f0f5a58ea99c8f473bbde98716ee9abb47478697971a079c32dfd7c36097de58702ec2104ecb8f6846f403019eb9ac66a772c6a14c7b89c0c
+  data.tar.gz: 1ae7b930ce05499c42e1d2cea7a140261d6d0240291ecbdd58394fe8da5649452f969ecccc219317b77baaa686dddf77107313d2c469aa4c4c3277aa997873fd

data/CHANGELOG.md

@@ -8,6 +8,66 @@ 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
@@ -669,7 +729,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.12.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

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

@@ -45,6 +45,8 @@ 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
@@ -94,6 +96,7 @@ 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
@@ -106,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; " \
@@ -311,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,7 +156,7 @@ 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)   # => LLM::ModelResult (`.output`)
@@ -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`,

data/docs/cli.md

@@ -17,19 +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 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
 ```
@@ -179,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
@@ -204,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.
 
@@ -357,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
@@ -368,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
@@ -601,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.
@@ -724,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

@@ -105,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
@@ -188,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
 

data/docs/guardrails.md

@@ -51,11 +51,14 @@ sees these diffs.
 
 Who answers:
 
-- REPL (`chi --no-shared`, `-p` without `--non-interactive`): at the `? ` prompt.
-- A shared session's worker: any attached TUI or web page. With none attached,
+- REPL (`chi --no-shared`, with or without `-p`): at the `? ` prompt.
+- A shared session's worker (plain `chi` and `chi -p …` while `session.shared` is on, the default): any attached TUI or web page. With none attached,
   the approval waits (in the session file) and shows on attach.
 - `-p … --non-interactive`: nobody; the call is denied ("No one to approve it
   (non-interactive run)").
+- A parent agent running chi as a sub-agent (`chi send --wait` exits 3 with
+  the approval): `chi answer` may deny it, never allow it by default. See
+  [Approvals from a parent agent](#approvals-from-a-parent-agent).
 
 The model gets one line on a deny. A rule's or hook's deny reads
 `[execute] Error: denied by guardrail (rule git-push, bundle guardrails): git push publishes commits. The user was not asked. Do not retry it or reach the same result another way; ask the user how to proceed.`
@@ -79,6 +82,65 @@ with one warning, and chi starts with no stored approvals (more asks, nothing lo
 `/guardrails` lists the rules and approvals; `/guardrails revoke N` removes one.
 The file tools can't write the store.
 
+### Approvals from a parent agent
+
+When another agent (Claude Code, Codex, a script) runs chi with
+`chi send --wait`, an approval comes back to it as exit 3 with `kind:
+approval`, and `chi answer` answers it. A rule with `verdict: ask` means "ask
+me", so by default a parent may only deny: `--option Deny --text "why"`,
+`--text` alone, or `--dismiss`. An Allow is refused (exit 1, `allowing a tool
+call is up to the user: deny it (--option Deny --text WHY), and tell your
+user`). The question block chi prints for an approval says the same: its
+command is a deny, with no `--option N` and no `chi --attach`.
+
+```yaml
+guardrails:
+  parent_approvals: once    # default off
+```
+
+`once` lets `chi answer --option "Allow once"` through, picked by the
+option's scope, not its label; the wider scopes (this session, this repo or
+directory, the rule) stay with the web and the terminal. An approval that
+doesn't offer "once" can't be allowed from a parent, and neither can one whose
+offered scopes are missing or don't fit its options: then only Deny goes.
+
+Whatever the setting, a parent can't allow a call on chi's own files: a
+`write`, `edit` or `execute` on the config dir (config.yml, installed bundles'
+rules), the hooks dir or the approval store, by its rule (`chi-config`,
+`chi-hooks`, `shell-touches-chi`), its paths or its command. "Allow once" on a
+config.yml rewrite would allow everything from then on, so those stay with the
+user: `chi answer` and the worker refuse the allow with `only the user can
+allow it`.
+
+The guardrails settings (`enabled`, `small_models`, `parent_approvals`) are
+read from config.yml only: they have no environment variable, and a worker
+chi starts unsets every `SAMAGOTCHI_GUARDRAILS_*` it would inherit. What a
+parent's environment does choose is the config dir: `XDG_CONFIG_HOME` picks
+which config.yml chi reads, and a worker the parent starts or wakes (`chi
+send` to a stopped session) reads the one the parent's `XDG_CONFIG_HOME`
+points at. chi doesn't record the config dir per session.
+
+The worker checks it too. `chi answer` marks its answers as a parent's
+(`client_id: "cli:answer"`), and the worker's Bridge refuses such an allow
+beyond what the *worker's* config.yml permits (`403 parent_approval_refused`;
+`chi answer` exits 1 with the reason), checked against the question pending
+at that moment. Answers from the web and an attached terminal keep every
+scope.
+
+A parent may also type its answer into chi itself: a piped `chi --attach ID`
+or `printf '2\n' | chi --no-shared -p …`. So chi treats an answer as a
+parent's, held to the same setting, when its input isn't a terminal or an
+agent marker is set: `CLAUDECODE`, `AI_AGENT`, or `SAMAGOTCHI_PARENT_SESSION`,
+which chi's own `execute` and `task_create` export (the session's id) into the
+commands they run. The markers survive a PTY wrapper (`script`, `expect`). A
+person at a terminal with no marker keeps every scope.
+
+This guards an honest but eager parent, not a hostile one: it is not a
+security boundary. The worker's Bridge and the web's answer route on localhost
+take an answer from any local process, which can leave the marker out (or
+post through the web) and get every scope. chi's instructions for parents ([chi as a
+sub-agent](sub-agent.md)) tell them to use `chi answer` only.
+
 ## Protected paths
 
 Built in, for `write`, `edit` and `memory_write` (symlinks resolved):
@@ -93,7 +155,7 @@ commands that name them.
 
 ```yaml
 guardrails:
-  enabled: true              # false: no rules, and hooks' asks are dropped (a deny still applies)
+  enabled: true              # false: no rules, and hooks' asks are dropped (a deny still applies); config.yml only
   rules:
     - id: git-push
       tool: shell            # execute + task_create; or a tool name, a glob, or a list
@@ -134,7 +196,7 @@ 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:
+only that bundle's. A single id works without the list (`disable: git-rebase`):
 
 ```yaml
 guardrails:
@@ -178,7 +240,7 @@ vote for the current model `off for this model`.
 Rules are read again on the next tool call after `config.yml` or an installed
 bundle's rules change, so a long-running worker follows edits without a
 restart. A rule that doesn't parse (an unknown key, a bad regex, no
-verdict, a `disable:` that isn't a list of ids) makes chi **deny every tool call** and say why, rather than run
+verdict, a `disable:` that isn't an id or a list of ids) makes chi **deny every tool call** and say why, rather than run
 without it.
 
 ## The guardrails bundle
@@ -191,8 +253,12 @@ installs a default rule set plus a short memory telling the model not to
 route around a deny. It asks before `git push`, `reset --hard`, `clean -f`,
 `branch -D`, `rebase`, `filter-branch`/`filter-repo`; `rm -rf` on `/`, `~`,
 `$HOME` or `..` paths; `curl … | sh` and `base64 -d … | sh`; writes outside the
-repo; and shell commands that name chi's config, hooks or guardrails or
-`.git/hooks`. It denies writes into `.git/hooks`. The rules are in
+repo; shell commands that name chi's config, hooks or guardrails or
+`.git/hooks`; and answering chi's questions around `chi answer`: `chi --attach`
+or `chi -p` with stdin from a pipe, a here-string or a file
+(`chi-answer-piped`), and `curl`/`wget` to a session's `/answer` route
+(`chi-answer-http`), both once or for the session. `chi answer` itself isn't
+asked about. It denies writes into `.git/hooks`. The rules are in
 `lib/samagotchi/bundles/guardrails/guardrails/rules.yml`.
 
 Small models (`models: small`, see above) get two more asks, in