samagotchi 0.65.0 → 0.66.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43045b7872d6b50ba24cc2ef1678ac6708346aac9236a5764593660e4e81fc6f
-  data.tar.gz: dad96a9922329ea3294d7bf04159b3c829796bdfda03d42eef724bbee4a3e4e7
+  metadata.gz: 0f78cadf95c501357ce71b15b672dee0a4558016b995a1948532924168580f86
+  data.tar.gz: 583f9594eed0ed2febe41390e9c2e0dfbfbde2df72c92f6eab5d8d6a3cf8d776
 SHA512:
-  metadata.gz: 4a35a44e9905f8c3411a656383c8a7f2493318732b959d526cdcbdc5dba90e71e874fe678057d3b060878dc5e4560398683790dade299258bd43cf541e0b62cf
-  data.tar.gz: 9dc56d9cd85b5c5f323315f99bc7c2f4e7580927966f41723a833db561dd5d6c0b3a8720c92ea32e1fafbb3b75e9eb0e93e57e9c4784e1a9983f95e7ac6f17c6
+  metadata.gz: 312f72d24bbfc6543d0899f164e69798d068916cef8728242d54893a783c3da7efceb2cbbfeac0337790596984af221e78f5c98541a910945266a2a1122e6ef7
+  data.tar.gz: 347d52314752545c6fbc37e7b1a7186faadb6fa2170f91e00b35b8101c76ed9b0ee80b8b954ea927382583c97511dae2fd0a6eca28b694778657f1b654c81226

data/CHANGELOG.md

