samagotchi 0.65.0 → 0.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43045b7872d6b50ba24cc2ef1678ac6708346aac9236a5764593660e4e81fc6f
-  data.tar.gz: dad96a9922329ea3294d7bf04159b3c829796bdfda03d42eef724bbee4a3e4e7
+  metadata.gz: 58f42be965113cdd1f5736f77b9a5be8e9fbd77088b4a2013f9b7e86ae7ceb12
+  data.tar.gz: a093f0921d62e84c9e6c34ac10482e57e9e041a5a9d21eda41a88052e819cda1
 SHA512:
-  metadata.gz: 4a35a44e9905f8c3411a656383c8a7f2493318732b959d526cdcbdc5dba90e71e874fe678057d3b060878dc5e4560398683790dade299258bd43cf541e0b62cf
-  data.tar.gz: 9dc56d9cd85b5c5f323315f99bc7c2f4e7580927966f41723a833db561dd5d6c0b3a8720c92ea32e1fafbb3b75e9eb0e93e57e9c4784e1a9983f95e7ac6f17c6
+  metadata.gz: d02e8644b724765182cabb9a74eafcfaec94eb13781680e29cc33bfb1ee2bc850f55a7df4117b61d8a2889c7d48bf4792b88ba316676a1fb6be5632cc98d1a3f
+  data.tar.gz: a4397b9a00729a4eb230415e265c834f85f42b8b6ded242dc3c981ad6f3e543f367d7a9df00ed6d516aef12c2e2266a765b0f66c7025f575975c83fd4b556b86

data/CHANGELOG.md

