samagotchi 0.62.0 → 0.64.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68aeb876a7c4c04d7f2f5de4290a1c6089df3acd181bce7380ccb6bde9ef9de8
-  data.tar.gz: ed308c360b3942d9f3d08233762396493a018585103e50661dd17ea4bb0d123c
+  metadata.gz: 61245b8998baef2bbb4c29cabc648314b4cc124cf9233099948cb7cf66dc890e
+  data.tar.gz: ac4e8fa165b5cc59d683b1541a3758e03f60a1d14b7fd9cded087770fda162de
 SHA512:
-  metadata.gz: 8a3ecca6a15d1c2d0e4acf5531491116139b3423ca0e6fe2b4ad558f5c99b332b50672a700437f9d37c1397d9ed92e527b843e6577b11198906ff75ab16b4ecd
-  data.tar.gz: 949538fdd97549e09bd215353cbdf9dccbe42a21806b965ff828db5b708521791e939abd2d2cb93892c23660abbfabd3106bb492412eb505f52cc0cd742d6d99
+  metadata.gz: 717ca2421c97d4f93493891e4f695528a0b8495ab11a2b47c348b29c726004abb32e638ab21b3e6af62676acfc4cc31c45527bdb9dfe72a9a270b3f7bfda3e02
+  data.tar.gz: 4916e876cf70f3b1b03e8c7554a127019e08e3b6f2e991305c8fe63ce1f6cf399155c43167ff36382c09eb2774792a4783ccbe39109702df6bd4efbe67a1ff53

data/CHANGELOG.md

