samagotchi 0.121.1 → 0.123.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b07fb49361e67b325eaaf3190d15d3f889a6df2e590585b45257a0a2b1409ac9
-  data.tar.gz: 37e6db4dc2235fcfe9127d38261056983f609ebd0dd1a214a903ec94c8afec35
+  metadata.gz: 8b284b838ef7182e859040f2955be576abe43fda373a9a96c094bd701ef8837c
+  data.tar.gz: d776a399ac831dd9a62405f58f5eb9c9843b83b021f82a52361fe32d4f49aba9
 SHA512:
-  metadata.gz: 8a8e5c43eee0002c4054c6e347f75a795fa09216a7f0ea3db30770043a5eaaf57fa34f9a1ee5a4ddf64117f1e8f3bb5ed4ccf8b34c55bb5c9a2e6398c1fec997
-  data.tar.gz: 23714d86e0872fdcba52fb019b30dbf84c4531a3c44a13f0cb30b72cc95bb59506c654cb53ae395b3d8ae5d83672c29fe8624958ef968dc5648b4189d9e8731f
+  metadata.gz: 1a590e517591c610712641c7496a916afad37502d3784669bbb58a582a5e8522246dc9c6a2bdcaad8b5fc9ad4d8c7b7bab95e52eeea012bf075af9d481e52680
+  data.tar.gz: 4e7917cc27174b89e870f6f6d768001de752b35f332f942f7c9223fab22a0614c2bb32839e79c6038282ed5a86f994e038a4cd8b2a1a3a83b3c2f52320309827

data/CHANGELOG.md

@@ -7,6 +7,70 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.123.0] - 2026-10-27
+
+### Added
+
+- chi web checks RubyGems daily and shows the newest aged, stable release newer than both the running and installed
+  chi, with its RubyGems page and a command to copy (`chi update`, or the blocker-specific command).
+- chi web sends one 24-hour phone push per newly available chi; it skips the push when a chi web page is in front.
+- `toolkit.suggest.mode: on` starts a new session on the kit System 1 suggests for its first prompt (or a later one
+  after `undecided`), waiting at most System 1's timeout before the first request, with a
+  `toolkit: NAME (suggested, p=…) · /toolkit to change` notice; anything uncertain keeps the default kit.
+- Pair access for a shared working session: a participant invited to a working session (not a `chi review`
+  session) while its worker runs pair turns gets turns that act with the session's tools under the owner's
+  guardrails; the grant is stamped `mode: pair` only when the share warning said so. Existing grants, and any invited
+  while the worker was older, stay read-only review participants until they are invited again. A pair turn's asks
+  reach the owner's card naming who asks, with Allow once only, and System 1 never answers them; a write outside the
+  project always asks, whatever the owner approved before. A new core check (`pair-boundary`) denies reading or
+  writing secrets and chi's own files (keys, shell startup files, histories, credential files; by a file tool, a
+  command, a glob, a variable or a script it hands a shell), running chi, backgrounding commands, reading the
+  environment or the keychain, git settings that run commands, sweeping home with find/tar/cp/grep, the owner-voiced
+  tools (delegate, reminders, notes, background tasks,
+  forgetting outputs, loading tools, memories) and the model's own question. A pair turn stops mid-turn once the
+  participant's cap is passed or their link is revoked or expires. A pair turn's commands run without
+  secret-named environment variables and are killed at the execute limit, and one that writes outside the project
+  asks the owner. Workers name a `pair_turns` feature.
+- Participant turns show a one-line tools overview with expandable, names-only rows that update as a turn runs.
+
+### Changed
+
+- Sharing a working session warns what a participant's turns may do there (writes included, asks to you) instead of
+  only how many tool outputs they can quote. Its participant messages carry a pair header, a `pair` badge and no
+  Apply; review sessions, their messages and their headers are unchanged. The system prompt's participants line,
+  the cap notice, the participant page's note and the participants panel follow the session's mode; the delivery
+  line says "after their turn".
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`); a participant
+invited before this release stays a review participant until invited again.
+
+## [0.122.0] - 2026-10-27
+
+### Added
+
+- Toolkit kits accept an optional `description:` (config `toolkit.kits` and `chi.toolkit`): what the kit is for, read
+  by the toolkit suggestion, never sent in a prompt.
+- A memory named `toolkit_<name>` defines a kit (one YAML block with `base`, `add`, `remove`, `groups` and a required
+  `description`); project memories win over system ones, config and bundle kits over both, and `/toolkit` shows the
+  source. chi's memory guide says when to write one.
+- Toolkit suggestion audit (`toolkit.suggest.mode: audit`, off by default): System 1 is asked which described kit fits
+  a new session's first prompt, in the background, without changing the session or delaying its turn; `chi toolkit
+  report` grades the suggestions against the tools each session then used.
+
+### Fixed
+
+- `chi sessions restart` on a stopped (SIGSTOPped, Ctrl-Z) worker refuses at once with its pid and `kill -CONT PID`,
+  instead of ~70 s of silence before "didn't take the restart".
+- `chi --remote NAME sessions restart` refusals keep their reasons (what the worker still has running) and name the
+  remote `chi --remote NAME sessions stop` command.
+- chi web's stream, and a remote terminal, say a running worker "didn't answer" instead of "no live worker".
+- The model's hint about a same-named project's memory folder asks the user first instead of offering an `mv`.
+- A participant's wait answers revoked (401) when their grant disappears mid-wait, not "chi web is stopping".
+- A bad `web.start_dir` says it came from config.yml (not `--start-dir`), and a relative one resolves from home.
+- A remote `chi note` whose reply has no status is a clear refusal instead of a crash.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`).
+
 ## [0.121.1] - 2026-10-27
 
 ### Fixed