@@ -8,6 +8,110 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.67.0] - 2026-10-14
+
+### Added
+
+- **Desktop helper: agents in tmux panes**: with `tmux.enabled: true` (then `chi update`) the panel lists agent CLIs
+  running in tmux panes, in any terminal, beside kitty's, and pastes into them with or without Enter (a pane in copy
+  mode is taken out of it first). `tmux.binary` defaults to the tmux on chi's PATH when the launch file is written;
+  `chi update` warns when there is none. `ChiHelper --kitty` is now `--agents` (the helper's internal seam). See
+  docs/desktop.md, "Agents in kitty and tmux".
+- **Continue on another model**: `chi send --new --continues ID --model NAME` and the web API's `POST /api/sessions`
+  with `continues` and `model` start the next link of a chain on that model (its host checked first, nothing
+  archived on a refusal). See docs/sessions.md, "Session chains".
+- **Host API keys from the macOS Keychain**: with the variable a host's `api_key_env:` names unset, chi reads the key
+  from the login Keychain (service `chi`, account the variable's name), so the desktop helper's sessions and model
+  list, launchd and cron reach keyed hosts. Store a key with `security add-generic-password -s chi -a VAR -w`.
+  `chi self` says `VAR (keychain)`, `chi desktop status` has a `host keys` row, and install/upgrade warn about keys
+  the helper won't get. `SAMAGOTCHI_KEYCHAIN=off` turns it off. See docs/configuration.md, "API keys from the Keychain".
+- **The peer loop**: chi and a paired Claude Code or Codex session can go back and forth on a part. A peer's answer
+  wakes chi up to `context.peer_turns` (default 3) turns in a row, within `session.max_wakes`; chi fixes what it
+  flagged or replies with `claude_send`/`codex_send`; an answer whose verdict is `VERDICT OK` arrives as a note and
+  ends the round; only a message typed in the web or a TUI starts the count again (not `chi send`). The wake note
+  frames the answer as the peer's advice, within your task; every other source keeps its guard line. Plugins
+  declare a peer's source with `chi.peer_source`. See docs/context.md, "Peer sources: the peer loop".
+
+### Changed
+
+- **claude-peer 0.3.0 and codex-peer 0.2.0** join the peer loop and need chi 0.67.0 (`chi update`, then `chi bundle
+  upgrade claude-peer` / `codex-peer`, and `/claude install-skill` / `/codex install-skill` again for the peer's
+  side). Both are now built on `Samagotchi::Plugin::Peer`, one shared base; their texts are unchanged but for the
+  peer loop's.
+- `session.max_wakes` caps every wake turn in a row (delegate reports, attached context, peers); the docs said
+  delegate reports only.
+- **MCP: `find_mcp_tools` and `mcp_call` are now `find_tools` and `call_tool`**, chi's own tool index's (the mcp
+  bundle publishes its servers' tools into it: `chi.tool_source`, docs/plugins.md). Run `chi bundle upgrade mcp`
+  (mcp 0.7.0) to get it; an older mcp bundle keeps its own two tools on this chi. Search, calls, lazy starts and
+  `/mcp` work as before. Rename `tool: mcp_call` in guardrail rules and hooks, and `mcp_call` in loop-guard's or
+  check-in's `ignore_tools` in config.yml, to `call_tool`; rules on `mcp_*` keep working (they match the MCP
+  tool). Approvals saved for MCP tools (keyed `mcp_call>…`) no longer match: each MCP tool is asked about once
+  more. The two tools' new names and place in the tool list re-prefill an MCP user's prompt once.
+- A continue whose previous link's model names a host config.yml no longer has (or a disabled one) starts the new
+  link on the default model with a warning (`chi send: warning: …`, the API's `model_warning`) instead of being
+  refused.
+
+### Fixed
+
+- Web: a session opened (or switched to) shows its live worker's features at once: the queue link on the delivery
+  line, the task-stop button, Alt+Enter's queue and the stale-worker badge with Restart no longer wait for the
+  session's next change.
+- Web: a switch starts the open session's page state over: a "copied ✓" on the info bar no longer carries into the
+  next session, a Restart under way in one session no longer blocks Restart in another, and a worker woken after a
+  failed load streams from its start, not from the previous session's cursor.
+- Web: a send stays with the session it was sent from: switching sessions while its images upload no longer sends the
+  prompt into the other session, and an image whose send failed in one session is uploaded again when it is sent to
+  another (it was refused there as an unknown image).
+
+Update with `chi update` (it upgrades the bundles too): mcp 0.7.0, claude-peer 0.3.0, codex-peer 0.2.0 and the
+system bundle 0.67.0. Then restart `chi web` and run `chi desktop upgrade` for the tmux support.
+
+## [0.66.0] - 2026-10-14
+
+### Added
+
+- **Plugin annotation actions** (web): `chi.annotation(label, command:, template:, send:)` adds a pill to the
+  selection bar that prepares a command line of the plugin from the selected text (`{quote}`, `{text}`, `{source}`):
+  it fills the composer (an earlier draft stays under the quote), or with `send: true` sends at once. Up to 3 inline,
+  the rest behind `⋯`. See docs/plugins.md, `chi.annotation`.
+- claude-peer 0.2.0: **Confirm with Claude** in the web's selection bar fills `/claude validate` with the quote;
+  `/claude validate|context` titles a quote by its first quoted line, not its `From …:` label.
+- The codex-peer bundle (in the dev profile): claude-peer for an OpenAI Codex CLI session. Codex pairs (its
+  `chi-peer` skill, installed by `/codex install-skill`), the `codex_send` tool and `/codex validate|context|last`
+  send it a part of the work with `codex queue` (killed after 10 s, never a hang), and Codex's answer comes back as
+  the `codex-review` context; **Confirm with Codex** in the web's selection bar. Codex's sandbox needs chi's
+  context folder in `writable_roots` (the install card shows the line). See docs/plugins.md, "The codex-peer bundle".
+- **Toolkits**: a session's toolkit names the tools its prompts declare. chi ships `full` (every built-in, the
+  default), `lean` (the file, shell, memory, task, question, `web_fetch` and `context_read` tools: ~1.4k tokens
+  fewer) and `child` (`lean` with `send_note`, without `memory_write`); config's `toolkit.kits` and bundles
+  (`chi.toolkit`) add their own. Pick one with `toolkit.default` / `toolkit.child`, `chi --toolkit NAME` (with
+  `--tool` / `--no-tool`, also on `chi send --new`) or `/toolkit NAME | add TOOL | remove TOOL`. It is saved in the
+  session when it is created and kept by continues and forks; a change applies at the next turn's start. A left-out
+  tool is named in one prompt line, and a call to it is refused before the guardrails. The web shows a session not
+  on `full` as a `tools` chip. See docs/configuration.md, "Toolkits".
+- Plugins: `ctx.toolkit` and `ctx.use_toolkit(name)` (before the session's first reply). The coordinator bundle
+  (0.4.0) declares the `coordinator` toolkit (`lean` + `delegate`, `delegate_result`, `list_sessions`), and
+  `/coordinate` puts a fresh session on it.
+
+### Changed
+
+- A command's name may be followed by any whitespace, a newline too: `/foo` on its own line with text under it
+  runs `/foo` with that text, in the terminals and the web (before, only a space did).
+- Web: a command refused as busy mid-turn comes back into the composer (it was cleared when sent).
+- A delegate child is told to report what should change (a wrong memory or skill, instructions that led it astray)
+  in its reply instead of writing memories (`delegated.md`).
+
+### Fixed
+
+- `dialect: fireworks` hosts: the web's ctx meter no longer reads 0% while an answer streams (Fireworks' first stream
+  event carries all-zero usage; its counts come at the end).
+
+**Still open:** the Claude 5.x "bound to a different conversation" 400 on Anthropic Messages hosts (see 0.65.0); its
+recovery comes in a later release.
+
+Update with `chi update` (the system bundle moves with the gem; claude-peer 0.2.0, coordinator 0.4.0, and the dev
+profile 0.5.0 with the new codex-peer 0.1.0).
+
 ## [0.65.0] - 2026-10-13
 
 ### Added
@@ -2833,7 +2937,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.65.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.67.0...HEAD
+[0.67.0]: https://github.com/dm1try/samagotchi/compare/v0.66.0...v0.67.0
+[0.66.0]: https://github.com/dm1try/samagotchi/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/dm1try/samagotchi/compare/v0.64.0...v0.65.0
 [0.64.0]: https://github.com/dm1try/samagotchi/compare/v0.63.0...v0.64.0
 [0.63.0]: https://github.com/dm1try/samagotchi/compare/v0.62.0...v0.63.0

data/README.md

@@ -153,7 +153,8 @@ in a child session in its own git worktree, check each report and ask you
 before each merge; `/children` shows the children and their state. With the
 `claude-peer` bundle (in `dev`), chi sends a part of its work to a Claude Code
 session you pair it with, to validate or as context, and Claude answers back
-into chi (`/claude`).
+into chi (`/claude`); the `codex-peer` bundle (in `dev`) does the same with an
+OpenAI Codex CLI session (`/codex`).
 
 `chi send` is the other half: the text goes in as your message, the same as
 typing it in the attached terminal or the web composer, and a turn runs. Piped

data/bin/chi

@@ -82,7 +82,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -119,6 +119,12 @@ parser = OptionParser.new do |opts|
   opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "This session's own thinking level: off|low|medium|high|default (saved in the session, " \
                               "before the model's; default unsets it; /thinking changes it). With chi web: the default for the sessions " \
                               "its workers run, below a session's own [env SAMAGOTCHI_THINKING_LEVEL]") { |l| options[:thinking] = l }
+  opts.on("--toolkit NAME", "This session's toolkit, the tools its prompts declare: full|lean|child|a config or bundle one " \
+                           "(saved in the session; config toolkit.default; /toolkit changes it)") { |n| options[:toolkit] = n }
+  opts.on("--tool NAME", "Also declare this tool on top of the toolkit (repeatable; a comma list too)") { |t| (options[:tools] ||= []) << t }
+  # --no-tool is taken out of ARGV before parse! (OptionParser would read it
+  # as --tool's negation); this is its help line.
+  opts.separator "        --no-tool NAME               Leave this tool out of the toolkit (repeatable; a comma list too)"
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
   opts.on("--append-system-prompt FILE", "Put FILE's text into the system prompt, after AGENTS.md (repeatable; saved in the session; " \
                                         "config append_system_prompt: is the baseline)") { |f| (options[:append_system_prompt] ||= []) << f }
@@ -171,6 +177,34 @@ parser = OptionParser.new do |opts|
   opts.on("--version", "Print chi's version") { puts "chi #{Samagotchi::VERSION}"; exit }
   opts.on("-h", "--help", "Show help") { puts opts; exit }
 end
+# --no-tool NAME (or --no-tool=NAME), up to a "--". A flag that takes a
+# value (-p, --model …: the parser's own list) keeps its next word, so
+# `chi -p "--no-tool=x is broken"` is a prompt. A tool name never starts
+# with "-": `--no-tool --` or `--no-tool --model` is a missing argument.
+takes_value = parser.instance_variable_get(:@stack).flat_map do |list|
+  list.list.select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }.flat_map { |switch| switch.long + switch.short }
+end
+missing_no_tool = lambda do
+  warn "Error: missing argument: --no-tool (see chi --help)"
+  exit 1
+end
+index = 0
+while index < ARGV.size && ARGV[index] != "--"
+  arg = ARGV[index]
+  if arg == "--no-tool"
+    value = ARGV[index + 1]
+    missing_no_tool.call if value.nil? || value.start_with?("-")
+    (options[:no_tools] ||= []) << ARGV.delete_at(index + 1)
+    ARGV.delete_at(index)
+  elsif arg.start_with?("--no-tool=")
+    value = arg.delete_prefix("--no-tool=")
+    missing_no_tool.call if value.empty? || value.start_with?("-")
+    options[:no_tools] = (options[:no_tools] || []) << value
+    ARGV.delete_at(index)
+  else
+    index += takes_value.include?(arg) ? 2 : 1
+  end
+end
 begin
   parser.parse!
 rescue OptionParser::ParseError => e