@@ -8,6 +8,81 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.64.0] - 2026-10-13
+
+### Added
+
+- `/queue TEXT` during a running turn now works in an attached terminal and the web composer too, as it did in the
+  plain REPL: TEXT runs as a turn of its own after the running one, instead of merging into it (`(queued: runs after
+  this turn)`). A session whose worker is older than this says to restart it rather than steering the turn. See
+  docs/cli.md, "Typing during a turn".
+- `chi send --queue`: the message runs as a turn of its own after the running turn instead of merging into it, and
+  `chi send --queue --wait` waits for that turn's own answer (a running turn no longer refuses it; the running turn's
+  reply, end and questions are not the answer). Each turn's reply file now carries its message's id. See
+  docs/sessions.md, "Sending a message", and docs/sub-agent.md.
+- Plugins: `ctx.sessions.send(id, text, delivery: :queue)` runs the message as a turn of its own after the session's
+  running turn; `delivery: :cut` raises (plugins never cut). See docs/plugins.md.
+
+### Changed
+
+- Plain REPL (`--no-shared`): the lines a turn left over (a steer it didn't merge, `/queue` lines, image lines, commands
+  that wait) run in the order you sent them; before, an unmerged steer ran ahead of a `/queue` line typed earlier.
+- A message with images sent during a running turn no longer holds back the text lines sent after it: they go in at
+  the turn's next step as usual, and the image message still runs as a turn of its own after it.
+
+### Fixed
+
+- Stopping a session mid-turn (`chi sessions stop`, the web's stop, a parent stopping its delegate) cancels the turn
+  with its own reason, `session_stopped`, instead of the user's Stop: the turn's line reads "canceled (session
+  stopped)", a command it was running "stopped as the session was stopped" (slow-commands 0.2.2 counts it as
+  stopped, not slow), and `chi send --wait --format json` reports `cancel_reason: session_stopped`.
+- A delegate (and any worker a session's own commands start, such as `chi send --new`) reads `hosts:` from config.yml
+  as it starts, so it sees a host added or changed after its parent's worker started; before, it got the parent's
+  start-time hosts through `SAMAGOTCHI_HOSTS_JSON`, which workers no longer inherit (one set in your shell
+  applies to that chi process only; put hosts in config.yml).
+- Web: a step that only called plugin tools with a verb label is titled by the label ("echoing"), not "working
+  with echoing"; among other tools such a call is named by its tool ("working with read, echo").
+- Web: a send from a stale tab into a session deleted meanwhile goes back to the start page with a "was not
+  found" notice, the line kept in the composer, instead of an alert.
+- `chi send`, the web composer and a plugin's `ctx.sessions.send` now report a message the session's worker refuses
+  (a 4xx answer such as a delivery it doesn't run) instead of writing it as an input file the worker would merge
+  anyway; a body over the worker's size limit still goes in as a file, as before.
+- `chi answer`, `chi send --wait ID` (no message) and `delegate_result` wait for the reply of the turn they are about
+  (the answered turn, the running turn, the follow-up's turn), not a newer one queued behind it; a Continue of the
+  step-limit question gets the continued turn's reply, and a Stop ends the wait as `not_continued`. Workers older
+  than this keep the old behaviour.
+
+## [0.63.0] - 2026-10-13
+
+### Added
+
+- The claude-peer bundle (in the dev profile): pair a chi session with a Claude Code session you work with, and
+  the `claude_send` tool sends Claude a part of the work (a plan step, a diff, a finding) to validate, as context or
+  with a question; Claude's answer comes back as the `claude-review` context. `/claude validate|context <text>` and
+  `/claude last` send without the model, `/claude` shows whether a Claude is paired, and `/claude install-skill`
+  installs Claude's `chi-peer` skill, which pairs ("pair with chi <id>"). See docs/plugins.md, "The claude-peer
+  bundle".
+- Plugins: `ctx.context.list` gives each source's last `summary:` too. See docs/plugins.md, "Attached context".
+
+### Fixed
+
+- Attached context: a source added with `chi context add NAME --push` now wakes an idle session when its first
+  push asks to (`"wake": true`); before, only later pushes could.
+- Plugins: `ctx.context.list` returns `[]` for a new session whose file isn't saved yet (a plugin command before
+  the first turn) instead of raising "Session not found".
+- An after_turn hook's file refs on the answer (`event[:refs]`) must be under the session's folder, as a plugin
+  tool row's are: a file elsewhere is refused (and logged), and a stored one is dropped when the answer is shown.
+- loop-guard (0.3.8): the card for a turn it stopped prints under the blocked call's row in the terminal, not
+  before it.
+- Attached TUI: joining a session whose last turn was images alone (sent from the web) names each image once, not
+  twice.
+- Attached TUI: text you had typed when the step-limit question opened comes back at the prompt once you answer
+  it, instead of being lost.
+- `chi -p … --non-interactive` says so on stderr and exits 1 when the iteration limit cuts the turn short, instead
+  of exiting 0 with the partial text as if it were the answer.
+- `chi --no-shared --resume` drops a question the session's last worker saved and died with, as an attached resume
+  does, instead of keeping it in the session file.
+
 ## [0.62.0] - 2026-10-13
 
 ### Added
@@ -2719,7 +2794,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.62.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.64.0...HEAD
+[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
 [0.62.0]: https://github.com/dm1try/samagotchi/compare/v0.61.0...v0.62.0
 [0.61.0]: https://github.com/dm1try/samagotchi/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/dm1try/samagotchi/compare/v0.59.0...v0.60.0

data/README.md

@@ -150,7 +150,10 @@ task to a child session that runs in parallel and reports back only its final
 reply (a normal session: `chi --attach <id>` steers it). With the `coordinator`
 bundle (in `dev`), `/coordinate <goal>` has chi split the work into tasks, each
 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.
+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`).
 
 `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

@@ -386,8 +386,9 @@ begin
     scratch: scratch
   ).run
   # `chi -p X </dev/null`: the turn failed (nothing was sent again); -p
-  # --non-interactive: the turn ended with no answer, or Ctrl-C cancelled it.
-  exit 1 if %i[turn_failed empty_answer].include?(ended)
+  # --non-interactive: the turn ended with no answer or at the iteration
+  # limit, or Ctrl-C cancelled it.
+  exit 1 if %i[turn_failed empty_answer iteration_limit].include?(ended)
   exit Samagotchi::CLI::Exit::INTERRUPTED if ended == :interrupted
 rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel => e
   warn "Error: #{e.message}"

data/docs/architecture.md

@@ -73,6 +73,12 @@ TerminalUI  ──  delegates  ──▶  Engine
   delegates all core work to an `Engine`.
 - The `on_event:` seam on `run_turn` exposes raw `KernelLoop` events plus the
   higher-level turn events, so any new UI can render without terminal coupling.
+- **`ComposerRoute`** (`lib/samagotchi/composer_route.rb`) decides where a line typed at
+  either terminal's prompt goes (the REPL's `steer_line` / `run_input_line`, the attached
+  `AttachedLoop#submit`): `/cut TEXT` / `/queue TEXT`, a terminal's own word, a session
+  command, a typo, a prompt. Each UI keeps what it does with the route. The web's
+  `composer.js#routeComposerLine` decides the same; `spec/fixtures/composer_routes.json`
+  holds the cases both answer (see [testing.md](testing.md)).
 
 ## Request / turn flow
 
@@ -369,7 +375,11 @@ session every 10 s, so a `kill -9` shows within a second. The summary (`Web::Ses
 shared with `/api/sessions` and the session view) carries `owner`, `project_root` and
 `bridge_up` (the sidecar is there *and* the lock is held: the page attaches its stream on it), and
 from that sidecar `worker_version` (the chi the worker runs) and `worker_features`
-(`Bridge::FEATURES`, what a client may ask of it beyond the routes). A worker's Bridge snapshot
+(`Bridge::FEATURES`, what a client may ask of it beyond the routes: `restart`, `task_stop`, `reparent`,
+`delivery`, a worker that queues a message for after the turn; `SessionManager.deliver_turn` and
+the attached TUI refuse a queue to a worker without it, which would steer; `turn_ids`, a worker whose running
+turn's mark, continue turn and Stop carry the turn's `enqueued_id`, which `chi answer`, `chi send --wait` with no
+message and `delegate_result` rely on through `ReplyWait.own_turn`). A worker's Bridge snapshot
 names its `chi_version` too.
 `POST/DELETE /api/sessions` and `/stop` rescan the session before answering (`SessionHub#touch`).
 `GET /api/sessions` is the hub's projection too (its sort, paging and total). `Server` always builds
@@ -448,7 +458,7 @@ stream events (server counts, else a chars/4 estimate). Model lists are `LLM::Mo
 server (`/props`), then the host's model list, then config.
 
 **Keys.** A host's API key comes only from the environment variable its
-`api_key_env:` names; it never reaches config.yml, `HOSTS_JSON`, `chi self`,
+`api_key_env:` names; it never reaches config.yml, `SAMAGOTCHI_HOSTS_JSON`, `chi self`,
 logs or events.
 
 ## Other components

data/docs/cli.md

@@ -18,7 +18,7 @@
 - `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). `stats ID` prints a session's cost, tokens and progress (a live worker's `GET stats`, else its saved `analytics.json`; `--format json` one object) without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle (see [Attached context](context.md))