@@ -4631,7 +4695,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.121.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.123.0...HEAD
+[0.123.0]: https://github.com/dm1try/samagotchi/compare/v0.122.0...v0.123.0
+[0.122.0]: https://github.com/dm1try/samagotchi/compare/v0.121.1...v0.122.0
 [0.121.1]: https://github.com/dm1try/samagotchi/compare/v0.121.0...v0.121.1
 [0.121.0]: https://github.com/dm1try/samagotchi/compare/v0.120.0...v0.121.0
 [0.120.0]: https://github.com/dm1try/samagotchi/compare/v0.119.0...v0.120.0

data/bin/chi

@@ -70,6 +70,8 @@ SUBCOMMANDS = {
   "bundle" => ["samagotchi/bundle_command", "BundleCommand"],
   # the System 1 record: replay the asks this machine's sessions already answered
   "guardrails" => ["samagotchi/guardrails_command", "GuardrailsCommand"],
+  # audit suggestions for which toolkit fits a session's first prompt
+  "toolkit" => ["samagotchi/toolkit_report_command", "ToolkitReportCommand"],
   # other machines' chi web, for chi --remote NAME (add, ls, rm)
   "remote" => ["samagotchi/remote_command", "RemoteCommand"]
 }.freeze
@@ -230,7 +232,8 @@ if options[:web]
                                       working_set: Samagotchi::Config.get("web.working_set"),
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
                                       editor: Samagotchi::Config.get("web.editor"),
-                                      start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"))
+                                      start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"),
+                                      start_dir_from: options[:start_dir] ? :flag : :config)
 end
 
 # --resume and --attach take a unique id prefix too, like git.

data/docs/architecture.md

@@ -502,7 +502,8 @@ reading `bridge.json` or probing a port itself: `WorkerLink.resolve(session_dir,
 outcome. The rule is the owner lock plus the sidecar's `pid`; there is no port probe (a port can be reused by another
 session's Bridge, a free lock is the kernel's proof the worker died). In order: no lock holder, or a chi REPL's: a
 sidecar is `Stale(:lock_free)` (removed with `unlink: true`, only if it is still the file that was read), else `None`;
-a holder with no kind yet: `Starting`; a leaving worker: `Leaving`; a worker whose sidecar names no port or another
+a holder with no kind yet: `Starting`; a leaving worker: `Leaving` (marked before its Bridge stops, on every way out:
+`Worker#teardown` marks it too, with `TEARDOWN_LEAVE_WAIT`); a worker whose sidecar names no port or another
 pid than the holder's (a worker that has not written its own yet): `Starting`, `stuck` once it has held the lock
 past `START_LIMIT` (30 s) with none; a sidecar whose `protocol` is newer than `WorkerLink::PROTOCOL`: `Skew` (a
 newer worker; never driven, `wake` answers 409 `worker_newer`); else `Live` (its sidecar; `#client` makes the one
@@ -532,12 +533,23 @@ The snapshot names chi's version: a tab served by another one (its `<body data-v
 reload in a toast, since an open tab keeps its old JS across a `chi web` upgrade. It also names
 `installed`, the newest chi on this machine (`InstalledVersions`: the highest `samagotchi-<v>.gemspec`
 in RubyGems' specification dirs, or a checkout's `version.rb` on disk; looked at again on each full
-probe, every 10 s), and a change is a `chi` frame `{version, installed}`. A newer one than the
-server runs is said in chi web's terminal and on the page: restart chi web (its workers already
-run the newest chi, [Sessions](sessions.md)). `GET /api/info` carries `installed` too, and the
-feature `newest_workers`; next to `cwd` (the folder chi web runs in) it names `start_dir`, the folder it
-starts in (`web.start_dir`, `--start-dir`; `Web::StartDir`), which a second `chi web` given another one
-mentions.
+probe, every 10 s). A `chi` frame and the `GET /api/events` snapshot carry the full state
+`{version, installed, available, update_blocked}`; `/api/info` and the session-command wake response
+carry the same fields. `SessionHub#update_available` publishes the checker result under the hub's
+Monitor, but fetching never holds it.
+
+`Web::UpdateCheck` runs its own thread beside the hub. When `update.notify: on` (the default), its
+first RubyGems check is about 30 seconds after chi web starts, then it checks at `update.check_hours`
+intervals. A stable release is available only after `update.min_age_hours` and when newer than both
+the running and newest installed chi. Its atomic, mode-0600
+`$XDG_STATE_HOME/samagotchi/update_check.json` keeps the check cooldown and versions already
+announced across restarts. `update.notify: off` starts no checker thread and makes no network
+request. `update_blocked` names why the local gem cannot be updated in place (checkout, Bundler, or
+an unwritable gem directory). The page tells the owner to run `chi update`; a newer `installed`
+version than the server itself still means restart chi web (its workers already run the newest chi,
+[Sessions](sessions.md)). `GET /api/info` also names `newest_workers`; next to `cwd` (the folder chi
+web runs in) it names `start_dir`, the folder it starts in (`web.start_dir`, `--start-dir`;
+`Web::StartDir`), which a second `chi web` given another one mentions.
 
 The page's scope is in its URL, and the server picks the default: `?dir=<folder>` is that folder's
 project (the list, the events stream and a new chat follow it), `?scope=all` every session, and a bare