@@ -327,6 +361,17 @@ if options[:append_system_prompt]
   end.uniq
 end
 
+# --toolkit/--tool/--no-tool: a new session's toolkit, as named (the
+# worker resolves it; a bundle's toolkit isn't known here).
+if options[:toolkit] || options[:tools] || options[:no_tools]
+  require "samagotchi/toolkit"
+  # The flags as given, for the line an existing session's run prints.
+  options[:toolkit_flags] = [("--toolkit" if options[:toolkit]), ("--tool" if options[:tools]),
+                             ("--no-tool" if options[:no_tools])].compact
+  options[:toolkit_value] = Samagotchi::Toolkit.from_flags(name: options[:toolkit], add: options[:tools],
+                                                           remove: options[:no_tools])
+end
+
 chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
@@ -361,7 +406,9 @@ if launch == :attached
                                                        muted_memories: options[:muted] || [],
                                                        llm_context: options[:llm_context] || {},
                                                        thinking: options[:thinking],
-                                                       appended_prompt_files: options[:appended_prompt_files] || [])
+                                                       appended_prompt_files: options[:appended_prompt_files] || [],
+                                                       toolkit: options[:toolkit_value],
+                                                       toolkit_flags: options[:toolkit_flags] || [])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -381,6 +428,8 @@ begin
     llm_context: options[:llm_context] || {},
     thinking: options[:thinking],
     appended_prompt_files: options[:appended_prompt_files] || [],