-- `chi send [-m TEXT] [--image PATH]... [--cut] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; `--format json` prints one JSON object instead; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
+- `chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it; `--queue` runs it as a turn of its own after the running one, and `--queue --wait` waits for that turn's own answer); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; `--format json` prints one JSON object instead; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). An approval can be denied, not allowed, unless `guardrails.parent_approvals: once` (a convention, not a security boundary; see [Guardrails](guardrails.md#approvals-from-a-parent-agent))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
@@ -250,7 +250,10 @@ Notes:
   retry lines and hooks' notices as they come, the after_turn hooks' ones
   (source-links' `sources:`) after the answer; and the error of a failed turn,
   then `chi: the session is kept with your prompt; continue it with: chi
-  --resume ID` (exit 1). Ctrl-C saves the session with the prompt and a
+  --resume ID` (exit 1). A turn the iteration limit (`turn.max_iterations`)
+  cut short prints what the model wrote so far, then `chi: the iteration limit
+  (N) was reached before the turn finished; continue it with: chi --resume ID`
+  on stderr (exit 1). Ctrl-C saves the session with the prompt and a
   cancel note and exits 130.
   Nobody can answer there: an approval is denied, and a question the model
   asks (`ask_user_question`) is dismissed at once (one line on stderr), never
@@ -295,8 +298,8 @@ and cuts nothing. `/cut TEXT` in a terminal or the web composer (or `chi send --
 once the model has streamed only thinking for `steer.cut_after` seconds (per host/model: `steer_cut_after`; default
 20), now or while your message waits, that generation is cut and the step starts again with your message, marked
 `↪ cut in for your message` (see
-[configuration.md](configuration.md#messages-during-a-running-turn-steer-and-cut)). The web
-composer has no `/queue` yet (it says so and sends nothing). The
+[configuration.md](configuration.md#messages-during-a-running-turn-steer-and-cut)). `/queue TEXT`
+(terminal or web composer, or `chi send --queue`) keeps TEXT for after the turn: it runs as a turn of its own once the running one ends. The
 first answer to an `ask_user_question` wins; the other UIs close their widget.
 An empty answer dismisses the question in every UI. The model is then told
 not to go ahead with what it asked about, or change anything else, and to wait.
@@ -538,10 +541,18 @@ REPL alike:
   20 s)` (it waits for the thinking; the step may end first) or `(cutting is
   off; goes in at the next step)` (`steer.cut_after` is 0, per host/model:
   `steer_cut_after`, or no generation to cut).
-- `/queue TEXT` (plain REPL only) runs TEXT as a turn of its own after this
-  one: `(queued: runs after this turn)`. An attached terminal says
-  `(/queue isn't available in an attached session yet)` and sends nothing (the web
-  composer: `(/queue isn't available in the web yet; …)`).
+- `/queue TEXT` runs TEXT as a turn of its own after this one, in an attached
+  terminal, the plain REPL and the web composer alike: `(queued: runs after this
+  turn)` (the web draws it as a queued bubble until its turn starts). It never
+  merges into the running turn, and a plain line sent after it still does.
+  Several queued lines run one turn each, in the order sent; they still run
+  after a Ctrl-C or a failed turn, and a queued line drops a continue offer as
+  any prompt does. Other terminals show someone else's queued line with the same
+  note. A session whose worker is older than queueing would steer it instead, so
+  it is not sent: `(/queue needs a newer worker: restart it with chi sessions
+  restart, then send again)` (the web shows the refusal under the line). A line
+  with images works the same way: it waits for the turn's end, and the lines
+  sent after it still go in at the next step.
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
   as a normal prompt.
 - Commands answer, wait or are refused, by what they do:
@@ -833,7 +844,7 @@ Notes:
 - Without `--default` the command is session-scoped and does not rewrite config files.
 - With `--default` the new default is written to `~/.config/samagotchi/config.yml` (honoring `XDG_CONFIG_HOME`) and takes effect for all new sessions; the current session's effective model is also updated immediately. Bare aliases and `host:model` are both valid.
 - `--default` and `--alias` change only their one key's line in `config.yml` (`default.model`, or the alias under `model_aliases:`): comments and the rest of the file stay as written, a symlinked file is written through and keeps its mode. When the edited text wouldn't read back as the expected settings (a flow-style section, anchors), chi writes the whole file out from the parsed data instead, which drops its comments.
-- Worker sessions inherit `hosts:` via `SAMAGOTCHI_HOSTS_JSON`.
+- A worker reads `hosts:` from config.yml when it starts (not from the chi that started it).
 - The idle recap uses the session's current model (a switch counts from the next recap), unless `recap: {host_ref, model}` pins one.
 
 ## Session recap

data/docs/configuration.md

@@ -106,7 +106,10 @@ Behavior:
   at its start until it is stopped; the web's model picker lists a `hosts:`
   edit at once). A worker gets the CLI flags of the chi that started it
   through its environment.
-- Workers inherit hosts via `SAMAGOTCHI_HOSTS_JSON` propagated through `SessionManager.spawn_options`.
+- A worker reads `hosts:` from the file as it starts, as every other setting, so a delegate (or any session
+  started later) sees a host added after its parent started. `SAMAGOTCHI_HOSTS_JSON` (a JSON object in the shape
+  of `hosts:`) replaces the file's `hosts:` for the process it is set on, the way specs use it; no worker inherits
+  it (`SessionManager.spawn_options` unsets it).
 
 This lets you run `chi` without repeating common defaults such as model
 and llama host/port on every invocation.
@@ -372,7 +375,7 @@ system prompt stays the same; a server that swaps models between turns goes unno
 `server (chat_template)`, `name`, `default`); `chi self` shows what config says without asking the server. A chat
 host (`api: openai`) formats nothing itself: its profile comes from the name and only strips thought tags.
 
-Workers get `hosts:` (with `profile:`) through `SAMAGOTCHI_HOSTS_JSON` and read `models:` from the same config file.
+Workers read `hosts:` (with `profile:`) and `models:` from the config file.
 `--profile` reaches the worker a chi starts, but a worker that another process wakes later (`chi web`, `--attach`
 after an idle exit) gets that process's environment, so put a lasting choice in config.
 
@@ -416,8 +419,8 @@ models:
 
 `/model` shows what applies (`sampling: temperature=0.6 presence_penalty=1.5 (hosts.work)`), and each request's
 `stream` line in the debug log carries a `sampling=` field with what was sent. The fields are read every turn, so a
-`/model` switch takes the new model's. A worker gets `hosts:` (with `sampling:`) when it starts, through
-`SAMAGOTCHI_HOSTS_JSON`, and reads `models:` from the config file each turn: after changing a host's `sampling:`,
+`/model` switch takes the new model's. A worker reads `hosts:` (with `sampling:`) from the config file when it
+starts, and `models:` each turn: after changing a host's `sampling:`,
 stop the session's worker (`chi sessions stop`) for it to take effect.
 
 ## Prices
@@ -907,7 +910,8 @@ that model's cut wait (`steer.cut_after` seconds, default `20`, `0` = never; cou
 so the wait for a busy server doesn't count) and still does, and the model starts the step again with the message
 (`↪ cut in for your message`). One that comes earlier cuts once the thinking passes it, unless the step ends first
 and the message goes in there. A plain message (from the web composer, `chi send` without `--cut`, a parent agent)
-never asks for a cut. Such a cut spends no `retry.empty_answer` attempt and sends no hidden note; only the cut
+never asks for a cut, nor does a queued one (`/queue TEXT`, `chi send --queue`, `ctx.sessions.send(…, delivery:
+:queue)`), which runs as a turn of its own after the running one. Such a cut spends no `retry.empty_answer` attempt and sends no hidden note; only the cut
 thinking is lost. A generation that has streamed visible text or a tool call is never cut, and a plugin's steer
 (`ctx.steer`, `ctx.sessions.send`) never cuts.
 
@@ -931,9 +935,12 @@ models:
 
 `/model` shows the resolved wait (`; steer cut: after 60 s (models: qwen)`, `; steer cut: never (hosts.splash)`).
 
-`/queue TEXT` in the plain REPL runs TEXT as a turn of its own after the running one; the attached terminal and the web
-don't queue yet, and a request that asks the Bridge or the web for `delivery: "queue"` is refused (400
-`delivery_unavailable`).
+`/queue TEXT` (in a terminal or the web composer) runs TEXT as a turn of its own after the running one: the request
+carries `delivery: "queue"`, the input file keeps it, and the worker's drain leaves the file for after the turn. The
+Bridge acks `delivery: "queue"` while a turn runs (to an idle session the message is simply the next turn:
+`next_step`). A worker whose sidecar doesn't name the `delivery` feature (older than queueing) would steer it, so the
+sender refuses it (`409 delivery_unavailable`, "restart it"), and so does a worker that answers the request with a
+400 `delivery_unavailable`.
 
 ## Server errors
 