data/docs/cli.md

@@ -27,7 +27,7 @@
 - `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`). What a parent may pick follows `guardrails.parent_answers`, or the session's own `parent_answers` when stricter (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
 - `chi remote add NAME URL [--token-file F | --token-stdin]`, `chi remote ls`, `chi remote rm NAME` — the other machines whose chi web the session commands reach with `--remote NAME` (see [Remote sessions](#remote-sessions))
 - `chi review FILE… [--dir DIR] [--model M]`, `chi review --from ID [FILE…]` — start a review session to invite participants to: for files of a project, or as a review of a working session that starts from its recap, not its transcript (see [Review sessions](#review-sessions))
-- `chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]`, `chi share ls [ID]`, `chi share cap ID P DOLLARS`, `chi share revoke ID [P] | --all` — invite a participant to review a session through chi web on the LAN (a link of their own, 7 days, a $2 spending cap), list them, change one's cap, revoke them (see [Participants](#participants))
+- `chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]`, `chi share ls [ID]`, `chi share cap ID P DOLLARS`, `chi share revoke ID [P] | --all` — invite a participant to a session through chi web on the LAN (read-only review turns in a review session, pair turns that act under your guardrails in a working session) (a link of their own, 7 days, a $2 spending cap), list them, change one's cap, revoke them (see [Participants](#participants))
 - `chi --remote NAME send|answer|note|context|sessions|share|review …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
 - `chi --remote NAME --attach ID` (`--resume ID`, `--dir DIR [-p TEXT]`) — the attached TUI on a session of that machine (see [Remote sessions](#remote-sessions))
 - `chi memory ls [--scope project|system] [--format text|json]` — the memories of both scopes (this folder's project first), one row each: scope, name, size, date, `from <bundle>`, the index description and its model overlays; `chi memory rm NAME [--scope project|system]` removes one as `memory_write` with `remove: true` does: its file and model overlays go to the bundle trash (the line names the dir; `chi bundle trash` lists and empties it) and its index line is dropped. NAME in both scopes without `--scope` exits 2 naming both; a missing NAME or a bundle's memory (`chi bundle uninstall` removes it) exits 1 (see [Memory: Listing and removing from the shell](memory.md#listing-and-removing-from-the-shell))
@@ -38,6 +38,7 @@
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — 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)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). 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. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
+- `chi toolkit report [--days N]` — grade toolkit suggestions: the kit on mode would have run (the suggested kit when it would have applied it, else the default; an on-mode line's `did` says what it ran) against the tools the session called from that turn on (only that turn when the toolkit was chosen since), `call_tool` targets included, for both the chat and the raw-prompt loop. Each is *covers*, *short of a tool* (naming the tools), *wider than needed* (a narrower kit offered in the same ask would also have covered) or *ungradable* (calls it can't read back); then a per-kit tally with what on mode would have done. Includes archived sessions and caps the report at 14 days and 500 sessions. Reads `toolkit_suggestions.jsonl` (each ask logs every offered kit's rules, expanded against the called tools here); it never runs the model or changes a session. Local only; `--days` must be a positive whole number.
 
 - `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
   and print its trace (see [Trying a bundle](#trying-a-bundle)).
@@ -232,6 +233,17 @@ Also shipped, not installed: dev (mcp, skills, source-links) (chi bundle install
 done
 ```
 
+- **chi web update notices.** By default, chi web checks RubyGems about 30
+  seconds after it starts and every 24 hours after that. Once a stable release
+  is at least 24 hours old and newer than both the running chi and the newest
+  installed one, the page shows its version, a link to that RubyGems release,
+  and a button to copy `chi update`. The notice is once per version per
+  browser: a reload or a chi web restart doesn't repeat it.
+  `update.notify: off` disables checking; `update.check_hours` and
+  `update.min_age_hours` tune the interval and release age (see
+  [configuration](configuration.md#all-settings)). If the gem can't be updated
+  in place, the notice gives the blocker and its command instead.
+
 - **The gem.** It asks rubygems.org for the newest samagotchi (5 s timeout)
   and, when that's newer, runs `gem install samagotchi` with the gem command
   of the Ruby chi runs on (the real one, not a mise/rbenv/asdf shim; a chi
@@ -1422,6 +1434,25 @@ chi share revoke --all          # every link to every session
   share cap` raises it. `/stats` shows each participant's spend. Their turns go only to a worker with the review
   boundary: restart an older one. While your turn waits at the step limit (Continue or Stop), their turns wait too
   (still queued, still counted): they run, in order, once you continue, stop or send a turn of your own.
+- **Pair turns: sharing a working session.** The read-only review turn is a review session's (`chi review`). Invite
+  someone to a working session instead and their turns **act** in it with its tools, writes included, under your
+  guardrails: what your rules allow runs, what they ask about comes to you as "Sam's turn asks: approve tool call?"
+  with **Allow once** only (nothing session-wide or repo-wide is approved from their calls), and System 1 never
+  answers for you. A write outside the project always asks you, whatever you approved before. It can't read or
+  write secrets or chi's own files (keys, shell startup files, histories, credential files; by a file tool, a
+  command, a glob or a variable), run chi, leave a command running in the background, read the environment or the
+  keychain, sweep your home with find/tar/cp/grep, delegate, set or cancel reminders, send notes, start or stop
+  background tasks, load tools, forget outputs or write memories, and it asks its questions in its reply, not on a
+  card. Its commands run without your secret-named environment variables (`KEY`, `TOKEN`, `SECRET`, `PASS`,
+  `CREDENTIAL`, `AUTH` in the name) and are killed at the execute limit rather than left running; a command that
+  writes outside the project asks you, as a write does (the tmp dirs aside). A pair turn stops mid-turn once their
+  cap is passed or their link ends. `chi share` and the panel's Invite
+  warn you with what their turns may do and how many tool outputs the history holds, and only a link issued with
+  that warning acts: links from before, or issued while the session's worker predated pair turns (the warning says
+  so), stay read-only until you restart the worker and invite them again. Their messages carry a `pair` badge and no
+  Apply (they acted already). This is an accident guard for a trusted team, not containment: a pair turn can still
+  send what it reads out through `web_fetch` or your MCP tools. A link without `--identity` gets the same access:
+  share it only with people you'd let type in your session.
 - **The participant page.** Their link opens a page of its own (never yours): the session's title and status, who
   else takes part, and the conversation as a participant sees it: every prompt and reply with who wrote it, each
   step's tools as one line (`read docs/plan.md`: the tool and a project file's path, never arguments or output), and

data/docs/configuration.md

@@ -163,6 +163,7 @@ or `chi web` restart.
 | `append_system_prompt` | Worker start for the file list | The config list is not saved in the session file. File text is read when the prompt is built; `/model` rebuilds it, while an already-built prompt is cached. CLI `--append-system-prompt` files are saved in the session. |
 | `toolkit.default`, `toolkit.child` | Session creation | The chosen toolkit is saved; changing the defaults does not move existing sessions. |
 | `toolkit.kits`, `execute.description`, `llm_context.policy` | Worker start | These are held by the engine's toolkit or tool registry. |
+| `toolkit.suggest.mode`, `toolkit.suggest.threshold`, `toolkit.suggest.defer_turns`, `toolkit.suggest.defer_tokens` | Worker start | Suggestion settings are config-only and are resolved when the worker runs its audit or on-mode ask. |
 | `skip_agents_md` | Prompt rebuild | A running engine caches its built prompt; a new worker or `/model` rebuild uses the changed value. |
 | `context.*` except `context.every_seconds`, `llm_context.*` except `llm_context.policy`, `steer.cut_after`, `memory.index_warn_tokens`, `status.line`, `web.participants.*` | Next matching turn, display, poll or write | Readers resolve these settings when they perform that operation. Session-specific LLM context and thinking values remain saved in the session. A participant's grant keeps the expiry and cap it was issued with; `web.participants.*` is what the next invite gets, and the cap and queue of a grant from before caps. |
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
@@ -176,7 +177,8 @@ or `chi web` restart.
 | `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
 | `history.file` | Next history access | The TUI and web composer resolve its path when they read or append history. |
 | `broadcast.*` | Next `chi broadcast` | Each broadcast invocation reads its targeting and triage settings. |
-| `update.*` | Next `chi update` | The command reads which components to update when it runs. |
+| `update.gem`, `update.bundles`, `update.desktop` | Next `chi update` | The command reads which components to update when it runs. |
+| `update.notify`, `update.check_hours`, `update.min_age_hours` | `chi web` start | The update checker starts with chi web; restart it to apply changes. |
 | `kitty.*`, `tmux.*` | `chi desktop upgrade` or desktop update | These settings are copied into the desktop helper's launch file. |
 | `model.profile`, `reasoning_history` | Not from config.yml | These are CLI/environment settings; `models:` and `hosts:` provide their model- and host-specific forms. |
 
@@ -1398,7 +1400,7 @@ toolkit:
   default: lean        # the sessions you start (unset: full)
   child: child         # delegate children (unset: full)
   kits:                # your own, on a base
-    audit: { base: lean, add: [web_fetch, delegate], remove: [memory_write] }
+    audit: { base: lean, add: [web_fetch, delegate], remove: [memory_write], description: "Code review and inspection" }
     terse: { base: lean, prompt: "- Be concise in your responses" }
     web: { base: lean, groups: [chrome] }
     coding: { base: lean, groups: [] }
@@ -1414,10 +1416,51 @@ toolkit:
 | `review` | `read`, `memory_read` (not `forget_outputs`, even under the `forget` layer): what a [participant's](internals/participants.md#turns) turn may call, whatever the session declares (the review boundary, [guardrails](guardrails.md#a-participants-review-boundary)). Reserved: `toolkit.kits.review` is refused ("review is reserved for participants' turns"), and a bundle can't declare it. A session may run on it too, as any kit |
 
 - **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:`, `remove:`, `prompt:` and `groups:`
+  the `forget` layer. A `kits:` entry takes `base:` (default `full`), `add:`, `remove:`, `prompt:`, `groups:` and
+  `description:`
   (any other key, a typo or a `tools:` list, is ignored with a warning); it can't reuse a built-in's name
   (`review`'s least of all: it is the participants' boundary). A bundle declares its own with `chi.toolkit`
-  ([plugins](plugins.md#chitoolkitname-base-add--remove--prompt-nil-groups-nil)).
+  ([plugins](plugins.md#chitoolkitname-base-add--remove--prompt-nil-groups-nil-description-nil)).
+  `description:` is optional classifier input, up to 300 characters; it is not included in the session prompt.
+- **Memory kits.** A memory named `toolkit_<name>.md` defines kit `<name>` with one fenced YAML block containing
+  optional `base:`, `add:`, `remove:` and `groups:`, plus a required `description:` (up to 300 characters).
+  `prompt:` is refused. A memory kit may use a config or bundle kit as its base. Built-ins cannot be redefined.
+  The precedence is built-ins, config, bundles, then memory kits; within memories, project scope wins over system
+  scope. Muted memory kits are skipped, and `/toolkit` shows each one's `memory:project` or `memory:system` source.
+  Kits are read once per worker, so changes take effect when a new worker starts. See
+  [Toolkit memories](memory.md#toolkit-memories) for the format and when to create one.
+- **Audit suggestions.** `toolkit.suggest.mode: audit` asks System 1 which described kit fits an eligible new session's
+  prompt, without changing its toolkit or delaying the turn. It offers the configured default as the fallback and
+  `undecided` for greetings or check-ins. Only a default-origin session with at least two described candidates is
+  asked; chosen or inherited toolkits, delegate children, review sessions and participant turns are skipped. After
+  `undecided`, later owner prompts may be asked again within both defer limits. The default is `off`. System 1's
+  host, model and timeout come from `guardrails.system_one.*`; the suggestion threshold and defer limits are its own
+  settings below. Suggestions are
+  kept in `toolkit_suggestions.jsonl`; `chi toolkit report` grades them against the session's tool calls. One ask
+  runs at a time (a turn that comes while one still runs goes unasked, with an info line), and a kit that doesn't
+  resolve (a missing base, a cycle) is left out of the candidates. A worker that exits waits about a second for a
+  running ask, so a one-shot `-p --non-interactive` run may end before its suggestion is logged.
+- **On mode.** `toolkit.suggest.mode: on` asks the same question on the same eligible turns, but the turn waits for
+  the answer before it declares any tool, for at most `guardrails.system_one.timeout_ms` from the ask's start (it
+  starts right after the turn does, so plugin and MCP start-up hide most of it). A described kit picked with
+  confidence at or above `toolkit.suggest.threshold` becomes the session's toolkit, saved with `toolkit_origin:
+  suggested`, and the turn's first request declares it; the notice reads
+  `toolkit: web (suggested, p=0.71) · /toolkit to change`. Anything else (the default, a low-confidence or unknown
+  pick, `undecided`, no answer, a failing System 1, which warns once as `[samagotchi:toolkit]`) keeps the default
+  kit. A Stop during the wait (or before it, even with the answer in) ends the turn before its first request, and
+  nothing switches. After an `undecided`, a later prompt within the defer limits may switch the session; that notice
+  says `from this turn`, and that request re-reads the whole prompt (system prompt, tools and conversation, which
+  the defer limits keep small) without `/toolkit`'s cache confirmation. `/toolkit` or `ctx.use_toolkit` marks the
+  toolkit chosen, and nothing is suggested after that; a `/toolkit` sent during a turn runs after it and replaces
+  that turn's suggestion. When System 1's host is the model's own local server (the same `hosts:` name or server
+  root, as audit checks), on mode asks only on a session's first turn, never on the deferred path, and sends no
+  warm-up (one info line). Otherwise an idle worker for an eligible session sends one warm-up ask with the real
+  question and a stand-in prompt so the server has its prefix cached; its answer is dropped and never logged, and
+  the first real ask stops a warm-up still running. Each answered ask's line in `toolkit_suggestions.jsonl` adds
+  `did`: `suggested`, `default`, `defer`, `chosen` (the toolkit was no longer the default), `unavailable` (the
+  picked kit was gone), `timeout` or `canceled` (written when the late answer arrives; a Stop after a timeout
+  doesn't cut it), or `failed` (the turn failed or the switch couldn't be saved); `chi toolkit report` grades
+  on-mode lines by what they did.
 - **Tool-index groups.** `groups:` selects source groups by name or glob (`chrome`, `db*`; any case, `{a,b}` braces,
   as the guardrails rules' `models:`); for the MCP bundle each group is a server. Anything but a name or a list (a
   map such as `{chrome: true}`) refuses every new session on that kit or on a kit built on it, on every surface (chi,
@@ -1982,6 +2025,10 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `context.peer_turns` | `3` | yes | Wake turns in a row a peer agent's answers may start (a peer bundle's outbox source, such as `codex-outbox`), with no message typed in the web or a TUI in between (`chi send` doesn't count); within `session.max_wakes`. Then answers wait as notes, and the UIs hear it once. An answer whose summary ends its verdicts with `VERDICT OK` wakes once to close the round, counted toward `session.max_wakes` only. `0`: a peer source wakes like any other. 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, unless its `delegate` call names one (`toolkit:`). See "Toolkits". |
+| `toolkit.suggest.mode` | `off` | | `audit` asks System 1 for a toolkit suggestion without changing the session; `on` waits for it (up to `guardrails.system_one.timeout_ms`) on an eligible turn and starts the session on a confidently suggested kit (Toolkits, On mode). The System 1 host, model and timeout come from `guardrails.system_one.*`. config.yml only. |
+| `toolkit.suggest.threshold` | `0.5` | | Minimum confidence for a non-default toolkit suggestion. config.yml only. |
+| `toolkit.suggest.defer_turns` | `3` | | Maximum owner-prompt number for another ask after `undecided` (the owner's own prompts: not steers, notes, reminders or `!` command output). config.yml only. |
+| `toolkit.suggest.defer_tokens` | `5000` | | Maximum estimated conversation size for another ask after `undecided` (characters / 4). config.yml only. |
 | `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". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
@@ -2003,6 +2050,9 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
 | `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |
+| `update.notify` | `on` | | `on`: chi web checks RubyGems once a day and shows aged stable releases newer than both this chi and the newest installed chi; `off`: no thread or network check. |
+| `update.check_hours` | `24` | | Hours between RubyGems checks (at least 1). The first check starts about 30 seconds after chi web starts. |
+| `update.min_age_hours` | `24` | | A release must be this old before chi web offers it; `0` disables the age delay. |
 | `kitty.listen_on` | none | | The desktop helper's kitty socket, copied from `kitty.conf`; unset = no kitty targets. See "Desktop helper: agents in kitty". |
 | `kitty.binary` | `/Applications/kitty.app/Contents/MacOS/kitty` | | The kitty the helper runs `kitty @` with. |
 | `kitty.agents` | `claude\|codex\|gemini\|aider\|opencode\|cursor-agent\|amp\|goose` | | Foreground programs whose kitty windows the helper lists, `\|`-separated (a YAML list works too); `*` lists every window. |
@@ -2027,7 +2077,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `web.working_set` | `true` | yes | The stage view's working set: the files, memories and URLs a turn brought into the model's context, in a rail in the stage, a footprint line under each finished turn and a `set N` chip in place of the mem chip; `false` brings the mem chip back. `?working_set=1` or `?working_set=0` on the page URL overrides it for that page load; the turn view ignores it. See [CLI: the working set](cli.md#the-working-set). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
-| `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; `/?scope=all` is every project. `~` and a relative path work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |
+| `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; `/?scope=all` is every project. `~` and a relative path (resolved from your home folder) work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |
 | `web.participants.expires` | `7d` | | How long a participant's link lasts unless `chi share --expires` says otherwise: `Nh` or `Nd`, 1h to 30d. See [participants](internals/participants.md). |
 | `web.participants.cap` | `2.0` | | What a participant's turns, and the side calls they cause, may cost you in dollars unless `chi share --cap` says otherwise ($0 to $1000); at the cap their next comment is refused (429 `cap_reached`) and you get a notice. `chi share cap ID P DOLLARS` changes one grant's. |
 | `web.participants.queue` | `3` | | How many of a participant's turns may wait behind their running one (0 to 20); one more is refused (429 `too_many_turns`). |

data/docs/guardrails.md

@@ -315,8 +315,11 @@ ordinary sessions don't get it. Like the rules it reads command text: a
 
 ## A participant's review boundary
 
-Built in, for a [participant's](internals/participants.md#turns) turns only (a
-turn whose author is `p:<id>`), in every mode (also with
+Built in, for a [participant's](internals/participants.md#turns) turns in a
+**review session** only (a turn whose author is `p:<id>`, in a session with a
+`review:` key: `ParticipantMode.of` is `:review`; a working session's
+participant turns get the [pair boundary](#a-participants-pair-boundary)
+instead), in every mode (also with
 `guardrails.enabled: false`) and without the guardrails bundle:
 `Guardrails::ReviewBoundary`, rule `review-boundary`, source `core`. It comes
 right after the load-failure check (rules that don't load deny every call) and before the hooks' asks, the
@@ -359,6 +362,96 @@ config can't widen the boundary. Hooks still run on a participant's turn, with
 the owner's power ([hooks](hooks.md#participants-turns)); a hook that rewrites a
 call is checked on the call it leaves.
 
+## A participant's pair boundary
+
+A participant's turn in a **working session** acts with the session's tools
+under the owner's guardrails, as the owner's own turns do: the rules, the
+protected paths and every approval the owner already granted apply, and an ask
+goes to the owner. It is a pair turn only when all three hold
+(`ParticipantMode.for_turn`, decided once at the turn's start:
+`GuardrailWiring#turn_mode`): the session has no `review:` key, its worker
+names the `pair_turns` feature, and the participant's grant was issued with
+`mode: pair`, which chi share and the web's Invite stamp only when the warning
+they showed said their turns act. A grant from before, or one issued while an
+older worker held the session, keeps review turns until it is invited again.
+
+`Guardrails::PairBoundary` (rule `pair-boundary`, source `core`) sits in the
+review boundary's seat in `GuardrailWiring#checks`, in every mode (also with
+`guardrails.enabled: false`), and **denies, never asks**, each with its own
+message:
+
+- secrets, read or written: the review boundary's denylist (chi's state and
+  config dirs, so `grants.json`, the web token and every `participants.json`;
+  `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config/gh`, `~/.config/fish`,
+  `~/.config/git`, `~/Library/LaunchAgents`, `~/.local/bin`; the home's shell
+  startup files, histories, `.gitconfig`, `.netrc`, `.npmrc`, `.pypirc`, `.claude.json`;
+  the project's secret files, any config under `.git`) on every file tool's
+  path (`read`, `write`, `edit`, a plugin's `targets:` paths) and on the paths
+  a command names (`execute`, and any call whose targets carry a command),
+  each word resolved as `touches: chi_dirs` resolves it; a glob that matches a
+  secret or whose fixed part leads into a denied folder (`~/.ss?/id_*`,
+  `~/.config/*/config.yml`, `.en?`), a `$var` word whose fixed part does
+  (`~/.ss${d}h`), and a text match for the rest;
+- sweeping a folder that holds secrets: `find`, `tar`, `cp`, `rsync`, `scp`,
+  `zip`, `ditto`, `grep`/`rg`/`ag` and the like given home or any folder above
+  a denied one;
+- the environment and the keychain: `env` or `printenv` alone, `set`,
+  `export`, `declare` or `typeset` that list, `launchctl getenv`, `ps e`,
+  `security`, `/proc/*/environ`. On top of it, a pair turn's `execute` runs
+  without every variable whose name matches `KEY|TOKEN|SECRET|PASS|CREDENTIAL|AUTH`
+  (`PairBoundary::SECRET_ENV_NAME`, case-insensitive), and a command still
+  running at the limit is killed, never handed over as a background task;
+- git settings that make git run a command (`core.hooksPath`,
+  `core.fsmonitor`, `core.sshCommand`, `core.pager`, `core.editor`, a `!`
+  alias) by `git config` or `git -c`, and `git config --global`/`--system`;
+- running chi, by any wrapper (`bin/chi`, `bundle exec chi`, `ruby … bin/chi`,
+  `env … chi`, `watch`, `npx`, `sh -c 'chi …'`, `$(chi …)`), in an assignment's
+  value or an alias, a function, after `-exec`/`-c`/`-e`, but `chi --version` and
+  `chi --help`: its commands act in the owner's name (shares, caps, sends,
+  answers, sessions);
+- leaving something running: `&` at a command's end, `nohup`, `setsid`,
+  `disown`, `screen -d…`, `tmux new -d`;
+- owner-voiced tools, which act in the owner's name beyond the turn:
+  `delegate` and any `delegate_*` tool, `register_reminder`,
+  `cancel_reminder`, `send_note`, `forget_outputs`, `task_create`,
+  `task_stop`, `find_tools` (it loads tools into the session), and
+  `memory_write` (a memory reaches the owner's later sessions);
+- `ask_user_question`, with the advice to ask in the reply: nobody on the
+  participant's side answers a card.
+
+A script a command hands on is read too (`Guardrails::PairCommand`): one a
+shell runs (`sh -c`, `eval`, a heredoc or here-string) as a command of its
+own, one another interpreter runs (`ruby -e`, `python - <<EOF`) by its text
+(chi, secrets, the environment, detaching). A heredoc written as data (`cat`,
+`tee`, `git commit -F -`) is not looked into: where it goes is checked. A
+command the checks can't read is refused, never let through on a text match.
+
+And it **asks the owner** before a `write` or `edit` outside the session's
+project root, and before a command that writes there (a redirection's target,
+`tee`'s files, a `cp`/`mv`/`ln`/`install`/`rsync`/`ditto` destination, or a
+target it can't resolve), every time: the ask is fresh (`Verdict#fresh_ask`: no
+stored approval answers it, and no rule lowers it), so it comes even in auto
+mode. The tmp dirs (`Dir.tmpdir`, `$TMPDIR`, `/tmp`, `/private/tmp`) and
+`/dev/null` neither ask nor deny.
+
+A participant's ask names them on the owner's card ("Sam's turn asks: approve
+tool call?", `approval.author`/`author_name`, `approval.asked_by`, the same
+line in the plain question: `Approval::ASKED_BY`) and offers **Allow once**
+only: no session, repo or rule approval is made from a participant's call.
+System 1 never judges it, and `chi guardrails replay` skips it. A pair turn
+stops before its next generation once the participant passed their spending
+cap or their link was revoked or expired
+([participants](internals/participants.md#limits-and-the-cap)).
+
+The trust model is a team's (everyone invited is trusted): the boundary is an
+**accident guard** for secrets and the owner's voice, not containment of a
+hostile participant; a review session is. A pair turn can still reach, through
+the owner's rules: `web_fetch` (an open egress path: what the turn can read it
+can send out in a URL), plugin and MCP tools, `memory_read` and `context_read`,
+`list_sessions` (the owner's other sessions' titles), and anything a script
+does that the command checks don't read (a script file's body, an interpreter's
+`-e` code). Share a working session only with people you would let type in it.
+
 ## Rules in config.yml
 
 ```yaml
@@ -666,6 +759,23 @@ a body that isn't JSON, a question with no answer, a request longer than
 `timeout_ms`. A nil means "ask the user", which is what the caller would
 have done anyway.
 
+Toolkit suggestions are a second use of System 1. When
+`toolkit.suggest.mode` is `audit` or `on`, the engine asks a `choice`
+question from a background thread after the turn starts. This uses the same
+configured host, model and timeout, but is gated by `toolkit.suggest.mode`,
+not `guardrails.system_one.mode`. Audit never changes the session's toolkit;
+on mode's turn waits for the answer (at most `timeout_ms`, cut by a Stop)
+and may start the session on the suggested kit (configuration.md, Toolkits).
+Its warnings use the `toolkit` tag and its records are written to
+`toolkit_suggestions.jsonl` beside the guardrail logs. To avoid competing
+with the session's model, audit skips (one info line) when
+the System 1 host is the model's local host: the same `hosts:` name, or
+another entry for the same server root (scheme, host and port). There is no
+reliable single-slot signal, so this host-identity check is the available
+contention guard. The session's own checks come first; the kits and the
+suggestion log are read only for a session that can be asked, the log only
+after an earlier `undecided`.
+
 ### What the audit writes
 
 With a client, `GuardrailWiring#request_approval` asks System 1 one `noul`
@@ -682,8 +792,8 @@ user's **earlier asks they answered** (`SystemOne::Similar`) — this rule in
 this repository first, then this rule anywhere, then any answered ask, ranked
 by how many words the logged call shares with this one, ties going to the
 newest. Reading the log is best-effort, so a log that cannot be read simply
-offers no examples. A participant's review turn is never judged: there is no
-user there to ask. The judgment runs before the card appears, so an ask is
+offers no examples. A participant's turn (review or pair) is never judged:
+there is no user there to ask, and its asks go to the owner. The judgment runs before the card appears, so an ask is
 slower by up to `timeout_ms` (2000 ms by default).
 
 Each judgment is a line in `judgments.jsonl`, beside `approvals.json` in
@@ -970,9 +1080,11 @@ send; [internals/participants.md](internals/participants.md#apply)). A quote
 lowers the risk, it doesn't remove it: your line still asks the model to act
 on what it quotes, with your tools, so read the quote before you send it.
 
-Within its own turn a participant's text can't act: the review boundary
-leaves it reads of the project only, and an injection that convinces the
-model still meets the boundary (containment over detection). What it can do
+Within its own turn in a review session a participant's text can't act: the
+review boundary leaves it reads of the project only, and an injection that
+convinces the model still meets the boundary (containment over detection). In
+a working session it acts, by design ([the pair boundary](#a-participants-pair-boundary)):
+invite only people you would let type in your session, under your guardrails. What it can do
 is make the model *say* what the history holds: a review turn's model sees the
 whole conversation, earlier tool outputs included, so start a review in a
 fresh session (or a continue), not on a working session full of outputs. A

data/docs/internals/engine.md

@@ -35,19 +35,28 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #                      the user message's and the reminders' stamp too), continue: true (only on a continue),
   │     #                      resumed: true (only on a step-limit Continue: resumed: given),
   │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
+  │     # start_toolkit_suggestion: ToolkitSuggest's ask on its own thread from a copied snapshot (audit and on
+  │     #   mode: one eligibility, one thread). Audit never blocks the turn or changes the session; on mode
+  │     #   returns a ToolkitSuggest::Pending the turn joins below. See configuration.md (Toolkits) and
+  │     #   guardrails.md (System 1).
   │     # refresh_profile! (may ask the server's /props once)
   │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name, loads_tools … are set in
   │     #   generate, after the hooks, from the final model),
   │     #   from one EffectiveModel; ThinkingNotices#turn_started keeps the level and says one the host can't do
   │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools,
+  │     #   then (on mode) settle_toolkit_suggestion: waits for the ask up to System 1's timeout from its
+  │     #   start, or a Stop (which wins over an answer already in, and cuts the ask's request through
+  │     #   Pending#cancel_controller; a Stop after a timeout doesn't), and on a candidate picked ≥ threshold
+  │     #   ToolkitBinding#suggest sets the session's toolkit, origin suggested, saved, with the notice;
   │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, ToolIndex#refresh! for find_tools'
-  │     #   chi line, a prompt rebuild when it changed)
+  │     #   chi line, a prompt rebuild when it changed). A Stop during the probes or the waits returns false
+  │     #   (the ask's line says canceled; an ensure marks one the turn never settled failed).
   │     # 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
   │     #   + the plugins' staged tool loads (ctx.load_tools: a kind "tool_change" system entry per bundle,
   │     #   only when the turn's host takes tool changes; #append_tool_loads)
-  │     # Returns false when a Stop came during the probes or the init wait, else true
+  │     # Returns false when a Stop came during the probes, the init wait or the toolkit ask, else true
   │
   ├── generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
   │     # one EffectiveModel (after the hooks, which may switch the model): sync_kernel_client!, then