+    toolkit: options[:toolkit_value],
+    toolkit_flags: options[:toolkit_flags] || [],
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

data/docs/architecture.md

@@ -45,7 +45,7 @@ A compact visual overview of the current architecture, then the core API in pros
   │  task_create/get/list/stop/wait · delegate · delegate_result · ask_user_question │
   │  register_reminder/cancel_reminder/list_reminders · send_note · list_sessions ·  │
   │  context_read · forget_outputs (+ bundle plugin tools)                           │
-  │  declared via tool_declarations.rb                                               │
+  │  offered by Tools::Registry (Builtins + bundles), filtered by the toolkit        │
   └──────────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
@@ -83,10 +83,10 @@ TerminalUI  ──  delegates  ──▶  Engine
 ## Request / turn flow
 
 ```
-bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop ──┬─▶ Model API (LLM)
-        (builds)          │                            └─▶ Tool call(s) ─▶ Tool
-                          │                                 │
-                          └── on_event: ─▶ render update ────┘
+bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop / ChatLoop ──┬─▶ Model API (LLM)
+        (builds)          │                                         └─▶ Tool call(s) ─▶ Tool
+                          │                                              │
+                          └── on_event: ─▶ render update ────────────────┘
                                     (turn started / completed / canceled)
 ```
 