@@ -8,6 +8,52 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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 +2879,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.65.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.66.0...HEAD
+[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/cli.md

@@ -187,6 +187,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 +514,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

data/docs/configuration.md

@@ -319,11 +319,11 @@ hosts:
 
 `auth:` works on any host (`bearer` is the default everywhere but `api: anthropic`).
 
-**Known limit (until the next release):** Claude 5.x models (Opus, Sonnet and Haiku 5.5, Fable 5.1) bind each
+**Known limit (until a later release):** Claude 5.x models (Opus, Sonnet and Haiku 5.5, Fable 5.1) bind each
 thinking block to the request it came from. When the history before a block changes (the system prompt rebuilt after a
 worker restart or a `/model` switch, a changed tool set, the forget layer's edits), such a model may answer HTTP 400
 "… bound to a different conversation" and the turn fails with that error; `/reasoning-history turn` makes it rarer.
-The next release sends Anthropic's binding controls and recovers from that 400. Fireworks, Splash and other
+A later release sends Anthropic's binding controls and recovers from that 400. Fireworks, Splash and other
 non-Claude models are not affected.
 
 The loop, tools, events, hooks and UIs are the chat loop's, as for `api: openai`; only the wire differs: the
@@ -739,10 +739,10 @@ models:
 
 ## Changes that restart the prompt cache
 
-`/thinking` and `/reasoning-history` ask before a change that makes the server read the conversation again: Gemma's
-thinking switch, a remote chat host's thinking fields ("Thinking"), and a change to or from `all` once an earlier reply
-has thinking ("Reasoning history"). They ask only when the level the next turn runs under really changes and the
-session has a model reply.
+`/thinking`, `/reasoning-history` and `/toolkit` ask before a change that makes the server read the conversation again:
+Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a change to or from `all` once an earlier
+reply has thinking ("Reasoning history"), and any change to the declared tools, which start every request
+("Toolkits"). They ask only when what the next turn runs under really changes and the session has a model reply.
 
 - The reply says what it costs and changes nothing yet: `Nothing changed yet: send /thinking low --yes to apply.`
 - `--yes` (or `-y`, anywhere after the command) applies it at once.
@@ -1276,6 +1276,48 @@ work tree top when inside it, else with `~`.
   picked up by a new process or a rebuild (`/model`). `/stats` lists the files
   in the prompt on its `prompt files:` line.
 
+## Toolkits
+
+A session's **toolkit** names the tools its prompts declare. The declared tools are the front of every request (the
+`tools` field, or the native template's declarations), so a session that declares fewer sends a shorter prompt, and
+sessions on the same toolkit share that prefix in a prompt cache.
+
+```yaml
+toolkit:
+  default: lean        # the sessions you start (unset: full)
+  child: child         # delegate children (unset: full)
+  kits:                # your own, on a base
+    review: { base: lean, add: [web_fetch, delegate], remove: [memory_write] }
+```
+
+| toolkit | declares |
+|---|---|
+| `full` | every built-in; the default |
+| `lean` | `execute`, `read`, `write`, `edit`, `memory_read`, `memory_write`, `task_create`, `task_wait`, `task_get`, `task_list`, `task_stop`, `ask_user_question`, `web_fetch`, `context_read` |
+| `child` | `lean` plus `send_note`, without `memory_write` |
+| `coordinator` | `lean` plus `delegate`, `delegate_result`, `list_sessions` (declared by the coordinator bundle) |
+
+- **Plugin tools** are declared in every toolkit unless its `remove:` names them, and so is `forget_outputs` under
+  the `forget` layer. A `kits:` entry takes `base:` (default `full`), `add:` and `remove:`; it can't reuse a
+  built-in's name. A bundle declares its own with `chi.toolkit` ([plugins](plugins.md#chitoolkitname-base-add--remove-)).
+- **Saved at creation, never re-resolved from config.** A session stores its toolkit as named
+  (`"toolkit": {"name": "lean", "add": [], "remove": []}`) when it is created: `toolkit.default`, `toolkit.child`
+  for a delegate child, or `chi --toolkit NAME` / `--tool` / `--no-tool` ([cli](cli.md)). Changing `toolkit.default`
+  doesn't move existing sessions, not even when their worker is woken again; a session from before toolkits is on
+  `full`. A continue and a fork keep the toolkit. `/toolkit` shows and changes it.
+- **Not loaded.** When a toolkit leaves tools out, one line after the base prompt names them (`Not loaded in this
+  session (toolkit lean): …. Only the user can load one (/toolkit add <name>).`). A call to one is refused before
+  the guardrails (no approval card): `Error: delegate isn't loaded in this session (toolkit lean) …`.
+- **Applied at a turn's start.** A change (`/toolkit`, a plugin's `ctx.use_toolkit`) is saved at once and the next
+  turn declares it; once the session has a model reply, `/toolkit` asks first ("Changes that restart the prompt
+  cache").
+- **A name that doesn't resolve** (a typo, a bundle that was uninstalled) declares every tool for that process,
+  with one `toolkit>` warning at the first turn; the saved name stays, so the bundle's return brings it back.
+- **Versions.** A toolkit's definition can change with chi or a bundle, which changes what saved sessions on it
+  declare after an upgrade: the next request reads the prompt again once, as a tool's schema change does. So can
+  an edit to `toolkit.kits`: a session's worker reads the kits once when it starts, so a running session keeps its
+  tools and the edit reaches it at its next worker start (after an idle exit, `chi sessions restart`).
+
 ## LLM context: the forget layer
 
 Experimental, off by default. With `forget` in a model's `llm_context.strategy` (next to `stale`), chi offers that
@@ -1415,7 +1457,7 @@ Every setting below takes the three forms described in
 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:`,
-`append_system_prompt:`) are described in their own sections.
+`append_system_prompt:`, `toolkit.kits`) are described in their own sections.
 
 | Setting | Default | CLI | What it does |
 |---|---|---|---|
@@ -1483,6 +1525,8 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `context.status_thresholds` | `20,40,60,80` | yes | Percentages that put the estimate into a bucket; the rise into a guidance bucket (from the second up) leaves the model its own `[CONTEXT: …]` line, and the bucket decides the guidance. |
 | `context.every_seconds` | `300` | | How often an attached context source's command runs when it has no `--every` (seconds, at least 30). See [Attached context](context.md). |
 | `context.wake` | `true` | yes | A source whose update says `wake: true` may start a turn in a live, idle session (one per source per 10 minutes, within `session.max_wakes`); so may a session's pushed source's first push. `false`: updates wait as notes for the next turn. See [Waking](context.md#waking). |
+| `toolkit.default` | `full` | | The toolkit a new session is stored on: the tools its prompts declare (`full`, `lean`, `child`, one of `toolkit.kits` or a bundle's). `chi --toolkit` picks one per session. See "Toolkits". |
+| `toolkit.child` | `full` | | A delegate child's toolkit. See "Toolkits". |
 | `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |
 | `reasoning_history` | `turn` | | Which of its reasoning a chat host's model gets back: `drop`, `turn`, `all`; environment only (`SAMAGOTCHI_REASONING_HISTORY`), below a session's own level (`/reasoning-history`), above the `models:`/`hosts:` entries. See "Reasoning history". |
 | `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't; a session's own level outranks them all, and `--thinking` sets it on a session run (on `chi web` it sets this). See "Thinking". |

data/docs/context.md

@@ -126,7 +126,10 @@ pbpaste | chi context push clip --project
 A Claude Code session can be a pushed source too: the
 [claude-peer bundle](plugins.md#the-claude-peer-bundle)'s `pair` script attaches
 `claude-inbox` (Claude's inbox socket as the hint) and `claude-review`, where
-Claude pushes its answers as JSON with `wake: true`.
+Claude pushes its answers as JSON with `wake: true`. The
+[codex-peer bundle](plugins.md#the-codex-peer-bundle)'s does the same for a
+Codex session: `codex-inbox` (Codex's thread id as the hint) and
+`codex-review`.
 
 ### A stream: chat, a log, a feed
 

data/docs/internals/engine.md

@@ -35,7 +35,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
   │     # refresh_profile! (may ask the server's /props once)
   │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate)
-  │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools
+  │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools,
+  │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, a prompt rebuild when it changed)
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
   │     #   (a frozen copy of the history, the prompt, and resumed)
   │     # turn_messages: system head + history + due reminders (:reminder_injected) + the user message
@@ -227,6 +228,8 @@ One iteration with tool calls:
       → :tool_dispatch_started {iteration, call_count}
       → for each call: ToolRunner#run(call, iteration:, call_index:, call_count:,
                                       on_stream_event:, max_tool_output_chars:)
+          → a tool the session's toolkit leaves out (Registry#left_out) skips the gate: no hooks, no card;
+            KernelLoop#dispatch answers it with the not-loaded error
           → Guardrails::Gate#evaluate (the before_tool_call hooks, then the core checks)
           → :tool_call_started
           → an ask verdict: Gate#settle_ask (asks the user, records waited_ms)

data/docs/internals/prompt-caching.md

@@ -22,11 +22,13 @@ right-hand column happens.
 ```
  shared by every session ──────────────────────────────────────────────────  breaks it
 ┌──────────────────────────────────────────────────────────────────────────┐
-│ tools        built-ins, then plugin tools sorted by (bundle, name)       │  a tool added/changed,
-│              (chat: the `tools` field; native: the model's template)     │  /model, a profile change
+│ tools        built-ins, then plugin tools sorted by (bundle, name),      │  a tool added/changed,
+│              those the session's toolkit declares (per toolkit)          │  /model, a profile change,
+│              (chat: the `tools` field; native: the model's template)     │  a toolkit change
 ├──────────────────────────────────────────────────────────────────────────┤
 │ SYSTEM, stable part                         SystemPrompt#system_prompt_with_index
 │   [native thinking token] base prompt                                    │
+│   not-loaded line (only when the toolkit leaves tools out)               │
 │   rg guidance                                                            │  /thinking level,
 │   system identity (+ model overlay)                                      │  /model, editing a
 │   model notes (model_notes_* matching the model)                         │  memory / AGENTS.md
@@ -57,6 +59,12 @@ right-hand column happens.
 - The system prompt is built **once per loop** and rebuilt only on `@prompt_builder.reset!`: a model switch
   (`Engine#switch_model!`), a plugin's `tools_changed!`, or a profile change. A per-turn rebuild would
   break everything below it.
+- The tools layer is shared **per toolkit** (configuration.md, "Toolkits"): sessions on the same toolkit share it,
+  and a chain's links keep theirs. A session's toolkit is saved when it is created and never resolved again from
+  config. A change (`/toolkit`, `ctx.use_toolkit`) is applied only at a turn's start (`Engine#apply_toolkit!`,
+  beside `apply_staged_tools!`, then `reset!`): the chat loop builds `tools:` per request, so a mid-turn change
+  would differ from the turn's prompt. Under `full` nothing is filtered and no line is added: the bytes are what
+  they were before toolkits.
 - On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
   breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint
   #2, so the **next request in the session** reads everything up to it. Mid and tail system messages never take

data/docs/memory.md

@@ -270,7 +270,7 @@ profiles, meta bundles that install a set of them:
 | profile | bundles |
 |---|---|
 | `core` | loop-guard, check-in, guardrails, slow-commands, agents-md: the recommended safety set |
-| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer |
+| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing
 install gets neither by itself: `chi bundle install core` (or `dev`).

data/docs/plugins.md

@@ -92,10 +92,14 @@ A line that is not a known command keeps its old meaning: in the terminal
 UIs `/foo` goes to the model as a prompt; the web refuses it and names the
 commands it knows.
 
+Any whitespace may follow the name, a newline too: `/hello` on its own line
+with text under it runs `/hello` with that text as `args` (its inner lines,
+blank lines and indentation as typed; only the ends are stripped).
+
 #### `anytime: true`
 
 A plugin's normal command waits for its turn: typed while a turn runs, it is
-refused as busy (the REPL puts it back into the prompt; a plugin command can't
+refused as busy (the REPL puts it back into the prompt, the web into an empty composer; a plugin command can't
 ask to run after the turn, as the built-in `/model X` does). An `anytime: true` command
 runs **at once, on its own thread, beside the running turn**, and the turn
 goes on:
@@ -144,6 +148,54 @@ chi's own, each bundle's with the bundle's name, and the terminal UIs' own
 `attached only`, `repl only`, or `terminal and web only` (`/cut`).
 It works in all three UIs.
 
+### `chi.annotation(label, command:, template: "{quote}", send: false)`
+
+This adds a pill to the web's selection bar. Selecting text in an answer, a
+thinking block, a step, a tool row or your own message shows
+`[ Annotate | <presets> ┊ <plugin pills> ]`; a plugin pill prepares a command
+line of the plugin from the selection:
+
+```ruby
+chi.command "/claude", "…", anytime: true do |args, ctx| … end
+chi.annotation "Confirm with Claude", command: "/claude validate"
+```
+
+Clicking it on a thinking line fills the composer with
+
+```
+/claude validate
+From your thinking:
+> the quoted line
+
+```
+
+and the caret goes under the quote, for your note; Send runs `/claude` with
+everything after the name as `args`.
+
+- `label`: the pill's text, 1–40 characters. Its tooltip adds the bundle.
+- `command:`: `/name` or `/name words`, and `/name` must be a command **this
+  plugin** registers (checked once `register` returns, so the order of the
+  calls doesn't matter; another one's is a load error). At most 5 per plugin.
+- `template:` goes on the lines under the command line, filled in the
+  browser: `{quote}` the labelled quote block Annotate makes, `{text}` the
+  selection alone, `{source}` where it came from (`answer`, `thinking`,
+  `step`, `tool`, `user`). Another `{x}` stays as written. Each line's
+  trailing blanks and the blank lines at either end are dropped, and
+  indentation is kept (code stays indented).
+- **Fill** (the default) never sends: an empty composer gets the line; a
+  composer that already starts with the same command line gets the quote
+  appended (several selections collect under one command); any other draft
+  stays, under the command line and the quote.
+- `send: true` sends the line at once (the pill is marked ↗). While a turn
+  runs, such a pill is disabled unless its command is `anytime`: it would
+  come back busy. A fill pill always works; a typed command refused as busy
+  comes back into the composer.
+
+Pills ride on their command's listing (the worker's snapshot): a muted
+bundle's go with its command, and a session's pills need a worker started
+after the bundle was installed. Up to 3 show inline, the rest behind `⋯`.
+Web only: the terminals type the command (`/claude validate <text>`).
+
 ### `chi.tool(name, description, params:, schema:, label:, preview:, targets:, refs:) { |args, ctx| … }`
 
 This adds a tool the model can call. It is declared in the system prompt and
@@ -512,6 +564,21 @@ end
 - Each task runs once per session start. A `-p … --non-interactive` run
   starts them with its turn and shows nothing but the answer.
 
+### `chi.toolkit(name, base:, add: [], remove: [])`
+
+A toolkit sessions can be put on: `base`'s tools (`full`, `lean`, `child`, a
+config or bundle toolkit) with `add` declared and `remove` left out. Users pick
+it like chi's own (`chi --toolkit NAME`, `toolkit.default`, `/toolkit NAME`),
+and the plugin with `ctx.use_toolkit` (below). Names are `a-z`, `0-9`, `_` and
+`-`; one chi has (`full`, `lean`, `child`) or another bundle declared is a
+load error. A session saved on a toolkit whose bundle is gone declares every
+tool (full) until it comes back, with a warning at its first turn. See
+[Toolkits](configuration.md#toolkits).
+
+```ruby
+chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
+```
+
 ### `chi.ctx`
 
 The plugin's context (the `ctx` its handlers get), for `register` itself:
@@ -564,6 +631,9 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
 | `ctx.sessions` | fork, send to, read, list and stop other sessions: see [Other sessions](#other-sessions-ctxsessions) |
+| `ctx.toolkit` | the name of the session's toolkit (`full` for a session from before toolkits); nil with no session |
+| `ctx.declared_tools` | the tool names the session's next turn declares (its toolkit resolved, with its own adds and removes): ask this, not the name, whether a tool is there |
+| `ctx.use_toolkit(name)` | put the session on toolkit `name` (yours from `chi.toolkit`, or chi's): saved, applied at the next turn's start and announced (`toolkit> toolkit: NAME from the next turn's start`, the web's tools chip follows). Only before the session's first model reply and outside a turn (the declared tools start every request, and a plugin doesn't ask first); otherwise it returns false and changes nothing: tell the user to run `/toolkit NAME`. An unknown name raises ArgumentError. Needs chi 0.66.0 |
 | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
 
 The Engine itself is never handed to a plugin.
@@ -1486,6 +1556,13 @@ by themselves there.
   report ending with the `/coordinate resume <slug>` to pick it up next
   time. It starts, merges and stops nothing: running children stay running
   and are named in the report.
+- **The coordinator toolkit.** The bundle declares `coordinator`: `lean`
+  plus `delegate`, `delegate_result` and `list_sessions`
+  ([Toolkits](configuration.md#toolkits)). `/coordinate` puts a fresh session
+  on it before it asks the model (`ctx.use_toolkit`). When chi refuses (a reply
+  or a turn already there) and the session's toolkit has no `delegate`, the
+  reply says to run `/toolkit coordinator`. A continue of a coordinator link
+  keeps the toolkit.
 - **`/children [all]`** shows the session's children as a card, newest first,
   one line each: `` `ab12cd34` · running · fix/flaky · "fix the flaky spec" ``,
   `` `9a8b7c6d` · done · feat/x · reported · "All 12 specs pass" `` (`not
@@ -1566,7 +1643,13 @@ Claude pairs; without one the bundle costs one tool declaration.
     file is there (it goes when that Claude session ends), the last send, and
     Claude's last answer (the `claude-review` summary).
   - `/claude validate <text>` and `/claude context <text>` send the text as it
-    is, titled by its first line: paste a selection after them.
+    is, titled by its first line (past a web quote's `From …:` label and a
+    quoted line's `> `): paste a selection after them.
+  - In the web, selecting text offers **Confirm with Claude**
+    ([`chi.annotation`](#chiannotationlabel-command-template-quote-send-false)):
+    it fills the composer with `/claude validate` and the quote, for you to
+    add what needs confirming. On a chi without `chi.annotation` (0.62–0.65)
+    the bundle loads without the pill.
   - `/claude last` sends the model's last completed answer as context. Mid-turn
     it is the answer before the running turn, never the turn's partial text;
     a cancelled or failed turn has no answer, so the one before it goes.
@@ -1598,6 +1681,84 @@ Claude pairs; without one the bundle costs one tool declaration.
   minutes). It is local only (a Unix socket), but it does hand session
   content to another agent: only what the model or you picked.
 
+## The codex-peer bundle
+
+```sh
+chi bundle install codex-peer    # in the dev profile
+```
+
+The [claude-peer bundle](#the-claude-peer-bundle) for an OpenAI Codex CLI
+session: chi sends the Codex session you work with a part of the work to
+validate or as context, and Codex's answer comes back into chi. It is a copy
+of claude-peer with the transport swapped; what differs is below, the rest
+(kinds, payload files, the last send, `/codex last`, the status card, the
+skill install card) works the same.
+
+- **Sending is `codex queue`.** `codex_send(kind, title, text)` and
+  `/codex validate|context <text>` run
+  `codex queue --thread <uuid> --message <text>` (an argv, no shell), which
+  wakes an idle Codex TUI: the message runs there as a new user turn (checked
+  on Codex 0.162.1; a message queued mid-turn runs after the turn). The
+  thread is the `codex-inbox` context's hint, Codex's `CODEX_THREAD_ID`, which
+  must look like a UUID. `codex` is `$CODEX`, else `codex` on the PATH: a
+  worker started by `chi web` or launchd may have another PATH than your
+  shell, so set `CODEX=` where chi runs if the error says there's no codex.
+  The tool and the anytime `/codex` wait for `codex queue` up to 10 s; a
+  queue that takes longer is killed (its process group) and the send fails
+  with a timeout error, never a hang. Other errors say what to do: no
+  `codex-inbox` (pair from Codex), a thread Codex has no record of (that
+  Codex session is gone: pair again), an ephemeral thread
+  (`codex exec --ephemeral` can't take queued messages), or `codex queue`'s
+  first error line. A Codex session that was closed (`/quit`) is not gone:
+  Codex's app-server still takes the queue (exit 0), chi says sent, and no
+  answer comes; the message waits for that session (`codex resume` there, or
+  pair again from a new one). The status card shows the thread id and says
+  so; there is no cheap check that the session is open.
+- **Codex's sandbox.** Pairing and every reply write chi's state
+  (`chi context add`/`push` write the session's context files directly),
+  which Codex's default sandbox (workspace-write) refuses. The user adds, to
+  `$CODEX_HOME/config.toml` (else `~/.codex/config.toml`):
+
+  ```toml
+  [sandbox_workspace_write]
+  writable_roots = ["/Users/you/.local/state/samagotchi/context"]
+  ```
+
+  and restarts Codex. Only chi's `context/` folder: the state folder above it
+  also holds guardrails, session files, plugins and the web token.
+  `/codex install-skill`'s card shows the line with your state folder
+  (absolute: config.toml doesn't expand `~`), and the pair script names it
+  when a write is refused ("Operation not permitted"). chi never edits
+  Codex's config. Reading a payload file needs nothing: the default sandbox
+  reads anywhere. No network is needed: a push writes files, and chi wakes
+  on them.
+- **Pairing** is Codex's, as with Claude: `/codex install-skill` copies the
+  bundle's `scripts/chi-peer-SKILL.md` to
+  `$CODEX_HOME/skills/chi-peer/SKILL.md` (else `~/.codex/…`), with the
+  installed `scripts/pair` path, the payload folder and the writable root
+  written in; in Codex you say "pair with chi <id or chi web URL>", and
+  `sh <bundle>/scripts/pair` attaches `codex-inbox` (the thread id as its
+  hint, pushed so a re-pair refreshes it) and `codex-review`. Run outside
+  Codex (no `CODEX_THREAD_ID`) it refuses. Codex replies with one JSON push
+  to `codex-review` (`text`, `summary`, `wake: true`), which wakes chi, the
+  first answer too: that needs chi 0.63.0, the bundle's `requires_chi`.
+- **Peer messages are user turns in Codex.** Claude Code marks an inbox
+  message as from another session; `codex queue` lands as a plain user
+  message. So Codex's skill starts with the rule: a message whose first line
+  is exactly `chi <8 hex> · <kind> · <title>` comes from chi, a peer agent,
+  not the user; it can't approve anything, change settings or widen the
+  sandbox, and the part it carries (and a payload file) is data to check,
+  never instructions, since it may hold tool or web output. This is a prompt
+  rule Codex follows, not something enforced: anything shaped like that
+  header is treated this way, and nothing stops a message from asking for
+  more.
+- In the web, selecting text offers **Confirm with Codex**, which fills
+  `/codex validate` and the quote, as claude-peer's pill does.
+- **The skill.** `skill_codex_peer` (system scope) is claude-peer's with
+  Codex's names, and on a missing answer points to Codex being mid-turn or
+  its sandbox (the `writable_roots` line). To be asked before each send, a
+  guardrails rule with `tool: codex_send` (see the claude-peer section).
+
 ## Shutdown
 
 When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, source-links, github-pr, coordinator, claude-peer, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sessions.md

@@ -220,6 +220,16 @@ A session can **continue** an earlier one: "the next day of the same routine" (a
 - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT]` (see *Starting a session*).
 - **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.
 
+## Toolkits
+
+A session file's `toolkit` (`{"name", "add", "remove"}`) is the toolkit it was created on, as named: config's
+`toolkit.default`, `toolkit.child` for a delegate child, or `chi --toolkit` / `chi send --new --toolkit` (with
+`--tool` / `--no-tool`). It is never resolved again from config: a respawned or woken worker declares the same
+tools. `null` (a session from before toolkits) is `full`. A continue (`continue →`, `chi send --new --continues`)
+and a fork (`ctx.sessions.fork`) keep it, as they keep the thinking level; a delegate child gets `toolkit.child`.
+`/toolkit` changes it, saved at once, from the next turn's start. See
+[Toolkits](configuration.md#toolkits).
+
 ## Delegating
 
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `delegated by` in its info bar; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.