@@ -1350,7 +1357,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `memory.index_warn_tokens` | `2500` | yes | The tokens one scope's memory index (project or system; sent with every prompt) may hold before a `memory_write`, `write` or `edit` that takes it over gets a note asking the model to tighten long index descriptions; `0`: no note. Estimated as characters / `context.chars_per_token`. `memory:` is its own section, not the `memories:` preload list. See [Memory](memory.md). |
 | `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`); `false`: updates wait as notes for the next turn. See [Waking](context.md#waking). |
+| `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). |
 | `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

@@ -123,6 +123,11 @@ chi context add clip --push --project
 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`.
+
 ### A stream: chat, a log, a feed
 
 A source's text is a snapshot, not a log: each run replaces it. For
@@ -233,6 +238,10 @@ you're away from the terminal. All of these must hold:
 - the source asked (`"wake": true`; a plain-text source never does), in
   any change since the session last heard of it: a later change that doesn't
   ask doesn't take the wake back;
+- it's a change, not the source's first text, except for a session's pushed
+  source (`chi context add NAME --push`, attached empty): its first push can
+  wake too. A command or URL source's first fetch runs as you attach it, and a
+  project source's first text may predate the session, so neither wakes;
 - `context.wake` is on (default `true`);
 - the session's worker is up and idle: no turn running, nothing queued, no
   question or continue offer waiting, not just started;
@@ -242,15 +251,16 @@ you're away from the terminal. All of these must hold:
 - the source hasn't woken the session in the last 10 minutes.
 
 Otherwise the change arrives as a note, as above. The turn starts with the
-update note, whose last line becomes:
+update note, or, for a session's pushed source, its attached note, whose last
+line becomes:
 
 > chi started this turn because the source changed; your user didn't write anything. Tell your user in a sentence or two what changed and what it may mean for their work. Don't run commands, change files or reply on the source for it: wait for your user to ask.
 
 Every UI labels the turn `context <name> changed`, and the web's
 notifications count it as a finished turn however short.
 
-A wake turn that fails goes back to before it and keeps the update as a
-plain note; the model reads `[SYSTEM: the previous turn failed before any
+A wake turn that fails goes back to before it and keeps its note as a
+plain one; the model reads `[SYSTEM: the previous turn failed before any
 answer: … The wake turn for the change in attached context <name> was not
 answered; chi starts no other wake turn until the user writes.]`.
 

data/docs/hooks.md

@@ -301,9 +301,12 @@ end
   keywords only (String or Symbol keys inside `target` and `actions`).
   - `match`: the text in the answer the ref stands for (at most 500 characters).
   - `kind`: a short lowercase word. `"file"` takes `target: {path:, line:, end_line:}`
-    (the lines optional); a relative path is resolved against the session's
-    folder, an absolute one is kept as given. Any other kind (`"issue"`,
-    `"commit"`, …) takes `target: {id:}`.
+    (the lines optional); the path is absolute or relative to the session's
+    folder, and must be **under** it (its own spelling or its real path:
+    `/tmp/x` or `/private/tmp/x`), as a plugin tool row's file refs
+    ([plugins.md](plugins.md)): a file elsewhere is refused. It is kept under
+    the folder's real path. Any other kind (`"issue"`, `"commit"`, …) takes
+    `target: {id:}`.
   - `label`: what a UI shows for it (optional, at most 200 characters).
   - `actions`: links a UI offers on top of the kind's own, each
     `{id:, label:, url:}`; http(s) URLs only, without userinfo (`user:pass@`),

data/docs/internals/engine.md

@@ -54,8 +54,10 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │
   ├── complete_turn(turn, result)
   │     # end_turn(turn, "completed" | "canceled"): under the event lock the session gets the kept
-  │     #   messages, goes IDLE, records last_turn, and :turn_completed {result, turn_summary,
-  │     #   display_pending} or :turn_canceled {cancellation_reason, cancelled_by, duration_ms} is emitted
+  │     #   messages, goes IDLE, records last_turn (enqueued_id: the turn's input, from its origin;
+  │     #   a continue turn's origin carries its offer turn's, ContinueOffer#run_continue_turn),
+  │     #   and :turn_completed {result, turn_summary, display_pending} or :turn_canceled
+  │     #   {cancellation_reason, cancelled_by, duration_ms} is emitted
   │     # then the :after_turn hook (status, messages, present: the AnswerDisplay presenter,
   │     #   refs: the AnswerRefs adder)
   │     # store_answer_display (one replace of the answer: `display` and/or `display_refs`;
@@ -521,7 +523,12 @@ Both loops:
 - **A cut generation** (`after_cut`): a generation a plugin cut (`stop_generation`) spends the same retry budget
   with its own nudge; when it is used up, the turn ends cancelled (`:hook`). A steer's cut asks again with the
   steer and spends nothing.
-- **Steering**: queued input goes in at iteration boundaries (`Steer.inject!`, `:pending_input_merged`).
+- **Steering**: queued input goes in at iteration boundaries (`Steer.inject!`, `:pending_input_merged`). A
+  worker's drain (`Worker#pending_input_drain`) takes every input file in name order except the ones
+  `SessionInbox.waits_for_turn_end?` leaves for a turn of their own (`delivery: queue`, or images): those are
+  skipped, not a barrier, so a line sent after them still merges. Only the files it claims reach
+  `:input_merged`, the failure hand-back (`@merged_this_turn`) and the checkpoint; the skipped ones run after the
+  turn, one turn each, in name order (`Worker#run_input_files`).
 - **Context status**: an estimate of the window's fill before each request,
   emitted on every request (`:context_status`) so the UI always has a current
   number, with a guidance line on the tail only when it rises far enough.

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 |
+| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-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

@@ -675,6 +675,7 @@ llama.cpp serves on a native host too.
 id = ctx.sessions.fork(messages: ctx.messages + [{ role: "user", content: q }, { role: "model", content: a }],
                        title: "btw: #{q}")
 ctx.sessions.send(id, "go on from here")
+ctx.sessions.send(id, "then the docs", delivery: :queue)  # after its running turn
 ctx.sessions.read(id)      # => {id:, title:, status:, parent_id:, running:, messages:}
 ctx.sessions.children      # => [{id:, short_id:, state:, branch:, last_reply:, reported:, ...}]
 ctx.sessions.stop(id)      # one of this session's own children
@@ -695,6 +696,12 @@ ctx.sessions.stop(id)      # one of this session's own children
   5 s for the session's worker, so call it from an anytime command or a
   thread of your own, never from a tool or hook of a running turn. A
   session open in a chi REPL can't take it.
+  - A running turn takes it at its next step. `delivery: :queue` runs it as
+    a turn of its own after that turn instead (as `/queue TEXT` does; to an
+    idle session it simply runs). A plugin never cuts the running turn's
+    thinking: `delivery: :cut` raises `Samagotchi::Plugin::Sessions::Error`,
+    as does an unknown value. A worker older than queueing refuses a queue
+    (it would steer): `Error` with its reason; nothing is sent.
 - `read(id)` gives a session now: from its worker when one runs (with a
   running turn so far, `running: true`), else as saved. `messages` has no
   system prompt.
@@ -722,7 +729,7 @@ ctx.sessions.stop(id)      # one of this session's own children
 ```ruby
 ctx.context.attach(url: "https://github.com/acme/app/pull/42", why: "branch feat/x has open PR #42")
 ctx.context.attach(name: "ci", cmd: "bin/ci-status", why: "this branch's CI", every_seconds: 120)
-ctx.context.list  # => [{name:, scope:, why:, hint:, fetched_at:, error:, provider:}]
+ctx.context.list  # => [{name:, scope:, why:, hint:, fetched_at:, error:, provider:, summary:}]
 ctx.context.decline(url: "https://github.com/acme/app/pull/42")    # => "pr-42"
 ctx.context.mark_offered("pr-42", "https://github.com/acme/app/pull/42", why: "branch feat/x has open PR #42")
 ctx.context.offered("pr-42")  # => #<data Offer name="pr-42", hint="https://…", why="branch…", at="2026-10-08T…Z">, or nil
@@ -756,7 +763,10 @@ gets a note when its text changes.
 - The source is the session's (not the project's), marked
   `added_by: plugin:<bundle>`. It is plugin code, so it isn't asked about as
   the agent's `chi context add --cmd` is.
-- `list` gives the session's sources, its own then its project's.
+- `list` gives the session's sources, its own then its project's (`[]` before
+  the session has an id or its file is saved: a command before the first turn). `hint` is the
+  one the last text gave (else the source's), `summary` that text's summary
+  (nil before any text; chi 0.63.0).
 - Two attaches of one source at once (a double click) both return its
   name.
 - `attach`, `decline` and `mark_offered` raise
@@ -1504,6 +1514,90 @@ by themselves there.
         reason: merging a child's branch
   ```
 
+## The claude-peer bundle
+
+```sh
+chi bundle install claude-peer    # in the dev profile
+```
+
+A live link between a chi session and a Claude Code session you already work
+with: chi sends it a part of the work (a plan step, a diff, a finding) to
+validate or as context, and Claude's answer comes back into chi. This is
+Claude with the context it has, not a fresh review run. Nothing runs until a
+Claude pairs; without one the bundle costs one tool declaration.
+
+- **Pairing is Claude's.** chi can't see Claude's inbox, so Claude attaches
+  two pushed sources to the chi session: `claude-inbox`, whose hint is its
+  per-session inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`, Claude Code
+  2.1.224 or later), and `claude-review`, where its answers come. You never
+  run that yourself:
+  1. `/claude install-skill` (once) shows a card with the target,
+     `$CLAUDE_CONFIG_DIR/skills/chi-peer/SKILL.md` (else `~/.claude/…`),
+     whether one is there and, when it differs, a short diff; its Install (or
+     Replace) button runs `/claude install-skill --yes`, which copies the
+     bundle's `scripts/chi-peer-SKILL.md` there with the installed
+     `scripts/pair` path written in. The copy happens inside chi, where no
+     guardrail sees it: the button is your consent. The card also offers the
+     Claude Code permission rule `Read(~/.local/state/samagotchi/plugins/claude-peer/**)`
+     (your state folder), so Claude isn't asked before reading a long part's
+     file; chi never writes Claude's settings.
+  2. In Claude Code you say "pair with chi <id or chi web URL>". The skill runs
+     `sh <bundle>/scripts/pair <id or URL>`, which attaches `claude-inbox` (the
+     socket as its hint, pushed as JSON so a re-pair after a Claude restart
+     refreshes it) and `claude-review`, and lists the session's context. A
+     re-pair keeps Claude's last answer.
+  3. Claude answers a validate or a question with a JSON push to
+     `claude-review` (`text`, `summary`, `wake: true`), which wakes chi, the
+     first answer too (on chi 0.62 the first one arrives as a note without
+     waking); the model reads it with `context_read claude-review`.
+- **The tool `claude_send(kind, title, text)`**, `kind` being `validate`,
+  `context` or `question`, writes one JSON line to that socket. The message
+  starts with a header, `chi <id> · <kind> · <title>`. A text up to 4,000
+  characters follows inline; a longer one goes to a file,
+  `$XDG_STATE_HOME/samagotchi/plugins/claude-peer/sessions/<id>/<HHMMSS>-<slug>.md`
+  (removed with the session), and the message names it (`payload: <path>`).
+  The tool is declared whether or not a Claude is paired, so pairing doesn't
+  change the prompt. Its errors say what to do: no `claude-inbox` (pair from
+  Claude), the socket gone or refusing (that Claude session ended or
+  restarted: pair again), a text over 200,000 characters.
+- **`/claude`** (an anytime command, so it works mid-turn) sends without
+  the model:
+  - `/claude` alone shows a card: paired or not, the socket and whether its
+    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.
+  - `/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.
+- **The skill.** `skill_claude_peer` (system scope) tells the model to send
+  only when you ask, to pick the part rather than the session, not to wait
+  or poll, and how to read the `claude-review` answer (a validate ends with
+  `VERDICT: OK`, `CHANGES` or `UNSURE`).
+- **Asking first.** The tool has no `targets:`, so guardrails match it by name
+  only: to be asked before each send, add a rule ([Rules in
+  config.yml](guardrails.md#rules-in-configyml)):
+
+  ```yaml
+  guardrails:
+    rules:
+      - id: claude-send
+        tool: claude_send
+        verdict: ask
+        reason: sends session content to Claude Code
+  ```
+
+- **Limits.** The socket's format (`{"type":"user","message":{"role":"user","content":"…"}}`)
+  is undocumented: it was found in, and checked on, Claude Code 2.1.296. A
+  line Claude Code can't parse is dropped silently, so a Claude Code update
+  could break this without an error. No auth line is sent: it is optional on
+  macOS and Linux, and native Windows, which needs it, isn't supported.
+  Claude's `crossSessionInbound` setting decides what it does with a peer
+  message: an interactive auto-mode session delivers it; a session that
+  bypasses permissions holds it for approval (in `-p` it expires after 5
+  minutes). It is local only (a Unix socket), but it does hand session
+  content to another agent: only what the model or you picked.
+
 ## 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, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, source-links, github-pr, coordinator, claude-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:`