@@ -99,12 +99,12 @@ terminal renders the events it gets over the Bridge.
 |-------|-----------|----------------|
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, model↔tool loop (`run_turn`). No terminal coupling. |
 | UI | `Samagotchi::TerminalUI` | REPL (Reline), rendering, REPL commands. Delegates all core work to an `Engine`. |
-| Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt or OpenAI chat API, chosen per host (see below). |
+| Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt, or a chat API (OpenAI chat, Anthropic Messages), chosen per host (see below). |
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, Anthropic's Messages API, and the HTTP they share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, forget_outputs, plus runtime/output-guardrails. |
 | Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way merge), build, uninstall; the install record under `.bundles/<name>/` that the hook, guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
 | Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` forks/spawns one worker process per session; its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
-| Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick single-port `127.0.0.1:4567` (index.html + `/api/*` + SSE). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
+| Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick on one port, `127.0.0.1:4567` (index.html + `/api/*` + SSE); with `web.host: lan` also on this machine's LAN address, behind an access token (`Web::Lan`, `Web::Token`). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File `sessions/<uuid>.json` + sidecar `input/`/`output/`; retention 14d/500, `updated_at desc`, lazy sweep. |
 
 ## Entry points
@@ -122,7 +122,8 @@ terminal renders the events it gets over the Bridge.
   as a client of its Bridge (`BridgeClient#follow`, `post_turn`, `post_command`, `cancel`, `answer`,
   `dismiss_question`). The worker runs in the session's `working_directory`, so `!cmd` and
   the tools don't depend on where the terminal attached from.
-- `bin/chi web` → builds `Web::Server` (Rack+WEBrick on `127.0.0.1:4567`, `--port`/`SAMAGOTCHI_WEB_PORT`, `--open`).
+- `bin/chi web` → builds `Web::Server` (Rack+WEBrick on `127.0.0.1:4567`, `--port`/`SAMAGOTCHI_WEB_PORT`, `--open`;
+  `web.host: lan` adds a LAN address, `--new-token` replaces its access token).
 - `bin/chi sessions {list,stop,restart,archive,unarchive,delete,prune,clean,stats}` (`SessionsCommand`; not the REPL's `SessionCommands`) → retention & ordering (`SessionRetention`, `updated_at desc`, dry-run, test-only); `stop` is `SessionManager.stop_session(wait:)`, which waits for the worker to release `owner.lock`; `delete` (`SessionDeleteCommand`) is `SessionManager.delete_session(stop:)`, which the TUI's `/exit --delete` and the web's `DELETE /api/sessions/:id` use too.
 - In REPL mode `TerminalUI` builds the `Engine` in process (`-p` and `--non-interactive` too);
   otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
@@ -132,7 +133,7 @@ terminal renders the events it gets over the Bridge.
 - **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. 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), manual via `bin/chi sessions prune --dry-run`.
+- **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner guard, only when `*.json` present; lazy sweep at most once per `session.sweep_interval_hours` (default 24) from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls), 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`.
 
@@ -145,9 +146,9 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 |-------|-------|----------------|
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, the model↔tool loop (`run_turn`). No terminal coupling. |
 | UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
-| Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
+| Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
 | Bridge (SSE/HTTP) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, no auth, localhost-only). |
-| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. `bin/chi web` entrypoint. |
+| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request but this machine's needs the access token (`App#token_gate`: the `chi_token` cookie or `Authorization: Bearer`; [CLI](cli.md#chi-web-on-your-phone)). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. `bin/chi web` entrypoint. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File-based `~/.local/state/samagotchi/sessions/<uuid>.json` + sidecar `input/`/`output/`; retention (14d/500) + ordering (`updated_at desc`). |
 
 - `bin/chi` in REPL mode (see `LaunchMode` above) builds `TerminalUI`. `TerminalUI#run` is the single
@@ -199,21 +200,24 @@ renders whatever it needs from the stream + final `Result`. The public Engine AP
 ```ruby
 engine.run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, # nil: turn.max_iterations
                 max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
-                images: [], id: nil)
+                images: [], id: nil, resumed: false, resume_from: nil)   # resumed/resume_from: a step-limit Continue
 engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
 
-The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance, the
-identity and the preloaded memories, AGENTS.md, the memory indexes, and last **the
-model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
+The system prompt (`SystemPrompt#build`, assembled in `#system_prompt_with_index`) is the
+base prompt, then the toolkit's "Not loaded in this session" line (only when the toolkit
+leaves tools out), rg guidance, the identity, the model notes, the preloaded memories,
+AGENTS.md (root → cwd), the appended files (`--append-system-prompt`), the memory
+indexes, and last **the model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
 the model to answer "which model are you" from it, not from training), the working
 directory and the session id and log (Gemma's native tool declarations still follow).
 The order is for the servers' prompt caches, which reuse only an exact token prefix:
 what every session shares first, what changes least before what changes more, the
 per-session lines last, so a new session reuses everything above them. It is built
-once per loop and rebuilt only by a model switch (or changed tools), so the model
-line costs no KV churn.
+once per loop and thinking level and rebuilt only by a model switch, changed tools or a
+toolkit change (`Engine#apply_toolkit!`, at a turn's start), so the model line costs no
+KV churn.
 The full request layout, what breaks the cache and the rules for changes:
 [internals/prompt-caching.md](internals/prompt-caching.md).
 
@@ -272,7 +276,8 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
 - `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
   (`TaskRuntime.stop_task by: "user"`, the web's stop-task button on a running `task_wait`;
   web route `POST /api/sessions/:id/tasks/:task_id/stop`). Only a task this conversation's
-  `task_create` started (the saved messages, or the running turn's accumulator); answers once the
+  `task_create` started, or an `execute` handed over as a task at its limit (`TaskRuntime.created_ids_in` on the
+  saved messages, or the running turn's accumulator); answers once the
   task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
   The worker names it in its sidecar features (`task_stop`).
 - `POST /session/:id/relay` — the approval relay, on a delegated child's worker
@@ -307,7 +312,10 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   actions: its turn no longer runs), `event_seq`, `event_id`, all taken in one event-log hold; no message
   list, so it costs the same however long the session is. `?turn_id=` answers that turn's answer
   (an unknown or missing id: the newest); the only route that reads its query.
-- `OPTIONS *` — CORS preflight (`Access-Control-Allow-Origin: *`).
+- No browser: only chi's own clients talk to a Bridge. A request with an `Origin` header, a `Sec-Fetch-Site`
+  other than `none`, or a `Host` that isn't loopback (a DNS-rebound page) is `403 cross_origin`
+  (`Bridge#browser_request?`, before any route); there is no CORS and no `OPTIONS` route. The browser reaches a
+  worker only through `chi web`.
 
 The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` frames
 (`SessionMetrics#snapshot`) carry the session's totals and only the recent timing records: the
@@ -438,7 +446,7 @@ attached TUI get a fresh number each time), and on a rise past the second
 threshold puts the model's own `[CONTEXT: …]` line on the tail as a system
 message (docs/internals/context-telemetry.md).
 
-**Adapters.** `Client` (raw-prompt servers) and `LLM::OpenAIChat` (one per host,
+**Adapters.** `Client` (raw-prompt servers), `LLM::OpenAIChat` and `LLM::AnthropicMessages` (one per host,
 `HostRegistry#adapter_for`, built by `LLM::Adapters` from the host's api) share
 `LLM::HTTP`: timeouts, TLS for https, a line reader for streamed bodies, the retry loop (`retry.*`; network errors, 429 and
 500/502/503/504/529, honouring `Retry-After`; never after a stream has produced
@@ -459,7 +467,10 @@ of chi reads (the prompt is input + cache reads + cache writes), stop reasons to
 (`max_tokens` → `length`, `tool_use` → `tool_calls`, `end_turn` → `stop`). A stream is read by content-block index
 from the `data:` lines alone (`event:` lines are not needed); `message_start` / `message_delta` events reach
 `on_delta` with that normalized `usage`, pings not at all, and a block's start or delta counts as shown for the
-first-token limit. Both adapters share their model-list cache (`LLM::ModelListing`).
+first-token limit. Both adapters share their model-list cache (`LLM::ModelListing`) and their HTTP plumbing
+(`LLM::AdapterCommon`: timeouts, the paged model list, the SSE line loop, JSON errors). A host's `dialect:`
+(`LLM::Dialect`, `fireworks`) changes the auth header, the thinking `display`, the cache breakpoints and a session
+header; [internals/anthropic.md](internals/anthropic.md) covers the adapter.
 
 **Errors.** A failed request raises an `LLM::ProviderError` of one kind:
 `ConnectionError` (`RetryExhausted`), `RateLimited` (`CreditsHeld`: a 402 about
@@ -474,9 +485,10 @@ stream events (server counts, else a chars/4 estimate). Model lists are `LLM::Mo
 (`HostRegistry#list_all_models`); the context window comes from the running
 server (`/props`), then the host's model list, then config.
 
-**Keys.** A host's API key comes only from the environment variable its
-`api_key_env:` names; it never reaches config.yml, `SAMAGOTCHI_HOSTS_JSON`, `chi self`,
-logs or events.
+**Keys.** A host's API key comes from the environment variable its
+`api_key_env:` names, else, on macOS, the login Keychain's item for that name (`HostKeys`, read through
+`/usr/bin/security` with a deadline; hits cached per process; `SAMAGOTCHI_KEYCHAIN=off` skips it); it never
+reaches config.yml, `SAMAGOTCHI_HOSTS_JSON`, `chi self`, logs or events.
 
 ## Other components
 
@@ -487,16 +499,26 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
-| Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, hooks, services ([plugins.md](plugins.md)). |
+| Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources ([plugins.md](plugins.md)). |
+| Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
-| Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb` | Hook registration and dispatch ([hooks.md](hooks.md)). |
+| Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb`, `hook_routes.rb` (`HookRoutes`) | Hook registration and dispatch; what a hook or plugin does beyond reading its event (notice, question, stop, steer) routed to the UIs ([hooks.md](hooks.md)). |
 | Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/rules.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing, YAML rules, approvals ([guardrails.md](guardrails.md)). |
 | Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `relay_desk.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
 | send / broadcast | `send_command.rb` (`SendCommand`), `broadcast_command.rb` (`BroadcastCommand`), `broadcast/` | `chi send` and `chi broadcast` ([broadcast.md](broadcast.md), [sub-agent.md](sub-agent.md)). |
 | Idle work | `idle_scheduler.rb` (`IdleScheduler`), `idle_recap.rb` (`IdleRecap`), `idle_reminders.rb` | One poller for an idle session's recap and reminders. |
-| Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb` | External sources a session keeps fresh ([context.md](context.md)). |
+| Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. |
 | Analytics | `analytics_file.rb` (`AnalyticsFile`) | A session's `analytics.json` (`SessionMetrics#persist`). |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
-| Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). |
+| Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
+| Steer delivery | `steer.rb` (`Steer`), `delivery.rb` (`Delivery`), `steer_cut.rb` (`SteerCut`), `generation_phase.rb`, `waiting_steer.rb`, `steer_cut_after.rb` (`SteerCutAfter`), `cut_policy.rb` (`CutPolicy`) | A message for a running turn: at the next boundary, cutting a thinking-only generation, or queued for the turn's end ([internals/engine.md](internals/engine.md)). |
+| Prompt files | `prompt_files.rb` (`PromptFiles`) | The AGENTS.md chain (root → cwd) and the appended files the system prompt carries. |
+| Model settings | `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | A model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |
+| Dialects | `llm/dialect.rb` (`LLM::Dialect`) | What an `api: anthropic` provider's `/v1/messages` does differently (`dialect: fireworks`) ([internals/anthropic.md](internals/anthropic.md)). |
+| Logging | `log.rb` (`Log`), `log_subscriber.rb` (`LogSubscriber`), `log_path.rb` (`LogPath`), `log_line.rb` | The debug log: tagged records, a session's event trail, where the file goes ([configuration.md](configuration.md#debug-log-file)). |
+| Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |
+| Setup and update | `bootstrap_command.rb`, `bootstrap/`, `update_command.rb`, `gem_update.rb` | `chi bootstrap` (first config.yml, system bundle, core profile) and `chi update` (the gem, shipped bundles, the macOS helper). |
+| Process groups | `process_group.rb` (`ProcessGroup`) | A command in a process group of its own, stopped as a group (TERM, grace, KILL): execute, tasks, context fetches, the mcp bundle's servers. |
+| Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb`, `desktop/macos/*.swift` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). The helper's Swift side: the panel (`Panel.swift`), the chi CLI runner (`ChiRunner.swift`), agent terminals behind `AgentTerminal` (`AgentTerminal.swift`, `Kitty.swift`, `Tmux.swift`; `ChiHelper --agents` is their CLI seam). |

data/docs/cli.md

@@ -44,7 +44,9 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   at once.
 - **The key.** A server that answers 401/403 wants an API key: `--key-env VAR`
   names the environment variable holding it (on a terminal chi asks for the
-  name). Only the variable's name is written, never the key.
+  name); on macOS a key only the login Keychain holds under that name counts
+  (docs/configuration.md, "API keys from the Keychain"). Only the variable's
+  name is written, never the key.
 - **The model.** One model is taken; with several, `--model ID` picks one
   (a terminal gets a numbered list, a script the ids and exit 2). A llama.cpp
   server also shows its context size and the prompt profile its chat template
@@ -187,6 +189,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
+| `--toolkit NAME`, `--tool NAME`, `--no-tool NAME` | A new session's toolkit, the tools its prompts declare: `full` (every built-in), `lean`, `child`, one of config's `toolkit.kits` or a bundle's (without `--toolkit`: config's `toolkit.default`), with tools declared on top of it (`--tool`) or left out (`--no-tool`); both repeatable, a comma list too. Saved in the session as given; a respawned worker, a fork and a continue keep it. Ignored with `--attach`/`--resume` (one line, as `--memory`); `/toolkit` changes it. Not on `chi web` (config's `toolkit.default` covers its sessions). See [Toolkits](configuration.md#toolkits). |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
@@ -513,7 +516,16 @@ reasoning of the turn it continues. `/stats` shows it on its `reasoning history:
 line, the web as the `reasoning` chip. See "Reasoning history" in
 [configuration.md](configuration.md).
 
-A `/thinking` or `/reasoning-history` change that restarts the prompt cache
+`/toolkit` lists the tools the next turn declares (each with its estimated
+tokens), the session's toolkit and the tools it leaves out. `/toolkit NAME` puts
+the session on another toolkit (dropping its own adds and removes); `/toolkit
+add TOOL` and `/toolkit remove TOOL` change one tool (a tool's name keeps its
+case). The change is saved at once and applies from the next turn's start; a
+running turn keeps its tools. `/toolkit` alone answers mid-turn too; a change
+sent while a turn runs waits for the turn's end. The web shows a session that
+isn't on `full` as the `tools` chip. See [Toolkits](configuration.md#toolkits).
+
+A `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
 that applies it (`/thinking low --yes`). `--yes` (or `-y`) applies it at once.
 The terminal puts that line in the next input (Enter applies it); the web's